Bun

Node.js module

node:test

The 'node:test' module is Node.js's built-in test runner that provides a zero-dependency testing framework. It supports test() functions, lifecycle hooks (before, after), and assertions.

Tests run in isolation with concurrent support, snapshot testing, and detailed reporting, making it a lightweight alternative to external test frameworks.

Works in Bun

Basic test runner structure exists but lacks key features like mocking, snapshot testing, and timer manipulation/mocking. Use `bun:test` for a more complete testing solution.

  • namespace 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.

    It is possible to apply the same configuration to all files by placing common configuration code in a module preloaded with --require or --import.

    • function register(
      name: string,
      fn: (this: TestContext, ...args: any[]) => void
      ): void;

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

  • function describe(
    name?: string,
    options?: TestOptions,
    fn?: SuiteFn
    ): Promise<void>;

    Alias for suite.

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

    function describe(
    name?: string,
    fn?: SuiteFn
    ): Promise<void>;

    Alias for suite.

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

    function describe(
    options?: TestOptions,
    fn?: SuiteFn
    ): Promise<void>;

    Alias for suite.

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

    function describe(
    fn?: SuiteFn
    ): Promise<void>;

    Alias for suite.

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

    namespace describe

    • function only(
      name?: string,
      options?: TestOptions,
      fn?: SuiteFn
      ): Promise<void>;

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

      function only(
      name?: string,
      fn?: SuiteFn
      ): Promise<void>;

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

      function only(
      options?: TestOptions,
      fn?: SuiteFn
      ): Promise<void>;

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

      function only(
      fn?: SuiteFn
      ): Promise<void>;

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

    • function skip(
      name?: string,
      options?: TestOptions,
      fn?: SuiteFn
      ): Promise<void>;

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

      function skip(
      name?: string,
      fn?: SuiteFn
      ): Promise<void>;

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

      function skip(
      options?: TestOptions,
      fn?: SuiteFn
      ): Promise<void>;

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

      function skip(
      fn?: SuiteFn
      ): Promise<void>;

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

    • function todo(
      name?: string,
      options?: TestOptions,
      fn?: SuiteFn
      ): Promise<void>;

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

      function todo(
      name?: string,
      fn?: SuiteFn
      ): Promise<void>;

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

      function todo(
      options?: TestOptions,
      fn?: SuiteFn
      ): Promise<void>;

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

      function todo(
      fn?: SuiteFn
      ): Promise<void>;

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

  • function it(
    name?: string,
    options?: TestOptions,
    fn?: TestFn
    ): Promise<void>;

    Alias for test.

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

    function it(
    name?: string,
    fn?: TestFn
    ): Promise<void>;

    Alias for test.

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

    function it(
    options?: TestOptions,
    fn?: TestFn
    ): Promise<void>;

    Alias for test.

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

    function it(
    fn?: TestFn
    ): Promise<void>;

    Alias for test.

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

    namespace it

    • function only(
      name?: string,
      options?: TestOptions,
      fn?: TestFn
      ): Promise<void>;

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

      function only(
      name?: string,
      fn?: TestFn
      ): Promise<void>;

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

      function only(
      options?: TestOptions,
      fn?: TestFn
      ): Promise<void>;

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

      function only(
      fn?: TestFn
      ): Promise<void>;

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

    • function skip(
      name?: string,
      options?: TestOptions,
      fn?: TestFn
      ): Promise<void>;

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

      function skip(
      name?: string,
      fn?: TestFn
      ): Promise<void>;

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

      function skip(
      options?: TestOptions,
      fn?: TestFn
      ): Promise<void>;

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

      function skip(
      fn?: TestFn
      ): Promise<void>;

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

    • function todo(
      name?: string,
      options?: TestOptions,
      fn?: TestFn
      ): Promise<void>;

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

      function todo(
      name?: string,
      fn?: TestFn
      ): Promise<void>;

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

      function todo(
      options?: TestOptions,
      fn?: TestFn
      ): Promise<void>;

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

      function todo(
      fn?: TestFn
      ): Promise<void>;

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

  • namespace snapshot

    • serializers: readonly (value: any) => any[]
      ): void;

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

      By default, the test runner performs serialization by calling JSON.stringify(value, null, 2) on the provided value. JSON.stringify() does have limitations regarding circular structures and supported data types. If a more robust serialization mechanism is required, this function should be used to specify a list of custom serializers.

      Serializers are called in order, with the output of the previous serializer passed as input to the next. The final result must be a string value.

      @param serializers

      An array of synchronous functions used as the default serializers for snapshot tests.

    • fn: (path: undefined | string) => string
      ): void;

      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.

      @param fn

      A function used to compute the location of the snapshot file. The function receives the path of the test file as its only argument. If the test is not associated with a file (for example in the REPL), the input is undefined. fn() must return a string specifying the location of the snapshot file.

  • function suite(
    name?: string,
    options?: TestOptions,
    fn?: SuiteFn
    ): Promise<void>;

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

    @param name

    The name of the suite, which is displayed when reporting test results. Defaults to the name property of fn, or '<anonymous>' if fn does not have a name.

    @param options

    Configuration options for the suite. This supports the same options as test.

    @param fn

    The suite function declaring nested tests and suites. The first argument to this function is a SuiteContext object.

    @returns

    Immediately fulfilled with undefined.

    function suite(
    name?: string,
    fn?: SuiteFn
    ): Promise<void>;

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

    @param name

    The name of the suite, which is displayed when reporting test results. Defaults to the name property of fn, or '<anonymous>' if fn does not have a name.

    @param fn

    The suite function declaring nested tests and suites. The first argument to this function is a SuiteContext object.

    @returns

    Immediately fulfilled with undefined.

    function suite(
    options?: TestOptions,
    fn?: SuiteFn
    ): Promise<void>;

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

    @param options

    Configuration options for the suite. This supports the same options as test.

    @param fn

    The suite function declaring nested tests and suites. The first argument to this function is a SuiteContext object.

    @returns

    Immediately fulfilled with undefined.

    function suite(
    fn?: SuiteFn
    ): Promise<void>;

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

    @param fn

    The suite function declaring nested tests and suites. The first argument to this function is a SuiteContext object.

    @returns

    Immediately fulfilled with undefined.

    namespace suite

    • function only(
      name?: string,
      options?: TestOptions,
      fn?: SuiteFn
      ): Promise<void>;

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

      function only(
      name?: string,
      fn?: SuiteFn
      ): Promise<void>;

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

      function only(
      options?: TestOptions,
      fn?: SuiteFn
      ): Promise<void>;

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

      function only(
      fn?: SuiteFn
      ): Promise<void>;

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

    • function skip(
      name?: string,
      options?: TestOptions,
      fn?: SuiteFn
      ): Promise<void>;

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

      function skip(
      name?: string,
      fn?: SuiteFn
      ): Promise<void>;

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

      function skip(
      options?: TestOptions,
      fn?: SuiteFn
      ): Promise<void>;

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

      function skip(
      fn?: SuiteFn
      ): Promise<void>;

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

    • function todo(
      name?: string,
      options?: TestOptions,
      fn?: SuiteFn
      ): Promise<void>;

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

      function todo(
      name?: string,
      fn?: SuiteFn
      ): Promise<void>;

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

      function todo(
      options?: TestOptions,
      fn?: SuiteFn
      ): Promise<void>;

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

      function todo(
      fn?: SuiteFn
      ): Promise<void>;

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

  • function test(
    name?: string,
    fn?: TestFn
    ): Promise<void>;

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

    The TestContext object passed to the fn argument can be used to perform actions related to the current test. Examples include skipping the test, adding additional diagnostic information, or creating subtests.

    test() returns a Promise that fulfills once the test completes. if test() is called within a suite, it fulfills immediately. The return value can usually be discarded for top level tests. However, the return value from subtests should be used to prevent the parent test from finishing first and cancelling the subtest as shown in the following example.

    test('top level test', async (t) => {
      // The setTimeout() in the following subtest would cause it to outlive its
      // parent test if 'await' is removed on the next line. Once the parent test
      // completes, it will cancel any outstanding subtests.
      await t.test('longer running subtest', async (t) => {
        return new Promise((resolve, reject) => {
          setTimeout(resolve, 1000);
        });
      });
    });
    

    The timeout option can be used to fail the test if it takes longer than timeout milliseconds to complete. However, it is not a reliable mechanism for canceling tests because a running test might block the application thread and thus prevent the scheduled cancellation.

    @param name

    The name of the test, which is displayed when reporting test results. Defaults to the name property of fn, or '<anonymous>' if fn does not have a name.

    @param fn

    The function under 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.

    @returns

    Fulfilled with undefined once the test completes, or immediately if the test runs within a suite.

    function test(
    name?: string,
    options?: TestOptions,
    fn?: TestFn
    ): Promise<void>;

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

    The TestContext object passed to the fn argument can be used to perform actions related to the current test. Examples include skipping the test, adding additional diagnostic information, or creating subtests.

    test() returns a Promise that fulfills once the test completes. if test() is called within a suite, it fulfills immediately. The return value can usually be discarded for top level tests. However, the return value from subtests should be used to prevent the parent test from finishing first and cancelling the subtest as shown in the following example.

    test('top level test', async (t) => {
      // The setTimeout() in the following subtest would cause it to outlive its
      // parent test if 'await' is removed on the next line. Once the parent test
      // completes, it will cancel any outstanding subtests.
      await t.test('longer running subtest', async (t) => {
        return new Promise((resolve, reject) => {
          setTimeout(resolve, 1000);
        });
      });
    });
    

    The timeout option can be used to fail the test if it takes longer than timeout milliseconds to complete. However, it is not a reliable mechanism for canceling tests because a running test might block the application thread and thus prevent the scheduled cancellation.

    @param name

    The name of the test, which is displayed when reporting test results. Defaults to the name property of fn, or '<anonymous>' if fn does not have a name.

    @param options

    Configuration options for the test.

    @param fn

    The function under 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.

    @returns

    Fulfilled with undefined once the test completes, or immediately if the test runs within a suite.

    function test(
    options?: TestOptions,
    fn?: TestFn
    ): Promise<void>;

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

    The TestContext object passed to the fn argument can be used to perform actions related to the current test. Examples include skipping the test, adding additional diagnostic information, or creating subtests.

    test() returns a Promise that fulfills once the test completes. if test() is called within a suite, it fulfills immediately. The return value can usually be discarded for top level tests. However, the return value from subtests should be used to prevent the parent test from finishing first and cancelling the subtest as shown in the following example.

    test('top level test', async (t) => {
      // The setTimeout() in the following subtest would cause it to outlive its
      // parent test if 'await' is removed on the next line. Once the parent test
      // completes, it will cancel any outstanding subtests.
      await t.test('longer running subtest', async (t) => {
        return new Promise((resolve, reject) => {
          setTimeout(resolve, 1000);
        });
      });
    });
    

    The timeout option can be used to fail the test if it takes longer than timeout milliseconds to complete. However, it is not a reliable mechanism for canceling tests because a running test might block the application thread and thus prevent the scheduled cancellation.

    @param options

    Configuration options for the test.

    @param fn

    The function under 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.

    @returns

    Fulfilled with undefined once the test completes, or immediately if the test runs within a suite.

    function test(
    fn?: TestFn
    ): Promise<void>;

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

    The TestContext object passed to the fn argument can be used to perform actions related to the current test. Examples include skipping the test, adding additional diagnostic information, or creating subtests.

    test() returns a Promise that fulfills once the test completes. if test() is called within a suite, it fulfills immediately. The return value can usually be discarded for top level tests. However, the return value from subtests should be used to prevent the parent test from finishing first and cancelling the subtest as shown in the following example.

    test('top level test', async (t) => {
      // The setTimeout() in the following subtest would cause it to outlive its
      // parent test if 'await' is removed on the next line. Once the parent test
      // completes, it will cancel any outstanding subtests.
      await t.test('longer running subtest', async (t) => {
        return new Promise((resolve, reject) => {
          setTimeout(resolve, 1000);
        });
      });
    });
    

    The timeout option can be used to fail the test if it takes longer than timeout milliseconds to complete. However, it is not a reliable mechanism for canceling tests because a running test might block the application thread and thus prevent the scheduled cancellation.

    @param fn

    The function under 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.

    @returns

    Fulfilled with undefined once the test completes, or immediately if the test runs within a suite.

    namespace test

  • class 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.

    • readonly filePath: undefined | string

      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.

    • readonly name: string

      The name of the suite.

    • readonly signal: AbortSignal

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

  • class 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.

    • readonly assert: TestContextAssert

      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.
      });
      
    • readonly filePath: undefined | string

      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.

    • readonly fullName: string

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

    • readonly mock: MockTracker

      Each test provides its own MockTracker instance.

    • readonly name: string

      The name of the test.

    • readonly signal: AbortSignal
      test('top level test', async (t) => {
        await fetch('some/uri', { signal: t.signal });
      });
      
    • test: typeof 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.

    • fn?: TestContextHookFn,
      options?: HookOptions
      ): void;

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

      @param fn

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

      @param options

      Configuration options for the hook.

    • fn?: TestContextHookFn,
      options?: HookOptions
      ): void;

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

      @param fn

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

      @param options

      Configuration options for the hook.

    • fn?: TestContextHookFn,
      options?: HookOptions
      ): void;

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

      @param fn

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

      @param options

      Configuration options for the hook.

    • fn?: TestContextHookFn,
      options?: HookOptions
      ): void;

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

      @param fn

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

      @param options

      Configuration options for the hook.

    • message: string
      ): void;

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

      Message to be reported.

    • count: number,
      options?: TestContextPlanOptions
      ): void;

      This function is 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.

      Note: To make sure assertions are tracked, t.assert must be used instead of assert directly.

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

      When using the wait option, you can control how long the test will wait for the expected assertions. For example, setting a maximum wait time ensures that the test will wait for asynchronous assertions to complete within the specified timeframe:

      test('plan with wait: 2000 waits for async assertions', (t) => {
        t.plan(1, { wait: 2000 }); // Waits for up to 2 seconds for the assertion to complete.
      
        const asyncActivity = () => {
          setTimeout(() => {
               *       t.assert.ok(true, 'Async assertion completed within the wait time');
          }, 1000); // Completes after 1 second, within the 2-second wait time.
        };
      
        asyncActivity(); // The test will pass because the assertion is completed in time.
      });
      

      Note: If a wait timeout is specified, it begins counting down only after the test function finishes executing.

    • shouldRunOnlyTests: boolean
      ): void;

      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 }),
        ]);
      });
      
      @param shouldRunOnlyTests

      Whether or not to run only tests.

    • message?: string
      ): void;

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

      Optional skip message.

    • message?: string
      ): void;

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

      Optional TODO message.

    • condition: () => T,
      options?: TestContextWaitForOptions
      ): Promise<Awaited<T>>;

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

      @param condition

      An assertion function that is invoked periodically until it completes successfully or the defined polling timeout elapses. Successful completion is defined as not throwing or rejecting. This function does not accept any arguments, and is allowed to return any value.

      @param options

      An optional configuration object for the polling operation.

      @returns

      Fulfilled with the value returned by condition.

  • const mock: MockTracker
  • function after(
    fn?: HookFn,
    options?: HookOptions
    ): void;

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

    describe('tests', async () => {
      after(() => console.log('finished running tests'));
      it('is a subtest', () => {
        assert.ok('some relevant assertion here');
      });
    });
    
    @param fn

    The hook function. If the hook uses callbacks, the callback function is passed as the second argument.

    @param options

    Configuration options for the hook.

  • function afterEach(
    fn?: HookFn,
    options?: HookOptions
    ): void;

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

    describe('tests', async () => {
      afterEach(() => console.log('finished running a test'));
      it('is a subtest', () => {
        assert.ok('some relevant assertion here');
      });
    });
    
    @param fn

    The hook function. If the hook uses callbacks, the callback function is passed as the second argument.

    @param options

    Configuration options for the hook.

  • function before(
    fn?: HookFn,
    options?: HookOptions
    ): void;

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

    describe('tests', async () => {
      before(() => console.log('about to run some test'));
      it('is a subtest', () => {
        assert.ok('some relevant assertion here');
      });
    });
    
    @param fn

    The hook function. If the hook uses callbacks, the callback function is passed as the second argument.

    @param options

    Configuration options for the hook.

  • function beforeEach(
    fn?: HookFn,
    options?: HookOptions
    ): void;

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

    describe('tests', async () => {
      beforeEach(() => console.log('about to run a test'));
      it('is a subtest', () => {
        assert.ok('some relevant assertion here');
      });
    });
    
    @param fn

    The hook function. If the hook uses callbacks, the callback function is passed as the second argument.

    @param options

    Configuration options for the hook.

  • function describe(
    name?: string,
    options?: TestOptions,
    fn?: SuiteFn
    ): Promise<void>;

    Alias for suite.

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

    function describe(
    name?: string,
    fn?: SuiteFn
    ): Promise<void>;

    Alias for suite.

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

    function describe(
    options?: TestOptions,
    fn?: SuiteFn
    ): Promise<void>;

    Alias for suite.

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

    function describe(
    fn?: SuiteFn
    ): Promise<void>;

    Alias for suite.

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

    function only(
    name?: string,
    options?: TestOptions,
    fn?: SuiteFn
    ): Promise<void>;

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

    function only(
    name?: string,
    fn?: SuiteFn
    ): Promise<void>;

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

    function only(
    options?: TestOptions,
    fn?: SuiteFn
    ): Promise<void>;

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

    function only(
    fn?: SuiteFn
    ): Promise<void>;

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

    function skip(
    name?: string,
    options?: TestOptions,
    fn?: SuiteFn
    ): Promise<void>;

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

    function skip(
    name?: string,
    fn?: SuiteFn
    ): Promise<void>;

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

    function skip(
    options?: TestOptions,
    fn?: SuiteFn
    ): Promise<void>;

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

    function skip(
    fn?: SuiteFn
    ): Promise<void>;

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

    function todo(
    name?: string,
    options?: TestOptions,
    fn?: SuiteFn
    ): Promise<void>;

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

    function todo(
    name?: string,
    fn?: SuiteFn
    ): Promise<void>;

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

    function todo(
    options?: TestOptions,
    fn?: SuiteFn
    ): Promise<void>;

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

    function todo(
    fn?: SuiteFn
    ): Promise<void>;

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

  • function it(
    name?: string,
    options?: TestOptions,
    fn?: TestFn
    ): Promise<void>;

    Alias for test.

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

    function it(
    name?: string,
    fn?: TestFn
    ): Promise<void>;

    Alias for test.

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

    function it(
    options?: TestOptions,
    fn?: TestFn
    ): Promise<void>;

    Alias for test.

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

    function it(
    fn?: TestFn
    ): Promise<void>;

    Alias for test.

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

    function only(
    name?: string,
    options?: TestOptions,
    fn?: TestFn
    ): Promise<void>;

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

    function only(
    name?: string,
    fn?: TestFn
    ): Promise<void>;

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

    function only(
    options?: TestOptions,
    fn?: TestFn
    ): Promise<void>;

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

    function only(
    fn?: TestFn
    ): Promise<void>;

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

    function skip(
    name?: string,
    options?: TestOptions,
    fn?: TestFn
    ): Promise<void>;

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

    function skip(
    name?: string,
    fn?: TestFn
    ): Promise<void>;

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

    function skip(
    options?: TestOptions,
    fn?: TestFn
    ): Promise<void>;

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

    function skip(
    fn?: TestFn
    ): Promise<void>;

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

    function todo(
    name?: string,
    options?: TestOptions,
    fn?: TestFn
    ): Promise<void>;

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

    function todo(
    name?: string,
    fn?: TestFn
    ): Promise<void>;

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

    function todo(
    options?: TestOptions,
    fn?: TestFn
    ): Promise<void>;

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

    function todo(
    fn?: TestFn
    ): Promise<void>;

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

  • function only(
    name?: string,
    options?: TestOptions,
    fn?: TestFn
    ): Promise<void>;

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

    function only(
    name?: string,
    fn?: TestFn
    ): Promise<void>;

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

    function only(
    options?: TestOptions,
    fn?: TestFn
    ): Promise<void>;

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

    function only(
    fn?: TestFn
    ): Promise<void>;

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

  • function run(
    options?: RunOptions
    ): TestsStream;

    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.

    import { tap } from 'node:test/reporters';
    import { run } from 'node:test';
    import process from 'node:process';
    import path from 'node:path';
    
    run({ files: [path.resolve('./tests/test.js')] })
      .compose(tap)
      .pipe(process.stdout);
    
    @param options

    Configuration options for running tests.

  • function skip(
    name?: string,
    options?: TestOptions,
    fn?: TestFn
    ): Promise<void>;

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

    function skip(
    name?: string,
    fn?: TestFn
    ): Promise<void>;

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

    function skip(
    options?: TestOptions,
    fn?: TestFn
    ): Promise<void>;

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

    function skip(
    fn?: TestFn
    ): Promise<void>;

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

  • function suite(
    name?: string,
    options?: TestOptions,
    fn?: SuiteFn
    ): Promise<void>;

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

    @param name

    The name of the suite, which is displayed when reporting test results. Defaults to the name property of fn, or '<anonymous>' if fn does not have a name.

    @param options

    Configuration options for the suite. This supports the same options as test.

    @param fn

    The suite function declaring nested tests and suites. The first argument to this function is a SuiteContext object.

    @returns

    Immediately fulfilled with undefined.

    function suite(
    name?: string,
    fn?: SuiteFn
    ): Promise<void>;

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

    @param name

    The name of the suite, which is displayed when reporting test results. Defaults to the name property of fn, or '<anonymous>' if fn does not have a name.

    @param fn

    The suite function declaring nested tests and suites. The first argument to this function is a SuiteContext object.

    @returns

    Immediately fulfilled with undefined.

    function suite(
    options?: TestOptions,
    fn?: SuiteFn
    ): Promise<void>;

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

    @param options

    Configuration options for the suite. This supports the same options as test.

    @param fn

    The suite function declaring nested tests and suites. The first argument to this function is a SuiteContext object.

    @returns

    Immediately fulfilled with undefined.

    function suite(
    fn?: SuiteFn
    ): Promise<void>;

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

    @param fn

    The suite function declaring nested tests and suites. The first argument to this function is a SuiteContext object.

    @returns

    Immediately fulfilled with undefined.

    function only(
    name?: string,
    options?: TestOptions,
    fn?: SuiteFn
    ): Promise<void>;

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

    function only(
    name?: string,
    fn?: SuiteFn
    ): Promise<void>;

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

    function only(
    options?: TestOptions,
    fn?: SuiteFn
    ): Promise<void>;

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

    function only(
    fn?: SuiteFn
    ): Promise<void>;

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

    function skip(
    name?: string,
    options?: TestOptions,
    fn?: SuiteFn
    ): Promise<void>;

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

    function skip(
    name?: string,
    fn?: SuiteFn
    ): Promise<void>;

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

    function skip(
    options?: TestOptions,
    fn?: SuiteFn
    ): Promise<void>;

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

    function skip(
    fn?: SuiteFn
    ): Promise<void>;

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

    function todo(
    name?: string,
    options?: TestOptions,
    fn?: SuiteFn
    ): Promise<void>;

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

    function todo(
    name?: string,
    fn?: SuiteFn
    ): Promise<void>;

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

    function todo(
    options?: TestOptions,
    fn?: SuiteFn
    ): Promise<void>;

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

    function todo(
    fn?: SuiteFn
    ): Promise<void>;

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

  • function test(
    name?: string,
    fn?: TestFn
    ): Promise<void>;

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

    The TestContext object passed to the fn argument can be used to perform actions related to the current test. Examples include skipping the test, adding additional diagnostic information, or creating subtests.

    test() returns a Promise that fulfills once the test completes. if test() is called within a suite, it fulfills immediately. The return value can usually be discarded for top level tests. However, the return value from subtests should be used to prevent the parent test from finishing first and cancelling the subtest as shown in the following example.

    test('top level test', async (t) => {
      // The setTimeout() in the following subtest would cause it to outlive its
      // parent test if 'await' is removed on the next line. Once the parent test
      // completes, it will cancel any outstanding subtests.
      await t.test('longer running subtest', async (t) => {
        return new Promise((resolve, reject) => {
          setTimeout(resolve, 1000);
        });
      });
    });
    

    The timeout option can be used to fail the test if it takes longer than timeout milliseconds to complete. However, it is not a reliable mechanism for canceling tests because a running test might block the application thread and thus prevent the scheduled cancellation.

    @param name

    The name of the test, which is displayed when reporting test results. Defaults to the name property of fn, or '<anonymous>' if fn does not have a name.

    @param fn

    The function under 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.

    @returns

    Fulfilled with undefined once the test completes, or immediately if the test runs within a suite.

    function test(
    name?: string,
    options?: TestOptions,
    fn?: TestFn
    ): Promise<void>;

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

    The TestContext object passed to the fn argument can be used to perform actions related to the current test. Examples include skipping the test, adding additional diagnostic information, or creating subtests.

    test() returns a Promise that fulfills once the test completes. if test() is called within a suite, it fulfills immediately. The return value can usually be discarded for top level tests. However, the return value from subtests should be used to prevent the parent test from finishing first and cancelling the subtest as shown in the following example.

    test('top level test', async (t) => {
      // The setTimeout() in the following subtest would cause it to outlive its
      // parent test if 'await' is removed on the next line. Once the parent test
      // completes, it will cancel any outstanding subtests.
      await t.test('longer running subtest', async (t) => {
        return new Promise((resolve, reject) => {
          setTimeout(resolve, 1000);
        });
      });
    });
    

    The timeout option can be used to fail the test if it takes longer than timeout milliseconds to complete. However, it is not a reliable mechanism for canceling tests because a running test might block the application thread and thus prevent the scheduled cancellation.

    @param name

    The name of the test, which is displayed when reporting test results. Defaults to the name property of fn, or '<anonymous>' if fn does not have a name.

    @param options

    Configuration options for the test.

    @param fn

    The function under 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.

    @returns

    Fulfilled with undefined once the test completes, or immediately if the test runs within a suite.

    function test(
    options?: TestOptions,
    fn?: TestFn
    ): Promise<void>;

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

    The TestContext object passed to the fn argument can be used to perform actions related to the current test. Examples include skipping the test, adding additional diagnostic information, or creating subtests.

    test() returns a Promise that fulfills once the test completes. if test() is called within a suite, it fulfills immediately. The return value can usually be discarded for top level tests. However, the return value from subtests should be used to prevent the parent test from finishing first and cancelling the subtest as shown in the following example.

    test('top level test', async (t) => {
      // The setTimeout() in the following subtest would cause it to outlive its
      // parent test if 'await' is removed on the next line. Once the parent test
      // completes, it will cancel any outstanding subtests.
      await t.test('longer running subtest', async (t) => {
        return new Promise((resolve, reject) => {
          setTimeout(resolve, 1000);
        });
      });
    });
    

    The timeout option can be used to fail the test if it takes longer than timeout milliseconds to complete. However, it is not a reliable mechanism for canceling tests because a running test might block the application thread and thus prevent the scheduled cancellation.

    @param options

    Configuration options for the test.

    @param fn

    The function under 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.

    @returns

    Fulfilled with undefined once the test completes, or immediately if the test runs within a suite.

    function test(
    fn?: TestFn
    ): Promise<void>;

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

    The TestContext object passed to the fn argument can be used to perform actions related to the current test. Examples include skipping the test, adding additional diagnostic information, or creating subtests.

    test() returns a Promise that fulfills once the test completes. if test() is called within a suite, it fulfills immediately. The return value can usually be discarded for top level tests. However, the return value from subtests should be used to prevent the parent test from finishing first and cancelling the subtest as shown in the following example.

    test('top level test', async (t) => {
      // The setTimeout() in the following subtest would cause it to outlive its
      // parent test if 'await' is removed on the next line. Once the parent test
      // completes, it will cancel any outstanding subtests.
      await t.test('longer running subtest', async (t) => {
        return new Promise((resolve, reject) => {
          setTimeout(resolve, 1000);
        });
      });
    });
    

    The timeout option can be used to fail the test if it takes longer than timeout milliseconds to complete. However, it is not a reliable mechanism for canceling tests because a running test might block the application thread and thus prevent the scheduled cancellation.

    @param fn

    The function under 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.

    @returns

    Fulfilled with undefined once the test completes, or immediately if the test runs within a suite.

  • function todo(
    name?: string,
    options?: TestOptions,
    fn?: TestFn
    ): Promise<void>;

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

    function todo(
    name?: string,
    fn?: TestFn
    ): Promise<void>;

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

    function todo(
    options?: TestOptions,
    fn?: TestFn
    ): Promise<void>;

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

    function todo(
    fn?: TestFn
    ): Promise<void>;

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

Type definitions

  • type Mock<F extends Function> = F & { mock: MockFunctionContext<F> }