node-async-testing

A simple test runner with testing asynchronous code in mind.

Some goals of the project:

• Simple and intuitive. You create a test and then run the code you want to test and make assertions as you go along. Tests should be functions.

• Use the assertion module that comes with Node. If you are familiar with it you won't have any problems. You shouldn't have to learn new assertion functions.

• Test files to be executable by Node. No preprocessors. If your test file is called "my_test_file.js" then "node my_test_file.js" should run the tests.

• Address the issue of testing asynchronouse code. Node is asynchronous, so testing should be too.

• Not another Behavior Driven Development testing framework. I don't like specifications and what not. They only add verbosity.

  test('X does Y',function() { //test goes here });

  is good enough for me.

• Make no assumptions about the code being tested.

Feedback/suggestions encouraged!

Writing Tests

The hard part of writing a test suite for asynchronous code is that when a test fails, you don't know which test it was that failed. Errors won't get caught by try/catch statements.

This module aims to address that by making sure

1. First, it gives each test its own unique assert object. That way you know which assertions correspond to which tests.

2. Second, the tests get ran one at a time. That way, it is possible to add a global exceptionHandler for the process and catch the tests whenever they happen.

   To only run one test at a time, asynchronous tests receive a finished() function as an argument. They must call this function when they are done. The next test won't be run until this function is called.

Tests are added to a TestSuite object.

var TestSuite = require('async_testing').TestSuite;

var suite = new TestSuite();
suite.addTests({
    "simple asynchronous": function(assert, finished) {
      setTimeout(function() {
        assert.ok(true);
        finished();
      });
    }
  });

If your test isn't asynchronous, you don't have to use the finished callback. If you don't list the finished callback in the parameters of the test, node-async-testing will assume the test is synchronous.

var suite = new TestSuite();
suite.addTests({
    "simple synchronous": function(assert) {
      assert.ok(true);
    }
  });

You can add a setup function that is ran once at the beginning of each test. You can do a teardown function, as well:

var suite = new TestSuite();
suite.setup(function() {
  this.foo = 'bar';
});
suite.teardown(function() {
  this.foo = null;
});
suite.addTests({
  "synchronous foo equals bar": function(assert) {
    assert.equal('bar', this.foo);
  }
});

If you need to access the variables created in the setup function asynchronously your tests receive a third argument which has this information:

var suite = new TestSuite();
suite.setup(function() {
  this.foo = 'bar';
});
suite.teardown(function() {
  this.foo = null;
});
suite.addTests({
  "asynchronous foo equals bar": function(assert, finished, test) {
    process.nextTick(function() {
      assert.equal('bar', test.foo);
      finished();
    });
  }
});

If you want to be explicit about the number of assertions run in a given test, you can set numAssertionsExpected on the test. This can be helpful in asynchronous tests where you want to be sure all callbacks get fired.

var suite = new TestSuite();
suite.addTests({
    "assertions expected (fails)": function(assert) {
      this.numAssertionsExpected = 3;

      assert.ok(true);
      // this test will fail!
    }
  });

If you need to make assertions about what kind of errors are thrown, you can listen for the uncaughtException event on the test:

var suite = new TestSuite();
suite.addTests({
    "uncaughtException listener": function(assert, finished, test) {
      test.numAssertionsExpected = 1;
      test.addListener('uncaughtException', function(err) {
          assert.equal('hello', err.message);
          finished();
        });

      throw new Error('hello');
    }
  });

All the functions to a TestSuite can be chained to cut down on verbosity:

(new TestSuite())
  .setup(function() {
    this.foo = 'bar';
  })
  .teardown(function() {
    this.foo = null;
  })
  .addTests({
    "foo equal bar": function(assert) {
      assert.equal('bar', foo);
    }
  });

Running test suites

To run a test suite, you call runTests() on it.

var suite = new TestSuite();
suite.addTests({
    "simple": function(assert) {
      assert.ok(true);
    }
  });
suite.runTests();

There is also a test runner which can run many TestSuites at once:

var suites = {
  'first suite':  new TestSuite(),
  'second suite':  new TestSuite()
};

require('async_testing').runSuites(suites);

It is recommended that you export your test suites, so other more capable scripts can handle running them. However, it is still convenient to be able to run a specific file. Here's how you can allow both:

exports['first suite'] = new TestSuite();
exports['second suite'] = new TestSuite();

if (module === require.main) {
  require('../async_testing').runSuites(exports);
}

This way the tests will only be run automatically if the file containing them is the script being ran.

node-async-testing also comes with a script that will run all test files in a specified directory. A test file is one that matches this regular expression: /^test-.*\.js$/. To use the script make sure node-async-testing has been installed properly and then run:

node-async-test testsDir

Installing

To install, the file async_testing.js needs to be in your Node path. The easiest place to put it is in ~/.node_libraries.

Notes

• If you don't care about being able to count the number of assertions in a given test, you can use any assertion library you'd like.