Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

A Node.js test harness for writing client side javascript tests and automating test runs with a headless browser.

branch: master

Fetching latest commit…

Octocat-spinner-32-eaf2f5

Cannot retrieve the latest commit at this time

Octocat-spinner-32 bin
Octocat-spinner-32 examples
Octocat-spinner-32 jasmine
Octocat-spinner-32 lib
Octocat-spinner-32 qunit
Octocat-spinner-32 specs
Octocat-spinner-32 .gitignore
Octocat-spinner-32 LICENSE
Octocat-spinner-32 README.md updated package.json to require node 0.4, and updated readme for clar… March 21, 2012
Octocat-spinner-32 TODO
Octocat-spinner-32 package.json
README.md

Ichabod - A Node.js Automated Testharness for Client Side Javascript

Writing tests for client side javascript isn't that hard, tools like Jasmine or qunit make it pretty easy. What's hard is getting those tests automated and running in a continuous build server (like Jenkins).

Ichabod takes care of running your entire test suite in a headless (or remote) browser instance and collecting the test results, which go to both the console and the build server.

The included example projects show how to use Jasmine or qunit to write your tests, and includes a custom reporter that outputs JUnit XML for continuous integration systems to ingest.

It also supports require.js, so you can easily test your AMD modules.

Install

npm install -g ichabod

The Config File

To use Ichabod as a test runner you need to provide it a config file so that it knows where your test directory is and what tests to run. The file is written in json format. A simple example:

{
    "srcDir": "./src",
    "testDir": "./test",
    "reportsDir": "./reports",
    "sources": [
        "https://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js",
        "*.js"
    ],
    "tests": [
        "*Spec.js"
    ]
}
  • srcDir: (required) the root of your src directory, will be available at the doc root via the static server.
  • testDir: (required) the root of your test directory, will be available at the doc root via the static server.
  • reportsDir: (required) the directory where the test output will be written to. If it doesn't exist it will be created.
  • sources: (required) an array that contains all source files to include. It is assumed they are relative to the 'srcDir'. You can also include references to 3rd party libs hosted on external CDNs (ex: jQuery via Google CDN).
  • tests: (required) an array that contains all the test pages to run. It is assumed they are relative to the 'testDir'.
  • runner: (optional) either "zombie" or "selenium". Zombie.js is the headless DOM, where as selenium is Selenium RC. It is expected you'll have Selenium Server running as well. Defaults to using Zombie.js.
  • browser: (optional) only used if you want to use selenium. Takes any valid selenium browser string. Defaults to "firefox".
  • requirejs: (options) set this to true and require.js will be used. removes the need to provide any sources.

Paths relative to the config file (recommended) will be expanded out to absolute paths at runtime.

Test file strings can be glob expressions and will be expanded out at runtime.

Running

The Ichabod source comes with an example project, feel free to use it as a base template to get started.

When Developing Tests

Ichabod can be used as a basic webserver to develop your tests.

ichabod -c <path-to-config> -m serve

... and then point your web browser to:

http://localhost:8000/specrunner.html

Automated Runs

To do an automated run of your entire test suite use the following command:

ichabod -c <path-to-your-config-file>

You should then see output on the command line:

Basic Suite: 2 of 2 passed.
Another Suite: 1 of 1 passed.

Final Summary: 
3 passed, 0 failed, 3 total.

Using the -r and -b command line args you can also run the tests via selenium, which can be useful to do cross browser testing and verify that your tests run correctly in a real browser environment.

ichabod -c <path/to/ichabod.conf> -r selenium -b safari

Customizing

The included bin/ichabod script wraps both a static server and the ichabod runner. This assumes your tests are isolated and have no server dependencies. If you have a more complex setup, such as back end components and live ajax calls, there are a few approaches:

  1. Mock out your external dependencies (see: Jasmine Spies) and get your client side javascript running in a self contained environment that just requires a functioning DOM. Your tests will run faster and be less brittle.

  2. If you're already using Node.js for your project, then just modify the bin/ichabod script as needed to start your app server and pass the host:port to the Runner.

  3. If you have a non-Node.js application stack, then start your app server, and use the bin/ichabod script as a template to write your own script and invoke the Runner with the host:port to your app server.

Known Issues

Since Ichabod uses Zombie.js as its headless browser, it will be missing any browser freatures that Zombie.js is currently missing. Fortunately Zombie.js continues to improve, and I've found it comparable to HtmlUnit. If this is a limiting factor for you, I highly recommend using the selenium runner instead.

Currently qunit tests seem to have issues running reliably in zombie.js, the selenium runner does not have these limitations.

Currently Ichabod is geared towards a single server environment, and assumes things like Selenium Server are running on the same host. It is planned to bake in remote server support as well as support for Selenium Grid.

Why Ichabod?

Ichabod Crane was a character from The Legend of Sleepy Hollow, who ran from the Headless Horseman. Get it?

Something went wrong with that request. Please try again.