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 misc/contribute#installing-dependencies Installing Dependencies}
2. {@link misc/contribute#forking-angular-on-github Forking Angular on Github}
3. {@link misc/contribute#building-angularjs Building AngularJS}
4. {@link misc/contribute#running-a-local-development-web-server Running a Local Development Web Server}
5. {@link misc/contribute#running-the-unit-test-suite Running the Unit Test Suite}
6. {@link misc/contribute#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:

* [Git](http://git-scm.com/): The [Github Guide to
Installing Git](https://help.github.com/articles/set-up-git) is a good source of information.

* [Node.js](http://nodejs.org): 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.

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

* [Grunt](http://gruntjs.com): We use Grunt as our build system. Install the grunt command-line tool globally with:

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

* [Bower](http://bower.io/): 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 [here](https://github.com/signup/free).
Afterwards, go ahead and [fork](http://help.github.com/forking) the [main AngularJS repository](https://github.com/angular/angular.js).


## Building AngularJS

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

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

2. Go to the AngularJS directory:
  ```shell
  cd angular.js
  ```

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

4. Install node.js dependencies:
  ```shell
  npm install
  ```

5. Install bower components:
  ```shell
  bower install
  ```

6. Build AngularJS:
  ```shell
  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>

<div class="alert alert-warning">
**Note:** If you're using Linux, and npm install fails with the message
'Please try running this command again as root/Administrator.', you may need to globally install grunt and bower:
<ul>
<li>sudo npm install -g grunt-cli</li>
<li>sudo npm install -g bower</li>
</ul>

</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.

3. To access the locally served docs, visit this URL:
   ```
   http://localhost:8000/build/docs/
   ```

## 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

Angular's end to end tests are run with Protractor. Simply run:

```shell
grunt test:e2e
```

This will start the webserver and run the tests on Chrome.