Improve this Doc

# 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`, `yarn`, `grunt`, and `bower`.

See the contributing guidelines for how to contribute your own code to AngularJS.

1. Installing Dependencies
2. Forking Angular on Github
3. Building AngularJS
4. Running a Local Development Web Server
5. Running the Unit Test Suite
6. 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: The Github Guide to Installing Git is a good source of information.

- Node.js v6.x (LTS): 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.

  We recommend using nvm (or nvm-windows) to manage and install Node.js, which makes it easy to change the version of Node.js per project.

- Yarn: We use Yarn to install our Node.js module dependencies (rather than using npm). There are detailed installation instructions available at https://yarnpkg.com/en/docs/install.

- Java: We minify JavaScript using our Closure Tools jar. Make sure you have Java (version 7 or higher) installed and included in your PATH variable.

- Grunt: We use Grunt as our build system. Install the grunt command-line tool globally with:

      yarn global add grunt-cli

## Forking Angular on Github

To create a Github account, follow the instructions here. Afterwards, go ahead and fork the 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:

    # Clone your Github repository:
    git clone https://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:
    yarn install

    # Build AngularJS (which will install `bower` dependencies automatically):
    grunt package

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.
Note: If you're using Linux, and `yarn install` fails with the message 'Please try running this command again as root/Administrator.', you may need to globally install `grunt` and `bower`:

- sudo yarn global add grunt-cli
- sudo yarn global add bower

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:

       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:

    grunt test:unit

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

    grunt test:unit --browsers=Chrome,Firefox

Note there should be no spaces between browsers. `Chrome, Firefox` is INVALID.

During development, however, it's 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:

       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):

       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:

    grunt --help

## Running the End-to-end Test Suite

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

    grunt test:e2e

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