测试运行器

稳定性：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 选项）会选择其标签集合包含每个 提供的过滤值的测试。

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

在 test()、it()、suite() 或 describe() 任一函数上传入 tags 数组。 标签通过并集从套件继承到其子测试——套件中带有 ['db'] 标签的测试如果声明了自己的 tags: ['integration'] ，则实际上同时拥有这两个标签。

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）不会声明它们自己的 标签。它们作为其所属套件的一部分运行，而该套件承载 套件的标签。

每个 --experimental-test-tag-filter 值都是一个字面标签名。一个 测试只有在其标签集合包含该名称时才会运行。该标志可以 多次指定；测试必须匹配 每个 过滤条件才能运行。run()[] 上的 testTagFilters 数组也同样适用。过滤器不区分大小写，并与 --test-name-pattern、 --test-skip-pattern 和 .only 过滤进行 AND 组合。

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

TestContext 对象通过 context.tags 将测试的标签作为一个冻结数组暴露， 因此测试可以根据自己的元数据进行分支。

违反上述验证规则的标签值会在注册位置抛出 ERR_INVALID_ARG_VALUE，且发生在任何测试运行之前。 非数组的 tags 值会抛出 ERR_INVALID_ARG_TYPE。

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

在以下示例中，一个测试完成时仍有两个 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 };

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

可以通过传递 --test 标志从命令行调用 Node.js 测试运行器：

node --test

默认情况下，Node.js 将运行所有匹配以下模式的文件：

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

除非提供 --no-strip-types，否则还会匹配以下附加模式：

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

或者，可以将一个或多个 glob 模式作为 Node.js 命令的最终参数提供，如下所示。 Glob 模式遵循 glob(7) 的行为。 在命令行上，glob 模式应包含在双引号中，以防止 shell 扩展，这可以减少跨系统的可移植性问题。

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

稳定性：1.0 - 早期开发

测试运行器可以随机化执行顺序以帮助检测依赖顺序的测试。启用时，运行器会随机化发现的文件以及每个文件内排队的测试。使用 --test-randomize 启用此模式。

node --test --test-randomize

启用随机化时，测试运行器会将用于运行的种子作为诊断消息打印出来：

Randomized test order seed: 12345

使用 --test-random-seed=<number> 以确定性地重放相同的随机顺序。提供 --test-random-seed 也会启用随机化，因此提供种子时 --test-randomize 是可选的：

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

在大多数测试文件中，随机化会自动工作。一个重要的例外是当子测试被逐个等待时。在这种模式下，每个子测试仅在前一个完成后才开始，因此运行器保持声明顺序而不是随机化它。

示例：这是顺序运行的，未随机化。

import test from 'node:test';

test('math', async (t) => {
  for (const name of ['adds', 'subtracts', 'multiplies']) {
    // 顺序等待每个子测试会保留声明顺序。
    await t.test(name, async () => {});
  }
});

使用套件风格的 API（如 describe()/it() 或 suite()/test()）仍然允许随机化，因为兄弟测试是一起排队的。

示例：这仍然符合随机化条件。

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

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

--test-randomize 和 --test-random-seed 不支持与 --watch 模式一起使用。

匹配的文件作为测试文件执行。 有关测试文件执行的更多信息，可以在 测试运行器执行模型 部分找到。

当启用进程级测试隔离时，每个匹配的测试文件都在单独的子进程中执行。任何时间运行的子进程的最大数量由 --test-concurrency 标志控制。如果子进程以退出码 0 结束，则测试视为通过。否则，测试视为失败。测试文件必须可由 Node.js 执行，但不需要在内部使用 node:test 模块。

每个测试文件的执行都好像它是一个常规脚本。也就是说，如果测试文件本身使用 node:test 来定义测试，则所有这些测试都将在单个应用程序线程内执行，无论 test() 的 concurrency 选项值如何。

当禁用进程级测试隔离时，每个匹配的测试文件都导入到测试运行器进程中。加载所有测试文件后，顶层测试以并发数 1 执行。因为所有测试文件都在同一上下文中运行，所以测试可能以启用隔离时不可能的方式相互交互。例如，如果测试依赖于全局状态，则该状态可能被源自另一个文件的测试修改。

在进程隔离模式下运行测试时（默认情况），生成的子进程会从父进程继承 Node.js 选项，包括 配置文件 中指定的选项。但是，某些标志会被过滤掉以启用正确的测试运行器功能：

• --test - 防止递归测试执行
• --experimental-test-coverage - 由测试运行器管理
• --experimental-test-tag-filter - 筛选值由父进程验证并重新发送到子进程
• --watch - 监视模式由父级处理
• --experimental-default-config-file - 配置文件加载由父级处理
• --test-reporter - 报告由父进程管理
• --test-reporter-destination - 输出目标由父级控制
• --experimental-config-file - 配置文件路径由父级管理
• --test-randomize - 随机化由父进程管理并传播到子进程
• --test-random-seed - 随机化种子由父进程管理并传播到子进程

来自命令行参数、环境变量和配置文件的所有其他 Node.js 选项都由子进程继承。

稳定性：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('这段代码永远不会被执行');
}

tap 和 spec 报告器将打印覆盖率统计信息的摘要。还有一个 lcov 报告器，它将生成一个 lcov 文件，可用作深度覆盖率报告。

node --test --experimental-test-coverage --test-reporter=lcov --test-reporter-destination=lcov.info

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

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

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

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

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

请参阅 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);
});

模拟计时器 API 还允许模拟 Date 对象。这对于测试依赖时间的功能或模拟内部日历函数（如 Date.now()）是一个有用的功能。

日期实现也是 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';

--test-reporter 可用于指定自定义报告器的路径。 自定义报告器是一个导出值的模块， 该值被 stream.compose 接受。 报告器应转换由 {TestsStream} 发出的事件

使用 <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, `total line count: ${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 `total line count: ${totalLineCount}\n`;
        break;
      }
    }
  }
}

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

--test-reporter 标志可以指定多次，以多种格式报告测试结果。在这种情况下， 需要使用 --test-reporter-destination 为每个报告器指定一个目标。 目标可以是 stdout、stderr 或文件路径。 报告器和目标根据它们指定的顺序进行配对。

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

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

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

run(options?): void

注意： 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(name?, options?, fn?): void

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

suite.skip(name?, options?, fn?): void

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

suite.todo(name?, options?, fn?): void

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

suite.only(name?, options?, fn?): void

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

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

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 毫秒时使其失败。但是，这不是 一种可靠的取消测试机制，因为正在运行的测试可能会阻塞应用程序线程， 从而阻止计划中的取消。

test.skip(name?, options?, fn?): void

用于跳过测试的简写， 这与 [test([name], { skip: true }[, fn])][it options] 相同。

test.todo(name?, options?, fn?): void

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

test.only(name?, options?, fn?): void

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

describe(name?, options?, fn?): void

suite() 的别名。

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

describe.skip(name?, options?, fn?): void

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

describe.todo(name?, options?, fn?): void

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

describe.only(name?, options?, fn?): void

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

it(name?, options?, fn?): void

test() 的别名。

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

it.skip(name?, options?, fn?): void

用于跳过测试的简写， 这与 [it([name], { skip: true }[, fn])][it options] 相同。

it.todo(name?, options?, fn?): void

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

it.only(name?, options?, fn?): void

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

before(fn?, options?): void

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

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

after(fn?, options?): void

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

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

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

beforeEach(fn?, options?): void

此函数创建一个在当前套件中每个测试之前运行的钩子。

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

afterEach(fn?, options?): void

此函数创建一个在当前测试套件中每个测试之后运行的钩子。 即使测试失败，afterEach() 钩子也会运行。

describe('tests', async () => {
  afterEach(() => console.log('测试运行完成'));
  it('是一个子测试', () => {
    // 相关断言写在这里
  });
});

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

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

assert.register(name, fn): void

使用给定的名称和函数定义一个新的断言函数。如果同名断言已存在，则会被替换。

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

snapshot.setDefaultSnapshotSerializers(serializers): void

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

snapshot.setResolveSnapshotPath(fn): void

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

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

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

ctx.callCount(): void

• 返回：<integer> 此 mock 被调用的次数。

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

ctx.mockImplementation(implementation): void

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

以下示例使用 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.mockImplementation(addTwo);
  assert.strictEqual(fn(), 3);
  assert.strictEqual(fn(), 5);
});

ctx.mockImplementationOnce(implementation, onCall?): void

此函数用于仅更改现有 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);
});

ctx.resetCalls(): void

重置 mock 函数的调用历史。

ctx.restore(): void

将 mock 函数实现重置为其原始行为。调用此函数后仍可继续使用 mock。

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

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

ctx.restore(): void

重置被 mock 的模块实现。

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

• 类型：<Array>

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

ctx.accessCount(): void

• 返回：<integer> 属性被访问的次数（读取或写入）。

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

ctx.mockImplementation(value): void

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

ctx.mockImplementationOnce(value, onAccess?): void

此函数用于更改单次现有 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);
});

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

ctx.resetAccesses(): void

重置被 mock 属性的访问历史。

ctx.restore(): void

将被 mock 属性实现重置为其原始行为。调用此函数后，mock 仍然可以继续使用。