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`, `yarn`, `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 v6.x (LTS)](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.

  We recommend using [nvm](https://github.com/creationix/nvm) to manage and install Node.js,
  which makes it easy to change the version of Node.js per project.

* [Yarn](https://yarnpkg.com): 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](http://www.java.com): We minify JavaScript using our
  [Closure Tools](https://developers.google.com/closure/) jar. Make sure you have Java (version 7 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
  yarn global add grunt-cli
  ```

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

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


<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 `yarn 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 yarn global add grunt-cli</li>
<li>sudo yarn global add 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:
   ```text
   http://localhost:8000/
   ```
   By default, it serves the contents of the AngularJS project directory.

3. To access the locally served docs, visit this URL:
   ```text
   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, 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:

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

   ```text
   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.