A quick introduction to the main components required for automated JavaScript testing will help you understand what is required and how things interoperate so you can get started testing. Intern includes the WD.js NodeJS WebDriver client API, the Chai assertion library and Istanbul for code coverage analysis. You will also likely want Selenium's WebDriver server and/or ChromeDriver.

WebDriver is a W3C specification for a RESTful JSON-encoded API for controlling a web browser remotely (that is, creating UI actions that would otherwise be done manually with a mouse and/or keyboard). For browsers that do not implement this natively (all of them as of Jan 2014) a driver is required, e.g. ChromeDriver. The driver listens for RESTful API calls over HTTP and launches & controls a web browser instance. Selenium server can control multiple browser-specific WebDriver implementations. Intern is designed to interact with Selenium server in order to test in multiple browsers, but during test development it is sufficient to work in Chrome with ChromeDriver.

Chai is an assertion library that provides numerous convenience methods (isTrue, isFalse, include, deepEqual, etc) for evaluating test-case conditions. A failed assertion will throw an error which will be interpreted by Intern as a failed test.

Code coverage is a measure of how many lines of your application code are run during testing. With Istanbul you can get a good measure of how comprehensively your test cases are exercising your application code.

Be sure to read the Quick start and Running Intern. Writing tests is covered by the tutorial and writing tests wiki pages. To run your tests locally, you'll need a WebDriver and NodeJS.

1. Install NodeJS
2. Install Intern
   1. npm install intern
   2. (Looking at the sample file structure below, you would run this command in the myProject folder)
3. Download and extract ChromeDriver
4. Launch ChromeDriver (configured to use the same port and URL Intern expects):
   1. chromedriver --port=4444 --url-base=wd/hub
5. Set useSauceConnect to false in your Intern config
6. Launch Intern to run your tests:
   1. node node_modules/intern/runner config=path/to/your/intern/config
   2. For example, given the following file structure:

myProject/
            dojo/
            node_modules/
                intern/
            myPackage/
                test/
                    intern.js (Intern configuration module)

1. From the `myProject` folder you would run:
    * `node node_modules/intern/runner config=myPackage/test/intern`

1. This should launch a new instance of Chrome and run the tests specified in your Intern config

Keep in mind that JavaScript code is running in two separate environments: your test suites are run in NodeJS, while the page loaded by functional tests runs in a web browser. Debugging code on the test page should be done prior to testing time by opening it directly and using the browser's debugging tools. Debugging your test suite is a little tricky, but can be done with node-inspector.

1. npm install -g node-inspector
2. Your test modules are loaded dynamically by Intern, so they will likely not show up in the debugger's file list. In order to set a break point you will need to add a debugger statement in your test code.
3. Launch NodeJS with debugging enabled, set to pause on the first line of code:
   • node --debug-brk node_modules/intern/runner config=myPackage/test/intern
4. Open Chrome (must be Chrome as node-inspector leverages Chrome's developer tools) to:
   • http://127.0.0.1:8080/debug?port=5858
5. Hit F8 to continue code execution until your debugger statement

(This is currently (Jan 2014) broken in Selenium's Firefox Webdriver)

The WD.js implementation of the WebDriver API is pretty extensively documented. To send a Shift+Click to the browser you need to use the keys command along with Unicode key codes (included in WD.js):

require([
    'intern!object',
    'chai!assert',
    'dojo/node!wd/lib/special-keys'
], function (registerSuite, assert, specialKeys) {
    registerSuite({
        name: 'test',
        'test1': function () {
            var remote = this.remote();
            remote.get('testpage.html');
            remote.elementById('testLink');
            remote.keys(specialKeys.Shift);
            remote.clickElement();
            remote.keys(specialKeys.NULL);
            return remote.end();
        }
    });
});

After the tests are done the browser is closed. This makes sense and is ideal for running automated tests but can be a hassle during test development when you want to inspect the page to make adjustments or troubleshoot the cause of a failure. One hack for getting the browser to stay open is to edit out the call to remote.quit() in runner.js: https://github.com/theintern/intern/blob/master/runner.js#L218 For example, this should work: return topic.publish('/session/end', remote); The NodeJS session remains active until you manually close the browser.

Once you've developed your tests and are happy with them, you may want to do additional local testing before using a remote testing service like Sauce Labs. In your Intern config you can change the browserName value in environments, or you can specify multiple browsers:

{
    environments: [
        { browserName: 'chrome' },
        { browserName: 'firefox' },
        { browserName: 'internet explorer' },
        { browserName: 'safari' }
    ]
}

Selenium server includes drivers for Firefox and Safari. For Chrome and IE you need to download the individual drivers (Chrome, IE) and add the executable to your PATH. The Selenium wiki includes documentation for each driver.

1. Download Selenium server (the standalone .jar)
2. Launch Selenium server: java -jar selenium-server-standalone-2.39.0.jar
3. Run your Intern tests: node node_modules\intern\runner config=myPackage/test/intern

If your tests results in a NodeJS stacktrace leading with the message: Error: Error response status: XX you can see the list of error codes documented in the JsonWireProtocol wiki under Response Status Codes

(The correct direct URL [before being mangled by GitHub] is:)

https://code.google.com/p/selenium/wiki/JsonWireProtocol#Response_Status_Codes