# tape-promise

> Promise/async support for tape.

Latest version **4.0.0** (published 2018-09-27) · MIT license · 0 weekly downloads

## Install

```sh
npm install tape-promise
pnpm add tape-promise
yarn add tape-promise
bun add tape-promise
```

## Health

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

Positive: has types package; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 4.0.0 |
| Published | 2018-09-27 |
| First published | 2015-11-06 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | separate (@types/tape-promise) |
| Module format | CommonJS |
| Dependencies | 2 |
| Unpacked size | 12.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | JP Richardson |
| Maintainers | jprichardson, ryanzim |
| Keywords | tape, promise, async, test, testing, tdd, unit |

## Links

- npm: https://www.npmjs.com/package/tape-promise
- Repository: https://github.com/jprichardson/tape-promise
- Homepage: https://github.com/jprichardson/tape-promise#readme
- Issues: https://github.com/jprichardson/tape-promise/issues
- npm.io page: https://npm.io/package/tape-promise

## Dependencies (2)

- [onetime](https://npm.io/package/onetime.md) ^2.0.0
- [is-promise](https://npm.io/package/is-promise.md) ^2.1.0

## Alternatives

- [duck](https://npm.io/package/duck.md) — 4.2M weekly downloads
- [ava](https://npm.io/package/ava.md) — 560.2K weekly downloads
- [storybook-addon-module-mock](https://npm.io/package/storybook-addon-module-mock.md) — 71.7K weekly downloads
- [@ethereum-waffle/mock-contract](https://npm.io/package/@ethereum-waffle/mock-contract.md) — 40.0K weekly downloads
- [aws-elasticsearch-connector](https://npm.io/package/aws-elasticsearch-connector.md) — 37.4K weekly downloads

## Recent versions

- 4.0.0 (latest) — 2018-09-27
- 3.0.0 — 2018-03-15
- 2.0.1 — 2016-11-28
- 2.0.0 — 2016-10-30
- 1.1.0 — 2016-04-06
- 1.0.1 — 2015-11-26
- 1.0.0 — 2015-11-06

## README

tape-promise
============

[![build status](https://api.travis-ci.org/jprichardson/tape-promise.svg)](http://travis-ci.org/jprichardson/tape-promise)

Promise and ES2016 (ES7) `async/await` support for [Tape](https://github.com/substack/tape).

This module assumes that you're familiar with at least the concepts of Promises
and if you want to use `async/await`, then you must be familiar with [Babel](https://babeljs.io/).

Install
-------

    npm i --save-dev tape-promise


Usage
-----

Make sure that you have `tape` installed:

    npm i --save-dev tape

Unlike [`blue-tape`](https://www.npmjs.com/package/blue-tape), `tape-promise` is
just a decorator (not an ES7 decorator). That is, it does NOT depend upon `tape`
and requires that you pass it in.

### ES5

```js
var tape = require('tape')
var _test = require('tape-promise').default // <---- notice 'default'
var test = _test(tape) // decorate tape
```

### ES6 (ES2015)

```js
import tape from 'tape'
import _test from 'tape-promise'
const test = _test(tape) // decorate tape
```

or, for convenience...

```js
import test from 'tape-promise/tape'
```

but you must explicitly have `tape` as a dependency.


### Example (promises)

Just return the promise.

```js
// example function that returns a Promise
function delay (time) {
  return new Promise(function (resolve, reject) {
    setTimeout(function () {
      resolve()
    }, time)
  })
}

test('ensure promises works', function (t) {
  return delay(100).then(function () {
    t.true(true)
  })
})
```

### Example (async/await)

Async/await functions just transform to Promises.
Don't forget to put the `async` keyword on your function.

```js
// example function that returns a Promise
// it could also be an async function
function delay (time) {
  return new Promise(function (resolve, reject) {
    setTimeout(function () {
      resolve()
    }, time)
  })
}

// NOTICE 'async'?
test('ensure async works', async function (t) {
  await delay(100)
  t.true(true)
  t.end() // not really necessary
})
```

### Example (normal tape tests)

Of course you can write normal tape tests as you would.

```js
test('ensure that regular test functions still work', function (t) {
  t.true(true)
  t.end()
})
```

## New Assertions

### t.rejects(promise, expected, msg)

Assert that the promise will reject.

If `promise` is a function, then it is called, and the returned promise is used.

`expected` is the error that should be rejected with, if present, must be a `RegExp` or `Function`. The `RegExp` matches the string representation of the exception, as generated by `err.toString()`. The `Function` is the exception thrown (e.g. `Error`). If the promise rejects, but its error doesn't match `expected`, then the assertion fails.

`msg` is an optional description of the assertion.

This function returns a promise that resolves when the assertion is complete (after the promise is settled). The test will not wait for the assertion automatically, so it needs to be `await`ed.

### t.doesNotReject(promise, expected, msg)

Assert that the promise will resolve.

If `promise` is a function, then it is called, and the returned promise is used.

`expected` is the error that the promise shouldn't reject with, if present, it must be a `RegExp` or `Function`. The `RegExp` matches the string representation of the exception, as generated by `err.toString()`. The `Function` is the exception thrown (e.g. `Error`). If the promise rejects, but its error doesn't match `expected`, then the assertion passes.

`msg` is an optional description of the assertion.

This function returns a promise that resolves when the assertion is complete (after the promise is settled). The test will not wait for the assertion automatically, so it needs to be `await`ed.


### example

```js
test('reject and doesNotReject example', async (t) => {
  await t.rejects(asyncFunction)
  await t.rejects(asyncFunction())
  await t.doesNotReject(Promise.resolve())
})
```

License
-------

Licensed under MIT

Copyright (c) [JP Richardson](https://github.com/jprichardson)

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