test

A getter that returns a copy of the internal array used to track calls to the mock. Each entry in the array is an object with the following properties.

This function returns the number of times that this mock has been invoked. This function is more efficient than checking ctx.calls.length because ctx.calls is a getter that creates a copy of the internal call tracking array.

This function is used to change the behavior of an existing mock.

The following example creates a mock function using t.mock.fn(), calls the mock function, and then changes the mock implementation to a different function.

test('changes a mock behavior', (t) => {
  let cnt = 0;

  function addOne() {
    cnt++;
    return cnt;
  }

  function addTwo() {
    cnt += 2;
    return cnt;
  }

  const fn = t.mock.fn(addOne);

  assert.strictEqual(fn(), 1);
  fn.mock.mockImplementation(addTwo);
  assert.strictEqual(fn(), 3);
  assert.strictEqual(fn(), 5);
});

This function is used to change the behavior of an existing mock for a single invocation. Once invocation onCall has occurred, the mock will revert to whatever behavior it would have used had mockImplementationOnce() not been called.

The following example creates a mock function using t.mock.fn(), calls the mock function, changes the mock implementation to a different function for the next invocation, and then resumes its previous behavior.

test('changes a mock behavior once', (t) => {
  let cnt = 0;

  function addOne() {
    cnt++;
    return cnt;
  }

  function addTwo() {
    cnt += 2;
    return cnt;
  }

  const fn = t.mock.fn(addOne);

  assert.strictEqual(fn(), 1);
  fn.mock.mockImplementationOnce(addTwo);
  assert.strictEqual(fn(), 3);
  assert.strictEqual(fn(), 4);
});

Resets the call history of the mock function.

Resets the implementation of the mock function to its original behavior. The mock can still be used after calling this function.

Resets the implementation of the mock module.

Calls MockTimers.reset().

Enables timer mocking for the specified timers.

Note: When you enable mocking for a specific timer, its associated clear function will also be implicitly mocked.

Note: Mocking Date will affect the behavior of the mocked timers as they use the same internal clock.

Example usage without setting initial time:

import { mock } from 'node:test';
mock.timers.enable({ apis: ['setInterval', 'Date'], now: 1234 });

The above example enables mocking for the Date constructor, setInterval timer and implicitly mocks the clearInterval function. Only the Date constructor from globalThis, setInterval and clearInterval functions from node:timers, node:timers/promises, and globalThis will be mocked.

Example usage with initial time set

import { mock } from 'node:test';
mock.timers.enable({ apis: ['Date'], now: 1000 });

Example usage with initial Date object as time set

import { mock } from 'node:test';
mock.timers.enable({ apis: ['Date'], now: new Date() });

Alternatively, if you call mock.timers.enable() without any parameters:

All timers ('setInterval', 'clearInterval', 'Date', 'setImmediate', 'clearImmediate', 'setTimeout', and 'clearTimeout') will be mocked.

The setInterval, clearInterval, setTimeout, and clearTimeout functions from node:timers, node:timers/promises, and globalThis will be mocked. The Date constructor from globalThis will be mocked.

If there is no initial epoch set, the initial date will be based on 0 in the Unix epoch. This is January 1st, 1970, 00:00:00 UTC. You can set an initial date by passing a now property to the .enable() method. This value will be used as the initial date for the mocked Date object. It can either be a positive integer, or another Date object.

This function restores the default behavior of all mocks that were previously created by this MockTimers instance and disassociates the mocks from the MockTracker instance.

Note: After each test completes, this function is called on the test context's MockTracker.

import { mock } from 'node:test';
mock.timers.reset();

Triggers all pending mocked timers immediately. If the Date object is also mocked, it will also advance the Date object to the furthest timer's time.

The example below triggers all pending timers immediately, causing them to execute without any delay.

import assert from 'node:assert';
import { test } from 'node:test';

test('runAll functions following the given order', (context) => {
  context.mock.timers.enable({ apis: ['setTimeout', 'Date'] });
  const results = [];
  setTimeout(() => results.push(1), 9999);

  // Notice that if both timers have the same timeout,
  // the order of execution is guaranteed
  setTimeout(() => results.push(3), 8888);
  setTimeout(() => results.push(2), 8888);

  assert.deepStrictEqual(results, []);

  context.mock.timers.runAll();
  assert.deepStrictEqual(results, [3, 2, 1]);
  // The Date object is also advanced to the furthest timer's time
  assert.strictEqual(Date.now(), 9999);
});

Note: The runAll() function is specifically designed for triggering timers in the context of timer mocking. It does not have any effect on real-time system clocks or actual timers outside of the mocking environment.

You can use the .setTime() method to manually move the mocked date to another time. This method only accepts a positive integer. Note: This method will execute any mocked timers that are in the past from the new time. In the below example we are setting a new time for the mocked date.

import assert from 'node:assert';
import { test } from 'node:test';
test('sets the time of a date object', (context) => {
  // Optionally choose what to mock
  context.mock.timers.enable({ apis: ['Date'], now: 100 });
  assert.strictEqual(Date.now(), 100);
  // Advance in time will also advance the date
  context.mock.timers.setTime(1000);
  context.mock.timers.tick(200);
  assert.strictEqual(Date.now(), 1200);
});

Advances time for all mocked timers.

Note: This diverges from how setTimeout in Node.js behaves and accepts only positive numbers. In Node.js, setTimeout with negative numbers is only supported for web compatibility reasons.

The following example mocks a setTimeout function and by using .tick advances in time triggering all pending timers.

import assert from 'node:assert';
import { test } from 'node:test';

test('mocks setTimeout to be executed synchronously without having to actually wait for it', (context) => {
  const fn = context.mock.fn();

  context.mock.timers.enable({ apis: ['setTimeout'] });

  setTimeout(fn, 9999);

  assert.strictEqual(fn.mock.callCount(), 0);

  // Advance in time
  context.mock.timers.tick(9999);

  assert.strictEqual(fn.mock.callCount(), 1);
});

Alternativelly, the .tick function can be called many times

import assert from 'node:assert';
import { test } from 'node:test';

test('mocks setTimeout to be executed synchronously without having to actually wait for it', (context) => {
  const fn = context.mock.fn();
  context.mock.timers.enable({ apis: ['setTimeout'] });
  const nineSecs = 9000;
  setTimeout(fn, nineSecs);

  const twoSeconds = 3000;
  context.mock.timers.tick(twoSeconds);
  context.mock.timers.tick(twoSeconds);
  context.mock.timers.tick(twoSeconds);

  assert.strictEqual(fn.mock.callCount(), 1);
});

Advancing time using .tick will also advance the time for any Date object created after the mock was enabled (if Date was also set to be mocked).

import assert from 'node:assert';
import { test } from 'node:test';

test('mocks setTimeout to be executed synchronously without having to actually wait for it', (context) => {
  const fn = context.mock.fn();

  context.mock.timers.enable({ apis: ['setTimeout', 'Date'] });
  setTimeout(fn, 9999);

  assert.strictEqual(fn.mock.callCount(), 0);
  assert.strictEqual(Date.now(), 0);

  // Advance in time
  context.mock.timers.tick(9999);
  assert.strictEqual(fn.mock.callCount(), 1);
  assert.strictEqual(Date.now(), 9999);
});

This function is used to create a mock function.

The following example creates a mock function that increments a counter by one on each invocation. The times option is used to modify the mock behavior such that the first two invocations add two to the counter instead of one.

test('mocks a counting function', (t) => {
  let cnt = 0;

  function addOne() {
    cnt++;
    return cnt;
  }

  function addTwo() {
    cnt += 2;
    return cnt;
  }

  const fn = t.mock.fn(addOne, addTwo, { times: 2 });

  assert.strictEqual(fn(), 2);
  assert.strictEqual(fn(), 4);
  assert.strictEqual(fn(), 5);
  assert.strictEqual(fn(), 6);
});

This function is syntax sugar for MockTracker.method with options.getter set to true.

This function is used to create a mock on an existing object method. The following example demonstrates how a mock is created on an existing object method.

test('spies on an object method', (t) => {
  const number = {
    value: 5,
    subtract(a) {
      return this.value - a;
    },
  };

  t.mock.method(number, 'subtract');
  assert.strictEqual(number.subtract.mock.calls.length, 0);
  assert.strictEqual(number.subtract(3), 2);
  assert.strictEqual(number.subtract.mock.calls.length, 1);

  const call = number.subtract.mock.calls[0];

  assert.deepStrictEqual(call.arguments, [3]);
  assert.strictEqual(call.result, 2);
  assert.strictEqual(call.error, undefined);
  assert.strictEqual(call.target, undefined);
  assert.strictEqual(call.this, number);
});

This function is used to mock the exports of ECMAScript modules, CommonJS modules, and Node.js builtin modules. Any references to the original module prior to mocking are not impacted.

Only available through the --experimental-test-module-mocks flag.

This function restores the default behavior of all mocks that were previously created by this MockTracker and disassociates the mocks from the MockTracker instance. Once disassociated, the mocks can still be used, but the MockTracker instance can no longer be used to reset their behavior or otherwise interact with them.

After each test completes, this function is called on the test context's MockTracker. If the global MockTracker is used extensively, calling this function manually is recommended.

This function restores the default behavior of all mocks that were previously created by this MockTracker. Unlike mock.reset(), mock.restoreAll() does not disassociate the mocks from the MockTracker instance.

This function is syntax sugar for MockTracker.method with options.setter set to true.

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

The name of the suite.

Can be used to abort test subtasks when the test has been aborted.

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.