Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 266 lines (164 sloc) 8.964 kb
5d7c49c @reid Yeti Next is now Yeti.
reid authored
1 # Yeti
9266040 @reid Add README
reid authored
2
8ad5d52 @reid Show CI badge for yui/yeti at master.
reid authored
3 [![Build Status](https://secure.travis-ci.org/yui/yeti.png?branch=master)](http://travis-ci.org/yui/yeti)
d86d2a6 @reid Add Travis CI badge to the README.
reid authored
4
2b00553 @reid Update README.md documentation.
reid authored
5 Yeti is a command-line tool for launching JavaScript unit tests in a browser
6 and reporting the results without leaving your terminal.
7 Yeti is designed to work with tests built on [YUI Test][yuitest] just as they are.
8
9 ## Install Yeti
10
11 The latest release can be installed easily:
12
13 npm install -g yeti
14
15 Yeti requires Node.js, which provides the `npm` command for installation.
16 You can [download Node.js](http://nodejs.org/download/) source or pre-built
17 installers from their website.
459f668 @reid Yeti Next Hub. New package.json.
reid authored
18
52f9ab3 @reid Increase README indent level.
reid authored
19 ## Using Yeti
308acee @reid Expand the contributor section of the README.
reid authored
20
52f9ab3 @reid Increase README indent level.
reid authored
21 ### Running a test
459f668 @reid Yeti Next Hub. New package.json.
reid authored
22
f8855dc @reid Update README.md for new status line feature.
reid authored
23 Just run Yeti with the HTML files containing your tests.
9266040 @reid Add README
reid authored
24
f8855dc @reid Update README.md for new status line feature.
reid authored
25 $ yeti test/*.html
9f69f2c @reid Update the README.
reid authored
26 Creating a Hub at http://localhost:9000
27 Waiting for agents to connect at http://localhost:9000.
28 When ready, press Enter to begin testing.
9266040 @reid Add README
reid authored
29
9f69f2c @reid Update the README.
reid authored
30 Point your browsers at that URL, then come back and press Enter.
835eaab @reid Update README with server goodness.
reid authored
31
f8855dc @reid Update README.md for new status line feature.
reid authored
32 [Open some browsers...]
835eaab @reid Update README with server goodness.
reid authored
33
f8855dc @reid Update README.md for new status line feature.
reid authored
34 Agent connected: Safari (6.0) / Mac OS
35 Agent connected: Chrome (22.0.1221.0) / Mac OS
36
37 [Come back, press Enter]
38
39 ✔ Testing started on Safari (6.0) / Mac OS, Chrome (22.0.1221.0) / Mac OS
40 Testing... / 86% complete (19/22) 121.99 tests/sec ✔ Agent completed: Safari (6.0) / Mac OS
41 Testing... | 95% complete (21/22) 115.40 tests/sec ✔ Agent completed: Chrome (22.0.1221.0) / Mac OS
42 Testing... \ 100% complete (22/22) 115.23 tests/sec 504 tests passed! (9164ms)
9f69f2c @reid Update the README.
reid authored
43 $
2f8bf8b @reid Update README for sexy new test output.
reid authored
44
9f69f2c @reid Update the README.
reid authored
45 Yeti exits automatically when all tests complete. If test failures occur, Yeti will exit with a non-zero status code.
9266040 @reid Add README
reid authored
46
e047487 @reid Add docs for code coverage, timeouts, and query.
reid authored
47 ### Code coverage
48
49 Yeti automatically includes a line coverage summary if your tests were instrumented with [YUI Test Coverage][yuitest].
50
51 ✔ Testing started on Safari (6.0) / Mac OS
52 Testing... \ 13% complete (10/60) 11.85 tests/sec 44% line coverage
53
52f9ab3 @reid Increase README indent level.
reid authored
54 ### Yeti Hub
9266040 @reid Add README
reid authored
55
9f69f2c @reid Update the README.
reid authored
56 To save time, start a Yeti Hub.
9266040 @reid Add README
reid authored
57
9f69f2c @reid Update the README.
reid authored
58 $ yeti --server
59 Yeti Hub listening on port 9000.
835eaab @reid Update README with server goodness.
reid authored
60
9f69f2c @reid Update the README.
reid authored
61 Point browsers at your local Yeti on port 9000. Now, you're ready to run tests without having to reconnect browsers each time.
835eaab @reid Update README with server goodness.
reid authored
62
f8855dc @reid Update README.md for new status line feature.
reid authored
63 Starting Yeti in another terminal will connect to that Hub instead of starting a new one
64 and will begin testing immediately if browsers are already connected.
835eaab @reid Update README with server goodness.
reid authored
65
f8855dc @reid Update README.md for new status line feature.
reid authored
66 $ yeti test/*.html
9f69f2c @reid Update the README.
reid authored
67 Connected to http://localhost:9000
f8855dc @reid Update README.md for new status line feature.
reid authored
68 Agent connected: Chrome (22.0.1221.0) / Mac OS
69 Agent connected: Safari (6.0) / Mac OS
70 ✔ Testing started on Chrome (22.0.1221.0) / Mac OS, Safari (6.0) / Mac OS
71 Testing... / 68% complete (15/22) 98.84 tests/sec ✔ Agent completed: Chrome (22.0.1221.0) / Mac OS
72 Testing... | 95% complete (21/22) 91.65 tests/sec ✔ Agent completed: Safari (6.0) / Mac OS
73 Testing... \ 100% complete (22/22) 91.60 tests/sec 504 tests passed! (11529ms)
74 $
835eaab @reid Update README with server goodness.
reid authored
75
52f9ab3 @reid Increase README indent level.
reid authored
76 ### Sharing Your Yeti Hub
835eaab @reid Update README with server goodness.
reid authored
77
9f69f2c @reid Update the README.
reid authored
78 Your Yeti Hub can be shared with other developers.
78adf33 @reid Documentation sync with current Yeti code.
reid authored
79
9f69f2c @reid Update the README.
reid authored
80 First, I'll start a Hub on test.yeti.cx on port 80.
78adf33 @reid Documentation sync with current Yeti code.
reid authored
81
9f69f2c @reid Update the README.
reid authored
82 $ yeti --server --port 80
835eaab @reid Update README with server goodness.
reid authored
83
9f69f2c @reid Update the README.
reid authored
84 Go ahead and point a few browsers there.
835eaab @reid Update README with server goodness.
reid authored
85
9f69f2c @reid Update the README.
reid authored
86 Now, others can connect to it from their computer like so:
835eaab @reid Update README with server goodness.
reid authored
87
f8855dc @reid Update README.md for new status line feature.
reid authored
88 $ yeti --hub http://test.yeti.cx/ test/*.html
9f69f2c @reid Update the README.
reid authored
89 Connected to http://test.yeti.cx/
90 Waiting for agents to connect at http://test.yeti.cx/.
91 When ready, press Enter to begin testing.
78adf33 @reid Documentation sync with current Yeti code.
reid authored
92
9f69f2c @reid Update the README.
reid authored
93 Your `pwd` and your test file will be served through the Hub. Like magic.
835eaab @reid Update README with server goodness.
reid authored
94
9f69f2c @reid Update the README.
reid authored
95 [Hit Enter]
f8855dc @reid Update README.md for new status line feature.
reid authored
96 Agent connected: Chrome (22.0.1221.0) / Mac OS
97 Agent connected: Safari (6.0) / Mac OS
98 ✔ Testing started on Chrome (22.0.1221.0) / Mac OS, Safari (6.0) / Mac OS
99 Testing... - 91% complete (20/22) 122.51 tests/sec ✔ Agent completed: Safari (6.0) / Mac OS
100 Testing... | 95% complete (21/22) 120.21 tests/sec ✔ Agent completed: Chrome (22.0.1221.0) / Mac OS
101 Testing... \ 100% complete (22/22) 120.05 tests/sec 504 tests passed! (8763ms)
835eaab @reid Update README with server goodness.
reid authored
102
9f69f2c @reid Update the README.
reid authored
103 This makes it really simple to setup an ad-hoc testing lab shared with your team.
7304e7d @reid Update README, include contributing details.
reid authored
104
e047487 @reid Add docs for code coverage, timeouts, and query.
reid authored
105 ### Timeouts
106
107 Yeti will disconnect a browser if it does not record any activity from it for 45 seconds.
108 You can adjust this interval with the `--timeout` option.
109
110 This will run Yeti with a 120 second timeout:
111
112 $ yeti --timeout 120 test.html
113
114 ### Query string parameters
115
b57a074 @reid Improve query string documentation.
reid authored
116 You can specify query string parameters to add to your test URLs.
e047487 @reid Add docs for code coverage, timeouts, and query.
reid authored
117 This can be used to pass information to your tests that control its behavior.
118
119 This will append `?fliter=coverage` to your tests, which is used by the tests
120 for the [YUI Library][YUI] to trigger loading instrumented code.
121
122 $ yeti --query 'filter=coverage' test/*.html
78adf33 @reid Documentation sync with current Yeti code.
reid authored
123
52f9ab3 @reid Increase README indent level.
reid authored
124 ### Error handling
78adf33 @reid Documentation sync with current Yeti code.
reid authored
125
9f69f2c @reid Update the README.
reid authored
126 Yeti will report an uncaught exceptions as Script Errors.
78adf33 @reid Documentation sync with current Yeti code.
reid authored
127
9f69f2c @reid Update the README.
reid authored
128 Yeti enforces [No-Quirks Mode][] in your tests because it may impact DOM-related APIs. [Add a DOCTYPE][doctype] to your test document to fix this.
78adf33 @reid Documentation sync with current Yeti code.
reid authored
129
52f9ab3 @reid Increase README indent level.
reid authored
130 ### Mobile testing made easy
835eaab @reid Update README with server goodness.
reid authored
131
9f69f2c @reid Update the README.
reid authored
132 When combined with [localtunnel][], mobile testing is simple. If you're not dealing with sensitive information, startup your Yeti Hub and then run:
835eaab @reid Update README with server goodness.
reid authored
133
9f69f2c @reid Update the README.
reid authored
134 $ localtunnel 9000
135 Port 9000 is now publicly accessible from http://3z48.localtunnel.com ...
835eaab @reid Update README with server goodness.
reid authored
136
137 You can then visit that URL on your mobile (or any other) device and have it run new tests.
138
52f9ab3 @reid Increase README indent level.
reid authored
139 ### Yeti API
308acee @reid Expand the contributor section of the README.
reid authored
140
141 You can `require("yeti")` inside your application to script Yeti for your own use.
9266040 @reid Add README
reid authored
142
308acee @reid Expand the contributor section of the README.
reid authored
143 For API documentation:
91d1af4 @reid Update README: install, --server, Windows support
reid authored
144
308acee @reid Expand the contributor section of the README.
reid authored
145 - Run `make html` to build HTML documentation to `./build_docs`.
146 - Review code comments inside `lib/yeti.js`, `lib/client.js` and `lib/hub/index.js`.
147
148 Yeti follows [Semantic Versioning](http://semver.org/) but is currently at a 0.x.y release. **The public API is not stable.** There will be changes.
149
52f9ab3 @reid Increase README indent level.
reid authored
150 ### Caveats
308acee @reid Expand the contributor section of the README.
reid authored
151
9848093 @reid Update for Node.js 0.7.11 and Windows .\jake.bat.
reid authored
152 Yeti should work on all platforms supported by Node.js.
153 It's tested on Linux and OS X.
91d1af4 @reid Update README: install, --server, Windows support
reid authored
154
9f69f2c @reid Update the README.
reid authored
155 You must start Yeti's client in the directory you'll be serving tests from. For security reasons, Yeti will reject requests that try to access files outside of the directory you start Yeti in.
9266040 @reid Add README
reid authored
156
2b00553 @reid Update README.md documentation.
reid authored
157 ## Install latest Yeti snapshot
9266040 @reid Add README
reid authored
158
2b00553 @reid Update README.md documentation.
reid authored
159 You can install the latest in-development snapshot of Yeti easily, too:
9266040 @reid Add README
reid authored
160
308acee @reid Expand the contributor section of the README.
reid authored
161 npm install -g http://latest.yeti.cx
7617de8 @reid Add npm install instructions.
reid authored
162
2b00553 @reid Update README.md documentation.
reid authored
163 This will install Yeti as it exists on the [yui/yeti GitHub repository][github].
164 You can check the stability of the Yeti snapshot by checking [yui/yeti on Travis][travis].
835eaab @reid Update README with server goodness.
reid authored
165
52f9ab3 @reid Increase README indent level.
reid authored
166 ## Develop Yeti
01ef719 @reid Use yuidocjs build tool for `make html`.
reid authored
167
308acee @reid Expand the contributor section of the README.
reid authored
168 Do you want to add new features or fix bugs in Yeti itself? We made it easy for you to hack on Yeti.
01ef719 @reid Use yuidocjs build tool for `make html`.
reid authored
169
9848093 @reid Update for Node.js 0.7.11 and Windows .\jake.bat.
reid authored
170 ### Experimental: Develop on Windows
171
172 After running `npm install`, replace the `make` commands below with
173 `.\jake.bat` to use the experimental Jake tasks that are Windows ready.
174
52f9ab3 @reid Increase README indent level.
reid authored
175 ### Install dependencies
01ef719 @reid Use yuidocjs build tool for `make html`.
reid authored
176
308acee @reid Expand the contributor section of the README.
reid authored
177 Clone Yeti.
01ef719 @reid Use yuidocjs build tool for `make html`.
reid authored
178
308acee @reid Expand the contributor section of the README.
reid authored
179 git clone https://github.com/yui/yeti.git
180 cd yeti
181
2b00553 @reid Update README.md documentation.
reid authored
182 Install Yeti's dependencies.
308acee @reid Expand the contributor section of the README.
reid authored
183
184 npm install
185
2b00553 @reid Update README.md documentation.
reid authored
186 ### Run tests & code coverage
308acee @reid Expand the contributor section of the README.
reid authored
187
2b00553 @reid Update README.md documentation.
reid authored
188 Yeti's automated tests require PhantomJS.
189 You can [download PhantomJS](http://phantomjs.org/download.html) source or pre-built
190 binaries from their website. Make sure the `phantomjs` binary is installed in your PATH.
308acee @reid Expand the contributor section of the README.
reid authored
191
192 make test
193 make coverage
9f69f2c @reid Update the README.
reid authored
194
2b00553 @reid Update README.md documentation.
reid authored
195 The latter command uses [JSCoverage for Node.js][jsc],
308acee @reid Expand the contributor section of the README.
reid authored
196 which will be built and installed to `./tools/jscoverage`.
29ca09c @reid Add client tests, driven by PhantomJS.
reid authored
197
52f9ab3 @reid Increase README indent level.
reid authored
198 ### HTML documentation
29ca09c @reid Add client tests, driven by PhantomJS.
reid authored
199
9021e43 @reid Update YUIDocJS. API documentation works again.
reid authored
200 #### Website
201
2b00553 @reid Update README.md documentation.
reid authored
202 Yeti uses [Selleck][] to generate its website. Selleck files are located in `doc/`.
9021e43 @reid Update YUIDocJS. API documentation works again.
reid authored
203
308acee @reid Expand the contributor section of the README.
reid authored
204 make html
5beb6e9 @reid README feedback: x-platform, localtunnel, etc.
reid authored
205
2b00553 @reid Update README.md documentation.
reid authored
206 Documentation will be built to `build_docs/`.
9021e43 @reid Update YUIDocJS. API documentation works again.
reid authored
207
208 #### JavaScript API
209
2b00553 @reid Update README.md documentation.
reid authored
210 Yeti uses [YUIDocJS][] to generate API documentation from inline JSDoc comment blocks.
9021e43 @reid Update YUIDocJS. API documentation works again.
reid authored
211
212 make html-api
213
2b00553 @reid Update README.md documentation.
reid authored
214 Documentation will be built to `build_docs/api/everything/`.
9021e43 @reid Update YUIDocJS. API documentation works again.
reid authored
215
913fd3f @reid Switch from JSLint to JSHint for code quality.
reid authored
216 ### Linter
308acee @reid Expand the contributor section of the README.
reid authored
217
218 make lint
219
8b0c7e4 @reid Remove `./lint`, replace with `./go lint`.
reid authored
220 You may also run the linter on individual files with `./go lint`:
9021e43 @reid Update YUIDocJS. API documentation works again.
reid authored
221
8b0c7e4 @reid Remove `./lint`, replace with `./go lint`.
reid authored
222 ./go lint test/blizzard.js
9021e43 @reid Update YUIDocJS. API documentation works again.
reid authored
223
913fd3f @reid Switch from JSLint to JSHint for code quality.
reid authored
224 Yeti uses [JSHint][] to analyze code for problems. See `.jshintrc` for options used by Yeti.
225
c1a7df4 @reid Add profiler script. Ref #67.
reid authored
226 ### Profiler
227
2b00553 @reid Update README.md documentation.
reid authored
228 Requires [Google Chrome Canary][canary] and OS X.
c1a7df4 @reid Add profiler script. Ref #67.
reid authored
229
230 Profile the Yeti Hub:
231
232 ./go profile --server
233
234 Using `./go profile` without `--server` to profile the Yeti client
235 requires an interactive terminal, which does not yet work.
236
52f9ab3 @reid Increase README indent level.
reid authored
237 ### Contribute to Yeti
308acee @reid Expand the contributor section of the README.
reid authored
238
a24db5c @reid Add CONTRIBUTING.md.
reid authored
239 See [CONTRIBUTING.md](https://github.com/yui/yeti/blob/master/CONTRIBUTING.md).
308acee @reid Expand the contributor section of the README.
reid authored
240
52f9ab3 @reid Increase README indent level.
reid authored
241 ## Bugs & Feedback
9f69f2c @reid Update the README.
reid authored
242
243 Open a ticket on [YUILibrary.com's Yeti Issue Tracker][issues] to report bugs or feature requests.
244
52f9ab3 @reid Increase README indent level.
reid authored
245 ## License
7304e7d @reid Update README, include contributing details.
reid authored
246
2b00553 @reid Update README.md documentation.
reid authored
247 Yeti is free to use under YUI's BSD license.
248 See the LICENSE file or the [YUI license page](http://yuilibrary.com/license/)
249 for license text and copyright information.
7304e7d @reid Update README, include contributing details.
reid authored
250
c1a7df4 @reid Add profiler script. Ref #67.
reid authored
251 [canary]: https://tools.google.com/dlpage/chromesxs
2b00553 @reid Update README.md documentation.
reid authored
252 [github]: https://github.com/yui/yeti
253 [travis]: http://travis-ci.org/yui/yeti
913fd3f @reid Switch from JSLint to JSHint for code quality.
reid authored
254 [JSHint]: http://jshint.com/
9021e43 @reid Update YUIDocJS. API documentation works again.
reid authored
255 [YUIDocJS]: https://github.com/davglass/yuidocjs
256 [Selleck]: http://github.com/rgrove/selleck
29ca09c @reid Add client tests, driven by PhantomJS.
reid authored
257 [jsc]: https://github.com/visionmedia/node-jscoverage
835eaab @reid Update README with server goodness.
reid authored
258 [localtunnel]: http://localtunnel.com/
9266040 @reid Add README
reid authored
259 [node]: http://nodejs.org/
260 [npm]: http://npmjs.org/
64d5cf2 @reid Update README for YUI Labs, native installer
reid authored
261 [issues]: http://yuilibrary.com/projects/yeti/newticket
262 [YUI]: http://yuilibrary.com/
2b00553 @reid Update README.md documentation.
reid authored
263 [yuitest]: http://yuilibrary.com/yuitest/
78adf33 @reid Documentation sync with current Yeti code.
reid authored
264 [doctype]: http://www.whatwg.org/specs/web-apps/current-work/multipage/syntax.html#the-doctype
265 [No-Quirks Mode]: http://www.whatwg.org/specs/web-apps/current-work/multipage/dom.html#no-quirks-mode
Something went wrong with that request. Please try again.