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.

Follow the tutorial to see how AngularJS makes browsers smarter — without the use of native
extensions or plug-ins:

 See examples of how to use client-side data

binding to build dynamic views of data that
change immediately in response to user
actions.
 See how AngularJS keeps your views in
sync with your data without the need for
DOM manipulation.
 Learn a better, easier way to test your web
apps, with Karma and Protractor.
 Learn how to use dependency injection and
services to make common web tasks, such
as getting data into your app, easier.

When you finish the tutorial you will be able to:

  Create a dynamic application that works in
all modern browsers.
 Use data binding to wire up your data model
to your views.
 Create and run unit tests, with Karma.
 Create and run end-to-end tests, with
Protractor.
 Move application logic out of the template
and into components and controllers.
 Get data from a server using AngularJS
services.
 Apply animations to your application, using
the ngAnimate module.
 Structure your AngularJS applications in a
modular way that scales well for larger
projects.
 Identify resources for learning more about
AngularJS.

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.

Environment Setup
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.

Working with the Code

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.

Install Git
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.

Download angular-phonecat
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.

The --depth=16 option tells Git to pull down only the last 16 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 within
the angular-phonecat directory.

Install Node.js
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:

node --version

In Debian based distributions, there might be a name clash with another utility called node.
The suggested solution is to also install the nodejs-legacy apt package, which
renames node to nodejs.

apt-get install nodejs-legacy npm

nodejs --version
npm --version

If you need to run different versions of Node.js in your local environment, consider
installing Node Version Manager (nvm) or Node Version Manager (nvm) for Windows.
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:

npm install

This command reads angular-phonecat's package.json file and downloads the following

dependencies into the node_modules directory:

 Http-Server - simple local static web server

 Karma - unit test runner
 Protractor - end-to-end (E2E) test runner

Running npm install will also automatically copy the AngularJS framework and other
dependencies necessary for our app to work into the app/lib/ directory.
Note the angular-phonecat project is setup to install and run these utilities via npm scripts.
This means that you do not have to have any of these utilities installed globally on your
system to follow the tutorial. See Installing Helper Tools below for more information.
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.

Install Helper Tools (optional)

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:

http-server ./app
Running the Development Web Server
While AngularJS 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 an 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 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.
To serve the web app on a different IP address or port, edit the "start" script
within package.json. You can use -a to set the address and -p to set the port. You also need to
update the baseUrl configuration property in e2e-test/protractor.conf.js.

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 test
files (specs) side-by-side with the application code. This way it's easier to find them and keep
them up-to-date with the code under test. It also makes refactoring our app structure easier,
since tests are moved together with the source code.
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 karma.conf.js, located at the root of the project directory. This configuration file tells
Karma to:

 Open up instances of the Chrome and

Firefox browsers and connect them to
Karma.
 Execute all the unit tests in these browsers.
 Report the results of these tests in the
terminal/command line window.
 Watch all the project's JavaScript files and
re-run the tests whenever any of these
change.

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 E2E Tests

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 e2e-tests directory.
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

You don't have to manually run this command. Our npm scripts are configured so that it will
be automatically executed as part of the command that runs the E2E tests.
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 e2e-tests/protractor.conf.js. This configuration

file tells Protractor to:

 Open up a Chrome browser and connect it

to the application.
 Execute all the E2E tests in this browser.
 Report the results of these tests in the
terminal/command line window.
 Close the browser and exit.

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.

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
in package.json) and also copy the necessary files into app/lib/. For example,
if package.json contains "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.

See here for more info on the various version range formats.

Common Issues

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 git:.)
If you run into this issue, you can force the use of https: instead, by running the following
command: git config --global url."https://".insteadOf git://

Updating WebDriver takes too long

Running 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.

Protractor dependencies
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 npm start.
Now that you have set up your local machine, let's get started with the tutorial: Step 0 -
Bootstrapping