Insanely fast, full-stack, headless browser testing using node.js
Insanely fast, full-stack, headless browser testing using node.js
If you're going to write an insanely fast, headless browser, how can you not call it Zombie? Zombie it is.
Zombie.js is a lightweight framework for testing client-side JavaScript code in a simulated environment. No browser required.
Let's try to sign up to a page and see what happens:
…
This example uses the Mocha testing framework, but Zombie will work with other testing frameworks. Since Mocha supports promises, we can also write the test like this:
…
Well, that was easy.
WARNING: Crawling untrusted web pages with Zombie.js is not safe.
To install Zombie.js you will need Node.js:
$ npm install zombie --save-dev
Methods for making assertions against the browser, such as
browser.assert.element('.foo').
See Assertions for detailed discussion.
You can use this to set the HTTP Referer header.
Access to history of retrieved resources. See Resources for detailed discussion.
Access to the pipeline for making requests and processing responses. Use this
to add new request/response handlers the pipeline for a single browser instance,
or use Pipeline.addHandler to modify all instances. See
Pipeline.
Array of all open tabs (windows). Allows you to operate on more than one open window at a time.
See Tabs for detailed discussion.
The proxy option takes a URL so you can tell Zombie what protocol, host and
port to use. Also supports Basic authentication, e.g.:
browser.proxy = 'http://me:secret@myproxy:8080'
Attaches a file to the specified input field. The second argument is the file name. callback - called with error or nothing.
Navigate to the previous page in history. Returns the zombie.browser.Browser to allow function chaining.
Returns a zombie.dom.DOMNode representing the body element of the current document.
Checks a checkbox. If called without a callback, returns a promise.
selects a radio box option. If called without a callback, returns a promise.
Clicks on a link. Clicking on a link can trigger other events, load new page, etc. Use a callback to be notified of completion. Finds link by text content or selector.
Dump information to the console: Zombie version, current URL, history, cookies, event loop,
etc. Useful for debugging and submitting error reports. output defaults to
process.stdout.
Evaluates a JavaScript expression in the context of the current window and returns the result. When evaluating external script, also include filename.
You can also use this to evaluate a function in the context of the window: for timers and asynchronous callbacks (e.g. XHR).
Find and return an input field (INPUT, TEXTAREA or SELECT) based on a CSS selector,
field name (its name attribute) or the text value of a label associated with that field
(case sensitive, but ignores leading/trailing spaces).
Fill in an input field or text area with the provided value. If called without a callback, returns a promise.
Fire a DOM event. You can use this to simulate a DOM event, e.g. clicking
a link. These events will bubble up and can be cancelled. Like wait
this method takes an optional callback. If called without a callback, returns a promise.
Finds and returns a link by its text content or selector.
Loads the HTML, processes events and calls the callback. Without a callback, returns a promise.
Return the location of the current document (same as window.location).
Press a button (button element or input of type submit). Typically this will submit the
form. Use the callback to wait for the from submission, page to load and all events run
their course.
Evaluates the CSS selector against the document (or context node) and return an element.context defaults to document.
Evaluates the CSS selector against the document (or context node) and return array of nodes.
context defaults to document.
Selects the first matching element and returns it.
Returns True if the page request followed a redirect.
Reloads the current page. Returns the zombie.browser.Browser to allow function chaining.
Selects an option inside of selector with given value. If called without a callback,
returns a promise.
Selects an option.
Returns the status code returned for this window (200, 303, etc). The same as
browser.statusCode
Return true if last response had status code 200 .. 299
Returns the text contents of the selected elements. context defaults to document.
Unchecks a checkbox. If called without a callback, returns a promise.
Unselects an option. If called without a callback, returns a promise.
Unselects the an option. If called without a callback, returns a promise.
Loads document from the specified URL, processes events and calls the callback, or returns a promise.
Click on the selected element. If called without callback, returns a promise.
Collection of errors accumulated by the browser while loading page and executing scripts.
Returns a string of the source HTML from the last response.
Returns a string of HTML for a selected HTML element. If argument element is undefined,
the function returns a string of the source HTML from the last response.
Example uses:
browser.html('div');
browser.html('div#contain');
browser.html('.selector');
browser.html();
Allows you to make requests against a named domain and HTTP/S port, and will route it to the test server running on localhost and unprivileged port.
For example, if you want to call your application "example.com", and redirect traffic from port 80 to the test server that's listening on port 3000, you can do this:
Browser.localhost('example.com', 3000)
browser.visit('/path', function() {
console.log(browser.location.href);
});
=> 'http://example.com/path'
The first time you call Browser.localhost, if you didn't specify
Browser.site, it will set it to the hostname (in the above example,
"example.com"). Whenever you call browser.visit with a relative URL, it
appends it to Browser.site, so you don't need to repeat the full URL in every
test case.
You can use wildcards to map domains and all hosts within these domains, and you can specify the source port to map protocols other than HTTP. For example:
// HTTP requests for example.test www.example.test will be answered by localhost
// server running on port 3000
Browser.localhost('*.example.test', 3000);
// HTTPS requests will be answered by localhost server running on port 3001
Browser.localhost('*.example.test:443', 3001);
The underlying implementation hacks net.Socket.connect, so it will route any
TCP connection made by the Node application, whether Zombie or any other
library. It does not affect other processes running on your machine.
You can use this to customize new browser instances for your specific needs. The extension function is called for every new browser instance, and can change properties, bind methods, register event listeners, etc.
Browser.extend(function(browser) {
browser.on('console', function(level, message) {
logger.log(message);
});
browser.on('log', function(level, message) {
logger.log(message);
});
});
To make life easier, Zombie introduces a set of convenience assertions that you can access directly from the browser object. For example, to check that a page loaded successfully:
browser.assert.success();
browser.assert.text('title', 'My Awesome Site');
browser.assert.element('#main');
These assertions are available from the browser object since they operate on a
particular browser instance -- generally dependent on the currently open window,
or document loaded in that window.
Many assertions require an element/elements as the first argument, for example,
to compare the text content (assert.text), or attribute value
(assert.attribute). You can pass one of the following values:
Many assertions take an expected value and compare it against the actual value.
For example, assert.text compares the expected value against the text contents
of one or more strings. The expected value can be one of:
undefined or null are used to assert the lack of valueassert.deepEqualNote that in some cases the DOM specification indicates that lack of value is an
empty string, not null/undefined.
All assertions take an optional last argument that is the message to show if the assertion fails. Better yet, use a testing framework like Mocha that has good diff support and don't worry about these messages.
The following assertions are available:
Asserts the named attribute of the selected element(s) has the expected value.
Fails if no element found.
browser.assert.attribute('form', 'method', 'post');
browser.assert.attribute('form', 'action', '/customer/new');
// Disabled with no attribute value, i.e. <button disabled>
browser.assert.attribute('button', 'disabled', '');
// No disabled attribute i.e. <button>
browser.assert.attribute('button', 'disabled', null);
Asserts that selected element(s) has that and only that class name. May also be space-separated list of class names.
Fails if no element found.
browser.assert.className('form input[name=email]', 'has-error');
Asserts that a cookie exists and has the expected value, or if expected is
null, that no such cookie exists.
The identifier is either the name of a cookie, or an object with the property
name and the optional properties domain and path.
browser.assert.cookie('flash', 'Missing email address');
Asserts that on
No open issues yet, or sync has not completed.