Improve this doc

PhoneCat Tutorial App

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.

demo
application running in the browser

Follow the tutorial to see how Angular 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.

Get Started

The rest of this page explains how you can set up your machine to work with the code on your local machine. If you just want to read the tutorial then you can just go straight to the first step: Step 0 - Bootstrapping.

Working with the code

You can follow along with this tutorial and hack on the code in the comfort of your own computer. In 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.

Install Git

You can download and install Git from http://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:

Download angular-phonecat

Clone the angular-phonecat repository located at GitHub by running the following command:

git clone --depth=14 https://github.com/angular/angular-phonecat.git

This command creates the angular-phonecat directory in your current directory.

The --depth=14 option just tells Git to pull down only the last 14 commits. This makes the download much smaller and faster.

Change your current directory to angular-phonecat.

cd angular-phonecat

The tutorial instructions, from now on, assume you are running all commands from the angular-phonecat directory.

Install Node.js

If you want to run the preconfigured local web-server and the test tools then you will also need Node.js v0.10+.

You can download a Node.js installer for your operating system from http://nodejs.org/download/.

Check the version of Node.js that you have installed by running the following command:

node --version
If you need to run a different versions of node.js in your local environment, consider installing Node Version Manager (nvm) .

Once you have Node.js installed on your machine you can download the tool dependencies by running:

npm install

This command will download the following tools, into the node_modules directory:

Running npm install will also automatically run bower install, which will download the Angular framework into the bower_components directory.

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:

Running Development Web Server

While Angular applications are purely client-side code, and it is possible to open them in a web browser directly from the file system, it is better to serve them from a HTTP web server. In particular, for security reasons, most modern browsers will not allow JavaScript to make server requests if the page is loaded directly from the file system.

The angular-phonecat project is configured with a simple static web server for hosting the application during development. Start the web server by running:

npm start

This will create a local webserver that is listening to port 8000 on your local machine. You can now browse to the application at:

http://localhost:8000/app/index.html

Running Unit Tests

We use unit tests to ensure that the JavaScript code in our application is operating correctly. Unit tests focus on testing small isolated parts of the application. The unit tests are kept in the test/unit directory.

The angular-phonecat project is configured to use Karma to run the unit tests for the application. Start Karma by running:

npm test

This will start the Karma unit test runner. Karma will read the configuration file at test/karma.conf.js. 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.

Running End to End Tests

We use End to End tests to ensure that the application as a whole operates as expected. End to End 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 End to End tests are kept in the test/e2e directory.

The angular-phonecat project is configured to use Protractor to run the End to End 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

(You should only need to do this once.)

Since Protractor works by interacting with a running application, we need to start our web server:

npm start

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 test/protractor-conf.js. This configuration tells Protractor to:

It is good to run the end to end 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 End to End tests before pushing a new commit of changes to a remote repository.