稳定性：2 - 稳定

node:test 模块有助于创建 JavaScript 测试。 要访问它：

import test from 'node:test';

此模块仅在 node: 方案下可用。

通过 test 模块创建的测试由单个函数组成，该函数通过以下三种方式之一进行处理：

1. 一个同步函数，如果抛出异常则视为失败，否则视为通过。
2. 一个返回 Promise 的函数，如果 Promise 被拒绝则视为失败，如果 Promise 被履行则视为通过。
3. 一个接收回调函数的函数。如果回调接收任何真值作为其第一个参数，则测试视为失败。如果将假值作为第一个参数传递给回调，则测试视为通过。如果测试函数接收回调函数并且还返回 Promise，则测试将失败。

以下示例说明了如何使用 test 模块编写测试。

test('同步通过测试', (t) => {
  // 此测试通过，因为它没有抛出异常。
  assert.strictEqual(1, 1);
});

test('同步失败测试', (t) => {
  // 此测试失败，因为它抛出了异常。
  assert.strictEqual(1, 2);
});

test('异步通过测试', async (t) => {
  // 此测试通过，因为 async 函数返回的 Promise 已结算且未被拒绝。
  assert.strictEqual(1, 1);
});

test('异步失败测试', async (t) => {
  // 此测试失败，因为 async 函数返回的 Promise 被拒绝。
  assert.strictEqual(1, 2);
});

test('使用 Promise 的失败测试', (t) => {
  // Promise 也可以直接使用。
  return new Promise((resolve, reject) => {
    setImmediate(() => {
      reject(new Error('这将导致测试失败'));
    });
  });
});

test('回调通过测试', (t, done) => {
  // done() 是回调函数。当 setImmediate() 运行时，它调用
  // done() 不带参数。
  setImmediate(done);
});

test('回调失败测试', (t, done) => {
  // 当 setImmediate() 运行时，done() 被传入一个 Error 对象且
  // 测试失败。
  setImmediate(() => {
    done(new Error('回调失败'));
  });
});

如果任何测试失败，进程退出代码将设置为 1。

测试上下文的 test() 方法允许创建子测试。 它允许你以层次结构方式组织测试， 你可以在较大的测试内创建嵌套测试。 此方法的行为与顶级 test() 函数完全相同。 以下示例演示了创建一个 带有两个子测试的顶级测试。

test('顶级测试', async (t) => {
  await t.test('子测试 1', (t) => {
    assert.strictEqual(1, 1);
  });

  await t.test('子测试 2', (t) => {
    assert.strictEqual(2, 2);
  });
});

注意： beforeEach 和 afterEach 钩子在 每个子测试执行之间触发。

在此示例中，使用 await 来确保两个子测试都已完成。 这是必要的，因为测试不会等待其子测试 完成，这与在套件内创建的测试不同。 当父测试完成时任何仍未完成的子测试 将被取消并视为失败。任何子测试失败都会导致父 测试失败。

测试运行器支持将运行状态持久化到文件，允许 测试运行器重新运行失败的测试，而不必重新运行整个测试套件。 使用 --test-rerun-failures 命令行选项指定一个文件路径，用于 存储运行状态。如果状态文件不存在，测试运行器将 创建它。 状态文件是一个包含运行尝试数组的 JSON 文件。 每次运行尝试是一个对象，将成功的测试映射到它们通过的尝试。 此映射中识别测试的键是测试文件路径，以及定义测试的行和列。 如果在特定位置定义的测试被运行多次， 例如在函数或循环内， 计数器将附加到键上，以消除测试运行的歧义。 注意，更改测试执行顺序或测试位置可能导致测试运行器 将测试视为在之前的尝试中已通过， 意味着 --test-rerun-failures 应在测试以确定顺序运行时使用。

状态文件示例：

[
  {
    "test.js:10:5": { "passed_on_attempt": 0, "name": "test 1" }
  },
  {
    "test.js:10:5": { "passed_on_attempt": 0, "name": "test 1" },
    "test.js:20:5": { "passed_on_attempt": 1, "name": "test 2" }
  }
]

在此示例中，有两次运行尝试，test.js 中定义了两个测试， 第一个测试在第一次尝试时成功，第二个测试在第二次尝试时成功。

当使用 --test-rerun-failures 选项时，测试运行器将只运行尚未通过的测试。

node --test-rerun-failures /path/to/state/file

套件和测试也可以使用 describe() 和 it() 函数编写。describe() 是 suite() 的别名，it() 是 test() 的别名。

describe('某事物', () => {
  it('应该工作', () => {
    assert.strictEqual(1, 1);
  });

  it('应该没问题', () => {
    assert.strictEqual(2, 2);
  });

  describe('嵌套事物', () => {
    it('应该工作', () => {
      assert.strictEqual(3, 3);
    });
  });
});

describe() 和 it() 从 node:test 模块导入。

import { describe, it } from 'node:test';

可以通过向测试传递 skip 选项，或通过 调用测试上下文的 skip() 方法来跳过单个测试，如下 所示示例。

// 使用了 skip 选项，但未提供消息。
test('skip option', { skip: true }, (t) => {
  // 此代码永远不会执行。
});

// 使用了 skip 选项，并提供了消息。
test('skip option with message', { skip: 'this is skipped' }, (t) => {
  // 此代码永远不会执行。
});

test('skip() method', (t) => {
  // 如果测试包含额外逻辑，也请确保在此处返回。
  t.skip();
});

test('skip() method with message', (t) => {
  // 如果测试包含额外逻辑，也请确保在此处返回。
  t.skip('this is skipped');
});

可以通过向测试传递 todo 选项，或通过调用测试上下文的 todo() 方法，将单个测试标记为不稳定或未完成，如下 所示示例。这些测试代表待实现的实现或需要修复的 错误。TODO 测试会被执行，但不被视为测试 失败，因此不会影响进程退出代码。如果测试被标记 为 TODO 和跳过，则 TODO 选项将被忽略。

// 使用了 todo 选项，但未提供消息。
test('todo option', { todo: true }, (t) => {
  // 此代码会被执行，但不被视为失败。
  throw new Error('this does not fail the test');
});

// 使用了 todo 选项，并提供了消息。
test('todo option with message', { todo: 'this is a todo test' }, (t) => {
  // 此代码会被执行。
});

test('todo() method', (t) => {
  t.todo();
});

test('todo() method with message', (t) => {
  t.todo('this is a todo test and is not treated as a failure');
  throw new Error('this does not fail the test');
});

这会翻转特定测试或套件的通过/失败报告：标记的测试 用例必须抛出异常才能通过，而标记的未抛出异常的测试用例 则失败。

在以下每种情况中，doTheThing() 未能返回 true，但由于 测试被标记为 expectFailure，它们会通过。

it.expectFailure('应该做这件事', () => {
  assert.strictEqual(doTheThing(), true);
});

it('应该做这件事', { expectFailure: true }, () => {
  assert.strictEqual(doTheThing(), true);
});

it('应该做这件事', { expectFailure: '功能尚未实现' }, () => {
  assert.strictEqual(doTheThing(), true);
});

如果 expectFailure 的值是 <RegExp> | <Function> | <Object> | <Error> 则仅当测试抛出匹配的值时才会通过。 请参阅 assert.throws 了解如何处理每种值类型。

以下每个测试都失败了，尽管 被标记为 expectFailure 因为失败不匹配特定的 预期 失败。

it('由于正则表达式不匹配而失败', {
  expectFailure: /expected message/,
}, () => {
  throw new Error('different message');
});

it('由于对象匹配器不匹配而失败', {
  expectFailure: { code: 'ERR_EXPECTED' },
}, () => {
  const err = new Error('boom');
  err.code = 'ERR_ACTUAL';
  throw err;
});

要为 expectFailure 提供原因和特定错误，请使用 { label, match }。

it('应以特定错误和原因失败', {
  expectFailure: {
    label: '失败原因',
    match: /error message/,
  },
}, () => {
  assert.strictEqual(doTheThing(), true);
});

skip 和/或 todo 与 expectFailure 互斥，skip 或 todo 在同时应用时将“获胜”（skip 胜过两者，todo 胜过 expectFailure）。

这些测试将被跳过（且不运行）：

it.expectFailure('应该做这件事', { skip: true }, () => {
  assert.strictEqual(doTheThing(), true);
});

it.skip('应该做这件事', { expectFailure: true }, () => {
  assert.strictEqual(doTheThing(), true);
});

这些测试将被标记为“todo”（静默错误）：

it.expectFailure('应该做这件事', { todo: true }, () => {
  assert.strictEqual(doTheThing(), true);
});

it.todo('应该做这件事', { expectFailure: true }, () => {
  assert.strictEqual(doTheThing(), true);
});

如果 Node.js 使用 --test-only 命令行选项启动，或者测试隔离被禁用，则可以通过向应该运行的测试传递 only 选项来跳过除选定子集之外的所有测试。当设置了带有 only 选项的测试时，所有子测试也会运行。 如果套件设置了 only 选项，则运行套件内的所有测试，除非它有设置了 only 选项的后代，在这种情况下，只运行那些测试。

当在 test()/it() 中使用 [子测试][] 时，需要标记所有祖先测试带有 only 选项，以便仅运行选定的测试子集。

测试上下文的 runOnly() 方法可用于在子测试级别实现相同的行为。未执行的测试将从测试运行器输出中省略。

// 假设 Node.js 是使用 --test-only 命令行选项运行的。
// 套件的 'only' 选项已设置，因此运行这些测试。
test('此测试会运行', { only: true }, async (t) => {
  // 在此测试内，默认运行所有子测试。
  await t.test('运行子测试');

  // 可以更新测试上下文以运行带有 'only' 选项的子测试。
  t.runOnly(true);
  await t.test('此子测试现在被跳过');
  await t.test('此子测试会运行', { only: true });

  // 将上下文切换回以执行所有测试。
  t.runOnly(false);
  await t.test('此子测试现在会运行');

  // 显式不运行这些测试。
  await t.test('跳过的子测试 3', { only: false });
  await t.test('跳过的子测试 4', { skip: true });
});

// 未设置 'only' 选项，因此跳过此测试。
test('此测试不会运行', () => {
  // 此代码未运行。
  throw new Error('fail');
});

describe('一个套件', () => {
  // 已设置 'only' 选项，因此运行此测试。
  it('此测试会运行', { only: true }, () => {
    // 此代码已运行。
  });

  it('此测试不会运行', () => {
    // 此代码未运行。
    throw new Error('fail');
  });
});

describe.only('一个套件', () => {
  // 已设置 'only' 选项，因此运行此测试。
  it('此测试会运行', () => {
    // 此代码已运行。
  });

  it('此测试会运行', () => {
    // 此代码已运行。
  });
});

--test-name-pattern 命令行选项可用于仅运行名称与所提供模式匹配的测试，而 --test-skip-pattern 选项可用于跳过名称与所提供模式匹配的测试。测试名称模式会被解释为 JavaScript 正则表达式。--test-name-pattern 和 --test-skip-pattern 选项可以指定多次，以运行嵌套测试。对于执行的每个测试，任何相应的测试钩子（如 beforeEach()）也会运行。未执行的测试将从测试运行器输出中省略。

给定以下测试文件，使用 --test-name-pattern="test [1-3]" 选项启动 Node.js 将导致测试运行器执行 test 1、test 2 和 test 3。如果 test 1 不匹配测试名称模式，则其子测试将不会执行，即使它们匹配该模式。也可以通过多次传递 --test-name-pattern 来执行同一组测试（例如 --test-name-pattern="test 1"、--test-name-pattern="test 2" 等）。

test('test 1', async (t) => {
  await t.test('test 2');
  await t.test('test 3');
});

test('Test 4', async (t) => {
  await t.test('Test 5');
  await t.test('test 6');
});

测试名称模式也可以使用正则表达式字面量指定。这允许使用正则表达式标志。在前面的示例中，使用 --test-name-pattern="/test [4-5]/i"（或 --test-skip-pattern="/test [4-5]/i"）启动 Node.js 将匹配 Test 4 和 Test 5，因为该模式不区分大小写。

要使用模式匹配单个测试，你可以使用其所有祖先测试名称作为前缀（用空格分隔），以确保它是唯一的。 例如，给定以下测试文件：

describe('test 1', (t) => {
  it('some test');
});

describe('test 2', (t) => {
  it('some test');
});

使用 --test-name-pattern="test 1 some test" 启动 Node.js 将仅匹配 test 1 中的 some test。

测试名称模式不会更改测试运行器执行的文件集。

如果同时提供了 --test-name-pattern 和 --test-skip-pattern，测试必须满足 两者 要求才能执行。

稳定性：1.0 - 早期开发

标签使用任意字符串标签为测试和套件添加注释。--experimental-test-tag-filter CLI 标志（或 run() 上的 testTagFilters 选项）会选择其标签集合包含每个 提供的过滤值的测试。

标签是将元数据编码到测试名称之外的一种替代方式。它们 适用于诸如子系统、速度等级、易波动性 或环境等横切维度，因为名称模式在这些场景下会比较脆弱。

import { describe, it } from 'node:test';

describe('database', { tags: ['db'] }, () => {
  it('reads a row');                                            // 标签：['db']
  it('writes a row', { tags: ['integration'] });                // 标签：['db', 'integration']
  it('reconnects after disconnect', { tags: ['flaky'] });       // 标签：['db', 'flaky']
});

标签值必须是非空字符串。标签匹配时不区分大小写； 规范形式为小写。同一 tags 数组内的重复项会按小写形式折叠， 并保留首次出现的声明顺序。

钩子（before、after、beforeEach、afterEach）不会声明它们自己的 标签。它们作为其所属套件的一部分运行，而该套件承载 套件的标签。

在任何非空过滤条件下，未加标签的测试都会被排除，因为过滤条件 要求标签存在。

一旦测试函数完成执行，结果会尽快报告，同时保持测试的顺序。然而，测试函数可能会产生比测试本身存活时间更长的异步活动。测试运行器处理此类活动，但不会为了适应它而延迟测试结果的报告。

在以下示例中，一个测试完成时仍有两个 setImmediate() 操作未完成。第一个 setImmediate() 尝试创建一个新的子测试。因为父测试已经完成并输出了结果，新的子测试会立即标记为失败，并在稍后报告给 <TestsStream>。

第二个 setImmediate() 创建一个 uncaughtException 事件。源自已完成测试的 uncaughtException 和 unhandledRejection 事件会被 test 模块标记为失败，并由 <TestsStream> 在顶层报告为诊断警告。

test('一个创建异步活动的测试', (t) => {
  setImmediate(() => {
    t.test('太晚创建的子测试', (t) => {
      throw new Error('error1');
    });
  });

  setImmediate(() => {
    throw new Error('error2');
  });

  // 测试在此行之后结束。
});

稳定性：1 - 实验性

Node.js 测试运行器支持通过传递 --watch 标志以监视模式运行：

node --test --watch

在监视模式下，测试运行器将监视测试文件及其依赖项的更改。检测到更改时，测试运行器将重新运行受更改影响的测试。 测试运行器将持续运行，直到进程终止。

稳定性：1.0 - 早期开发

测试运行器支持指定一个模块，该模块将在所有测试执行之前进行评估，并可用于设置测试的全局状态或夹具。这对于准备多个测试所需的资源或设置共享状态很有用。

该模块可以导出以下任何内容：

• 一个 globalSetup 函数，在所有测试开始前运行一次
• 一个 globalTeardown 函数，在所有测试完成后运行一次

该模块在使用命令行运行测试时使用 --test-global-setup 标志指定。

// setup-module.js
async function globalSetup() {
  // 设置共享资源、状态或环境
  console.log('全局设置已执行');
  // 运行服务器、创建文件、准备数据库等。
}

async function globalTeardown() {
  // 清理资源、状态或环境
  console.log('全局清理已执行');
  // 关闭服务器、移除文件、断开数据库连接等。
}

module.exports = { globalSetup, globalTeardown };

如果全局设置函数抛出错误，将不会运行任何测试，进程将以非零退出码退出。 在这种情况下，全局清理函数不会被调用。

The Node.js test runner can be invoked from the command line by passing the --test flag:

node --test

By default, Node.js will run all files matching the following patterns:

• **/*.test.{cjs,mjs,js}
• **/*-test.{cjs,mjs,js}
• **/*_test.{cjs,mjs,js}
• **/test-*.{cjs,mjs,js}
• **/test.{cjs,mjs,js}
• **/test/**/*.{cjs,mjs,js}

Unless --no-strip-types is provided, the following additional patterns are also matched:

• **/*.test.{cts,mts,ts}
• **/*-test.{cts,mts,ts}
• **/*_test.{cts,mts,ts}
• **/test-*.{cts,mts,ts}
• **/test.{cts,mts,ts}
• **/test/**/*.{cts,mts,ts}

Alternatively, one or more glob patterns can be provided as the final arguments to the Node.js command, as shown below. Glob patterns follow the behavior of glob(7). On the command line, glob patterns should be enclosed in double quotes to prevent shell expansion, which can reduce portability issues across systems.

node --test "**/*.test.js" "**/*.spec.js"

When randomization is enabled, the test runner prints the seed used for the run as a diagnostic message:

Randomized test order seed: 12345

Use --test-random-seed=<number> to deterministically replay the same random order. Providing --test-random-seed also enables randomization, so --test-randomize is optional when a seed is provided:

node --test --test-random-seed=12345

In most test files, randomization takes effect automatically. One important exception is when subtests are awaited one by one. In this mode, each subtest starts only after the previous one completes, so the runner preserves declaration order instead of randomizing it.

Example: this runs in order, and is not randomized.

import test from 'node:test';

test('math', async (t) => {
  for (const name of ['adds', 'subtracts', 'multiplies']) {
    // Awaiting each subtest sequentially preserves declaration order.
    await t.test(name, async () => {});
  }
});

Using suite-style APIs such as describe()/it() or suite()/test() still allows randomization because sibling tests are queued together.

Example: this is still eligible for randomization.

import { describe, it } from 'node:test';

describe('math', () => {
  it('adds', () => {});
  it('subtracts', () => {});
  it('multiplies', () => {});
});

--test-randomize and --test-random-seed are not supported together with --watch mode.

Matching files are executed as test files. For more information about test file execution, see the Test runner execution model section.

Each test file is executed as though it were a regular script. That is, if the test file itself uses node:test to define tests, then all such tests are executed within a single application thread, regardless of the concurrency option value of test().

When process-level test isolation is disabled, each matching test file is imported into the test runner process. After all test files have been loaded, top-level tests are executed with a concurrency of 1. Because all test files run in the same context, tests may interact with each other in ways that are not possible when isolation is enabled. For example, if tests depend on global state, that state may be modified by tests originating from another file.

When running tests in process isolation mode (the default), spawned child processes inherit Node.js options from the parent process, including those specified in the [configuration file][]. However, certain flags are filtered out to enable correct test runner functionality:

• --test - Prevents recursive test execution
• --experimental-test-coverage - Managed by the test runner
• --experimental-test-tag-filter - Filter values are validated by the parent process and re-sent to the child process
• --watch - Watch mode is handled by the parent
• --experimental-default-config-file - Configuration file loading is handled by the parent
• --test-reporter - Reporting is managed by the parent process
• --test-reporter-destination - Output destination is controlled by the parent
• --experimental-config-file - Configuration file path is managed by the parent
• --test-randomize - Randomization is managed by the parent process and propagated to child processes
• --test-random-seed - Randomization seed is managed by the parent process and propagated to child processes

All other Node.js options from command-line arguments, environment variables, and configuration files are inherited by the child processes.

稳定性：1 - 实验性

当 Node.js 使用 --experimental-test-coverage 命令行标志启动时，会收集代码覆盖率，并在所有测试完成后报告统计数据。如果使用 NODE_V8_COVERAGE 环境变量指定代码覆盖率目录，生成的 V8 覆盖率文件将写入该目录。默认情况下，Node.js 核心模块和 node_modules/ 目录内的文件不包含在覆盖率报告中。但是，可以通过 --test-coverage-include 标志显式包含它们。默认情况下，所有匹配的测试文件都从覆盖率报告中排除。可以通过使用 --test-coverage-exclude 标志来覆盖排除项。如果启用了覆盖率，覆盖率报告将通过 'test:coverage' 事件发送到任何 [测试报告器][]。

可以使用以下注释语法在一系列行上禁用覆盖率：

/* node:coverage disable */
if (anAlwaysFalseCondition) {
  // 此分支中的代码永远不会被执行，但这些行会被忽略以用于
  // 覆盖率目的。'disable' 注释之后的所有行都会被忽略
  // 直到遇到相应的 'enable' 注释。
  console.log('这段代码永远不会被执行');
}
/* node:coverage enable */

也可以禁用指定行数的覆盖率。在指定行数之后，覆盖率将自动重新启用。如果未明确提供行数，则忽略单行。

/* node:coverage ignore next */
if (anAlwaysFalseCondition) { console.log('这段代码永远不会被执行'); }

/* node:coverage ignore next 3 */
if (anAlwaysFalseCondition) {
  console.log('这段代码永远不会被执行');
}

• 此报告器不报告任何测试结果。
• 理想情况下，此报告器应与另一个报告器一起使用。

node:test 模块支持通过顶层 mock 对象在测试期间进行模拟。以下示例创建一个函数的间谍，该函数将两个数字相加。然后使用间谍来断言该函数是否按预期被调用。

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

test('spy on a function', () => {
  const sum = mock.fn((a, b) => {
    return a + b;
  });

  assert.strictEqual(sum.mock.callCount(), 0);
  assert.strictEqual(sum(3, 4), 7);
  assert.strictEqual(sum.mock.callCount(), 1);

  const call = sum.mock.calls[0];
  assert.deepStrictEqual(call.arguments, [3, 4]);
  assert.strictEqual(call.result, 7);
  assert.strictEqual(call.error, undefined);

  // 重置全局跟踪的模拟对象。
  mock.reset();
});

相同的模拟功能也暴露在每个测试的 TestContext 对象上。以下示例使用 TestContext 上暴露的 API 创建对象方法的间谍。通过测试上下文进行模拟的好处是，一旦测试完成，测试运行器将自动恢复所有模拟的功能。

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

  t.mock.method(number, 'add');
  assert.strictEqual(number.add.mock.callCount(), 0);
  assert.strictEqual(number.add(3), 8);
  assert.strictEqual(number.add.mock.callCount(), 1);

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

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

请参阅 MockTimers 类以获取方法和功能的完整列表。

这使得开发人员能够为依赖时间的功能编写更可靠和 可预测的测试。

下面的示例展示了如何模拟 setTimeout。 使用 .enable({ apis: ['setTimeout'] }); 它将模拟 node:timers 和 node:timers/promises 模块中的 setTimeout 函数， 以及来自 Node.js 全局上下文的函数。

注意： 此 API 目前不支持解构函数，例如 import { setTimeout } from 'node:timers'。

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

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

  // 可选地选择要模拟的内容
  mock.timers.enable({ apis: ['setTimeout'] });
  setTimeout(fn, 9999);
  assert.strictEqual(fn.mock.callCount(), 0);

  // 推进时间
  mock.timers.tick(9999);
  assert.strictEqual(fn.mock.callCount(), 1);

  // 重置全局跟踪的模拟对象。
  mock.timers.reset();

  // 如果调用 reset 模拟实例，它也会重置计时器实例
  mock.reset();
});

相同的模拟功能也暴露在每个测试的 TestContext 对象的 mock 属性上。通过测试上下文进行模拟的好处是 一旦测试完成，测试运行器将自动恢复所有模拟的计时器 功能。

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

  // 推进时间
  context.mock.timers.tick(9999);
  assert.strictEqual(fn.mock.callCount(), 1);
});

日期实现也是 MockTimers 类的一部分。请参阅它以获取方法和功能的完整列表。

注意： 日期和计时器在一起模拟时是依赖的。这意味着 如果你同时模拟了 Date 和 setTimeout，推进时间也会 推进模拟的日期，因为它们模拟的是单个内部时钟。

下面的示例展示了如何模拟 Date 对象并获取当前 Date.now() 值。

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

test('mocks the Date object', (context) => {
  // 可选地选择要模拟的内容
  context.mock.timers.enable({ apis: ['Date'] });
  // 如果未指定，初始日期将基于 UNIX 纪元的 0
  assert.strictEqual(Date.now(), 0);

  // 推进时间也会推进日期
  context.mock.timers.tick(9999);
  assert.strictEqual(Date.now(), 9999);
});

如果没有设置初始纪元，初始日期将基于 Unix 纪元的 0。这是 1970 年 1 月 1 日，00:00:00 UTC。你可以通过向 .enable() 方法传递 now 属性来设置初始日期。此值将用作模拟 Date 对象的初始日期。它可以是正整数，也可以是另一个 Date 对象。

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

test('mocks the Date object with initial time', (context) => {
  // 可选地选择要模拟的内容
  context.mock.timers.enable({ apis: ['Date'], now: 100 });
  assert.strictEqual(Date.now(), 100);

  // 推进时间也会推进日期
  context.mock.timers.tick(200);
  assert.strictEqual(Date.now(), 300);
});

你可以使用 .setTime() 方法手动将模拟的日期移动到另一个 时间。此方法仅接受正整数。

注意： 此方法不会执行任何在新时间之前过去的模拟计时器。

在下面的示例中，我们为模拟的日期设置了一个新时间。

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

test('sets the time of a date object', (context) => {
  // 可选地选择要模拟的内容
  context.mock.timers.enable({ apis: ['Date'], now: 100 });
  assert.strictEqual(Date.now(), 100);

  // 推进时间也会推进日期
  context.mock.timers.setTime(1000);
  context.mock.timers.tick(200);
  assert.strictEqual(Date.now(), 1200);
});

当你调用 setTime() 时，过去安排的计时器不会运行。要执行这些计时器，你可以使用 .tick() 方法从新时间向前移动。

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

test('setTime does not execute timers', (context) => {
  // 可选地选择要模拟的内容
  context.mock.timers.enable({ apis: ['setTimeout', 'Date'] });
  const fn = context.mock.fn();
  setTimeout(fn, 1000);

  context.mock.timers.setTime(800);
  // 计时器未执行，因为时间尚未到达
  assert.strictEqual(fn.mock.callCount(), 0);
  assert.strictEqual(Date.now(), 800);

  context.mock.timers.setTime(1200);
  // 计时器仍然未执行
  assert.strictEqual(fn.mock.callCount(), 0);
  // 推进时间以执行计时器
  context.mock.timers.tick(0);
  assert.strictEqual(fn.mock.callCount(), 1);
  assert.strictEqual(Date.now(), 1200);
});

使用 .runAll() 将执行当前队列中的所有计时器。这 也会将模拟的日期推进到最后执行的计时器的时间，就像时间已经过去了一样。

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

test('runs timers as setTime passes ticks', (context) => {
  // 可选地选择要模拟的内容
  context.mock.timers.enable({ apis: ['setTimeout', 'Date'] });
  const fn = context.mock.fn();
  setTimeout(fn, 1000);
  setTimeout(fn, 2000);
  setTimeout(fn, 3000);

  context.mock.timers.runAll();
  // 所有计时器已执行，因为时间现已到达
  assert.strictEqual(fn.mock.callCount(), 3);
  assert.strictEqual(Date.now(), 3000);
});

快照测试允许将任意值序列化为字符串值，并与一组已知良好值进行比较。这些已知良好值被称为快照，并存储在快照文件中。快照文件由测试运行器管理，但设计为人类可读以辅助调试。最佳实践是将快照文件与测试文件一起检入版本控制。

快照文件是通过使用 --test-update-snapshots 命令行标志启动 Node.js 生成的。每个测试文件都会生成一个单独的快照文件。默认情况下，快照文件与测试文件具有相同的名称，但带有 .snapshot 文件扩展名。此行为可以使用 snapshot.setResolveSnapshotPath() 函数进行配置。每个快照断言对应于快照文件中的一个导出。

下面显示了一个快照测试示例。第一次执行此测试时，它将失败，因为相应的快照文件不存在。

// test.js
suite('快照测试套件', () => {
  test('快照测试', (t) => {
    t.assert.snapshot({ value1: 1, value2: 2 });
    t.assert.snapshot(5);
  });
});

通过使用 --test-update-snapshots 运行测试文件来生成快照文件。测试应该通过，并且一个名为 test.js.snapshot 的文件将创建在与测试文件相同的目录中。快照文件的内容如下所示。每个快照由测试的全名和一个计数器标识，以区分同一测试中的快照。

exports[`快照测试套件 > 快照测试 1`] = `
{
  "value1": 1,
  "value2": 2
}
`;

exports[`快照测试套件 > 快照测试 2`] = `
5
`;

一旦创建了快照文件，再次运行测试而不使用 --test-update-snapshots 标志。现在测试应该通过。

node:test 模块支持传递 --test-reporter 标志，以便测试运行器使用特定的报告器。

支持以下内置报告器：

• spec spec 报告器以人类可读格式输出测试结果。这是默认报告器。

• tap tap 报告器以 TAP 格式输出测试结果。

• dot dot 报告器以紧凑格式输出测试结果， 其中每个通过的测试由一个 . 表示， 每个失败的测试由一个 X 表示。

• junit junit 报告器以 jUnit XML 格式输出测试结果

• lcov lcov 报告器在与 --experimental-test-coverage 标志一起使用时输出测试覆盖率。

这些报告器的确切输出可能会在 Node.js 版本之间发生变化，不应以编程方式依赖。如果需要以编程方式访问测试运行器的输出，请使用由 <TestsStream> 发出的事件。

报告器可通过 node:test/reporters 模块获得：

import { tap, spec, dot, junit, lcov } from 'node:test/reporters';

使用 <stream.Transform> 的自定义报告器示例：

import { Transform } from 'node:stream';

const customReporter = new Transform({
  writableObjectMode: true,
  transform(event, encoding, callback) {
    switch (event.type) {
      case 'test:dequeue':
        callback(null, `test ${event.data.name} dequeued`);
        break;
      case 'test:enqueue':
        callback(null, `test ${event.data.name} enqueued`);
        break;
      case 'test:watch:drained':
        callback(null, 'test watch queue drained');
        break;
      case 'test:watch:restarted':
        callback(null, 'test watch restarted due to file change');
        break;
      case 'test:start':
        callback(null, `test ${event.data.name} started`);
        break;
      case 'test:pass':
        callback(null, `test ${event.data.name} passed`);
        break;
      case 'test:fail':
        callback(null, `test ${event.data.name} failed`);
        break;
      case 'test:plan':
        callback(null, 'test plan');
        break;
      case 'test:diagnostic':
      case 'test:stderr':
      case 'test:stdout':
        callback(null, event.data.message);
        break;
      case 'test:coverage': {
        const { totalLineCount } = event.data.summary.totals;
        callback(null, `总行数：${totalLineCount}\n`);
        break;
      }
    }
  },
});

export default customReporter;

使用生成器函数的自定义报告器示例：

export default async function * customReporter(source) {
  for await (const event of source) {
    switch (event.type) {
      case 'test:dequeue':
        yield `test ${event.data.name} dequeued\n`;
        break;
      case 'test:enqueue':
        yield `test ${event.data.name} enqueued\n`;
        break;
      case 'test:watch:drained':
        yield 'test watch queue drained\n';
        break;
      case 'test:watch:restarted':
        yield 'test watch restarted due to file change\n';
        break;
      case 'test:start':
        yield `test ${event.data.name} started\n`;
        break;
      case 'test:pass':
        yield `test ${event.data.name} passed\n`;
        break;
      case 'test:fail':
        yield `test ${event.data.name} failed\n`;
        break;
      case 'test:plan':
        yield 'test plan\n';
        break;
      case 'test:diagnostic':
      case 'test:stderr':
      case 'test:stdout':
        yield `${event.data.message}\n`;
        break;
      case 'test:coverage': {
        const { totalLineCount } = event.data.summary.totals;
        yield `总行数：${totalLineCount}\n`;
        break;
      }
    }
  }
}

提供给 --test-reporter 的值应该是一个字符串，类似于 JavaScript 代码中 import() 使用的字符串，或者是提供给 --import 的值。

在以下示例中，spec 报告器将输出到 stdout， 而 dot 报告器将输出到 file.txt：

node --test-reporter=spec --test-reporter=dot --test-reporter-destination=stdout --test-reporter-destination=file.txt

当指定单个报告器时，除非明确提供了目标，否则目标将默认为 stdout。

注意： shard 用于在机器或进程之间水平并行化测试运行， 适用于跨不同环境的大规模执行。它与 watch 模式不兼容，后者旨在通过在文件更改时自动重新运行测试来实现快速代码迭代。

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')] })
 .on('test:fail', () => {
   process.exitCode = 1;
 })
 .compose(tap)
 .pipe(process.stdout);

suite() 函数从 node:test 模块导入。

用于跳过套件的简写。这与 suite([name], { skip: true }[, fn]) 相同。

用于将套件标记为 TODO 的简写。这与 suite([name], { todo: true }[, fn]) 相同。

用于将套件标记为 only 的简写。这与 suite([name], { only: true }[, fn]) 相同。

test() 函数是从 test 模块导入的一个值。每次调用此函数都会向 <TestsStream> 报告一个测试。

传递给 fn 参数的 TestContext 对象可用于执行与当前测试相关的操作。示例包括跳过测试、添加 额外的诊断信息，或创建子测试。

test() 返回一个在测试完成后兑现的 Promise。 如果在套件内调用 test()，它会立即兑现。 顶层测试的返回值通常可以忽略。 但是，子测试的返回值应当使用，以防止父测试 过早结束并取消子测试，如以下示例所示。

test('顶层测试', async (t) => {
  // 如果删除下一行中的 'await'，则下面子测试中的 setTimeout() 将会导致
  // 它的存活时间超过其父测试。一旦父测试完成，它将取消任何未完成的子测试。
  await t.test('运行时间较长的子测试', async (t) => {
    return new Promise((resolve, reject) => {
      setTimeout(resolve, 1000);
    });
  });
});

timeout 选项可用于在测试执行时间超过 timeout 毫秒时使其失败。但是，这不是 一种可靠的取消测试机制，因为正在运行的测试可能会阻塞应用程序线程， 从而阻止计划中的取消。

A shorthand for skipping tests,
this is the same as test([name], { skip: true }[, fn]).

用于将测试标记为 TODO 的简写， 这与 test([name], { todo: true }[, fn]) 相同。

用于将测试标记为 only 的简写， 这与 test([name], { only: true }[, fn]) 相同。

suite() 的别名。

describe() 函数从 node:test 模块导入。

用于跳过套件的简写。这与 describe([name], { skip: true }[, fn]) 相同。

用于将套件标记为 TODO 的简写。这与 describe([name], { todo: true }[, fn]) 相同。

用于将套件标记为 only 的简写。这与 describe([name], { only: true }[, fn]) 相同。

test() 的别名。

it() 函数从 node:test 模块导入。

用于跳过测试的简写， 这与 仅 相同。

用于将测试标记为 已跳过 的简写， 这与 跳过 相同。

用于将测试标记为 仅运行 的简写， 这与 仅 相同。

• 钩子 <Function> | <AsyncFunction> 钩子函数。 如果钩子使用回调， 则回调函数作为第二个参数传入。默认： 无操作函数。
• 选项 <Object> 钩子的配置项。支持以下属性：
  • signal <AbortSignal> 允许中止正在进行中的钩子。
  • timeout <number> 钩子在多少毫秒后失败。 如果未指定，子测试会从其父级继承此值。 默认： 0。

此函数创建一个在执行套件之前运行的钩子。

describe('tests', async () => {
  before(() => console.log('即将运行一些测试'));
  it('is a subtest', () => {
    // 这里有一些相关断言
  });
});

此函数会创建一个在执行套件之后运行的钩子。

describe('tests', async () => {
  after(() => console.log('测试运行结束'));
  it('is a subtest', () => {
    // 这里有一些相关断言
  });
});

注意： after 钩子保证会运行， 即使套件内的测试失败也是如此。

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

describe('tests', async () => {
  beforeEach(() => console.log('A test is about to run'));
  it('is a subtest', () => {
    // There are some relevant assertions here
  });
});

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

describe('tests', async () => {
  afterEach(() => console.log('测试运行完成'));
  it('is a subtest', () => {
    // Related assertions go here
  });
});

一个对象，其方法用于配置当前进程中 node:assert 对象可用的断言。默认情况下，node:assert 中的方法和快照测试函数可用。

可以通过将通用配置代码放入通过 --import 或 --require 预加载的模块中，将相同的配置应用于所有文件。

一个对象，其方法用于配置当前进程中的默认快照设置。可以通过将通用配置代码放入通过 --import 或 --require 预加载的模块中，将相同的配置应用于所有文件。

此函数用于自定义测试运行器使用的默认序列化机制。默认情况下，测试运行器通过对提供的值调用 util.inspect 来序列化值。util.inspect 在循环结构和支持的数据类型方面确实存在限制。如果需要更强大的序列化机制，应使用此函数。

此函数用于自定义快照测试所使用的快照文件位置。默认情况下，快照文件的名称与入口文件相同，扩展名为 .snap。

MockTracker 类用于检查或操纵通过 [node:test][] API 创建的 mock 的行为。

一个 getter，返回用于跟踪对 mock 调用的内部数组副本。数组中的每个条目都是一个具有以下属性的对象。

此函数返回此 mock 被调用的次数。此函数比检查 calls 更高效，因为 calls 是一个会创建内部调用跟踪数组副本的 getter。

此函数用于更改现有 mock 的行为。

以下示例使用 MockTracker 创建一个 mock 函数，调用该 mock 函数，然后将 mock 实现更改为另一个函数。

test('更改 mock 行为', (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);
});

此函数用于仅更改现有 mock 单次调用的行为。一旦 onCall 指定的调用发生，mock 将恢复为如果未调用 mockImplementationOnce() 时本应具有的行为。

以下示例使用 t.mock.fn() 创建一个 mock 函数，调用该 mock 函数，将下一次调用的 mock 实现更改为另一个函数，然后恢复其之前的行为。

test('只更改一次 mock 行为', (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);
});

稳定性：1.0 - 早期开发阶段

MockModuleContext 类用于操纵通过 MockTracker API 创建的模块 mock 的行为。

MockPropertyContext 类用于检查或操纵通过 MockTracker API 创建的属性 mock 的行为。

一个 getter，返回用于跟踪被 mock 属性访问（get/set）的内部数组副本。数组中的每一项都是一个具有以下属性的对象：

此函数返回属性被访问的次数。 此函数比检查 ctx.accesses.length 更高效，因为 ctx.accesses 是一个 getter，它会创建内部访问跟踪数组的副本。

此函数用于更改被 mock 属性 getter 返回的值。

此函数用于更改单次现有 mock 的行为。一旦发生 onAccess 调用，mock 将恢复为在未调用 mockImplementationOnce() 时本应使用的行为。

下面的示例使用 t.mock.property() 创建一个 mock 函数，调用该被 mock 属性，将下一次调用的 mock 实现更改为不同的值，然后恢复其先前行为。

test('更改一次 mock 行为', (t) => {
  const obj = { foo: 1 };

  const prop = t.mock.property(obj, 'foo', 5);

  assert.strictEqual(obj.foo, 5);
  prop.mock.mockImplementationOnce(25);
  assert.strictEqual(obj.foo, 25);
  assert.strictEqual(obj.foo, 5);
});

为了与其余模拟 API 保持一致，此函数将属性的 get 和 set 都视为访问。如果在相同的访问索引处发生属性 set，那么“once”值会被 set 操作消费，并且被模拟的属性值将被更改为“once”值。如果你打算仅将“once”值用于 get 操作，这可能会导致意外行为。

MockTracker 类用于管理 mock 功能。test runner 模块提供一个顶层的 mock 导出，它是一个 MockTracker 实例。 每个测试也都有自己的 MockTracker 实例，可通过测试上下文的 mock 属性访问。

此函数用于创建 mock 函数。

下面的示例创建了一个在每次调用时都会递增计数器的 mock 函数。times 选项用于修改 mock 行为，使前两次调用每次将计数器增加 2 而不是 1。

test('模拟一个计数函数', (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);
});

此函数用于在现有对象方法上创建 mock。下面的 示例演示如何在现有对象方法上创建 mock。

test('监听一个对象方法', (t) => {
  const number = {
    value: 5,
    subtract(a) {
      return this.value - a;
    },
  };

  t.mock.method(number, 'subtract');
  assert.strictEqual(number.subtract.mock.callCount(), 0);
  assert.strictEqual(number.subtract(3), 2);
  assert.strictEqual(number.subtract.mock.callCount(), 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);
});

此函数用于模拟 ECMAScript 模块、CommonJS 模块、JSON 模块和 Node.js 内置模块的导出。在 mock 之前对原始模块的任何引用都不会受到影响。要 启用模块 mock，Node.js 必须使用 --experimental-test-module-mocks 命令行标志运行。

注意：module customization hooks 通过 同步 API 注册时会影响传递给 mock.module 的 specifier 的解析。 通过 异步 API 注册的 customization hooks 当前会被忽略（因为 test runner 的 loader 是同步的，并且 Node 不支持 multi-chain/cross-chain loaders）。

下面的示例演示如何为模块创建 mock。

test('模拟内置模块在两种模块系统中的行为', async (t) => {
  // 为 'node:readline' 创建一个 mock，并带有一个名为 'foo' 的具名导出，
  // 该导出在原始 'node:readline' 模块中不存在。
  const mock = t.mock.module('node:readline', {
    exports: { foo: () => 42 },
  });

  let esmImpl = await import('node:readline');
  let cjsImpl = require('node:readline');

  // cursorTo() 是原始 'node:readline' 模块的一个导出。
  assert.strictEqual(esmImpl.cursorTo, undefined);
  assert.strictEqual(cjsImpl.cursorTo, undefined);
  assert.strictEqual(esmImpl.foo(), 42);
  assert.strictEqual(cjsImpl.foo(), 42);

  mock.restore();

  // mock 已恢复，因此我们会拿回原始内置模块。
  esmImpl = await import('node:readline');
  cjsImpl = require('node:readline');

  assert.strictEqual(typeof esmImpl.cursorTo, 'function');
  assert.strictEqual(typeof cjsImpl.cursorTo, 'function');
  assert.strictEqual(esmImpl.foo, undefined);
  assert.strictEqual(cjsImpl.foo, undefined);
});

在对象上的某个属性值创建 mock。这使你可以跟踪并控制对特定属性的访问， 包括它被读取（getter）或写入（setter）的次数，并在 mock 后恢复原始值。

test('模拟一个属性值', (t) => {
  const obj = { foo: 42 };
  const prop = t.mock.property(obj, 'foo', 100);

  assert.strictEqual(obj.foo, 100);
  assert.strictEqual(prop.mock.accessCount(), 1);
  assert.strictEqual(prop.mock.accesses[0].type, 'get');
  assert.strictEqual(prop.mock.accesses[0].value, 100);

  obj.foo = 200;
  assert.strictEqual(prop.mock.accessCount(), 2);
  assert.strictEqual(prop.mock.accesses[1].type, 'set');
  assert.strictEqual(prop.mock.accesses[1].value, 200);

  prop.mock.restore();
  assert.strictEqual(obj.foo, 42);
});

每个测试完成后，都会在测试上下文的 MockTracker 上调用此函数。如果大量使用全局 MockTracker，建议手动调用此函数。

Mock timers 是软件测试中常用的一种技术，用于模拟和控制定时器（例如 setInterval 和 setTimeout）的行为，而无需实际等待指定的时间间隔。

MockTimers 也可以模拟 Date 对象。

MockTracker 提供一个顶层的 timers 导出，它是一个 MockTimers 实例。

注意： 当你为某个特定定时器启用模拟时，其关联的清除函数也会被隐式模拟。

注意： 模拟 Date 会影响 mock timers 的行为，因为它们使用的是同一个内部时钟。

不设置初始时间的使用示例：

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

上面的示例启用了对 setInterval 定时器的模拟，并隐式模拟了 clearInterval 函数。来自 node:timers、 node:timers/promises 和 globalThis 的 setInterval 与 clearInterval 函数都会被模拟。

设置初始时间的使用示例

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

将初始 Date 对象设置为时间的使用示例

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

或者，如果你不带参数调用 mock.timers.enable()：

所有定时器（'setInterval'、'clearInterval'、'setTimeout'、'clearTimeout'、 'setImmediate' 和 'clearImmediate'）都会被模拟。来自 node:timers、node:timers/promises 和 globalThis 的 setInterval、clearInterval、setTimeout、clearTimeout、setImmediate 和 clearImmediate 函数都会被模拟。全局 Date 对象也会被模拟。

注意： 每个测试完成后，都会在测试上下文的 MockTracker 上调用此函数。

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

注意： 这与 Node.js 中 setTimeout 的行为不同，后者只接受正数。在 Node.js 中，带负数的 setTimeout 仅出于 Web 兼容性原因而被支持。

下面的示例会模拟一个 setTimeout 函数， 并通过使用 .tick 推进时间来触发所有待处理的定时器。

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

  // 推进时间
  context.mock.timers.tick(9999);

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

另外，.tick 可以多次调用

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 threeSeconds = 3000;
  context.mock.timers.tick(threeSeconds);
  context.mock.timers.tick(threeSeconds);
  context.mock.timers.tick(threeSeconds);

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

如果在启用模拟时也将 Date 设置为被模拟，那么使用 .tick 推进时间时，也会推进之后创建的任何 Date 对象的时间。

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

  // 推进时间
  context.mock.timers.tick(9999);
  assert.strictEqual(fn.mock.callCount(), 1);
  assert.strictEqual(Date.now(), 9999);
});

如前所述，来自定时器的所有清除函数（clearTimeout、clearInterval 和 clearImmediate）都会被隐式模拟。请看下面使用 setTimeout 的示例：

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 id = setTimeout(fn, 9999);

  // 也会被隐式模拟
  clearTimeout(id);
  context.mock.timers.tick(9999);

  // 因为那个 setTimeout 已被清除，所以 mock 函数永远不会被调用
  assert.strictEqual(fn.mock.callCount(), 0);
});