test

History

test(name?, options?, fn?): Promise

Attributes

name?:string

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

options:Object

Configuration options for the test. The following properties are supported:

concurrency?:number | boolean

If a number is provided, then that many tests would run asynchronously (they are still managed by the single-threaded event loop). If true, all scheduled asynchronous tests run concurrently within the thread. If false, only one test runs at a time. If unspecified, subtests inherit this value from their parent. Default: false.

If truthy, the test is expected to fail. If a non-empty string is provided, that string is displayed in the test results as the reason why the test is expected to fail. If a RegExp | Function | Object | Error is provided directly (without wrapping in { match: … }), the test passes only if the thrown error matches, following the behavior of assert.throws. To provide both a reason and validation, pass an object with label (string) and match (RegExp, Function, Object, or Error). Default: false.

only?:boolean

If truthy, and the test context is configured to run only tests, then this test will be run. Otherwise, the test is skipped. Default: false.

signal:AbortSignal

Allows aborting an in-progress test.

skip?:boolean | string

If truthy, the test is skipped. If a string is provided, that string is displayed in the test results as the reason for skipping the test. Default: false.

tags?:string[]

An array of string labels associated with the test. Used together with --experimental-test-tag-filter to filter which tests run. Tags inherit from suites to nested tests by union. See Test tags. Default: [].

todo?:boolean | string

If truthy, the test marked as TODO. If a string is provided, that string is displayed in the test results as the reason why the test is TODO. Default: false.

timeout?:number

A number of milliseconds the test will fail after. If unspecified, subtests inherit this value from their parent. Default: Infinity.

plan?:number

The number of assertions and subtests expected to be run in the test. If the number of assertions run in the test does not match the number specified in the plan, the test will fail. Default: undefined.

fn:Function | AsyncFunction

The function under test. If provided, it will take precedence over the fn parameter.

name:string

The name of the test. If provided, it will take precedence over the name parameter.

fn?:Function | AsyncFunction

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. Default: A no-op function.

Returns:Promise

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

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

JavaScript

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.