ichabod

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

Writing tests for client side javascript isn't that hard, tools like Jasmine 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 outputting the test results to the terminal for the user, and to disk for the build server.

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

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

Install

npm install 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:

{
    "testDir": ".",
    "reportsDir": "./reports",
    "sources": [
        "https://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js"
    ],
    "tests": [
        "*Spec.js"
    ]
}

• testDir: (required) the root of your test directory, and will be used as the doc root by static server.
• reportsDir: (required) the directory where the test output will be written to. If it doesn't exist it will be created.
• 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: 1 of 2 failed. :(
Another Suite: :)

Final Summary: 
2 passed, 1 failed, 3 total.

If you get all smiles, then celebrate, you have a passing test suite!

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 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 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?