Tester helps to do asserts and provides 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 tests

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().
  • 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.
• Miscellaneous:
  • any — returns the any object. It can be used in deep equivalency asserts to match any value. See deep6's any for details.
  • plan(n) — sets the number of tests in the test suite. Rarely used.
  • 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).

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'}));
});