From 7b0c5b937cabb7be656bc06a4e3b40a7c7a8932b Mon Sep 17 00:00:00 2001 From: Peter Bacon Darwin Date: Fri, 4 Apr 2014 10:22:33 +0100 Subject: [PATCH] docs(tutorial): clean up and elaborate introduction --- docs/content/tutorial/index.ngdoc | 181 ++++++++++++++++++------------ 1 file changed, 112 insertions(+), 69 deletions(-) diff --git a/docs/content/tutorial/index.ngdoc b/docs/content/tutorial/index.ngdoc index 53040f25..d0967f93 100644 --- a/docs/content/tutorial/index.ngdoc +++ b/docs/content/tutorial/index.ngdoc @@ -13,23 +13,25 @@ details for any device. demo application running in the browser -Work through the tutorial to see how Angular makes browsers smarter — without the use of native -extensions or plug-ins. As you work through the tutorial, you will: +Follow the tutorial to see how Angular makes browsers smarter — without the use of native +extensions or plug-ins: -* See examples of how to use client-side data binding and dependency injection to build dynamic -views of data that change immediately in response to user actions. -* See how Angular creates listeners on your data without the need for DOM manipulation. -* Learn a better, easier way to test your web apps. -* Learn how to use Angular services to make common web tasks, such as getting data into your app, -easier. +* 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 Angular keeps your views in synch 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. -* Define the differences between Angular and common JavaScript frameworks. -* Understand how data binding works in AngularJS. -* Create and run unit tests. -* Create and run end to end tests. +* 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 Controllers. +* Get data from a server using Angular services. +* Apply animations to your application, using ngAnimate. * Identify resources for learning more about AngularJS. The tutorial guides you through the entire process of building a simple application, including @@ -40,31 +42,46 @@ You can go through the whole tutorial in a couple of hours or you may want to sp really digging into it. If you're looking for a shorter introduction to AngularJS, check out the {@link misc/started 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](tutorial/step_00). # Working with the code -You can follow along with this tutorial and hack on the code in either the Mac/Linux or the Windows -environment. The tutorial relies on the use of the [Git][git] versioning system for source code -management. +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. -You don't need to know anything about Git to follow the tutorial. Select one of the tabs below -and follow the instructions for setting up your computer. +The tutorial relies on the use of the [Git][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 +### Install Git -You'll need Git, which you can get from [the Git site][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: + +- `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][angular-phonecat] located at GitHub by running the following command: ``` -git clone https://github.com/angular/angular-phonecat.git +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`. ``` @@ -75,118 +92,144 @@ The tutorial instructions, from now on, assume you are running all commands from `angular-phonecat` directory. -## Install Node.js +### Install Node.js -If you want to run the built-in web-server and the test tools then you will also need -Node.js v0.10, or later. +If you want to run the preconfigured local web-server and the test tools then you will also need +[Node.js v0.10+][node]. -You can download Node.js from the [node.js website][node]. +You can download a Node.js installer for your operating system from http://nodejs.org/download/. - -You can check the version of Node.js that you have installed by running the following command: +Check the version of Node.js that you have installed by running the following command: ``` node --version ``` -
Helpful note: If you need to run a different versions of node.js +
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 you can install the tool dependencies by running: +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` directive: +This command will download the following tools, into the `node_modules` directory: - [Bower][bower] - client-side code package manager -- [http-server][http-server] - simple local static web server +- [Http-Server][http-server] - simple local static web server - [Karma][karma] - unit test runner -- [protractor][protractor] - end 2 end test runner +- [Protractor][protractor] - end 2 end test runner 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. +tasks that you will need while developing: -## Running Development Web Server +- `npm start` : start a local development web-server +- `npm test` : start the Karma unit test runner +- `npm run protractor` : run the Protractor end 2 end tests +- `npm update-webdriver` : install the drivers needed by Protractor -The project is preconfigured to provide a simple static web server for hosting the application. -Start the web server by running: +### 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 server 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 ``` -Now you can browse to the application at: +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 +### Running Unit Tests -The project is preconfigured to use [Karma][karma] to run the unit tests for the application. Start -Karma by running: +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][karma] to run the unit tests for the +application. Start Karma by running: ``` npm test ``` -This will start the Karma unit test runner, open up a Chrome browser and execute all the unit tests -in this browser. Karma will then sit and watch all the source and test JavaScript files. -Whenever one of these files changes Karma re-runs all the unit tests. +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 as you will get immediate feedback from Karma as you -are working on the code. +- open up a Chrome browser and connect it to Karma +- execute all the unit tests in this browser +- 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 End to End Tests +### Running End to End Tests -The project is preconfigured to use [Protractor][protractor] to run the end to end tests for the -application. Set up the binaries protractor needs to run by running: +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][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 will only need to do this once) Execute the Protractor test scripts against your application -by running: + +*(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 ``` -This will start the Protractor end to end test runner, open up a Chrome browser and execute all the -end to end test scripts in this browser. Once the test scripts finish, the browser will close down -and Protractor will exit. +Protractor will read the configuration file at `test/protractor-conf.js`. This configuration tells +Protractor to: + +- open up a Chrome browser and connect it to the application +- execute all the End to End tests in this browser +- report the results of these tests in the terminal/command line window +- close down the browser and exit 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. - -
Helpful note: Protractor requires that a web server is running - and serving up the application at the default URL: `http://localhost:8000/app/index.html`. You can - start the provided development server by running `npm start`. -
+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. -# Get Started - -Now your environment is ready, it is time to get started developing the Angular PhoneCat -application. - -Step 0 - Bootstrapping - - - -[git]: http://git-scm.com/download -[angular-phonecat]: https://github.com/angular/angular-phonecat +[git]: http://git-scm.com/ [node]: http://nodejs.org/ +[angular-phonecat]: https://github.com/angular/angular-phonecat [protractor]: https://github.com/angular/protractor [bower]: http://bower.io/ [http-server]: https://github.com/nodeapps/http-server