Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 328 lines (225 sloc) 11.449 kB
92ab434 @assaf Added documentation page for CSS selectors.
authored
1 zombie.js(1) -- Insanely fast, headless full-stack testing using Node.js
2 ========================================================================
8f851ca @assaf Added troublehsooting guide.
authored
3
650947c @assaf Fixed documentation link.
authored
4
f35b8e2 @assaf First documentation you can actually use.
authored
5 ## The Bite
41ee2f2 @assaf Fixed test suite so vows command just works.
authored
6
cde857e @assaf Improved EventEmitter test cases.
authored
7 If you're going to write an insanely fast, headless browser, how can you not
41ee2f2 @assaf Fixed test suite so vows command just works.
authored
8 call it Zombie? Zombie it is.
9
62bf982 @assaf Fixed: too many forks in README (thanks strathmeyer)
authored
10 Zombie.js is a lightweight framework for testing client-side JavaScript code in
41ee2f2 @assaf Fixed test suite so vows command just works.
authored
11 a simulated environment. No browser required.
12
f35b8e2 @assaf First documentation you can actually use.
authored
13 Let's try to sign up to a page and see what happens:
41ee2f2 @assaf Fixed test suite so vows command just works.
authored
14
f35b8e2 @assaf First documentation you can actually use.
authored
15 var zombie = require("zombie");
51c0401 @assaf Fixed TOC, PDF header and added require("assert") to examples.
authored
16 var assert = require("assert");
41ee2f2 @assaf Fixed test suite so vows command just works.
authored
17
f35b8e2 @assaf First documentation you can actually use.
authored
18 // Load the page from localhost
9778d9e @assaf The `visit`, `clickLink` and `pressButton` methods now pass three
authored
19 zombie.visit("http://localhost:3000/", function (err, browser, status) {
41ee2f2 @assaf Fixed test suite so vows command just works.
authored
20
f35b8e2 @assaf First documentation you can actually use.
authored
21 // Fill email, password and submit form
22 browser.
23 fill("email", "zombie@underworld.dead").
24 fill("password", "eat-the-living").
9778d9e @assaf The `visit`, `clickLink` and `pressButton` methods now pass three
authored
25 pressButton("Sign Me Up!", function(err, browser, status) {
41ee2f2 @assaf Fixed test suite so vows command just works.
authored
26
f35b8e2 @assaf First documentation you can actually use.
authored
27 // Form submitted, new page loaded.
28 assert.equal(browser.text("title"), "Welcome To Brains Depot");
41ee2f2 @assaf Fixed test suite so vows command just works.
authored
29
f35b8e2 @assaf First documentation you can actually use.
authored
30 })
41ee2f2 @assaf Fixed test suite so vows command just works.
authored
31
f35b8e2 @assaf First documentation you can actually use.
authored
32 });
f050f19 @assaf Fixed loading to keep track of outstanding requests, so waiting
authored
33
f35b8e2 @assaf First documentation you can actually use.
authored
34 Well, that was easy.
d6803cc @assaf Starting to work on documentation
authored
35
099817a @assaf Updated README to explain installation procedure for OS X and Ubuntu.
authored
36
87cb065 @terryp Adding a basic infection/installation section.
terryp authored
37 ## Infection
38
099817a @assaf Updated README to explain installation procedure for OS X and Ubuntu.
authored
39 To install Zombie.js you need Node.js, NPM, a C++ compiler and Python.
40
ea9ba0b @assaf Updated installation instructions for OS X/Windows
authored
41 On OS X start by installing XCode, or use the [OSX GCC
42 installer](https://github.com/kennethreitz/osx-gcc-installer) (less to
43 download).
44
45 Next, assuming you're using the mighty
099817a @assaf Updated README to explain installation procedure for OS X and Ubuntu.
authored
46 [Homebrew](http://mxcl.github.com/homebrew/):
47
48 $ brew install node
49 $ node --version
1cf9f9d @assaf Updated installation instructions for Ubuntu.
authored
50 v0.6.2
099817a @assaf Updated README to explain installation procedure for OS X and Ubuntu.
authored
51 $ curl http://npmjs.org/install.sh | sudo sh
52 $ npm --version
1cf9f9d @assaf Updated installation instructions for Ubuntu.
authored
53 1.0.106
099817a @assaf Updated README to explain installation procedure for OS X and Ubuntu.
authored
54 $ npm install zombie
55
56 On Ubuntu try these steps:
57
1cf9f9d @assaf Updated installation instructions for Ubuntu.
authored
58 $ sudo apt-get install python-software-properties
59 $ sudo add-apt-repository ppa:chris-lea/node.js
60 $ sudo apt-get update
61 $ sudo apt-get install nodejs nodejs-dev npm
099817a @assaf Updated README to explain installation procedure for OS X and Ubuntu.
authored
62 $ node --version
1cf9f9d @assaf Updated installation instructions for Ubuntu.
authored
63 v0.6.2
099817a @assaf Updated README to explain installation procedure for OS X and Ubuntu.
authored
64 $ npm --version
1cf9f9d @assaf Updated installation instructions for Ubuntu.
authored
65 1.0.106
099817a @assaf Updated README to explain installation procedure for OS X and Ubuntu.
authored
66 $ npm install zombie
67
ea9ba0b @assaf Updated installation instructions for OS X/Windows
authored
68 On Windows you'll need Cygwin to get access to GCC, Python, etc. [Read
69 this](https://github.com/joyent/node/wiki/Building-node.js-on-Cygwin-(Windows))
70 for detailed instructions and troubleshooting.
87cb065 @terryp Adding a basic infection/installation section.
terryp authored
71
f35b8e2 @assaf First documentation you can actually use.
authored
72
2d4a116 @assaf Walking, just walking.
authored
73 ## Walking
f35b8e2 @assaf First documentation you can actually use.
authored
74
2e14582 @assaf Added `querySelector` and `querySelectorAll` based on the [DOM
authored
75 To start off we're going to need a browser. A browser maintains state
76 across requests: history, cookies, HTML 5 local and session stroage. A
77 browser has a main window, and typically a document loaded into that
78 window.
f35b8e2 @assaf First documentation you can actually use.
authored
79
2e14582 @assaf Added `querySelector` and `querySelectorAll` based on the [DOM
authored
80 You can create a new `zombie.Browser` and point it at a document, either
5234ecf @assaf Added documentation for using CSS selectors.
authored
81 by setting the `location` property or calling its `visit` function. As
82 a shortcut, you can just call the `zombie.visit` function with a URL and
2e14582 @assaf Added `querySelector` and `querySelectorAll` based on the [DOM
authored
83 callback.
84
85 The browser will load the document and if the document includes any
86 scripts, also load and execute these scripts. It will then process some
87 events, for example, anything your scripts do on page load. All of
88 that, just like a real browser, happens asynchronously.
89
90 To wait for the page to fully load and all events to fire, you pass
91 `visit` a callback function. This function takes two arguments. If
92 everything is successful (page loaded, events run), the callback is
05dbd1c @assaf Updaded documentation to describe new error handling behavior
authored
93 called with `null` and a reference to the browser.
94
95 Most errors that occur – resource loading and JavaScript execution – are
96 not fatal, so rather the stopping processing, they are collected in
97 `browser.errors`. The error list is passed to the callback as the
98 fourth argument (the third argument is the status code).
2e14582 @assaf Added `querySelector` and `querySelectorAll` based on the [DOM
authored
99
100 If you worked with Node.js before you're familiar with this callback
101 pattern. Every time you see a callback in the Zombie.js API, it works
9778d9e @assaf The `visit`, `clickLink` and `pressButton` methods now pass three
authored
102 that way: the first argument is an error, or null if there is no error.
05dbd1c @assaf Updaded documentation to describe new error handling behavior
authored
103 And if there are no fatal errors, the remaining arguments may hold
104 interesting values.
2e14582 @assaf Added `querySelector` and `querySelectorAll` based on the [DOM
authored
105
106 Whenever you want to wait for all events to be processed, just call
107 `browser.wait` with a callback.
108
43b4c33 @assaf Fixed Web site links to not require .html.
authored
109 Read more [on the Browser API](api)
2decad4 @assaf Moved "the guts" to its own page.
authored
110
2e14582 @assaf Added `querySelector` and `querySelectorAll` based on the [DOM
authored
111
2d55b46 @assaf You can now use `pressButton` with inputs of type button and reset
authored
112 ## Hunting
113
5234ecf @assaf Added documentation for using CSS selectors.
authored
114 There are several ways you can inspect the contents of a document. For
115 starters, there's the [DOM API](http://www.w3.org/DOM/DOMTR), which you
116 can use to find elements and traverse the document tree.
2d55b46 @assaf You can now use `pressButton` with inputs of type button and reset
authored
117
5234ecf @assaf Added documentation for using CSS selectors.
authored
118 You can also use CSS selectors to pick a specific element or node list.
119 Zombie.js implements the [DOM Selector
120 API](http://www.w3.org/TR/selectors-api/). These functions are
121 available from every element, the document, and the `Browser` object
122 itself.
123
124 To get the HTML contents of an element, read its `innerHTML` property.
125 If you want to include the element itself with its attributes, read the
126 element's `outerHTML` property instead. Alternatively, you can call the
127 `browser.html` function with a CSS selector and optional context
128 element. If the function selects multiple elements, it will return the
129 combined HTML of them all.
130
131 To see the textual contents of an element, read its `textContent`
132 property. Alternatively, you can call the `browser.text` function with
133 a CSS selector and optional context element. If the function selects
134 multiple elements, it will return the combined text contents of them
135 all.
136
137 Here are a few examples for checking the contents of a document:
138
139 // Make sure we have an element with the ID brains.
140 assert.ok(browser.querySelector("#brains"));
141
142 // Make sure body has two elements with the class hand.
143 assert.equal(browser.body.querySelectorAll(".hand").length, 2);
144
145 // Check the document title.
146 assert.equal(browser.text("title"), "The Living Dead");
147
148 // Show me the document contents.
149 console.log(browser.html());
150
151 // Show me the contents of the parts table:
152 console.log(browser.html("table.parts"));
153
154 CSS selectors are implemented by Sizzle.js. In addition to CSS 3
155 selectors you get additional and quite useful extensions, such as
156 `:not(selector)`, `[NAME!=VALUE]`, `:contains(TEXT)`, `:first/:last` and
157 so forth. Check out the [Sizzle.js
158 documentation](https://github.com/jeresig/sizzle/wiki) for more details.
2d55b46 @assaf You can now use `pressButton` with inputs of type button and reset
authored
159
43b4c33 @assaf Fixed Web site links to not require .html.
authored
160 Read more [on the Browser API](api) and [CSS
161 selectors](selectors)
2decad4 @assaf Moved "the guts" to its own page.
authored
162
163
2d55b46 @assaf You can now use `pressButton` with inputs of type button and reset
authored
164
165 ## Feeding
166
167 You're going to want to perform some actions, like clicking links,
168 entering text, submitting forms. You can certainly do that using the
169 [DOM API](http://www.w3.org/DOM/DOMTR), or several of the convenience
5234ecf @assaf Added documentation for using CSS selectors.
authored
170 functions we're going to cover next.
2d55b46 @assaf You can now use `pressButton` with inputs of type button and reset
authored
171
172 To click a link on the page, use `clickLink` with selector and callback.
b3f816a @assaf Added documentation for new API methods unselect, selectOption and
authored
173 The first argument can be a CSS selector (see _Hunting_), the `A`
9778d9e @assaf The `visit`, `clickLink` and `pressButton` methods now pass three
authored
174 element, or the text contents of the `A` element you want to click.
175
176 The second argument is a callback, which much like the `visit` callback
177 gets fired after all events are processed, with either an error, or
178 `null`, the browser and the HTTP status code.
2d55b46 @assaf You can now use `pressButton` with inputs of type button and reset
authored
179
180 Let's see that in action:
181
182 // Now go to the shopping cart page and check that we have
183 // three bodies there.
9778d9e @assaf The `visit`, `clickLink` and `pressButton` methods now pass three
authored
184 browser.clickLink("View Cart", function(err, browser, status) {
2d55b46 @assaf You can now use `pressButton` with inputs of type button and reset
authored
185 assert.equal(browser.querySelectorAll("#cart .body"), 3);
186 });
187
188 To submit a form, use `pressButton`. The first argument can be a CSS
b3f816a @assaf Added documentation for new API methods unselect, selectOption and
authored
189 selector, the button/input element. the button name (the value of the
190 `name` argument) or the text that shows on the button. You can press
191 any `BUTTON` element or `INPUT` of type `submit`, `reset` or `button`.
192 The second argument is a callback, just like `clickLink`.
2d55b46 @assaf You can now use `pressButton` with inputs of type button and reset
authored
193
194 Of course, before submitting a form, you'll need to fill it with values.
195 For text fields, use the `fill` function, which takes two arguments:
196 selector and the field value. This time the selector can be a CSS
b3f816a @assaf Added documentation for new API methods unselect, selectOption and
authored
197 selector, the input element, the field name (its `name` attribute), or
198 the text that shows on the label associated with that field.
2d55b46 @assaf You can now use `pressButton` with inputs of type button and reset
authored
199
200 Zombie.js supports text fields, password fields, text areas, and also
201 the new HTML 5 fields types like email, search and url.
202
203 The `fill` function returns a reference to the browser, so you can chain
204 several functions together. Its sibling functions `check` and `uncheck`
205 (for check boxes), `choose` (for radio buttons) and `select` (for drop
206 downs) work the same way.
207
208 Let's combine all of that into one example:
209
210 // Fill in the form and submit.
211 browser.
212 fill("Your Name", "Arm Biter").
213 fill("Profession", "Living dead").
d96f211 @geophree Correct some typos.
geophree authored
214 select("Born", "1968").
2d55b46 @assaf You can now use `pressButton` with inputs of type button and reset
authored
215 uncheck("Send me the newsletter").
9778d9e @assaf The `visit`, `clickLink` and `pressButton` methods now pass three
authored
216 pressButton("Sign me up", function(err, browser, status) {
2d55b46 @assaf You can now use `pressButton` with inputs of type button and reset
authored
217 // Make sure we got redirected to thank you page.
218 assert.equal(browser.location, "http://localhost:3003/thankyou");
219 });
220
43b4c33 @assaf Fixed Web site links to not require .html.
authored
221 Read more [on the Browser API](api)
2decad4 @assaf Moved "the guts" to its own page.
authored
222
2d55b46 @assaf You can now use `pressButton` with inputs of type button and reset
authored
223
fc74a5a @assaf Added list of supported features.
authored
224 ## Readiness
225
226 Zombie.js supports the following:
227
19a9ffb @assaf Updated README with new feature.
authored
228 - HTML5 parsing and dealing with tag soups
fc74a5a @assaf Added list of supported features.
authored
229 - [DOM Level 3](http://www.w3.org/DOM/DOMTR) implementation
230 - HTML5 form fields (`search`, `url`, etc)
d96f211 @geophree Correct some typos.
geophree authored
231 - CSS3 Selectors with [some extensions](http://sizzlejs.com/)
fc74a5a @assaf Added list of supported features.
authored
232 - Cookies and [Web Storage](http://dev.w3.org/html5/webstorage/)
19a9ffb @assaf Updated README with new feature.
authored
233 - `XMLHttpRequest` in all its glory
fc74a5a @assaf Added list of supported features.
authored
234 - `setTimeout`/`setInterval` and messing with the system clock
19a9ffb @assaf Updated README with new feature.
authored
235 - `pushState`, `popstate` and `hashchange` events
236 - Scripts that use `document.write`
444f095 @assaf Added IRC reference in documentation/site.
authored
237 - `alert`, `confirm` and `prompt`
fc74a5a @assaf Added list of supported features.
authored
238
239
b3de181 @assaf Added links to related projects.
authored
240 ## In The Family
241
242 **[capybara-zombie](https://github.com/plataformatec/capybara-zombie)** -- Capybara driver for zombie.js running on top of node.
243
244 **[zombie-jasmine-spike](https://github.com/mileskin/zombie-jasmine-spike)** -- Spike project for trying out Zombie.js with Jasmine
245
fb3375b @assaf Upgraded to JSDOM 0.2.4
authored
246 **[Vows BDD](https://github.com/jmreidy/vows-bdd)** -- A BDD wrapper for Vows, allowing for easy writing of tests in a given-when-then format
247
248 **[Mink](https://github.com/Behat/Mink)** -- PHP 5.3 acceptance test framework for web applications
249
b3de181 @assaf Added links to related projects.
authored
250
88d2364 @assaf Browser now has a property called `debug` that you can set to
authored
251 ## Reporting Glitches
252
253 **Step 1:** Run Zombie with debugging turned on, the trace will help
254 figure out what it's doing. For example:
255
256 var browser = new zombie.Browser({ debug: true });
9778d9e @assaf The `visit`, `clickLink` and `pressButton` methods now pass three
authored
257 browser.visit("http://thedead", function(err, browser, status) {
88d2364 @assaf Browser now has a property called `debug` that you can set to
authored
258 if (err)
259 throw(err.message);
2d291fe @djanowski Whitespace.
djanowski authored
260 ...
88d2364 @assaf Browser now has a property called `debug` that you can set to
authored
261 });
262
263 **Step 2:** Wait for it to finish processing, then dump the current
264 browser state:
265
266 brower.dump();
267
268 **Step 3:** If publicly available, include the URL of the page you're
269 trying to access. Even better, provide a test script I can run from the
270 Node.js console (similar to step 1 above).
271
43b4c33 @assaf Fixed Web site links to not require .html.
authored
272 Read more [about troubleshooting](troubleshoot)
2f9b7ee @assaf First NPM release.
authored
273
274
2d55b46 @assaf You can now use `pressButton` with inputs of type button and reset
authored
275 ## Giving Back
f050f19 @assaf Fixed loading to keep track of outstanding requests, so waiting
authored
276
444f095 @assaf Added IRC reference in documentation/site.
authored
277
2f9b7ee @assaf First NPM release.
authored
278 * Find [assaf/zombie on Github](http://github.com/assaf/zombie)
279 * Fork the project
280 * Add tests
281 * Make your changes
282 * Send a pull request
41ee2f2 @assaf Fixed test suite so vows command just works.
authored
283
43b4c33 @assaf Fixed Web site links to not require .html.
authored
284 Read more [about the guts of Zombie.js](guts) and check out the
285 outstanding [to-dos](todo).
41ee2f2 @assaf Fixed test suite so vows command just works.
authored
286
d8b8b26 @assaf Change from mailing list to Google Group:
authored
287 Follow announcements, ask questions on [the Google
288 Group](https://groups.google.com/forum/?hl=en#!forum/zombie-js)
d39328f @assaf Added link to mailing list.
authored
289
e2682e9 @assaf Added link to web-based IRC.
authored
290 Get help on IRC: join [zombie.js on
d8b8b26 @assaf Change from mailing list to Google Group:
authored
291 Freenode](irc://irc.freenode.net/zombie.js) or [web-based
292 IRC](http://webchat.freenode.net/?channels=zombie-js)
444f095 @assaf Added IRC reference in documentation/site.
authored
293
41ee2f2 @assaf Fixed test suite so vows command just works.
authored
294
f35b8e2 @assaf First documentation you can actually use.
authored
295 ## Brains
41ee2f2 @assaf Fixed test suite so vows command just works.
authored
296
2decad4 @assaf Moved "the guts" to its own page.
authored
297 Zombie.js is copyright of [Assaf Arkin](http://labnotes.org), released
71ad9f8 @assaf Added magical zombie girl and PDF.
authored
298 under the MIT License
d6803cc @assaf Starting to work on documentation
authored
299
ae07a36 @assaf Listing collaborators in README.
authored
300 Blood, sweat and tears of joy:
301
302 [Damian Janowski aka djanowski](https://github.com/djanowski)
303
304 [José Valim aka josevalim](http://blog.plataformatec.com.br/)
305
306 [Bob Lail boblail](http://boblail.tumblr.com/)
307
308 And all the fine people mentioned in [the changelog](changelog).
8750a5e @assaf Added credits linking to Github contribution page.
authored
309
2f9b7ee @assaf First NPM release.
authored
310 Zombie.js is written in
311 [CoffeeScript](http://jashkenas.github.com/coffee-script/) for
71ad9f8 @assaf Added magical zombie girl and PDF.
authored
312 [Node.js](http://nodejs.org/)
3c40783 @assaf Added browser/window.select using Sizzle.js.
authored
313
71ad9f8 @assaf Added magical zombie girl and PDF.
authored
314 DOM emulation by Elijah Insua's [JSDOM](http://jsdom.org/)
2decad4 @assaf Moved "the guts" to its own page.
authored
315
71ad9f8 @assaf Added magical zombie girl and PDF.
authored
316 HTML5 parsing by Aria Stewart's [HTML5](https://github.com/aredridel/html5)
2decad4 @assaf Moved "the guts" to its own page.
authored
317
71ad9f8 @assaf Added magical zombie girl and PDF.
authored
318 CSS selectors by John Resig's [Sizzle.js](http://sizzlejs.com/)
319
d7275cc @assaf Add documentation for browser.css and browser.xpath.
authored
320 XPath support using Google's [AJAXSLT](http://code.google.com/p/ajaxslt/)
321
71ad9f8 @assaf Added magical zombie girl and PDF.
authored
322 Magical Zombie Girl by [Toho Scope](http://www.flickr.com/people/tohoscope/)
f35b8e2 @assaf First documentation you can actually use.
authored
323
324
325 ## See Also
326
d7bfa7d @hellp Typo
hellp authored
327 **zombie-api**(7), **zombie-troubleshoot**(7), **zombie-selectors**(7), **zombie-changelog**(7), **zombie-todo**(7)
Something went wrong with that request. Please try again.