angular.js/docs/content/misc/contribute.ngdoc

@ngdoc overview
@name Develop
@description

# Building and Testing AngularJS

This document describes how to set up your development environment to build and test AngularJS, and
explains the basic mechanics of using `git`, `node`, `npm`, `grunt`, and `bower`.

See the [contributing guidelines](https://github.com/angular/angular.js/blob/master/CONTRIBUTING.md)
for how to contribute your own code to AngularJS.


1. {@link #building-and-testing-angularjs_installing-dependencies Installing Dependencies}
2. {@link #building-and-testing-angularjs_forking-angular-on-github Forking Angular on Github}
3. {@link #building-and-testing-angularjs_building-angularjs Building AngularJS}
4. {@link #building-and-testing-angularjs_running-a-local-development-web-server Running a Local Development Web Server}
5. {@link #building-and-testing-angularjs_running-the-unit-test-suite Running the Unit Test Suite}
6. {@link #building-and-testing-angularjs_running-the-end-to-end-test-suite Running the End-to-end Test Suite}

## Installing Dependencies

Before you can build AngularJS, you must install and configure the following dependencies on your
machine:

* {@link http://git-scm.com/ Git}: The {@link https://help.github.com/articles/set-up-git Github Guide to
Installing Git} is a good source of information.

* {@link http://nodejs.org Node.js}: We use Node to generate the documentation, run a
development web server, run tests, and generate distributable files. Depending on your system, you can install Node either from source or as a
pre-packaged bundle.

* {@link http://www.java.com Java}: We minify JavaScript using our
{@link https://developers.google.com/closure/ Closure Tools} jar. Make sure you have Java (version 6 or higher) installed
and included in your {@link http://docs.oracle.com/javase/tutorial/essential/environment/paths.html PATH} variable.

* {@link http://gruntjs.com Grunt}: We use Grunt as our build system. Install the grunt command-line tool globally with:

  ```shell
  npm install -g grunt-cli
  ```

* {@link http://bower.io/ Bower}: We use Bower to manage client-side packages for the docs. Install the `bower` command-line tool globally with:

  ```shell
  npm install -g bower
  ```

**Note:** You may need to use sudo (for OSX, *nix, BSD etc) or run your command shell as Administrator (for Windows) to install Grunt &
Bower globally.

## Forking Angular on Github

To create a Github account, follow the instructions {@link https://github.com/signup/free here}.
Afterwards, go ahead and {@link http://help.github.com/forking fork} the {@link
https://github.com/angular/angular.js main AngularJS repository}.


## Building AngularJS

To build AngularJS, you clone the source code repository and use Grunt to generate the non-minified and
minified AngularJS files:

```shell
# Clone your Github repository:
git clone git@github.com:<github username>/angular.js.git

# Go to the AngularJS directory:
cd angular.js

# Add the main AngularJS repository as an upstream remote to your repository:
git remote add upstream https://github.com/angular/angular.js.git

# Install node.js dependencies:
npm install

# Install bower components:
bower install

# Build AngularJS:
grunt package
```


<div class="alert alert-warning">
**Note:** If you're using Windows, you must use an elevated command prompt (right click, run as
Administrator). This is because `grunt package` creates some symbolic links.
</div>

The build output can be located under the `build` directory. It consists of the following files and
directories:

* `angular-<version>.zip` — The complete zip file, containing all of the release build
artifacts.

* `angular.js` — The non-minified `angular` script.

* `angular.min.js` —  The minified `angular` script.

* `angular-scenario.js` — The `angular` End2End test runner.

* `docs/` — A directory that contains all of the files needed to run `docs.angularjs.org`.

* `docs/index.html` — The main page for the documentation.

* `docs/docs-scenario.html` — The End2End test runner for the documentation application.


## Running a Local Development Web Server

To debug code and run end-to-end tests, it is often useful to have a local HTTP server. For this purpose, we have
made available a local web server based on Node.js.

1. To start the web server, run:
   ```shell
   grunt webserver
   ```

2. To access the local server, enter the following URL into your web browser:
   ```
   http://localhost:8000/
   ```
   By default, it serves the contents of the AngularJS project directory.


## Running the Unit Test Suite

We write unit and integration tests with Jasmine and execute them with Karma. To run all of the
tests once on Chrome run:

```shell
grunt test:unit
```

To run the tests on other browsers (Chrome, ChromeCanary, Firefox, Opera and Safari are pre-configured) use:

```shell
grunt test:unit --browsers Opera,Firefox
```

Note there should be _no spaces between browsers_. `Opera, Firefox` is INVALID.

During development it's however more productive to continuously run unit tests every time the source or test files
change. To execute tests in this mode run:

1. To start the Karma server, capture Chrome browser and run unit tests, run:

   ```shell
   grunt autotest
   ```

2. To capture more browsers, open this URL in the desired browser (URL might be different if you have multiple instance
   of Karma running, read Karma's console output for the correct URL):

   ```shell
   http://localhost:9876/
   ```

3. To re-run tests just change any source or test file.


To learn more about all of the preconfigured Grunt tasks run:

```shell
grunt --help
```


## Running the End-to-end Test Suite

Simply run:

```shell
grunt test:e2e
```

This will start the webserver and run the tests.