test - Node documentation

Node

test

Usage in Deno

import * as mod from "node:test";

The node:test module facilitates the creation of JavaScript tests. To access it:

import test from 'node:test';

This module is only available under the node: scheme. The following will not work:

import test from 'node:test';

Tests created via the test module consist of a single function that is processed in one of three ways:

A synchronous function that is considered failing if it throws an exception, and is considered passing otherwise.
A function that returns a Promise that is considered failing if the Promise rejects, and is considered passing if the Promise fulfills.
A function that receives a callback function. If the callback receives any truthy value as its first argument, the test is considered failing. If a falsy value is passed as the first argument to the callback, the test is considered passing. If the test function receives a callback function and also returns a Promise, the test will fail.

The following example illustrates how tests are written using the test module.

test('synchronous passing test', (t) => {
  // This test passes because it does not throw an exception.
  assert.strictEqual(1, 1);
});

test('synchronous failing test', (t) => {
  // This test fails because it throws an exception.
  assert.strictEqual(1, 2);
});

test('asynchronous passing test', async (t) => {
  // This test passes because the Promise returned by the async
  // function is settled and not rejected.
  assert.strictEqual(1, 1);
});

test('asynchronous failing test', async (t) => {
  // This test fails because the Promise returned by the async
  // function is rejected.
  assert.strictEqual(1, 2);
});

test('failing test using Promises', (t) => {
  // Promises can be used directly as well.
  return new Promise((resolve, reject) => {
    setImmediate(() => {
      reject(new Error('this will cause the test to fail'));
    });
  });
});

test('callback passing test', (t, done) => {
  // done() is the callback function. When the setImmediate() runs, it invokes
  // done() with no arguments.
  setImmediate(done);
});

test('callback failing test', (t, done) => {
  // When the setImmediate() runs, done() is invoked with an Error object and
  // the test fails.
  setImmediate(() => {
    done(new Error('callback failure'));
  });
});

If any tests fail, the process exit code is set to 1.

Classes #

MockFunctionContext

The MockFunctionContext class is used to inspect or manipulate the behavior of mocks created via the MockTracker APIs.

MockModuleContext

No documentation available

restore

MockTimers

Mocking timers is a technique commonly used in software testing to simulate and control the behavior of timers, such as setInterval and setTimeout, without actually waiting for the specified time intervals.

MockTracker

The MockTracker class is used to manage mocking functionality. The test runner module provides a top level mock export which is a MockTracker instance. Each test also provides its own MockTracker instance via the test context's mock property.

SuiteContext

An instance of SuiteContext is passed to each suite function in order to interact with the test runner. However, the SuiteContext constructor is not exposed as part of the API.

TestContext

An instance of TestContext is passed to each test function in order to interact with the test runner. However, the TestContext constructor is not exposed as part of the API.

TestsStream

A successful call to run() will return a new TestsStream object, streaming a series of events representing the execution of the tests.

Functions #

after

This function creates a hook that runs after executing a suite.

afterEach

This function creates a hook that runs after each test in the current suite. The afterEach() hook is run even if the test fails.

assert.register

Defines a new assertion function with the provided name and function. If an assertion already exists with the same name, it is overwritten.

before

This function creates a hook that runs before executing a suite.

beforeEach

This function creates a hook that runs before each test in the current suite.

default

The test() function is the value imported from the test module. Each invocation of this function results in reporting the test to the TestsStream.

default.after

This function creates a hook that runs after executing a suite.

default.afterEach

This function creates a hook that runs after each test in the current suite. The afterEach() hook is run even if the test fails.

default.assert.register

Defines a new assertion function with the provided name and function. If an assertion already exists with the same name, it is overwritten.

default.before

This function creates a hook that runs before executing a suite.

default.beforeEach

This function creates a hook that runs before each test in the current suite.

default.describe

Alias for suite.

default.describe.only

Shorthand for marking a suite as only. This is the same as calling describe with options.only set to true.

default.describe.skip

Shorthand for skipping a suite. This is the same as calling describe with options.skip set to true.

default.describe.todo

Shorthand for marking a suite as TODO. This is the same as calling describe with options.todo set to true.

default.it

Alias for test.

default.it.only

Shorthand for marking a test as only. This is the same as calling it with options.only set to true.

default.it.skip

Shorthand for skipping a test. This is the same as calling it with options.skip set to true.

default.it.todo

Shorthand for marking a test as TODO. This is the same as calling it with options.todo set to true.

default.only

Shorthand for marking a test as only. This is the same as calling test with options.only set to true.

default.run

Note: shard is used to horizontally parallelize test running across machines or processes, ideal for large-scale executions across varied environments. It's incompatible with watch mode, tailored for rapid code iteration by automatically rerunning tests on file changes.

default.skip

Shorthand for skipping a test. This is the same as calling test with options.skip set to true.

default.snapshot.setDefaultSnapshotSerializers

This function is used to customize the default serialization mechanism used by the test runner.

default.snapshot.setResolveSnapshotPath

This function is used to set a custom resolver for the location of the snapshot file used for snapshot testing. By default, the snapshot filename is the same as the entry point filename with .snapshot appended.

default.suite

The suite() function is imported from the node:test module.

default.suite.only

Shorthand for marking a suite as only. This is the same as calling suite with options.only set to true.

default.suite.skip

Shorthand for skipping a suite. This is the same as calling suite with options.skip set to true.

default.suite.todo

Shorthand for marking a suite as TODO. This is the same as calling suite with options.todo set to true.

default.todo

Shorthand for marking a test as TODO. This is the same as calling test with options.todo set to true.

describe

Alias for suite.

describe.only

Shorthand for marking a suite as only. This is the same as calling describe with options.only set to true.

describe.skip

Shorthand for skipping a suite. This is the same as calling describe with options.skip set to true.

describe.todo

Shorthand for marking a suite as TODO. This is the same as calling describe with options.todo set to true.

Alias for test.

it.only

Shorthand for marking a test as only. This is the same as calling it with options.only set to true.

it.skip

Shorthand for skipping a test. This is the same as calling it with options.skip set to true.

it.todo

Shorthand for marking a test as TODO. This is the same as calling it with options.todo set to true.

only

Shorthand for marking a test as only. This is the same as calling test with options.only set to true.

run

skip

Shorthand for skipping a test. This is the same as calling test with options.skip set to true.

snapshot.setDefaultSnapshotSerializers

This function is used to customize the default serialization mechanism used by the test runner.

snapshot.setResolveSnapshotPath

suite

The suite() function is imported from the node:test module.

suite.only

Shorthand for marking a suite as only. This is the same as calling suite with options.only set to true.

suite.skip

Shorthand for skipping a suite. This is the same as calling suite with options.skip set to true.

suite.todo

Shorthand for marking a suite as TODO. This is the same as calling suite with options.todo set to true.

test

The test() function is the value imported from the test module. Each invocation of this function results in reporting the test to the TestsStream.

test.after

This function creates a hook that runs after executing a suite.

test.afterEach

This function creates a hook that runs after each test in the current suite. The afterEach() hook is run even if the test fails.

test.assert.register

Defines a new assertion function with the provided name and function. If an assertion already exists with the same name, it is overwritten.

test.before

This function creates a hook that runs before executing a suite.

test.beforeEach

This function creates a hook that runs before each test in the current suite.

test.describe

Alias for suite.

test.describe.only

Shorthand for marking a suite as only. This is the same as calling describe with options.only set to true.

test.describe.skip

Shorthand for skipping a suite. This is the same as calling describe with options.skip set to true.

test.describe.todo

Shorthand for marking a suite as TODO. This is the same as calling describe with options.todo set to true.

test.it

Alias for test.

test.it.only

Shorthand for marking a test as only. This is the same as calling it with options.only set to true.

test.it.skip

Shorthand for skipping a test. This is the same as calling it with options.skip set to true.

test.it.todo

Shorthand for marking a test as TODO. This is the same as calling it with options.todo set to true.

test.only

Shorthand for marking a test as only. This is the same as calling test with options.only set to true.

test.run

test.skip

Shorthand for skipping a test. This is the same as calling test with options.skip set to true.

test.snapshot.setDefaultSnapshotSerializers

This function is used to customize the default serialization mechanism used by the test runner.

test.snapshot.setResolveSnapshotPath

test.suite

The suite() function is imported from the node:test module.

test.suite.only

Shorthand for marking a suite as only. This is the same as calling suite with options.only set to true.

test.suite.skip

Shorthand for skipping a suite. This is the same as calling suite with options.skip set to true.

test.suite.todo

Shorthand for marking a suite as TODO. This is the same as calling suite with options.todo set to true.

test.todo

Shorthand for marking a test as TODO. This is the same as calling test with options.todo set to true.

todo

Shorthand for marking a test as TODO. This is the same as calling test with options.todo set to true.

Interfaces #

AssertSnapshotOptions

No documentation available

serializers

HookOptions

Configuration options for hooks.

MockFunctionCall

No documentation available

MockFunctionOptions

No documentation available

times

MockMethodOptions

No documentation available

MockModuleOptions

No documentation available

MockTimersOptions

No documentation available

TestContextAssert

No documentation available

TestContextWaitForOptions

No documentation available

TestOptions

No documentation available

TestShard

No documentation available

Namespaces #

assert

An object whose methods are used to configure available assertions on the TestContext objects in the current process. The methods from node:assert and snapshot testing functions are available by default.

default.assert

default.snapshot

No documentation available

snapshot

No documentation available

test.assert

test.snapshot

No documentation available

Type Aliases #

FunctionPropertyNames

No documentation available

HookFn

The hook function. The first argument is the context in which the hook is called. If the hook uses callbacks, the callback function is passed as the second argument.

Mock

No documentation available

NoOpFunction

No documentation available

SuiteFn

The type of a suite test function. The argument to this function is a SuiteContext object.

TestContextHookFn

The hook function. The first argument is a TestContext object. If the hook uses callbacks, the callback function is passed as the second argument.

TestFn

The type of a function passed to test. The first argument to this function is a TestContext object. If the test uses callbacks, the callback function is passed as the second argument.

Timer

No documentation available