qunit-promises

QUnit plugin that adds assertions to check promises quickly

npm install qunit-promises
36 downloads in the last month

qunit-promises

QUnit plugin that adds assertions to check promises.

Test page

NPM

Build status Coverage Status dependencies dev dependencies

endorse

Available through bower and npm as qunit-promises. Included in the list of QUnit plugins.

Compatible with jQuery's and Q's promises.

Problem

Compared with other testing frameworks designed to deal with async code (see vows for example), there is way too much boilerplate code to check promises when using QUnit. For example, here is an asynchronous unit test that checks that a promise resolves successfully with a certain value:

// function delayedHello returns a promise

QUnit.test("test successful promise", 1, function (assert) {
    QUnit.stop();
    var promise = delayedHello();
    promise.then(function (actual) {
        assert.equal(actual, 'hello', 'promise resolved with "hello"');
    }).always(start);
});

Promises plugin

qunit-promises plugin adds a pair of methods to QUnit's assert object. It does these things for you:

  • stops current test queue
    • use QUnit.test(), not QUnit.asyncTest()
    • do not call QUnit.stop()
  • asserts that the promise either resolves or is rejected
  • compares the final value to expected
  • restarts the testing queue
    • so you don't have to call QUnit.start()

Same test as above, rewritten using new assertion:

QUnit.test("test successful promise", 1, function (assert) {
    assert.willEqual(delayedHello(), 'hello', 'returns value "hello"');
});

API

Successful promises

assert.will(fn, [message])

- fn: function that returns a promise that should be resolved
- message (optional): to push in the log
assert.willEqual(fn, expected, [message])

- fn: function that returns a promise that should be resolved
- expected: to compare with the resolved value using ==
- message (optional): to push in the log
assert.willDeepEqual(fn, expected, [message])

- fn: function that returns a promise that should be resolved
- expected value: to compare with the resolved value using QUnit.equiv
- message (optional): to push in the log

Rejected promises

assert.wont(fn, [message])

- fn: function that returns a promise that should be rejected (failed)
- message (optional): to push in the log
assert.wontEqual(fn, expected, [message])

- fn: function that returns a promise that should be rejected (failed)
- expected: to compare with the rejected value using ==
- message (optional): to push in the log
assert.wontDeepEqual(fn, expected, [message])

- fn: function that returns a promise that should be rejected (failed)
- expected: to compare with the rejected value using QUnit.equiv
- message (optional): to push in the log

Install

Browser

  • bower install qunit-promises
  • Include qunit-promises.js after qunit.js, new methods are added to the assert object.
<script src="http://code.jquery.com/qunit/qunit-1.12.0.js"></script>
<script src="qunit-promises.js"></script>
<script src="tests.js"></script>

For full example, see the test page.

Node

The qunit-promises is compatible with node-qunit and its wrapper grunt-node-qunit.

Also compatible with gt, which provides code coverage.

  • npm install qunit-promises --save
  • preload qunit-promises.js as a dependency
// via node-qunit
qunit -c test/node-tests.js -t test/node-tests.js -d qunit-promises.js

// via gt
gt qunit-promises.js test/node-tests.js

Advanced

qunit-promises simplify the tests when there is a single promise to be evaluated. In other cases, you might to combine promises (chain, or evaluate in parallel) yourself before calling assert.will... as the last step.

assert.will(promiseOne().then(promiseTwo), 'one, then two succeeded');

Small print

Author: Gleb Bahmutov © 2013

License: MIT - do anything with the code, but don't blame me if it does not work.

npm loves you