# assertive-as-promised

> Extends assertive with promise support

Latest version **1.0.4** (published 2018-01-05) · BSD-3-Clause license · 0 weekly downloads

## Install

```sh
npm install assertive-as-promised
pnpm add assertive-as-promised
yarn add assertive-as-promised
bun add assertive-as-promised
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.4 |
| Published | 2018-01-05 |
| First published | 2014-04-17 |
| Weekly downloads | 0 |
| License | BSD-3-Clause |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 2 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Groupon |
| Maintainers | dbushong, groupon |

## Links

- npm: https://www.npmjs.com/package/assertive-as-promised
- Repository: https://github.com/groupon/assertive-as-promised
- Issues: https://github.com/groupon/assertive-as-promised/issues
- npm.io page: https://npm.io/package/assertive-as-promised

## Dependencies (2)

- [bluebird](https://npm.io/package/bluebird.md) ^3.3.3
- [assertive](https://npm.io/package/assertive.md) ^1.3.2

## Recent versions

- 1.0.4 (latest) — 2018-01-05
- 1.0.3 — 2016-04-13
- 1.0.2 — 2016-03-07
- 1.0.1 — 2015-10-09
- 1.0.0 — 2015-10-09
- 0.1.0 — 2014-04-17

## README

# Assertive for Promises

**Assertive as Promised** extends [Assertive][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:

```coffee
assert = require 'assertive-as-promised'
assert.rejects -> doSomething('blah')
```

with

```coffee
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())
assert.rejects(doSomething('blah')).then (err) -> ...

# this version will turn any synchronous throw into a rejection which will
# be available as err
Promise = require 'bluebird'
assert.rejects(Promise.try -> doSomething('blah')).then (err) ->
```

## How to Use

This is best used with something like [Mocha] (version >= 1.18.0) 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)

```coffee
{ runSync, runAsync }  = require './some-library'
assert  = require 'assertive-as-promised'
Promise = require 'bluebird'
# runAsync returns a promise

it 'runs synchronously', ->
  assert.deepEqual 'got proper hash', { a: 42 }, runSync('good')

it 'fails synchronously', ->
  assert.throws 'fails on bad', -> runSync('bad')

it 'runs asynchronously', ->
  assert.deepEqual 'got proper hash', { a: 42 }, runAsync('good')

it 'fails asynchronously', ->
  assert.rejects 'fails on bad', -> runAsync('bad')

fn = -> Promise.try -> throw 'kaboom'
it 'fails asynchronously with the proper error', ->
  assert.equal 'kaboom', assert.rejects 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.:

```coffee
{ runAsync } = require './some-library'
assert       = require 'assertive-as-promised'
Promise      = require 'bluebird'

it 'runs and fails asynchronously', ->
  Promise.all [
    assert.deepEqual 'got proper hash', { a: 42 }, runAsync('good')
    assert.rejects '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 to `lib/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)

[assertive]: https://github.com/groupon/assertive
[Mocha]: https://mochajs.org/

---
_Source: https://npm.io/package/assertive-as-promised · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
