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 for how to contribute your own code to AngularJS.

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: 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: We minify JavaScript using our Closure Tools jar. Make sure you have Java (version 6 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:
```
npm install -g grunt-cli
```
Bower: We use Bower to manage client-side packages for the docs. Install the bower command-line tool globally with:
```
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. 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 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

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

sudo npm install -g grunt-cli
sudo npm install -g 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.

To start the web server, run:
```
grunt webserver
```
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.
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, Opera and Safari are pre-configured) use:

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:

To start the Karma server, capture Chrome browser and run unit tests, run:
```
grunt autotest
```
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/
```
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.