Zombie.js

Insanely fast, headless full-stack testing using Node.js

The Bite

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:

const Browser = require('zombie');

// We're going to make requests to http://example.com/signup
// Which will be routed to our test server localhost:3000
Browser.localhost('example.com', 3000);

describe('User visits signup page', function() {

  const browser = new Browser();

  before(function(done) {
    browser.visit('/signup', done);
  });

  describe('submits form', function() {

    before(function(done) {
      browser.fill('email', 'zombie@underworld.dead')
      .then(() => browser.fill('password', 'eat-the-living'))
      .then(() => browser.pressButton('Sign Me Up!', done));
    });

    it('should be successful', function() {
      browser.assert.success();
    });

    it('should see welcome page', function() {
      browser.assert.text('title', 'Welcome To Brains Depot');
    });
  });
});

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:

const Browser = require('zombie');

// We're going to make requests to http://example.com/signup
// Which will be routed to our test server localhost:3000
Browser.localhost('example.com', 3000);

describe('User visits signup page', function() {

  const browser = new Browser();

  before(function() {
    return browser.visit('/signup');
  });

  describe('submits form', function() {

    before(function() {
      return browser.fill('email', 'zombie@underworld.dead')
      .then(() => browser.fill('password', 'eat-the-living'))
      .then(() => browser.pressButton('Sign Me Up!'));
    });

    it('should be successful', function() {
      browser.assert.success();
    });

    it('should see welcome page', function() {
      browser.assert.text('title', 'Welcome To Brains Depot');
    });
  });

});

Well, that was easy.

WARNING: Crawling untrusted web pages with Zombie.js is not safe.

Installing
Browser
Assertions
Cookies
Tabs
Debugging
Events
Resources
Pipeline

Installing

To install Zombie.js you will need Node.js:

$ npm install zombie --save-dev

Browser

browser.assert

Methods for making assertions against the browser, such as browser.assert.element('.foo').

See Assertions for detailed discussion.

browser.referer

You can use this to set the HTTP Referer header.

browser.resources

Access to history of retrieved resources. See Resources for detailed discussion.

browser.pipeline

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.

browser.tabs

Array of all open tabs (windows). Allows you to operate on more than one open window at a time.

See Tabs for detailed discussion.

browser.proxy

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'

browser.attach(selection, filename, callback)

Attaches a file to the specified input field. The second argument is the file name. callback - called with error or nothing.

browser.back([callback])

Navigate to the previous page in history. Returns the zombie.browser.Browser to allow function chaining.

browser.body

Returns a zombie.dom.DOMNode representing the body element of the current document.

browser.check(selector, [callback])

Checks a checkbox. If called without a callback, returns a promise.

browser.choose(selector, [callback])

selects a radio box option. If called without a callback, returns a promise.

browser.clickLink(selector, callback)

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.

browser.dump([output])

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.

browser.evaluate(code, filename)

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).

browser.field(selector)

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).

browser.fill(selector, value, [callback])

Fill in an input field or text area with the provided value. If called without a callback, returns a promise.

browser.fire(selector, eventName, [callback])

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.

browser.link(selector)

Finds and returns a link by its text content or selector.

browser.load(html, [callback])

Loads the HTML, processes events and calls the callback. Without a callback, returns a promise.

browser.location

Return the location of the current document (same as window.location).

browser.pressButton(selector, [callback])

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.

browser.query(selector, [context])

Evaluates the CSS selector against the document (or context node) and return an element.
context defaults to document.

browser.queryAll(selector, [context])

Evaluates the CSS selector against the document (or context node) and return array of nodes. context defaults to document.

browser.querySelector(selector)

Selects the first matching element and returns it.

browser.redirected

Returns True if the page request followed a redirect.

browser.reload()

Reloads the current page. Returns the zombie.browser.Browser to allow function chaining.

browser.select(selector, value, [callback])

Selects an option inside of selector with given value. If called without a callback, returns a promise.

browser.selectOption(selector, [callback])

Selects an option.

browser.status

Returns the status code returned for this window (200, 303, etc). The same as browser.statusCode

browser.success

Return true if last response had status code 200 .. 299

browser.text(selector, [context])

Returns the text contents of the selected elements. context defaults to document.

browser.uncheck(selector, [callback])

Unchecks a checkbox. If called without a callback, returns a promise.

browser.unselect(selector, value, [callback])

Unselects an option. If called without a callback, returns a promise.

browser.unselectOption(selector, [callback])

Unselects the an option. If called without a callback, returns a promise.

browser.visit(url, options, [callback])

Loads document from the specified URL, processes events and calls the callback, or returns a promise.

browser.click(selector, [callback])

Click on the selected element. If called without callback, returns a promise.

browser.errors

Collection of errors accumulated by the browser while loading page and executing scripts.

browser.source

Returns a string of the source HTML from the last response.

browser.html(element)

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();

Browser.localhost(host, port)

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,

Zombie

Install / Use

README