Tester provides assertions and an interface between a test suite and the test harness.

Available properties

• signal — a signal (AbortSignal) to cancel asynchronous operations.
  • It is triggered when the test is stopped or timed out.
  • It is useful to control potentially run-away asynchronous operations.

Available methods

The following methods are available (all msg arguments are optional):

• Asserts:
  • pass(msg) — asserts that the test passed.
  • fail(msg) — asserts that the test failed.
  • ok(val, msg) — asserts that val is truthy.
    • true() — an alias of ok().
    • assert() — an alias of ok().
  • notOk(val, msg) — asserts that val is falsy.
    • false() — an alias of notOk().
    • notok() — an alias of notOk().
  • error(err, msg) — asserts that err is falsy.
    • ifError() — an alias of error().
    • ifErr() — an alias of error().
    • iferror() — an alias of error().
  • strictEqual(a, b, msg) — asserts that a and b are strictly equal.
    • Strict equality is defined as a === b.
    • is() — an alias of strictEqual().
    • equal() — an alias of strictEqual().
    • isEqual() — an alias of strictEqual().
    • equals() — an alias of strictEqual().
    • strictEquals() — an alias of strictEqual().
  • notStrictEqual(a, b, msg) — asserts that a and b are not strictly equal.
    • not() — an alias of notStrictEqual().
    • notEqual() — an alias of notStrictEqual().
    • notEquals() — an alias of notStrictEqual().
    • notStrictEquals() — an alias of notStrictEqual().
    • doesNotEqual() — an alias of notStrictEqual().
    • isUnequal() — an alias of notStrictEqual().
    • isNotEqual() — an alias of notStrictEqual().
    • isNot() — an alias of notStrictEqual().
  • looseEqual(a, b, msg) — asserts that a and b are loosely equal.
    • Loose equality is defined as a == b.
    • looseEquals() — an alias of looseEqual().
  • notLooseEqual(a, b, msg) — asserts that a and b are not loosely equal.
    • notLooseEquals() — an alias of notLooseEqual().
  • deepEqual(a, b, msg) — asserts that a and b are deeply equal.
    • Individual components of a and b are compared recursively using the strict equality.
    • See deep6's equal() for details.
    • same() — an alias of deepEqual().
    • deepEquals() — an alias of deepEqual().
    • isEquivalent() — an alias of deepEqual().
  • notDeepEqual(a, b, msg) — asserts that a and b are not deeply equal.
    • notSame() — an alias of notDeepEqual().
    • notDeepEquals() — an alias of notDeepEqual().
    • notEquivalent() — an alias of notDeepEqual().
    • notDeeply() — an alias of notDeepEqual().
    • isNotDeepEqual() — an alias of notDeepEqual().
    • isNotEquivalent() — an alias of notDeepEqual().
  • deepLooseEqual(a, b, msg) — asserts that a and b are deeply loosely equal.
    • Individual components of a and b are compared recursively using the loose equality.
  • notDeepLooseEqual(a, b, msg) — asserts that a and b are not deeply loosely equal.
  • throws(fn, msg) — asserts that fn throws.
    • fn is called with no arguments in the global context.
  • doesNotThrow(fn, msg) — asserts that fn does not throw.
  • matchString(string, regexp, msg) — asserts that string matches regexp.
  • doesNotMatchString(string, regexp, msg) — asserts that string does not match regexp.
  • match(a, b, msg) — asserts that a matches b.
    • See deep6's match() for details.
  • doesNotMatch(a, b, msg) — asserts that a does not match b.
  • rejects(promise, msg) — asserts that promise rejects.
    • This is an asynchronous method. It is likely to be waited for.
    • doesNotResolve() — an alias of rejects().
  • resolves(promise, msg) — asserts that promise resolves.
    • This is an asynchronous method. It is likely to be waited for.
    • doesNotReject() — an alias of resolves().
• Embedded test suites (all of them are asynchronous and should be waited for):
  • test(name, options, testFn) — runs a test suite asynchronously. See test() above.
  • skip(name, options, testFn) — skips a test suite asynchronously. See test.skip() above.
  • todo(name, options, testFn) — runs a provisional test suite asynchronously. See test.todo() above.
  • asPromise(name, options, testPromiseFn) — runs a test suite asynchronously. See test.asPromise() above.
  • Note: the top-level test() and its aliases (describe(), it(), suite()) auto-delegate to t.test() when called inside a test body. Using t.test() directly is preferred.
• Miscellaneous:
  • any — a symbol that can be used in deep equivalency asserts to match any value. See deep6's any for details.
    • _ — an alias of any.
  • plan(n) — records the expected number of direct assertions. Emits a # plan != count: expected N, ran M TAP comment at test end if the count diverges (diagnostic only, doesn't fail the test). Subtest assertions don't count toward the parent's plan.
  • comment(msg) — sends a comment to the test harness. Rarely used.
  • skipTest(...args, msg) — skips the current test yet sends a message to the test harness.
  • bailOut(msg) — stops the test suite and sends a message to the test harness.
• Evaluators:
  • OK(condition, msg, options) — a high-level helper for evaluating simple expressions. It takes a code snippet as a string and returns a code snippet as a string that checks the condition when evaluated with eval().
    • Available since 1.4.0.
    • Aliases: TRUE(), ASSERT().
    • Arguments:
      • condition is a simple JavaScript expression (a code snippet) as a string.
      • msg is a string that describes the condition.
      • options is an object that can contain additional options. Right now the only supported option is self — a string that represents the name of the tester object. Default: "t".
    • Return value: a code as a string that checks the condition when evaluated with eval().
    • Supported signatures:
      • OK(condition[, msg[, options]])
      • OK(condition, options)
    • If msg is not provided, condition will be used.
    • If fails, it provides a dictionary of all top-level variables in the condition and their values helping to see what went wrong.
• Hooks (see before and after hooks for more information):
  • beforeEach(fn) — a function that is called before each test in the current scope.
  • afterEach(fn) — a function that is called after each test in the current scope.
  • beforeAll(fn) — a function that is called before all tests in the current scope.
  • afterAll(fn) — a function that is called after all tests in the current scope.
  • before(fn) — an alias for beforeAll(fn).
  • after(fn) — an alias for afterAll(fn).
  • Note: the top-level hook functions auto-delegate to the current tester when called inside a test body. Using t.beforeAll(), etc. is preferred.

In all cases, the msg message is optional. If it is not provided, some suitable generic message will be used.

Examples

test('Sample test', async t => {
  const result = await getFromDb({first: 'Bob', last: 'Smith'});
  t.equal(result.position, 'chief bozo', 'the position is correct');
  t.ok(result.manager, 'the manager exists');

  const manager = await getFromDb(result.manager);
  t.ok(manager, 'the manager is retrieved');
  t.equal(manager.first, 'Jane', 'the manager is Jane');
  t.deepEqual(manager.employees, ['Bob Smith'], 'Jane manages only Bob Smith');
});

Examples on using OK() (AKA TRUE(), AKA ASSERT()):

test('Use OK()', t => {
  const a = 1,
    b = 2,
    c = 'three';
  eval(t.OK('a + b + c === "3three"'));
  // when the condition fails we'll see:
  // actual: {"a":1,"b":2,"c":"three"}
  eval(t.OK('a + (b + c) === "12three"'));
});

test('Use ASSERT() with custom tester name', tester => {
  // in this example we use a custom tester name "tester" instead of the default "t"
  // it should be supplied as an option in the call (see below)
  const a = 1,
    b = 2,
    c = 'three';
  eval(tester.ASSERT('a + b + c === "3three"', {self: 'tester'}));

  // lets log the evaluated code to inspect it:
  console.log(tester.ASSERT('a + b + c === "3three"', {self: 'tester'}));
});