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.
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
To create a Github account, follow the instructions here. Afterwards, go ahead and fork the main AngularJS repository.
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
grunt package
creates some symbolic links.
yarn install
fails with the message
'Please try running this command again as root/Administrator.', you may need to globally install grunt
and 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.
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/
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:
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
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.