class TestContext

An object containing assertion methods bound to the test context. The top-level functions from the node:assert module are exposed here for the purpose of creating test plans.

Note: Some of the functions from node:assert contain type assertions. If these are called via the TestContext assert object, then the context parameter in the test's function signature must be explicitly typed (ie. the parameter must have a type annotation), otherwise an error will be raised by the TypeScript compiler:

import { test, type TestContext } from 'node:test';

// The test function's context parameter must have a type annotation.
test('example', (t: TestContext) => {
  t.assert.deepStrictEqual(actual, expected);
});

// Omitting the type annotation will result in a compilation error.
test('example', t => {
  t.assert.deepStrictEqual(actual, expected); // Error: 't' needs an explicit type annotation.
});

The absolute path of the test file that created the current test. If a test file imports additional modules that generate tests, the imported tests will return the path of the root test file.

The name of the test and each of its ancestors, separated by >.

Each test provides its own MockTracker instance.

The name of the test.

This function is used to create subtests under the current test. This function behaves in the same fashion as the top level test function.

This function is used to create a hook that runs after the current test finishes.

This function is used to create a hook running after each subtest of the current test.

This function is used to create a hook running before subtest of the current test.

This function is used to create a hook running before each subtest of the current test.

This function is used to write diagnostics to the output. Any diagnostic information is included at the end of the test's results. This function does not return a value.

test('top level test', (t) => {
  t.diagnostic('A diagnostic message');
});

Used to set the number of assertions and subtests that are expected to run within the test. If the number of assertions and subtests that run does not match the expected count, the test will fail.

To make sure assertions are tracked, the assert functions on context.assert must be used, instead of importing from the node:assert module.

test('top level test', (t) => {
  t.plan(2);
  t.assert.ok('some relevant assertion here');
  t.test('subtest', () => {});
});

When working with asynchronous code, the plan function can be used to ensure that the correct number of assertions are run:

test('planning with streams', (t, done) => {
  function* generate() {
    yield 'a';
    yield 'b';
    yield 'c';
  }
  const expected = ['a', 'b', 'c'];
  t.plan(expected.length);
  const stream = Readable.from(generate());
  stream.on('data', (chunk) => {
    t.assert.strictEqual(chunk, expected.shift());
  });
  stream.on('end', () => {
    done();
  });
});

If shouldRunOnlyTests is truthy, the test context will only run tests that have the only option set. Otherwise, all tests are run. If Node.js was not started with the --test-only command-line option, this function is a no-op.

test('top level test', (t) => {
  // The test context can be set to run subtests with the 'only' option.
  t.runOnly(true);
  return Promise.all([
    t.test('this subtest is now skipped'),
    t.test('this subtest is run', { only: true }),
  ]);
});

This function causes the test's output to indicate the test as skipped. If message is provided, it is included in the output. Calling skip() does not terminate execution of the test function. This function does not return a value.

test('top level test', (t) => {
  // Make sure to return here as well if the test contains additional logic.
  t.skip('this is skipped');
});

This function adds a TODO directive to the test's output. If message is provided, it is included in the output. Calling todo() does not terminate execution of the test function. This function does not return a value.

test('top level test', (t) => {
  // This test is marked as `TODO`
  t.todo('this is a todo');
});

This method polls a condition function until that function either returns successfully or the operation times out.