Skip to content

Commit db373e9

Browse files
petebacondarwinpetebacondarwin
committed
docs(README.md): update instructions to match scripts
1 parent dd9fe39 commit db373e9

File tree

1 file changed

+166
-124
lines changed

1 file changed

+166
-124
lines changed

‎README.md‎

Lines changed: 166 additions & 124 deletions
Original file line numberDiff line numberDiff line change
@@ -12,8 +12,7 @@ The seed app doesn't do much, just shows how to wire two controllers and views t
1212

1313
## Getting Started
1414

15-
To get you started you can simply clone the angular-seed repository and run the preconfigured
16-
development web server...
15+
To get you started you can simply clone the angular-seed repository and install the dependencies:
1716

1817
### Clone angular-seed
1918

@@ -24,208 +23,251 @@ git clone https://github.com/angular/angular-seed.git
2423
cd angular-seed
2524
```
2625

27-
### Run the Application
26+
### Install Dependencies
27+
28+
We have two kinds of dependencies in this project: tools and angular framework code. The tools help
29+
us manage and test the application.
30+
31+
* We get the tools we depend upon via `npm`, the [node package manager][npm].
32+
* We get the angular code via `bower`, a [client-side code package manager][bower].
2833

29-
We have preconfigured the project with node.js to download the latest stable version
30-
of AngularJS and install a simple development web server. The simplest way to do this is:
34+
We have preconfigured `npm` to automatically run `bower` so we can simply do:
3135

3236
```
33-
npm start
37+
npm install
3438
```
3539

36-
Now browse to the app at `http://localhost:8080/app/index.html`.
37-
40+
Behind the scenes this will also call `bower install`. You should find that you have two new
41+
folders in your project.
3842

39-
## The AngularJS Files
43+
* `node_modules` - contains the npm packages for the tools we need
44+
* `bower_components` - contains the angular framework files
4045

41-
The AngularJS files are not stored inside the angular-seed project, we download them from the
42-
[bower][bower] repository. [Bower][bower] is a [node.js][node] utility for managing client-side web
43-
application dependencies. It is installed via npm.
46+
### Run the Application
4447

45-
**Running `npm start`, in the [Getting Started](#Getting-Started) section, automatically installed
46-
[bower][bower] locally for us. You may prefer to have [bower][bower] installed globally**:
48+
We have preconfigured the project with a simple development web server. The simplest way to start
49+
this server is:
4750

4851
```
49-
sudo npm install -g bower
52+
npm start
5053
```
5154

52-
Once we have bower installed, we can use it to get the Angular framework dependencies we need:
55+
Now browse to the app at `http://localhost:8000/app/index.html`.
5356

54-
```
55-
bower install
56-
```
5757

58-
Bower will download all the necessary dependencies into the `bower_components` folder. Again, this
59-
is done automatically for us when we run `npm start`.
6058

61-
## Serving the Application Files
59+
## Directory Layout
6260

63-
While angular is client-side-only technology and it's possible to create angular webapps that
64-
don't require a backend server at all, we recommend serving the project files using a local
65-
webserver during development to avoid issues with security restrictions (sandbox) in browsers. The
66-
sandbox implementation varies between browsers, but quite often prevents things like cookies, xhr,
67-
etc to function properly when an html page is opened via `file://` scheme instead of `http://`.
61+
app/ --> all of the files to be used in production
62+
css/ --> css files
63+
app.css --> default stylesheet
64+
img/ --> image files
65+
index.html --> app layout file (the main html template file of the app)
66+
index-async.html --> just like index.html, but loads js files asynchronously
67+
js/ --> javascript files
68+
app.js --> application
69+
controllers.js --> application controllers
70+
directives.js --> application directives
71+
filters.js --> custom angular filters
72+
services.js --> custom angular services
73+
partials/ --> angular view partials (partial html templates)
74+
partial1.html
75+
partial2.html
6876

77+
test/ --> test config and source files
78+
protractor-conf.js --> config file for running e2e tests with Protractor
79+
e2e/ --> end-to-end specs
80+
scenarios.js
81+
karma.conf.js --> config file for running unit tests with Karma
82+
unit/ --> unit level specs/tests
83+
controllersSpec.js --> specs for controllers
84+
directivessSpec.js --> specs for directives
85+
filtersSpec.js --> specs for filters
86+
servicesSpec.js --> specs for services
6987

70-
### Running the app during development
7188

72-
The angular-seed project comes preconfigured with a local development webserver. It is a node.js
73-
tool called `http-server`. You can start this webserver with `npm start` but you may choose to
74-
install the tool globally:
89+
## Testing
90+
91+
There are two kinds of tests in the angular-seed application: Unit tests and End to End tests.
92+
93+
### Running Unit Tests
94+
95+
The angular-seed app comes preconfigured with unit tests. These are written in
96+
[Jasmine][jasmine], which we run with the [Karma Test Runner][karma]. We provide a Karma
97+
configuration file to run them.
98+
99+
* the configuration is found at `test/karma.conf.js`
100+
* the unit tests are found in `test/unit/`.
101+
102+
The easiest way to run the unit tests is to use the supplied npm script:
75103

76104
```
77-
sudo npm install -g http-server
105+
npm test
78106
```
79107

80-
Then you can start your own development web server to server static files, from a folder, by
81-
running:
108+
This script will start the Karma test runner to execute the unit tests.
109+
110+
We can also have Karma sit and watch the application and test files for changes and re-run the
111+
tests whenever any of them change. You can do this with:
82112

83113
```
84-
http-server
114+
npm run test-watch
85115
```
86116

87-
Alternatively, you can choose to configure your own webserver, such as apache or nginx. Just
88-
configure your server to serve the files under the `app/` directory.
89117

118+
### End to end testing
90119

91-
### Running the app in production
120+
The angular-seed app comes with end-to-end tests, again written in [Jasmine][jasmine]. These tests
121+
are run with the [Protractor][protractor] End-to-End test runner. It uses native events and has
122+
special features for Angular applications.
92123

93-
This really depends on how complex is your app and the overall infrastructure of your system, but
94-
the general rule is that all you need in production are all the files under the `app/` directory.
95-
Everything else should be omitted.
124+
* the configuration is found at `test/protractor-conf.js`
125+
* the end-to-end tests are found in `test/e2e/`
96126

97-
Angular apps are really just a bunch of static html, css and js files that just need to be hosted
98-
somewhere, where they can be accessed by browsers.
127+
Protractor simulates interaction with our web app and verifies that the application responds
128+
correctly. Therefore, our web server needs to be serving up the application, so that Protractor
129+
can interact with it.
99130

100-
If your Angular app is talking to the backend server via xhr or other means, you need to figure
101-
out what is the best way to host the static files to comply with the same origin policy if
102-
applicable. Usually this is done by hosting the files by the backend server or through
103-
reverse-proxying the backend server(s) and webserver(s).
131+
```
132+
npm start
133+
```
104134

135+
In addition, since Protractor is built upon WebDriver we need to install this. The angular-seed
136+
project comes with a predefined script to do this:
105137

106-
## Testing
138+
```
139+
npm run update-webdriver
140+
```
107141

108-
There are two kinds of tests in the angular-seed application: Unit tests and End to End tests.
142+
This will download and install the latest version of the stand-alone WebDriver tool.
109143

110-
### Running Unit Tests
144+
Once you have ensured that the development web server hosting our application is up and running
145+
and WebDriver is updated, you can run the end-to-end tests using the supplied npm script:
111146

112-
We recommend using [jasmine](http://pivotal.github.com/jasmine/) and
113-
[Karma](http://karma-runner.github.io) for your unit tests/specs, but you are free
114-
to use whatever works for you.
147+
```
148+
npm run protractor
149+
```
115150

116-
The angular-seed app comes preconfigured with such tests and a Karma configuration file to run them.
151+
This script will execute the end-to-end tests against the application being hosted on the
152+
development server.
117153

118-
* the configuration is found at `test/karma.conf.js`
119-
* the unit tests are found in `test/unit/`.
120154

121-
The easiest way to run the unit tests is to use the supplied npm script:
155+
## Updating Angular
156+
157+
Previously we recommended that you merge in changes to angular-seed into your own fork of the project.
158+
Now that the angular framework library code and tools are acquired through package managers (npm and
159+
bower) you can use these tools instead to update the dependencies.
160+
161+
You can update the tool dependencies by running:
122162

123163
```
124-
npm test
164+
npm update
125165
```
126166

127-
This script will ensure that the Karma dependencies are installed and then start the Karma test
128-
runner to execute the unit tests. Karma will then sit and watch the application and test files for
129-
changes and re-run the tests whenever any of them change.
167+
This will find the latest versions that match the version ranges specified in the `package.json` file.
130168

131-
The Karma Test Runner is a [node.js][node] tool. You may choose to install the CLI tool globally
169+
You can update the Angular dependencies by running:
132170

133171
```
134-
sudo npm install -g karma
172+
bower update
135173
```
136174

137-
You can then start Karma directly, passing it the test configuration file:
175+
This will find the latest versions that match the version ranges specified in the `bower.json` file.
176+
177+
178+
## Loading Angular Asynchronously
179+
180+
The angular-seed project supports loading the framework and application scripts asynchronously. The
181+
special `index-async.html` is designed to support this style of loading. For it to work you must
182+
inject a piece of Angular JavaScript into the HTML page. The project has a predefined script to help
183+
do this.
138184

139185
```
140-
karma start test/karma.conf.js
186+
npm run update-index-async
141187
```
142188

143-
A browser will start and connect to the Karma server (Chrome is default browser, others can be
144-
captured by loading the same url as the one in Chrome or by changing the `test/karma.conf.js`
145-
file). Karma will then re-run the tests when there are changes to any of the source or test
146-
javascript files.
189+
This will copy the contents of the `angular-loader.js` library file into the `index-async.html` page.
190+
You can run this every time you update the version of Angular that you are using.
147191

148192

193+
## Serving the Application Files
149194

150-
### End to end testing
195+
While angular is client-side-only technology and it's possible to create angular webapps that
196+
don't require a backend server at all, we recommend serving the project files using a local
197+
webserver during development to avoid issues with security restrictions (sandbox) in browsers. The
198+
sandbox implementation varies between browsers, but quite often prevents things like cookies, xhr,
199+
etc to function properly when an html page is opened via `file://` scheme instead of `http://`.
151200

152-
We recommend using [Protractor][protractor] for end-to-end tests. It uses native events and has
153-
special features for Angular applications.
154201

155-
* the configuration is found at `test/protractor-conf.js`
156-
* the end-to-end tests are found in `test/e2e/`
202+
### Running the App during Development
157203

158-
Protractor simulates interaction with our web app and verifies that the application responds
159-
correctly. Therefore, our web server needs to be serving up the application, so that Protractor
160-
can interact with it.
204+
The angular-seed project comes preconfigured with a local development webserver. It is a node.js
205+
tool called [http-server][http-server]. You can start this webserver with `npm start` but you may choose to
206+
install the tool globally:
161207

162-
Once you have ensured that the development web server hosting our application is up and running
163-
(probably `npm start`) you can run the end-to-end tests using the supplied npm script:
208+
```
209+
sudo npm install -g http-server
210+
```
211+
212+
Then you can start your own development web server to server static files, from a folder, by
213+
running:
164214

165215
```
166-
npm run-script protractor
216+
http-server
167217
```
168218

169-
This script will ensure that the dependencies (including the Selenium Web Driver component) are
170-
up to date and then execute the end-to-end tests against the application being hosted on the
171-
development server.
219+
Alternatively, you can choose to configure your own webserver, such as apache or nginx. Just
220+
configure your server to serve the files under the `app/` directory.
172221

173222

174-
### Continuous Integration
223+
### Running the App in Production
175224

176-
CloudBees have provided a CI/deployment setup:
225+
This really depends on how complex is your app and the overall infrastructure of your system, but
226+
the general rule is that all you need in production are all the files under the `app/` directory.
227+
Everything else should be omitted.
177228

178-
<a href="https://grandcentral.cloudbees.com/?CB_clickstart=https://raw.github.com/CloudBees-community/angular-js-clickstart/master/clickstart.json"><img src="https://d3ko533tu1ozfq.cloudfront.net/clickstart/deployInstantly.png"/></a>
229+
Angular apps are really just a bunch of static html, css and js files that just need to be hosted
230+
somewhere, where they can be accessed by browsers.
179231

180-
If you run this, you will get a cloned version of this repo to start working on in a private git repo,
181-
along with a CI service (in Jenkins) hosted that will run unit and end to end tests in both Firefox and Chrome.
232+
If your Angular app is talking to the backend server via xhr or other means, you need to figure
233+
out what is the best way to host the static files to comply with the same origin policy if
234+
applicable. Usually this is done by hosting the files by the backend server or through
235+
reverse-proxying the backend server(s) and webserver(s).
182236

183-
### Receiving updates from upstream
184237

185-
When we upgrade angular-seed's repo with newer angular or testing library code, you can just
186-
fetch the changes and merge them into your project with git.
238+
## Continuous Integration
187239

240+
### Travis CI
188241

189-
## Directory Layout
242+
[Travis CI][travis] is a continuous integration service, which can monitor GitHub for new commits
243+
to your repository and execute scripts such as building the app or running tests. The angular-seed
244+
project contains a Travis configuration file, `.travis.yml`, which will cause Travis to run your
245+
tests when you push to GitHub.
190246

191-
app/ --> all of the files to be used in production
192-
css/ --> css files
193-
app.css --> default stylesheet
194-
img/ --> image files
195-
index.html --> app layout file (the main html template file of the app)
196-
index-async.html --> just like index.html, but loads js files asynchronously
197-
js/ --> javascript files
198-
app.js --> application
199-
controllers.js --> application controllers
200-
directives.js --> application directives
201-
filters.js --> custom angular filters
202-
services.js --> custom angular services
203-
lib/ --> angular and 3rd party javascript libraries
204-
angular/
205-
angular.js --> the latest angular js
206-
angular.min.js --> the latest minified angular js
207-
angular-*.js --> angular add-on modules
208-
version.txt --> version number
209-
partials/ --> angular view partials (partial html templates)
210-
partial1.html
211-
partial2.html
247+
You will need to enable the integration between Travis and GitHub. See the Travis website for more
248+
instruction on how to do this.
249+
250+
### CloudBees
251+
252+
CloudBees have provided a CI/deployment setup:
253+
254+
<a href="https://grandcentral.cloudbees.com/?CB_clickstart=https://raw.github.com/CloudBees-community/angular-js-clickstart/master/clickstart.json">
255+
<img src="https://d3ko533tu1ozfq.cloudfront.net/clickstart/deployInstantly.png"/></a>
256+
257+
If you run this, you will get a cloned version of this repo to start working on in a private git repo,
258+
along with a CI service (in Jenkins) hosted that will run unit and end to end tests in both Firefox and Chrome.
212259

213-
test/ --> test config and source files
214-
protractor-conf.js --> config file for running e2e tests with Protractor
215-
e2e/ --> end-to-end specs
216-
scenarios.js
217-
karma.conf.js --> config file for running unit tests with Karma
218-
unit/ --> unit level specs/tests
219-
controllersSpec.js --> specs for controllers
220-
directivessSpec.js --> specs for directives
221-
filtersSpec.js --> specs for filters
222-
servicesSpec.js --> specs for services
223260

224261
## Contact
225262

226263
For more information on AngularJS please check out http://angularjs.org/
227264

228265
[git]: http://git-scm.com/
229266
[bower]: http://bower.io
267+
[npm]: https://www.npmjs.org/
230268
[node]: http://nodejs.org
231-
[protractor]: https://github.com/angular/protractor
269+
[protractor]: https://github.com/angular/protractor
270+
[jasmine]: http://pivotal.github.com/jasmine/
271+
[karma]: http://karma-runner.github.io
272+
[travis]: https://travis-ci.org/
273+
[http-server]: https://github.com/nodeapps/http-server

0 commit comments

Comments
 (0)