Unit tests that always supply a good bug report when they fail.
Clone or download
Latest commit ea0baa3 Oct 8, 2018
Failed to load latest commit information.
docs Add tap-color instructions Sep 7, 2018
source Match param name to docs Oct 8, 2018
.eslintrc.json Initial commit Aug 14, 2017
.gitignore Initial commit Aug 14, 2017
.travis.yml Add .travis.yml Aug 14, 2017
LICENSE Initial commit Aug 14, 2017
README.md No more `end()` Oct 7, 2018
index.d.ts Rename describeCallback to TestFunction Oct 8, 2018
package-lock.json 3.0.0 Oct 8, 2018
package.json 3.0.0 Oct 8, 2018



Test assertions that always supply a good bug report when they fail.

  • Readable
  • Isolated/Integrated
  • Thorough
  • Explicit

RITEway forces you to write Readable, Isolated, and Explicit tests, because that's the only way you can use the API. It also makes it easier to be thorough by making test assertions so simple that you'll want to write more of them.

There are 5 questions every unit test must answer. RITEWay forces you to answer them.

  1. What is the unit under test (module, function, class, whatever)?
  2. What should it do? (Prose description)
  3. What was the actual output?
  4. What was the expected output?
  5. How do you reproduce the failure?


npm install --save-dev riteway

Example Usage

import { describe, Try } from 'riteway';

// a function to test
const sum = (...args) => {
  if (args.some(v => Number.isNaN(v))) throw new TypeError('NaN');
  return args.reduce((acc, n) => acc + n, 0);

describe('sum()', async assert => {
  const should = 'return the correct sum';

    given: 'no arguments',
    should: 'return 0',
    actual: sum(),
    expected: 0

    given: 'zero',
    actual: sum(2, 0),
    expected: 2

    given: 'negative numbers',
    actual: sum(1, -4),
    expected: -3

    given: 'NaN',
    should: 'throw',
    actual: Try(sum, 1, NaN),
    expected: new TypeError('NaN')


RITEway produces standard TAP output, so it's easy to integrate with just about any test formatter and reporting tool. (TAP is a well established standard with hundreds (thousands?) of integrations).

TAP version 13
# sum()
ok 1 Given no arguments: should return 0
ok 2 Given zero: should return the correct sum
ok 3 Given negative numbers: should return the correct sum
ok 4 Given NaN: should throw

# tests 4
# pass  4

# ok

Prefer colorful output? No problem. The standard TAP output has you covered. You can run it through any TAP formatter you like:

npm install -g tap-color
npm test | tap-color

Colorized output



describe = (unit: String, cb: TestFunction) => Void

Describe takes a prose description of the unit under test (function, module, whatever), and a callback function (cb: TestFunction). The callback function should be an async function so that the test can automatically complete when it reaches the end. RITEWay assumes that all tests are asynchronous. Async functions automatically return a promise in JavaScript, so RITEWay knows when to end each test.


TestFunction = assert => Promise | Void

The TestFunction is a user-defined function which takes assert() and should return a promise. If you supply an async function, it will return a promise automatically. If you don't, you'll need to explicitly return a promise.

Failure to resolve the TestFunction promise will cause an error telling you that your test exited without ending. Usually, the fix is to add async to your TestFunction signature, e.g.:

describe('sum()', async assert => {
  /* test goes here */


assert = ({
  given = Any,
  should = '',
  actual: Any,
  expected: Any
} = {}) => Void, throws

The assert function is the function you call to make your assertions. It takes prose descriptions for given and should (which should be strings), and invokes the test harness to evaluate the pass/fail status of the test. Unless you're using a custom test harness, assertion failures will cause a test failure report and an error exit status.


createStream = ({ objectMode: Boolean }) => NodeStream

Create a stream of output, bypassing the default output stream that writes messages to console.log(). By default the stream will be a text stream of TAP output, but you can get an object stream instead by setting opts.objectMode to true.

import { describe, createStream } from 'riteway';

createStream({ objectMode: true }).on('data', function (row) {

describe('foo', async assert => {
  /* your tests here */