This guide will show you how to configure testling-ci to run the tests for a simple reusable module.

write the code

First we'll need some code to test.

Let's build a simple module to compute the maximum value given some comparison function. We'll call it max-by.

Make a new directory called max-by and initialize git:

$ mkdir max-by
$ cd max-by
$ git init

Now we'll write an index.js:

module.exports = function (xs, f) {
    return xs.reduce(function (max, x) {
        return f(x) > f(max) ? x : max;
    });
};

Here we're using module.exports from the common.js variant that node uses to export our functionality.

write an example

Now we can just require() our code in an example/max.js file:

var maxBy = require('../');
var n = maxBy([9,3,4], function (x) { return x % 3 });
console.log(n);

Here we're using a relative require of '../' to load the index.js from the parent directory.

We can run this example in node:

$ node example/max.js
4

and our example prints 4 as expected since 4 % 3 is 1 and 9 % 3 and 3 % 3 are both 0.

writing tests

We can just copy this example into our test/ directory and then we'll add some assertions with tape:

var maxBy = require('../');
var test = require('tape');

test('simple comparisons', function (t) {
    t.plan(1);

    var n = maxBy([9,3,4], function (x) { return x % 3 });
    t.equal(n, 4);
});

The t.plan(1) tells tape that we are going to run a single test. We could have also called t.end() explicitly instead. The explicit approach that tape takes means we can test asynchronous APIs without requiring any additional exotic methods.

All we had to do for assertions was replace the console.log(n) with t.equal(n, 4).

First install tape by typing npm install tape, then we can run our test with node:

$ node test/max.js
TAP version 13
# simple comparisons
ok 1 should be equal

1..1
# tests 1
# pass  1

# ok

Our tests pass!

testing in local browsers

Now that our test suite is running in node, let's run our test in a local browser.

First, install browserify with npm install -g browserify.

Now you can do:

$ browserify test/*.js > test_bundle.js

to generate a test_bundle.js that you can drop into a <script> tag in a test.html file:

<script src="test_bundle.js"></script>

and now when you open the test.html in a browser, you will see the assertions printed to the debugger window since tape uses console.log() to output TAP-formatted output.

This is slightly cumbersome, so we can first npm install -g testling, and then we can do:

$ browserify test/max.js | testling

TAP version 13
# simple comparisons
ok 1 should be equal

1..1
# tests 1
# pass  1

# ok

The testling command will spin up a real local browser headlessly and forward the console.log() data directly into our terminal. We even get a non-zero exit code if there was a test failure!

package.json

Now create a package.json file with a "devDependency" entry for tape and a "testling" field with all the browsers you want to run:

{
  "name": "max-by",
  "version": "0.0.0",
  "main": "index.js",
  "devDependencies": {
    "tape": "~2.4.0"
  },
  "testling": {
    "files": "test/*.js",
    "browsers": [
      "ie/6..latest",
      "chrome/22..latest",
      "firefox/16..latest",
      "safari/latest",
      "opera/11.0..latest",
      "iphone/6",
      "ipad/6",
      "android-browser/latest"
    ]
  },
  "scripts": {
    "test": "tape test/*.js"
  }
}

If your module needs other dependencies from npm, put them in the "dependencies" field.

If your tests need additional modules, put them in the "devDependencies" field.

The scripts.test field lets us run our tests with npm test in node:

$ npm test
TAP version 13
# simple comparisons
ok 1 should be equal

1..1
# tests 1
# pass  1

# ok

Check your package.json into git and make sure all the other files we've created have been committed.

configuring the web hook

If you haven't already done so, at this point you should make a new github repository for this max-by module.

Then in a browser, visit:

https://github.com/$YOUR_USERNAME_HERE/max-by/settings/hooks

and under the "AVAILABLE SERVICE HOOKS" list, click on "WebHook URLs". Now add http://git.testling.com as a WebHook URL.

That's it!

push

Now git push your code and your test results will show up at:

https://ci.testling.com/$YOUR_USERNAME_HERE/max-by

You can also click the "test hook" button on the settings/hooks page on github to send a test hook manually.

badge

Now that your tests are running on every commit, you can add a .png to your repo page to get the current badge image:

https://ci.testling.com/$YOUR_USERNAME_HERE/max-by.png

Now you can put your browser badge in your readme.markdown with a link to the testling test output:

[![browser support](https://ci.testling.com/$YOUR_USERNAME_HERE/max-by.png)
](https://ci.testling.com/$YOUR_USERNAME_HERE/max-by)

Now your browser tests will run and your badge will update every time you push to github!