Assertive for Promises
Assertive as Promised extends Assertive for asserting things about standards-compliant promises. It is 100% backward-compatible, so all of the existing assertive documentation applies.
DEPRECATED
As of assertive-2.1.0
, this functionality has been rolled into
assertive itself. The only functional change is that you can no longer
pass functions-which-return-promises as arguments to resolves()
and
rejects()
- you should replace things like:
assert = require 'assertive-as-promised'assertrejects -> doSomething'blah'
with
assert = require 'assertive' # this version will explode your test if there is a synchronous throw # during the invocation of doSomething() (which may be a good thing - # you can test for that behavior separately with assert.throws()) assertrejectsdoSomething'blah'then ... # this version will turn any synchronous throw into a rejection which will # be available as err Promise = require 'bluebird'assertrejectsPromisetry -> doSomething'blah'then
How to Use
This is best used with something like Mocha which handles returned promises correctly. All of assertive's assertions are extended to accept promises as their argument to be tested and return a promise which will be resolved or rejected.
For all existing assertive functions, you may simply replace the
argument with a promise for an equivalent argument.
assert.equal('foo', funcThatReturnsAString())
becomes
assert.equal('foo', funcThatReturnsAPromiseForAString())
. Note that you may
get nicer and more consistent errors if you put any function calls that may
have a risk of throwing an exception synchronously inside a bluebird
Promise.try()
, thusly:
assert.equal('foo', Promise.try -> funcThatReturnsAPromiseForAString())
Note for throws()
and notThrows()
that they accept a function (which may
throw a synchronous exception) or a promise for a function (which
may throw a synchronous exception). The resolution status of the promise
itself is not being tested. Since you're often more interested in the
resolution status of the promise, there are two new functions:
rejects
and resolves
:
assert.rejects(-> funcThatReturnsAPromise(someArg))
takes as its
argument a promise OR a function that returns a promise. The equivalent
counterpart to notThrows
is called resolves
. rejects
returns a promise
for the rejection error, and thus composes nicely with other assertions.
Examples (using Mocha)
require './some-library'assert = require 'assertive-as-promised'Promise = require 'bluebird'# runAsync returns a promise it 'runs synchronously'-> assertdeepEqual 'got proper hash' a: 42 runSync'good' it 'fails synchronously'-> assertthrows 'fails on bad'-> runSync'bad' it 'runs asynchronously'-> assertdeepEqual 'got proper hash' a: 42 runAsync'good' it 'fails asynchronously'-> assertrejects 'fails on bad'-> runAsync'bad' = -> Promisetry -> throw 'kaboom'it 'fails asynchronously with the proper error'-> assertequal 'kaboom'assertrejects fn
Note that if you want to be able to put more than one asynchronous test in a
single it()
, you'll need to combine them somehow to make mocha-as-promised
happy, e.g.:
require './some-library'assert = require 'assertive-as-promised'Promise = require 'bluebird' it 'runs and fails asynchronously'-> Promiseall assertdeepEqual 'got proper hash' a: 42 runAsync'good' assertrejects 'fails on bad'-> runAsync'bad'
(this may be bad style, depending on who you ask, but I find it useful if you
have it()
s with a lot of setup overhead)
Development
src/aap.coffee
is the main library; it compiles tolib/aap.js
.test/assertive_test.coffee
is a copy of the assertive library tests, slightly modified to run correctly in our test environment (see comments at the top)