TestQueue

Enqueue and run tests (optionally in parallel).

Properties

Events

  • runStart RunStartInfo — 

    emitted when the queue begins processing tests

  • runEnd RunEndInfo — 

    emitted when the queue finishes processing tests

  • testResult TestResultInfo — 

    emitted when a test completes

  • error Error — 

    emitted when an error occurs (not including test failures) when running tests

new TestQueue(reporter, options)

Creates a new TestQueue object and sets the this.reporter property.

  • reporter Reporter — 

    optional (if not defined, no output will be written but events will still fire)

  • options Object — 

    optional

    • concurrency number — 

      how many tests to run in parallel

      (default: 1)
    • autoRun bool — 

      if true, start running tests as soon as the first one is defined

      (default: false)
    • bail bool — 

      if true, drain after first test failure

      (default: false)

Examples

const {Tap, Reporter, TestQueue} = require('spooning');
const testQueue = new TestQueue(new Reporter(new Tap(), process.stdout));

push(name, test, callback)

alias: test, it

Enqueue a test. This should not be called after this.run. Compatible with promisify.

This method is a context-bound version of the private method _push. If a subclass needs to override, it should override the private method.

  • name string — 

    name of test

  • test function — 

    test definition

    • callback function — 

      call to indicate test is complete

      • error Error|falsy — 

        Error indicating failure reason (or falsy)

      • message any — 

        optional diagnostic message (or falsy)

  • callback function — 

    called when test has run (optional)

Examples

testQueue.push('Should pass', (callback) => {
    setTimeout(() => {
        callback(null, 'optional diagnostic message'); // pass
    }, 100);
});

testQueue.push('Should fail', (callback) => {
    setTimeout(() => {
        callback(new Error('nope')); // fail
    }, 100);
});

pushPromise(name, test, callback)

alias: swear

Enqueue a Promise-based test. This should not be called after this.run. Compatible with promisify.

This method is a context-bound version of the private method _pushPromise. If a subclass needs to override, it should override the private method.

  • name string — 

    name of test

  • test function — 

    test definition, returns Promise object that resolves (with an optional diagnostic message of any type) or rejects (with Error) to indicate pass/fail

  • callback function — 

    called when test has run (optional)

Examples

testQueue.pushPromise('Should pass', () => new Promise((resove, reject) => {
    setTimeout(() => {
      resove('optional diagnostic message'); // pass
    }, 100);
}));

testQueue.pushPromise('Should fail', () => new Promise((resove, reject) => {
    setTimeout(() => {
      reject(new Error('nope')); // fail
    }, 100);
}));

pushSync(name, test, callback)

Enqueue a synchronous test. This should not be called after this.run. Compatible with promisify.

This method is a context-bound version of the private method _pushSync. If a subclass needs to override, it should override the private method.

  • name string — 

    name of test

  • test function — 

    test definition, returns optional diagnostic message of any type (or falsy), throw an Error to indicate failure

  • callback function — 

    called when test has run (optional)

Examples

testQueue.pushSync('Should pass', () => {
    return 'optional diagnostic message'; // pass
});

testQueue.pushSync('Should pass', () => {
    throw new Error('nope'); // fail
});

run(callback)

Run enqueued tests. This should only be called once. Compatible with promisify.

This method is a context-bound version of the private method _run. If a subclass needs to override, it should override the private method.

  • callback function — 

    called when all tests have run (optional)

    • error Error|falsy — 

      Reporter error (an error encountered while reporting the result, not an error indicating test failure) that occurred (or falsy)

    • info RunEndInfo

Examples

// exit the process when complete
testQueue.run(testQueue.exit);
// provide a custom callback
testQueue.run((error, info) => {
    // handle error/info
});

exit(error, info)

If error is not falsy, emit it. Otherwise, exit the process with code determined by info.exitCode.

This method is a context-bound version of the private method _exit. If a subclass needs to override, it should override the private method.

Examples

// exit the process when complete
testQueue.run(testQueue.exit);

setAutoRun(isEnabled)

Enable/disable auto-run mode. Tests will be executed as soon as they are defined (without waiting for this.run to be called).

When in auto-run mode, the runStart event does not fire and reporter.runStart is not called. Also, the TAP plan (ex. “1..4”) is not included in the output.

This method is context-bound.

Examples

testQueue.setAutoRun(true);

setBail(isEnabled)

Enable/disable bail mode. If true, the queue will drain after the first test failure (when running tests in parallel, tests that are already running when the failure occurs may still complete).

This method is context-bound.

Examples

testQueue.setBail(true);

setConcurrency(n)

Set the number of tests to run in parallel.

This method is context-bound.

  • n number — 

    max number of tests to run concurrently

Examples

testQueue.setConcurrency(10);