test()

test is the entry point to the test suite:

import test from 'tape-six';
// import {test} from 'tape-six';

// CommonJS:
// const {test} = require('tape-six');
// const {default: test} = require('tape-six');

Signatures

This function registers a test suite. Available options:

• async test(name, options, testFn) — registers a test suite to be executed asynchronously. The returned promise is resolved when the test suite is finished.
  • In most cases no need to wait for the returned promise.
  • The test function has the following signature: async testFn(tester)
    • The test function can be async or sync. No need to return a promise.
• test.skip(name, options, testFn) — registers a test suite to be skipped.
  • It is used to mark a test suite to be skipped. It will not be executed.
• test.todo(name, options, testFn) — registers a test suite that is marked as work in progress.
  • Tests in this suite will be executed, errors will be reported but not counted as failures.
  • It is used to mark tests for incomplete features under development.
• test.asPromise(name, options, testPromiseFn) — registers a test suite to be executed asynchronously using the callback-style API to notify that the test suite is finished.
  • The test function has a different signature: testPromiseFn(tester, resolve, reject).
    • The whole resolve/reject pair is modeled after the Promise API.
    • The resolve function is used to notify that the test suite is finished successfully.
      • The value passed to resolve() will be ignored.
    • The reject function is used to notify that the test suite is finished with an error.
      • The error passed to reject() will be reported as a failure.

All three arguments (name, options, testFn or testPromiseFn) are optional and can be used in any order (they are recognized by their types).

Arguments

The arguments mentioned above are:

• name — the optional name of the test suite. If not provided, it will be set to the name of the test function or '(anonymous)'.
• options — the optional options object. Available options:
  • name — the optional name of the test suite. If not provided, it will be set to the name of the test function or '(anonymous)'.
    • Can be overridden by the name argument.
  • testFn — the optional test function to be executed (see below).
    • Can be overridden by the testFn argument.
  • skip — if true, the test suite will be skipped.
  • todo — if true, the test suite will be marked as work in progress.
  • timeout — the optional timeout in milliseconds. It is used for asynchronous tests.
    • If the timeout is exceeded, the test suite will be marked as failed.
    • Important: JavaScript does not provide a generic way to cancel asynchronous operations. When the timeout is exceeded, tape6 will use signal property of the tester object to indicate that the test should be cancelled. See Tester for more details.
    • The default: no timeout.
  • Hooks (see below for details):
    • beforeAll — a function to be executed before all tests in the suite.
    • afterAll — a function to be executed after all tests in the suite.
    • beforeEach — a function to be executed before each test in the suite.
    • afterEach — a function to be executed after each test in the suite.
    • before — an alias for beforeAll.
      • If both are set, beforeAll will be executed before before.
    • after — an alias for afterAll.
      • If both are set, afterAll will be executed after after.
• testFn — a test function to be executed. It will be called with the tester object. The result will be ignored.
  • This function can be synchronous or asynchronous.
• testPromiseFn — a callback-based test function to be executed (see below). It will be called with the tester object and two callbacks: resolve and reject modeled on the Promise API.
  • Value supplied to resolve() will be ignored.
  • Value supplied to reject() will be used as the error message.

All hooks are functions with no arguments returning void or a Promise<void>:

() => void | Promise<void>;

Read more on hooks and their use in before and after hooks.

Examples

Given all that test and its helpers can be called like this:

test(name, options, testFn);
test(name, testFn);
test(testFn);
test(name, options);
test(options, testFn);
test(options);

// examples:
test('foo', t => {
  t.pass();
});
test('bar', async t => {
  t.fail();
});
test(function baz(t) {
  t.ok(1 < 2);
});
test({
  name: 'qux',
  todo: true,
  testFn: t => {
    t.ok(1 < 2);
  }
});

test.skip('foo1', t => {
  t.pass();
  t.fail();
});

test.todo('foo2', t => {
  t.pass();
  t.fail();
});

test.asPromise('foo3', (t, resolve, reject) => {
  const stream = fs.readStream('foo.txt');

  let buffer = '';
  stream.on('data', chunk => {
    buffer += chunk;
  });
  stream.on('end', () => {
    t.equal(buffer, 'foo');
    resolve();
  });
  stream.on('error', error => reject(error));
});

Embedded tests

The canonical way to embed tests is to use the test method of the tester object:

test('top', async t => {
  t.pass();
  await t.test('nested #1', async t => {
    t.pass();
  });
  await t.test('nested #2', async t => {
    t.pass();
    await t.test('even more nested', async t => {
      t.pass();
    });
  });
});

Yet it is also possible to use the test function:

test('top', async t => {
  t.pass();
  await test('nested #1', async t => {
    t.pass();
  });
  await test('nested #2', async t => {
    t.pass();
    await test('even more nested', async t => {
      t.pass();
    });
  });
});

The same goes for other similar methods like skip(), todo() and asPromise().