Client tests

Orion's client tests are written in JavaScript using the mocha test framework. Assertions are provided by chai. The tests run in a web browser. This section explains how Orion developers should write unit tests.

Organizing tests

Every source bundle in the Orion client repo (that is, every child folder of bundles/) should have exactly 1 test page. This makes it easy for developers to run all the bundle's tests in one shot.

Tests should be divided into files organized by functional components. Each component gets a separate file.

Running tests

To run the tests for a bundle, simply load its test page file in a web browser.

For example, the test page for the Web Tools bundle is webtoolsMochaTests.html. Therefore, to run the tests for the Web Tools bundle, you would navigate to http://[some_orion_server]/js-tests/webtools/webtoolsMochaTests.html.

Running self-hosted tests

Another method of running the tests (and the way that most committers run them) is to view them on a self-hosted site.

The steps are:

Create a self-hosting site. This can be done using the Sites button on the left navigation bar. Once on the sites page, press the Create button at the top, give your site a cool name, and hit submit.

The next page you are taken to is the site content page. Here you want to press the Convert to self-hosting button at the top. In the resulting dialog, you need to navigate to the org.eclipse.orion.client repository root (assuming you have cloned the repository in your workspace), and hit ok. Once this is done, you should see a bunch of paths added to you site. Now click the Editor button on the left navigation bar.

Now that your site is ready, you can navigate to any of the test files mentioned in this file, and finding the one you want, select it in the file navigator, open the context menu, select Open Related and then View on Site.

Now select the new site you created previously, click add and then view. This will navigate you to the site running the file you selected, which will run mocha and the tests.

Once you have the test suite running, you can open the developer tools for your browser and debug failing tests, or suspend and step through tests to confirm they work as expected.

Running the Tests Locally for Sauce

If you want to run the tests on your local machine and have them talk to sauce labs, you will need to do the following:

Writing tests

To create a test file for a component, start with this skeleton and add more tests as necessary:

// js-tests/foo/myNewTestFile.js

define([

"chai/chai",

"mocha/mocha",

],function(chai){

var assert = chai.assert;

describe("component X",function(){

it("should do Y",function(){

assert.equal(1,1,"Hopefully 1 == 1");

});

it("should do Z",function(){

// Make more assertions here

});

});

});

When you have a lot of tests, use nested describe()s to create a logical hierarchy among them.

Promises in tests

If your component performs asynchronous operations using promises, you may find it convenient to return a promise from the it() function, and use the promise's resolve() to pass or reject() to fail the test. This offers a cleaner alternative to mocha's done() callback when several async steps are involved. If your test rejects, it should provide an instance of Error as the value. Never call reject(null) or reject(undefined), or Mocha will count it as a pass!

// js-tests/foo/myNewTestFile.js

define([

"chai/chai",

"orion/Deferred",

"mocha/mocha",

],function(chai, Deferred){

it("should do Y asynchronously with a promise",function(){

var deferred =new Deferred();

setTimeout(function(){

deferred.reject(new Error("This test should fail"));

},0);

return deferred;

});

});

Adding to the bundle's test page

After creating a new test file, you must add it to the parent bundle's test page. To do this, simply edit the test page and add a dependency in the require([ .. ]) that goes around the mocha.run() call:

require(['mocha/sauce'],function(mocha){

mocha.setup('bdd');

require([

'js-tests/javascript/astManagerTests',

'js-tests/javascript/contentAssistTests',

'js-tests/javascript/finderTests',

'js-tests/javascript/occurrencesTests',

'js-tests/foo/myNewTestFile',

],function(){

mocha.run();

});

});

Reload the test page in a web browser, and your tests will be executed!

Writing a new bundle's test page

If you find yourself creating an entirely new bundle, then you'll have to create a test page for it. Start with this skeleton, and change as needed (pay close attention to the relative paths, in particular).

<!DOCTYPE html>

<html>

<head>

<title>My New Bundle Tests</title>

<link rel="stylesheet" href="../../mocha/mocha.css"/>

<script src="../../requirejs/require.js"></script>

<script>

/*jslint amd:true*/

require({

baseUrl:"../../"

});

require(["mocha/sauce"],function(mochaSauce){

mochaSauce.setup("bdd");

require([

/* List this bundle's test files here as dependencies */

],function(){

mochaSauce.run();

});

});

</script>

</head>

<body>

<h3>My New Bundle Tests</h3>

<div id="mocha"></div>

</body>

</html>

Note that we use the exports of mocha/sauce instead of the regular mocha global: this is necessary for build-time test integration. See Integrating tests with the build for more details.

Integrating tests with the build

To run a bundle's tests in the Orion nightly build, you must perform the following steps:

To verify this, load the test page in a browser. You should see some XML looking like <testcase name="whatever"… printed to the developer console: this means your test is correctly Sauce-enabled. If you don't see a pile of XML, then your test page is wrong and will break the build.

Open the package.json file and add your test page's URL to the urls array.

For details about the build-time unit test architecture, see Releng Builds.

Node.js Server Tests

Our Node server unit tests are written against the Mocha test framework, and run under Node.js. Developers are expected to run these tests before releasing changes to the server, and before publishing the minified orion package to npm.

Running the tests

From the org.eclipse.orion.client/modules/orionode directory, just run the command:

npm test

This will invoke Mocha and produce console output showing which tests passed and failed.

If you want to pass custom arguments to Mocha, you'll need to invoke it explicitly like this:

./node_modules/mocha/bin/mocha [debug] [options] [files]

To make this easier, you can install Mocha as a global npm package (npm install mocha -g), and then invoke it as simply mocha from a command shell.

Writing more tests

When you're prototyping a new feature, writing unit tests for it is always a good idea. Here's how to write a test:

Create a new file my_tests.js in the org.eclipse.orion.client/modules/orionode/test/ directory.

Write your tests in the file. Here are two resources to help you get started: