A great way to get introduced to AngularJS is to work through this tutorial, which walks you through the construction of an AngularJS web app. The app you will build is a catalog that displays a list of Android devices, lets you filter the list to see only devices that interest you, and then view details for any device.
Follow the tutorial to see how AngularJS makes browsers smarter — without the use of native extensions or plug-ins:
When you finish the tutorial you will be able to:
The tutorial guides you through the entire process of building a simple application, including writing and running unit and end-to-end tests. Experiments at the end of each step provide suggestions for you to learn more about AngularJS and the application you are building.
You can go through the whole tutorial in a couple of hours or you may want to spend a pleasant day really digging into it. If you're looking for a shorter introduction to AngularJS, check out the Getting Started document.
The rest of this page explains how you can set up your local machine for development. If you just want to read the tutorial, you can go straight to the first step: Step 0 - Bootstrapping.
You can follow along with this tutorial and hack on the code in the comfort of your own computer. This way, you can get hands-on practice of really writing AngularJS code and also on using the recommended testing tools.
The tutorial relies on the use of the Git versioning system for source code management. You don't need to know anything about Git to follow the tutorial other than how to install and run a few git commands.
You can download and install Git from https://git-scm.com/download. Once installed, you should have
access to the
git command line tool. The main commands that you will need to use are:
git clone ...: Clone a remote repository onto your local machine.
git checkout ...: Check out a particular branch or a tagged version of the code to hack on.
Clone the angular-phonecat repository located at GitHub by running the following command:
git clone --depth=16 https://github.com/angular/angular-phonecat.git
This command creates an
angular-phonecat sub-directory in your current directory.
--depth=16option tells Git to pull down only the last 16 commits. This makes the download much smaller and faster.
Change your current directory to
The tutorial instructions, from now on, assume you are running all commands from within the
In order to install dependencies (such as the test tools and AngularJS itself) and run the preconfigured local web server, you will also need Node.js v6+.
You can download a Node.js installer for your operating system from https://nodejs.org/en/download/.
Check the version of Node.js that you have installed by running the following command:
In Debian based distributions, there might be a name clash with another utility called
suggested solution is to also install the
nodejs-legacy apt package, which renames
apt-get install nodejs-legacy npm nodejs --version npm --version
By installing Node.js, you also get npm, which is a command line executable for downloading and managing Node.js packages. We use it to download the AngularJS framework as well as development and testing tools.
Once you have Node.js installed on your machine, you can download these dependencies by running:
This command reads angular-phonecat's
package.json file and downloads the following dependencies
npm install will also automatically copy the AngularJS framework and other dependencies
necessary for our app to work into the
The project is preconfigured with a number of npm helper scripts to make it easy to run the common tasks that you will need while developing:
npm start: Start a local development web server.
npm test: Start the Karma unit test runner.
npm run protractor: Run the Protractor end-to-end (E2E) tests.
npm run update-webdriver: Install the drivers needed by Protractor.
The Http-Server, Karma and Protractor modules are also executables, which can be installed globally
and run directly from a terminal/command prompt. You don't need to do this to follow the tutorial,
but if you decide you do want to run them directly, you can install these modules globally using,
sudo npm install --global ....
For instance, to install the
http-server command line executable you would do:
sudo npm install --global http-server
(Omit the sudo if running on Windows.)
Then you can run the
http-server tool directly, such as:
The angular-phonecat project is configured with a simple static web server for hosting the application during development. Start the web server by running:
This will create a local web server that is listening to port 8000 on your local machine. You can now browse to the application at http://localhost:8000/index.html.
package.json. You can use
-ato set the address and
-pto set the port. You also need to update the
baseUrlconfiguration property in
The angular-phonecat project is configured to use Karma to run the unit tests for the application. Start Karma by running:
This will start the Karma unit test runner. Karma will read the configuration file
located at the root of the project directory. This configuration file tells Karma to:
It is good to leave this running all the time, in the background, as it will give you immediate feedback about whether your changes pass the unit tests while you are working on the code.
We use E2E (end-to-end) tests to ensure that the application as a whole operates as expected. E2E tests are designed to test the whole client-side application, in particular that the views are displaying and behaving correctly. It does this by simulating real user interaction with the real application running in the browser.
The E2E tests are kept in the
The angular-phonecat project is configured to use Protractor to run the E2E tests for the application. Protractor relies upon a set of drivers to allow it to interact with the browser. You can install these drivers by running:
npm run update-webdriver
Since Protractor works by interacting with a running application, we need to start our web server:
Then, in a separate terminal/command line window, we can run the Protractor test scripts against the application by running:
npm run protractor
Protractor will read the configuration file at
e2e-tests/protractor.conf.js. This configuration
file tells Protractor to:
It is good to run the E2E tests whenever you make changes to the HTML views or want to check that the application as a whole is executing correctly. It is very common to run E2E tests before pushing a new commit of changes to a remote repository.
Each version of Protractor is compatible with specific browser versions. If you are reading this some time in the future, it is possible that the specified Protractor version is no longer compatible with the latest version of Chrome that you are using.
If that is the case, you can try upgrading Protractor to newer version. For instructions on how to upgrade dependencies see Updating dependencies.
In order to avoid surprises, all dependencies listed in
package.json are pinned to specific
versions (this is what the package-lock.json file is about). This ensures that the
same version of a dependency is installed every time.
Since all dependencies are acquired via npm, you can use the same tool to easily update them as well (although you probably don't need to for the purpose of this tutorial). Simply run the preconfigured script:
npm run update-deps
This will update all packages to the latest version that satisfy their version ranges (as specified
package.json) and also copy the necessary files into
app/lib/. For example, if
"some-package": "1.2.x", it will be updated to the latest 1.2.x version (e.g. 1.2.99),
but not to 1.3.x (e.g. 1.3.0).
If you want to update a dependency to a version newer than what the specificed range would permit,
you can change the version range in
package.json and then run
npm run update-deps as usual.
Firewall / Proxy issues
Git and other tools, often use the
git: protocol for accessing files in remote repositories.
Some firewall configurations are blocking
git:// URLs, which leads to errors when trying to clone
repositories or download dependencies. (For example corporate firewalls are "notorious" for blocking
If you run into this issue, you can force the use of
https: instead, by running the following
git config --global url."https://".insteadOf git://
Updating WebDriver takes too long
update-webdriver for the first time may take from several seconds up to a few minutes
(depending on your hardware and network connection). If you cancel the operation (e.g. using
Ctrl+C), you might get errors, when trying to run Protractor later.
In that case, you can delete the
node_modules/ directory and run
npm install again.
Under the hood, Protractor uses the Selenium Standalone Server, which in turn requires
the Java Development Kit (JDK) to be installed on your local machine. Check this by running
java -version from the command line.
If JDK is not already installed, you can download it here.
Error running the web server
The web server is configured to use port 8000. If the port is already in use (for example by another
instance of a running web server) you will get an
EADDRINUSE error. Make sure the port is
available, before running
Now that you have set up your local machine, let's get started with the tutorial: Step 0 - Bootstrapping