Narcissistic, Perfectly Modest

    qunit-promises

    0.2.0 • Public • Published

    qunit-promises

    QUnit plugin that adds assertions to check promises.

    Test page

    NPM

    Build status Coverage Status Code Climate Codacy dependencies

    semantic-release

    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(QUnit.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, [expectation [, message]])
    assert.will(fn, [message])
    
    - fn: function that returns a promise that should be resolved
    - expectation: function that will evaluate received result and
      return true / false if it's correct or wrong
    - message (optional): to push in the log
    
    assert.willEqual(fn, expected, [message], [actualTransform])
    
    - 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
    - actualTransform (optional): function that will transform promise's
      result for comparison with "expected", e.g. extract a member from object
    
    assert.willDeepEqual(fn, expected, [message], [actualTransform])
    
    - 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
    - actualTransform (optional): function that will transform promise's
      result for comparison with "expected", e.g. extract a member from object
    

    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.

    Install

    npm i qunit-promises

    DownloadsWeekly Downloads

    16

    Version

    0.2.0

    License

    MIT

    Last publish

    Collaborators

    • bahmutov