Node.js v25.0.0 文档

测试运行器执行模型#

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

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

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

覆盖率报告器#

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

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

• 此报告器不报告任何测试结果。
• 此报告器最好与另一个报告器一起使用。

定时器#

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

有关方法和功能的完整列表，请参阅 MockTimers 类。

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

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

注意： 此 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();

  // Optionally choose what to mock
  mock.timers.enable({ apis: ['setTimeout'] });
  setTimeout(fn, 9999);
  assert.strictEqual(fn.mock.callCount(), 0);

  // Advance in time
  mock.timers.tick(9999);
  assert.strictEqual(fn.mock.callCount(), 1);

  // Reset the globally tracked mocks.
  mock.timers.reset();

  // If you call reset mock instance, it will also reset timers instance
  mock.reset();
});const assert = require('node:assert');
const { mock, test } = require('node:test');

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

  // Optionally choose what to mock
  mock.timers.enable({ apis: ['setTimeout'] });
  setTimeout(fn, 9999);
  assert.strictEqual(fn.mock.callCount(), 0);

  // Advance in time
  mock.timers.tick(9999);
  assert.strictEqual(fn.mock.callCount(), 1);

  // Reset the globally tracked mocks.
  mock.timers.reset();

  // If you call reset mock instance, it will also reset timers instance
  mock.reset();
});copy

同样的模拟功能也暴露在每个测试的 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();

  // Optionally choose what to mock
  context.mock.timers.enable({ apis: ['setTimeout'] });
  setTimeout(fn, 9999);
  assert.strictEqual(fn.mock.callCount(), 0);

  // Advance in time
  context.mock.timers.tick(9999);
  assert.strictEqual(fn.mock.callCount(), 1);
});const assert = require('node:assert');
const { test } = require('node:test');

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

  // Optionally choose what to mock
  context.mock.timers.enable({ apis: ['setTimeout'] });
  setTimeout(fn, 9999);
  assert.strictEqual(fn.mock.callCount(), 0);

  // Advance in time
  context.mock.timers.tick(9999);
  assert.strictEqual(fn.mock.callCount(), 1);
});copy

日期#

模拟定时器 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) => {
  // Optionally choose what to mock
  context.mock.timers.enable({ apis: ['Date'] });
  // If not specified, the initial date will be based on 0 in the UNIX epoch
  assert.strictEqual(Date.now(), 0);

  // Advance in time will also advance the date
  context.mock.timers.tick(9999);
  assert.strictEqual(Date.now(), 9999);
});const assert = require('node:assert');
const { test } = require('node:test');

test('mocks the Date object', (context) => {
  // Optionally choose what to mock
  context.mock.timers.enable({ apis: ['Date'] });
  // If not specified, the initial date will be based on 0 in the UNIX epoch
  assert.strictEqual(Date.now(), 0);

  // Advance in time will also advance the date
  context.mock.timers.tick(9999);
  assert.strictEqual(Date.now(), 9999);
});copy

如果没有设置初始的纪元时间，初始日期将基于 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) => {
  // Optionally choose what to mock
  context.mock.timers.enable({ apis: ['Date'], now: 100 });
  assert.strictEqual(Date.now(), 100);

  // Advance in time will also advance the date
  context.mock.timers.tick(200);
  assert.strictEqual(Date.now(), 300);
});const assert = require('node:assert');
const { test } = require('node:test');

test('mocks the Date object with initial time', (context) => {
  // Optionally choose what to mock
  context.mock.timers.enable({ apis: ['Date'], now: 100 });
  assert.strictEqual(Date.now(), 100);

  // Advance in time will also advance the date
  context.mock.timers.tick(200);
  assert.strictEqual(Date.now(), 300);
});copy

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

注意： 此方法将执行所有在新时间之前应该触发的模拟定时器。

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

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

test('sets the time of a date object', (context) => {
  // Optionally choose what to mock
  context.mock.timers.enable({ apis: ['Date'], now: 100 });
  assert.strictEqual(Date.now(), 100);

  // Advance in time will also advance the date
  context.mock.timers.setTime(1000);
  context.mock.timers.tick(200);
  assert.strictEqual(Date.now(), 1200);
});const assert = require('node:assert');
const { test } = require('node:test');

test('sets the time of a date object', (context) => {
  // Optionally choose what to mock
  context.mock.timers.enable({ apis: ['Date'], now: 100 });
  assert.strictEqual(Date.now(), 100);

  // Advance in time will also advance the date
  context.mock.timers.setTime(1000);
  context.mock.timers.tick(200);
  assert.strictEqual(Date.now(), 1200);
});copy

如果您有任何设置为在过去运行的定时器，它将被执行，就好像调用了 .tick() 方法一样。如果您想测试已经过去的依赖时间的功能，这将非常有用。

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

test('runs timers as setTime passes ticks', (context) => {
  // Optionally choose what to mock
  context.mock.timers.enable({ apis: ['setTimeout', 'Date'] });
  const fn = context.mock.fn();
  setTimeout(fn, 1000);

  context.mock.timers.setTime(800);
  // Timer is not executed as the time is not yet reached
  assert.strictEqual(fn.mock.callCount(), 0);
  assert.strictEqual(Date.now(), 800);

  context.mock.timers.setTime(1200);
  // Timer is executed as the time is now reached
  assert.strictEqual(fn.mock.callCount(), 1);
  assert.strictEqual(Date.now(), 1200);
});const assert = require('node:assert');
const { test } = require('node:test');

test('runs timers as setTime passes ticks', (context) => {
  // Optionally choose what to mock
  context.mock.timers.enable({ apis: ['setTimeout', 'Date'] });
  const fn = context.mock.fn();
  setTimeout(fn, 1000);

  context.mock.timers.setTime(800);
  // Timer is not executed as the time is not yet reached
  assert.strictEqual(fn.mock.callCount(), 0);
  assert.strictEqual(Date.now(), 800);

  context.mock.timers.setTime(1200);
  // Timer is executed as the time is now reached
  assert.strictEqual(fn.mock.callCount(), 1);
  assert.strictEqual(Date.now(), 1200);
});copy

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

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

test('runs timers as setTime passes ticks', (context) => {
  // Optionally choose what to mock
  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();
  // All timers are executed as the time is now reached
  assert.strictEqual(fn.mock.callCount(), 3);
  assert.strictEqual(Date.now(), 3000);
});const assert = require('node:assert');
const { test } = require('node:test');

test('runs timers as setTime passes ticks', (context) => {
  // Optionally choose what to mock
  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();
  // All timers are executed as the time is now reached
  assert.strictEqual(fn.mock.callCount(), 3);
  assert.strictEqual(Date.now(), 3000);
});copy

自定义报告器#

--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;const { Transform } = require('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;
      }
    }
  },
});

module.exports = customReporter;copy

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

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;
      }
    }
  }
}module.exports = 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;
      }
    }
  }
};copy

提供给 --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 copy

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

assert.register(name, fn)#

使用提供的名称和函数定义一个新的断言函数。如果已存在同名的断言，它将被覆盖。

snapshot.setDefaultSnapshotSerializers(serializers)#

• serializers <Array> 一个同步函数数组，用作快照测试的默认序列化器。

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

snapshot.setResolveSnapshotPath(fn)#

• fn <Function> 一个用于计算快照文件位置的函数。该函数接收测试文件的路径作为其唯一参数。如果测试与文件无关（例如在 REPL 中），则输入为 undefined。fn() 必须返回一个指定快照文件位置的字符串。

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

ctx.calls#

• 类型：<Array>

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

• arguments <Array> 一个包含传递给模拟函数的参数的数组。
• error <any> 如果被模拟的函数抛出异常，则此属性包含抛出的值。默认值： undefined。
• result <any> 被模拟函数返回的值。
• stack <Error> 一个 Error 对象，其堆栈可用于确定被模拟函数调用的位置。
• target <Function> | <undefined> 如果被模拟的函数是构造函数，此字段包含正在构造的类。否则此字段为 undefined。
• this <any> 被模拟函数的 this 值。

ctx.callCount()#

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

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

ctx.mockImplementation(implementation)#

• implementation <Function> | <AsyncFunction> 用作模拟新实现的函数。

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

以下示例使用 t.mock.fn() 创建一个模拟函数，调用该模拟函数，然后将模拟实现更改为另一个函数。

test('changes a mock behavior', (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);
}); copy

ctx.mockImplementationOnce(implementation[, onCall])#

• implementation <Function> | <AsyncFunction> 用于在 onCall 指定的调用次数时作为模拟实现的函数。
• onCall <integer> 将使用 implementation 的调用次数。如果指定的调用已经发生，则抛出异常。默认值： 下一次调用的次数。

此函数用于在单次调用中更改现有模拟的行为。一旦第 onCall 次调用发生，模拟将恢复到未调用 mockImplementationOnce() 时的行为。

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

test('changes a mock behavior once', (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);
}); copy

ctx.resetCalls()#

重置模拟函数的调用历史记录。

ctx.restore()#

将模拟函数的实现重置为其原始行为。调用此函数后，模拟仍然可以使用。

ctx.restore()#

重置模拟模块的实现。

ctx.accesses#

• 类型：<Array>

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

• type <string> 'get' 或 'set'，表示访问的类型。
• value <any> 读取的值（对于 'get'）或写入的值（对于 'set'）。
• stack <Error> 一个 Error 对象，其堆栈可用于确定被模拟函数调用的位置。

ctx.accessCount()#

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

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

ctx.mockImplementation(value)#

• value <any> 要设置为模拟属性值的新值。

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

ctx.mockImplementationOnce(value[, onAccess])#

• value <any> 用于在由 onAccess 指定的调用次数时作为模拟实现的值。
• onAccess <integer> 将使用 value 的调用次数。如果指定的调用已经发生，则会抛出异常。默认值： 下一次调用的次数。

此函数用于在单次调用中更改现有模拟的行为。一旦第 onAccess 次调用发生，模拟将恢复到未调用 mockImplementationOnce() 时的行为。

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

test('changes a mock behavior once', (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);
}); copy

ctx.resetAccesses()#

重置模拟属性的访问历史记录。

ctx.restore()#

将模拟属性的实现重置为其原始行为。调用此函数后，模拟仍然可以使用。

mock.fn([original[, implementation]][, options])#

• original <Function> | <AsyncFunction> 一个可选的函数，在其上创建模拟。默认值： 一个空操作函数。
• implementation <Function> | <AsyncFunction> 一个可选的函数，用作 original 的模拟实现。这对于创建在指定调用次数内表现出一种行为，然后恢复 original 行为的模拟很有用。默认值： original 指定的函数。
• options <Object> 模拟函数的可选配置选项。支持以下属性：
  • times <integer> 模拟将使用 implementation 行为的次数。一旦模拟函数被调用了 times 次，它将自动恢复 original 的行为。此值必须是大于零的整数。默认值： Infinity。
• 返回：<Proxy> 被模拟的函数。被模拟的函数包含一个特殊的 mock 属性，它是 MockFunctionContext 的实例，可用于检查和更改被模拟函数的行为。

此函数用于创建模拟函数。

以下示例创建一个模拟函数，每次调用时将计数器加一。times 选项用于修改模拟行为，使得前两次调用将计数器加二而不是一。

test('mocks a counting function', (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);
}); copy

mock.getter(object, methodName[, implementation][, options])#

此函数是 MockTracker.method 的语法糖，其中 options.getter 设置为 true。

mock.method(object, methodName[, implementation][, options])#

• object <Object> 其方法被模拟的对象。
• methodName <string> | <symbol> object 上要模拟的方法的标识符。如果 object[methodName] 不是函数，则抛出错误。
• implementation <Function> | <AsyncFunction> 一个可选的函数，用作 object[methodName] 的模拟实现。默认值： object[methodName] 指定的原始方法。
• options <Object> 模拟方法的可选配置选项。支持以下属性：
  • getter <boolean> 如果为 true，则将 object[methodName] 视为 getter。此选项不能与 setter 选项一起使用。默认值： false。
  • setter <boolean> 如果为 true，则将 object[methodName] 视为 setter。此选项不能与 getter 选项一起使用。默认值： false。
  • times <integer> mock 将使用 implementation 行为的次数。一旦被 mock 的方法被调用了 times 次，它将自动恢复原始行为。该值必须是大于零的整数。默认值： Infinity。
• 返回：<Proxy> 被 mock 的方法。被 mock 的方法包含一个特殊的 mock 属性，它是 MockFunctionContext 的实例，可用于检查和更改被 mock 方法的行为。

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

test('spies on an object method', (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);
}); copy

mock.module(specifier[, options])#

• specifier <string> | <URL> 标识要 mock 的模块的字符串。
• options <Object> mock 模块的可选配置选项。支持以下属性：
  • cache <boolean> 如果为 false，每次调用 require() 或 import() 都会生成一个新的 mock 模块。如果为 true，后续调用将返回相同的模块 mock，并且该 mock 模块会插入到 CommonJS 缓存中。默认值： false。
  • defaultExport <any> 一个可选值，用作 mock 模块的默认导出。如果未提供此值，ESM mock 不包含默认导出。如果 mock 是 CommonJS 或内置模块，此设置将用作 module.exports 的值。如果未提供此值，CJS 和内置 mock 将使用一个空对象作为 module.exports 的值。
  • namedExports <Object> 一个可选对象，其键和值用于创建 mock 模块的命名导出。如果 mock 是 CommonJS 或内置模块，这些值将被复制到 module.exports 上。因此，如果创建的 mock 同时具有命名导出和非对象的默认导出，当作为 CJS 或内置模块使用时，该 mock 将抛出异常。
• 返回：<MockModuleContext> 一个可用于操作 mock 的对象。

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

以下示例演示了如何为模块创建 mock。

test('mocks a builtin module in both module systems', async (t) => {
  // Create a mock of 'node:readline' with a named export named 'fn', which
  // does not exist in the original 'node:readline' module.
  const mock = t.mock.module('node:readline', {
    namedExports: { fn() { return 42; } },
  });

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

  // cursorTo() is an export of the original 'node:readline' module.
  assert.strictEqual(esmImpl.cursorTo, undefined);
  assert.strictEqual(cjsImpl.cursorTo, undefined);
  assert.strictEqual(esmImpl.fn(), 42);
  assert.strictEqual(cjsImpl.fn(), 42);

  mock.restore();

  // The mock is restored, so the original builtin module is returned.
  esmImpl = await import('node:readline');
  cjsImpl = require('node:readline');

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

mock.property(object, propertyName[, value])#

• object <Object> 其值被 mock 的对象。
• propertyName <string> | <symbol> object 上要 mock 的属性的标识符。
• value <any> 一个可选值，用作 object[propertyName] 的 mock 值。默认值： 原始属性值。
• 返回：<Proxy> 指向被 mock 对象的代理。被 mock 的对象包含一个特殊的 mock 属性，它是 MockPropertyContext 的实例，可用于检查和更改被 mock 属性的行为。

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

test('mocks a property value', (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);
}); copy

mock.reset()#

此函数恢复所有先前由此 MockTracker 创建的 mock 的默认行为，并将这些 mock 与 MockTracker 实例解除关联。一旦解除关联，这些 mock 仍然可以使用，但 MockTracker 实例不能再用于重置它们的行为或以其他方式与它们交互。

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

mock.restoreAll()#

此函数恢复所有先前由此 MockTracker 创建的 mock 的默认行为。与 mock.reset() 不同，mock.restoreAll() 不会将 mock 与 MockTracker 实例解除关联。

mock.setter(object, methodName[, implementation][, options])#

此函数是 MockTracker.method 的语法糖，其中 options.setter 设置为 true。

timers.enable([enableOptions])#

为指定的计时器启用 mock 功能。

• enableOptions <Object> 启用计时器 mock 的可选配置选项。支持以下属性：
  • apis <Array> 一个包含要 mock 的计时器的可选数组。当前支持的计时器值为 'setInterval'、'setTimeout'、'setImmediate' 和 'Date'。默认值： ['setInterval', 'setTimeout', 'setImmediate', 'Date']。如果未提供数组，默认将 mock 所有与时间相关的 API（'setInterval'、'clearInterval'、'setTimeout'、'clearTimeout'、'setImmediate'、'clearImmediate' 和 'Date'）。
  • now <number> | <Date> 一个可选的数字或 Date 对象，表示用作 Date.now() 值的初始时间（以毫秒为单位）。默认值： 0。

注意： 当你为特定计时器启用 mock 时，其关联的清除函数也将被隐式 mock。

注意： mock Date 会影响被 mock 计时器的行为，因为它们使用相同的内部时钟。

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

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

上述示例为 setInterval 计时器启用 mock，并隐式 mock 了 clearInterval 函数。只有来自 node:timers、node:timers/promises 和 globalThis 的 setInterval 和 clearInterval 函数会被 mock。

设置初始时间的使用示例

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

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

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

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

所有计时器（'setInterval'、'clearInterval'、'setTimeout'、'clearTimeout'、'setImmediate' 和 'clearImmediate'）都将被 mock。来自 node:timers、node:timers/promises 和 globalThis 的 setInterval、clearInterval、setTimeout、clearTimeout、setImmediate 和 clearImmediate 函数将被 mock。以及全局 Date 对象。

timers.reset()#

此函数恢复所有先前由此 MockTimers 实例创建的 mock 的默认行为，并将这些 mock 与 MockTracker 实例解除关联。

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

import { mock } from 'node:test';
mock.timers.reset();const { mock } = require('node:test');
mock.timers.reset();copy

timers[Symbol.dispose]()#

调用 timers.reset()。

timers.tick([milliseconds])#

为所有被 mock 的计时器推进时间。

• milliseconds <number> 推进计时器的时间量，以毫秒为单位。默认值： 1。

注意： 这与 Node.js 中 setTimeout 的行为不同，只接受正数。在 Node.js 中，支持带有负数的 setTimeout 仅是为了 web 兼容性。

以下示例 mock 了一个 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);

  // Advance in time
  context.mock.timers.tick(9999);

  assert.strictEqual(fn.mock.callCount(), 1);
});const assert = require('node:assert');
const { test } = require('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);

  // Advance in time
  context.mock.timers.tick(9999);

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

另外，.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);
});const assert = require('node:assert');
const { test } = require('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);
});copy

使用 .tick 推进时间也会推进在 mock 启用后创建的任何 Date 对象的时间（如果 Date 也被设置为 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', 'Date'] });
  setTimeout(fn, 9999);

  assert.strictEqual(fn.mock.callCount(), 0);
  assert.strictEqual(Date.now(), 0);

  // Advance in time
  context.mock.timers.tick(9999);
  assert.strictEqual(fn.mock.callCount(), 1);
  assert.strictEqual(Date.now(), 9999);
});const assert = require('node:assert');
const { test } = require('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);

  // Advance in time
  context.mock.timers.tick(9999);
  assert.strictEqual(fn.mock.callCount(), 1);
  assert.strictEqual(Date.now(), 9999);
});copy

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

  // Optionally choose what to mock
  context.mock.timers.enable({ apis: ['setTimeout'] });
  const id = setTimeout(fn, 9999);

  // Implicitly mocked as well
  clearTimeout(id);
  context.mock.timers.tick(9999);

  // As that setTimeout was cleared the mock function will never be called
  assert.strictEqual(fn.mock.callCount(), 0);
});const assert = require('node:assert');
const { test } = require('node:test');

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

  // Optionally choose what to mock
  context.mock.timers.enable({ apis: ['setTimeout'] });
  const id = setTimeout(fn, 9999);

  // Implicitly mocked as well
  clearTimeout(id);
  context.mock.timers.tick(9999);

  // As that setTimeout was cleared the mock function will never be called
  assert.strictEqual(fn.mock.callCount(), 0);
});copy

import assert from 'node:assert';
import { test } from 'node:test';
import nodeTimers from 'node:timers';
import nodeTimersPromises from 'node:timers/promises';

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

  // Optionally choose what to mock
  context.mock.timers.enable({ apis: ['setTimeout'] });
  setTimeout(globalTimeoutObjectSpy, 9999);
  nodeTimers.setTimeout(nodeTimerSpy, 9999);

  const promise = nodeTimersPromises.setTimeout(9999).then(nodeTimerPromiseSpy);

  // Advance in time
  context.mock.timers.tick(9999);
  assert.strictEqual(globalTimeoutObjectSpy.mock.callCount(), 1);
  assert.strictEqual(nodeTimerSpy.mock.callCount(), 1);
  await promise;
  assert.strictEqual(nodeTimerPromiseSpy.mock.callCount(), 1);
});const assert = require('node:assert');
const { test } = require('node:test');
const nodeTimers = require('node:timers');
const nodeTimersPromises = require('node:timers/promises');

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

  // Optionally choose what to mock
  context.mock.timers.enable({ apis: ['setTimeout'] });
  setTimeout(globalTimeoutObjectSpy, 9999);
  nodeTimers.setTimeout(nodeTimerSpy, 9999);

  const promise = nodeTimersPromises.setTimeout(9999).then(nodeTimerPromiseSpy);

  // Advance in time
  context.mock.timers.tick(9999);
  assert.strictEqual(globalTimeoutObjectSpy.mock.callCount(), 1);
  assert.strictEqual(nodeTimerSpy.mock.callCount(), 1);
  await promise;
  assert.strictEqual(nodeTimerPromiseSpy.mock.callCount(), 1);
});copy

import assert from 'node:assert';
import { test } from 'node:test';
import nodeTimersPromises from 'node:timers/promises';
test('should tick five times testing a real use case', async (context) => {
  context.mock.timers.enable({ apis: ['setInterval'] });

  const expectedIterations = 3;
  const interval = 1000;
  const startedAt = Date.now();
  async function run() {
    const times = [];
    for await (const time of nodeTimersPromises.setInterval(interval, startedAt)) {
      times.push(time);
      if (times.length === expectedIterations) break;
    }
    return times;
  }

  const r = run();
  context.mock.timers.tick(interval);
  context.mock.timers.tick(interval);
  context.mock.timers.tick(interval);

  const timeResults = await r;
  assert.strictEqual(timeResults.length, expectedIterations);
  for (let it = 1; it < expectedIterations; it++) {
    assert.strictEqual(timeResults[it - 1], startedAt + (interval * it));
  }
});const assert = require('node:assert');
const { test } = require('node:test');
const nodeTimersPromises = require('node:timers/promises');
test('should tick five times testing a real use case', async (context) => {
  context.mock.timers.enable({ apis: ['setInterval'] });

  const expectedIterations = 3;
  const interval = 1000;
  const startedAt = Date.now();
  async function run() {
    const times = [];
    for await (const time of nodeTimersPromises.setInterval(interval, startedAt)) {
      times.push(time);
      if (times.length === expectedIterations) break;
    }
    return times;
  }

  const r = run();
  context.mock.timers.tick(interval);
  context.mock.timers.tick(interval);
  context.mock.timers.tick(interval);

  const timeResults = await r;
  assert.strictEqual(timeResults.length, expectedIterations);
  for (let it = 1; it < expectedIterations; it++) {
    assert.strictEqual(timeResults[it - 1], startedAt + (interval * it));
  }
});copy

timers.runAll()#

立即触发所有待处理的 mock 计时器。如果 Date 对象也被 mock，它也会将 Date 对象推进到最远计时器的时间。

下面的示例立即触发所有待处理的计时器，使它们无需任何延迟地执行。

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

test('runAll functions following the given order', (context) => {
  context.mock.timers.enable({ apis: ['setTimeout', 'Date'] });
  const results = [];
  setTimeout(() => results.push(1), 9999);

  // Notice that if both timers have the same timeout,
  // the order of execution is guaranteed
  setTimeout(() => results.push(3), 8888);
  setTimeout(() => results.push(2), 8888);

  assert.deepStrictEqual(results, []);

  context.mock.timers.runAll();
  assert.deepStrictEqual(results, [3, 2, 1]);
  // The Date object is also advanced to the furthest timer's time
  assert.strictEqual(Date.now(), 9999);
});const assert = require('node:assert');
const { test } = require('node:test');

test('runAll functions following the given order', (context) => {
  context.mock.timers.enable({ apis: ['setTimeout', 'Date'] });
  const results = [];
  setTimeout(() => results.push(1), 9999);

  // Notice that if both timers have the same timeout,
  // the order of execution is guaranteed
  setTimeout(() => results.push(3), 8888);
  setTimeout(() => results.push(2), 8888);

  assert.deepStrictEqual(results, []);

  context.mock.timers.runAll();
  assert.deepStrictEqual(results, [3, 2, 1]);
  // The Date object is also advanced to the furthest timer's time
  assert.strictEqual(Date.now(), 9999);
});copy

注意： runAll() 函数是专门为在计时器 mock 上下文中触发计时器而设计的。它对实时系统时钟或 mock 环境之外的实际计时器没有任何影响。

timers.setTime(milliseconds)#

设置将用作任何被 mock 的 Date 对象的参考的当前 Unix 时间戳。

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

test('runAll functions following the given order', (context) => {
  const now = Date.now();
  const setTime = 1000;
  // Date.now is not mocked
  assert.deepStrictEqual(Date.now(), now);

  context.mock.timers.enable({ apis: ['Date'] });
  context.mock.timers.setTime(setTime);
  // Date.now is now 1000
  assert.strictEqual(Date.now(), setTime);
});const assert = require('node:assert');
const { test } = require('node:test');

test('setTime replaces current time', (context) => {
  const now = Date.now();
  const setTime = 1000;
  // Date.now is not mocked
  assert.deepStrictEqual(Date.now(), now);

  context.mock.timers.enable({ apis: ['Date'] });
  context.mock.timers.setTime(setTime);
  // Date.now is now 1000
  assert.strictEqual(Date.now(), setTime);
});copy

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

test('runAll functions following the given order', (context) => {
  context.mock.timers.enable({ apis: ['setTimeout', 'Date'] });
  const results = [];
  setTimeout(() => results.push(1), 9999);

  assert.deepStrictEqual(results, []);
  context.mock.timers.setTime(12000);
  assert.deepStrictEqual(results, []);
  // The date is advanced but the timers don't tick
  assert.strictEqual(Date.now(), 12000);
});const assert = require('node:assert');
const { test } = require('node:test');

test('runAll functions following the given order', (context) => {
  context.mock.timers.enable({ apis: ['setTimeout', 'Date'] });
  const results = [];
  setTimeout(() => results.push(1), 9999);

  assert.deepStrictEqual(results, []);
  context.mock.timers.setTime(12000);
  assert.deepStrictEqual(results, []);
  // The date is advanced but the timers don't tick
  assert.strictEqual(Date.now(), 12000);
});copy

事件：'test:coverage'#

• data <Object>
  • summary <Object> 包含覆盖率报告的对象。
    • files <Array> 单个文件覆盖率报告的数组。每个报告都是一个具有以下结构的对象：
      • path <string> 文件的绝对路径。
      • totalLineCount <number> 总行数。
      • totalBranchCount <number> 总分支数。
      • totalFunctionCount <number> 总函数数。
      • coveredLineCount <number> 覆盖的行数。
      • coveredBranchCount <number> 覆盖的分支数。
      • coveredFunctionCount <number> 覆盖的函数数。
      • coveredLinePercent <number> 行覆盖率百分比。
      • coveredBranchPercent <number> 分支覆盖率百分比。
      • coveredFunctionPercent <number> 函数覆盖率百分比。
      • functions <Array> 表示函数覆盖率的函数数组。
        • name <string> 函数名。
        • line <number> 函数定义的行号。
        • count <number> 函数被调用的次数。
      • branches <Array> 表示分支覆盖率的分支数组。
        • line <number> 分支定义的行号。
        • count <number> 分支被采用的次数。
      • lines <Array> 表示行号及其被覆盖次数的行数组。
        • line <number> 行号。
        • count <number> 该行被覆盖的次数。
    • thresholds <Object> 包含每种覆盖类型是否达标的对象。
      • function <number> 函数覆盖率阈值。
      • branch <number> 分支覆盖率阈值。
      • line <number> 行覆盖率阈值。
    • totals <Object> 包含所有文件覆盖率摘要的对象。
      • totalLineCount <number> 总行数。
      • totalBranchCount <number> 总分支数。
      • totalFunctionCount <number> 总函数数。
      • coveredLineCount <number> 覆盖的行数。
      • coveredBranchCount <number> 覆盖的分支数。
      • coveredFunctionCount <number> 覆盖的函数数。
      • coveredLinePercent <number> 行覆盖率百分比。
      • coveredBranchPercent <number> 分支覆盖率百分比。
      • coveredFunctionPercent <number> 函数覆盖率百分比。
    • workingDirectory <string> 代码覆盖率开始时的工作目录。这对于在测试更改了 Node.js 进程工作目录的情况下显示相对路径名很有用。
  • nesting <number> 测试的嵌套层级。

当代码覆盖率启用且所有测试完成后发出。

事件：'test:complete'#

• data <Object>
  • column <number> | <undefined> 定义测试的列号，如果测试是通过 REPL 运行的，则为 undefined。
  • details <Object> 附加的执行元数据。
    • passed <boolean> 测试是否通过。
    • duration_ms <number> 测试的持续时间（以毫秒为单位）。
    • error <Error> | <undefined> 如果测试未通过，则为一个包装了测试抛出的错误的错误对象。
      • cause <Error> 测试实际抛出的错误。
    • type <string> | <undefined> 测试的类型，用于表示这是否是一个测试套件。
  • file <string> | <undefined> 测试文件的路径，如果测试是通过 REPL 运行的，则为 undefined。
  • line <number> | <undefined> 定义测试的行号，如果测试是通过 REPL 运行的，则为 undefined。
  • name <string> 测试名称。
  • nesting <number> 测试的嵌套层级。
  • testNumber <number> 测试的序数。
  • todo <string> | <boolean> | <undefined> 如果调用了 context.todo，则存在此字段。
  • skip <string> | <boolean> | <undefined> 如果调用了 context.skip，则存在此字段。

当一个测试完成其执行时发出。此事件不是按照测试定义的顺序发出的。相应的按声明顺序的事件是 'test:pass' 和 'test:fail'。

事件：'test:dequeue'#

• data <Object>
  • column <number> | <undefined> 定义测试的列号，如果测试是通过 REPL 运行的，则为 undefined。
  • file <string> | <undefined> 测试文件的路径，如果测试是通过 REPL 运行的，则为 undefined。
  • line <number> | <undefined> 定义测试的行号，如果测试是通过 REPL 运行的，则为 undefined。
  • name <string> 测试名称。
  • nesting <number> 测试的嵌套层级。
  • type <string> 测试类型。可以是 'suite' 或 'test'。

当一个测试出队，即将执行之前发出。此事件不保证按照测试定义的顺序发出。相应的按声明顺序的事件是 'test:start'。

事件：'test:diagnostic'#

• data <Object>
  • column <number> | <undefined> 定义测试的列号，如果测试是通过 REPL 运行的，则为 undefined。
  • file <string> | <undefined> 测试文件的路径，如果测试是通过 REPL 运行的，则为 undefined。
  • line <number> | <undefined> 定义测试的行号，如果测试是通过 REPL 运行的，则为 undefined。
  • message <string> 诊断信息。
  • nesting <number> 测试的嵌套层级。
  • level <string> 诊断信息的严重性级别。可能的值有：
    • 'info'：信息性消息。
    • 'warn'：警告。
    • 'error'：错误。

当调用 context.diagnostic 时发出。此事件保证按照测试定义的顺序发出。

事件：'test:enqueue'#

• data <Object>
  • column <number> | <undefined> 定义测试的列号，如果测试是通过 REPL 运行的，则为 undefined。
  • file <string> | <undefined> 测试文件的路径，如果测试是通过 REPL 运行的，则为 undefined。
  • line <number> | <undefined> 定义测试的行号，如果测试是通过 REPL 运行的，则为 undefined。
  • name <string> 测试名称。
  • nesting <number> 测试的嵌套层级。
  • type <string> 测试类型。可以是 'suite' 或 'test'。

当一个测试被加入执行队列时发出。

事件：'test:fail'#

• data <Object>
  • column <number> | <undefined> 定义测试的列号，如果测试是通过 REPL 运行的，则为 undefined。
  • details <Object> 附加的执行元数据。
    • duration_ms <number> 测试的持续时间（以毫秒为单位）。
    • error <Error> 一个包装了测试抛出的错误的错误对象。
      • cause <Error> 测试实际抛出的错误。
    • type <string> | <undefined> 测试的类型，用于表示这是否是一个测试套件。
    • attempt <number> | <undefined> 测试运行的尝试次数，仅在使用 --test-rerun-failures 标志时存在。
  • file <string> | <undefined> 测试文件的路径，如果测试是通过 REPL 运行的，则为 undefined。
  • line <number> | <undefined> 定义测试的行号，如果测试是通过 REPL 运行的，则为 undefined。
  • name <string> 测试名称。
  • nesting <number> 测试的嵌套层级。
  • testNumber <number> 测试的序数。
  • todo <string> | <boolean> | <undefined> 如果调用了 context.todo，则存在此字段。
  • skip <string> | <boolean> | <undefined> 如果调用了 context.skip，则存在此字段。

当一个测试失败时发出。此事件保证按照测试定义的顺序发出。相应的按执行顺序的事件是 'test:complete'。

事件：'test:pass'#

• data <Object>
  • column <number> | <undefined> 定义测试的列号，如果测试是通过 REPL 运行的，则为 undefined。
  • details <Object> 附加的执行元数据。
    • duration_ms <number> 测试的持续时间（以毫秒为单位）。
    • type <string> | <undefined> 测试的类型，用于表示这是否是一个测试套件。
    • attempt <number> | <undefined> 测试运行的尝试次数，仅在使用 --test-rerun-failures 标志时存在。
    • passed_on_attempt <number> | <undefined> 测试通过的尝试次数，仅在使用 --test-rerun-failures 标志时存在。
  • file <string> | <undefined> 测试文件的路径，如果测试是通过 REPL 运行的，则为 undefined。
  • line <number> | <undefined> 定义测试的行号，如果测试是通过 REPL 运行的，则为 undefined。
  • name <string> 测试名称。
  • nesting <number> 测试的嵌套层级。
  • testNumber <number> 测试的序数。
  • todo <string> | <boolean> | <undefined> 如果调用了 context.todo，则存在此字段。
  • skip <string> | <boolean> | <undefined> 如果调用了 context.skip，则存在此字段。

当一个测试通过时发出。此事件保证按照测试定义的顺序发出。相应的按执行顺序的事件是 'test:complete'。

事件：'test:plan'#

• data <Object>
  • column <number> | <undefined> 定义测试的列号，如果测试是通过 REPL 运行的，则为 undefined。
  • file <string> | <undefined> 测试文件的路径，如果测试是通过 REPL 运行的，则为 undefined。
  • line <number> | <undefined> 定义测试的行号，如果测试是通过 REPL 运行的，则为 undefined。
  • nesting <number> 测试的嵌套层级。
  • count <number> 已运行的子测试数量。

当给定测试的所有子测试都完成时发出。此事件保证按照测试定义的顺序发出。

事件：'test:start'#

• data <Object>
  • column <number> | <undefined> 定义测试的列号，如果测试是通过 REPL 运行的，则为 undefined。
  • file <string> | <undefined> 测试文件的路径，如果测试是通过 REPL 运行的，则为 undefined。
  • line <number> | <undefined> 定义测试的行号，如果测试是通过 REPL 运行的，则为 undefined。
  • name <string> 测试名称。
  • nesting <number> 测试的嵌套层级。

当一个测试开始报告其自身及其子测试的状态时发出。此事件保证按照测试定义的顺序发出。相应的按执行顺序的事件是 'test:dequeue'。

事件：'test:stderr'#

• data <Object>
  • file <string> 测试文件的路径。
  • message <string> 写入 stderr 的消息。

当正在运行的测试写入 stderr 时发出。此事件仅在传递了 --test 标志时发出。此事件不保证按照测试定义的顺序发出。

事件：'test:stdout'#

• data <Object>
  • file <string> 测试文件的路径。
  • message <string> 写入 stdout 的消息。

当正在运行的测试写入 stdout 时发出。此事件仅在传递了 --test 标志时发出。此事件不保证按照测试定义的顺序发出。

事件：'test:summary'#

• data <Object>
  • counts <Object> 包含各种测试结果计数的对象。
    • cancelled <number> 取消的测试总数。
    • failed <number> 失败的测试总数。
    • passed <number> 通过的测试总数。
    • skipped <number> 跳过的测试总数。
    • suites <number> 运行的测试套件总数。
    • tests <number> 运行的测试总数，不包括套件。
    • todo <number> TODO 测试的总数。
    • topLevel <number> 顶层测试和套件的总数。
  • duration_ms <number> 测试运行的持续时间（以毫秒为单位）。
  • file <string> | <undefined> 生成摘要的测试文件的路径。如果摘要对应多个文件，则此值为 undefined。
  • success <boolean> 指示测试运行是否被视为成功。如果发生任何错误情况，例如测试失败或未满足覆盖率阈值，此值将设置为 false。

当测试运行完成时发出。此事件包含与已完成测试运行相关的指标，对于确定测试运行是否通过或失败很有用。如果使用进程级测试隔离，除了最终的累积摘要外，还会为每个测试文件生成一个 'test:summary' 事件。

事件：'test:watch:drained'#

在监视模式下，当没有更多测试排队等待执行时发出。

事件：'test:watch:restarted'#

在监视模式下，由于文件更改而重新启动一个或多个测试时发出。

context.before([fn][, options])#

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

此函数用于创建一个在当前测试的子测试之前运行的钩子。

context.beforeEach([fn][, options])#

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

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

test('top level test', async (t) => {
  t.beforeEach((t) => t.diagnostic(`about to run ${t.name}`));
  await t.test(
    'This is a subtest',
    (t) => {
      assert.ok('some relevant assertion here');
    },
  );
}); copy

context.after([fn][, options])#

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

此函数用于创建一个在当前测试完成后运行的钩子。

test('top level test', async (t) => {
  t.after((t) => t.diagnostic(`finished running ${t.name}`));
  assert.ok('some relevant assertion here');
}); copy

context.afterEach([fn][, options])#

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

此函数用于创建一个在当前测试的每个子测试之后运行的钩子。

test('top level test', async (t) => {
  t.afterEach((t) => t.diagnostic(`finished running ${t.name}`));
  await t.test(
    'This is a subtest',
    (t) => {
      assert.ok('some relevant assertion here');
    },
  );
}); copy

context.assert#

一个包含绑定到 context 的断言方法的对象。node:assert 模块的顶层函数在这里公开，用于创建测试计划。

test('test', (t) => {
  t.plan(1);
  t.assert.strictEqual(true, true);
}); copy

test('snapshot test with default serialization', (t) => {
  t.assert.fileSnapshot({ value1: 1, value2: 2 }, './snapshots/snapshot.json');
}); copy

test('snapshot test with default serialization', (t) => {
  t.assert.snapshot({ value1: 1, value2: 2 });
});

test('snapshot test with custom serialization', (t) => {
  t.assert.snapshot({ value3: 3, value4: 4 }, {
    serializers: [(value) => JSON.stringify(value)],
  });
}); copy

context.diagnostic(message)#

• message <string> 要报告的消息。

此函数用于将诊断信息写入输出。任何诊断信息都包含在测试结果的末尾。此函数不返回值。

test('top level test', (t) => {
  t.diagnostic('A diagnostic message');
}); copy

context.filePath#

创建当前测试的测试文件的绝对路径。如果一个测试文件导入了其他生成测试的模块，导入的测试将返回根测试文件的路径。

context.fullName#

测试的名称及其每个祖先的名称，用 > 分隔。

context.name#

测试的名称。

context.plan(count[,options])#

• count <number> 预期运行的断言和子测试的数量。
• options <Object> 计划的附加选项。
  • wait <boolean> | <number> 计划的等待时间
    • 如果为 true，计划将无限期等待所有断言和子测试运行。
    • 如果为 false，计划将在测试函数完成后立即进行检查，不等待任何待处理的断言或子测试。在此检查之后完成的任何断言或子测试将不计入计划中。
    • 如果是一个数字，它指定了在等待预期断言和子测试匹配时超时的最大等待时间（以毫秒为单位）。如果达到超时，测试将失败。默认值： false。

此函数用于设置测试中预期运行的断言和子测试的数量。如果运行的断言和子测试数量与预期数量不匹配，测试将失败。

注意：为确保断言被跟踪，必须使用 t.assert 而不是直接使用 assert。

test('top level test', (t) => {
  t.plan(2);
  t.assert.ok('some relevant assertion here');
  t.test('subtest', () => {});
}); copy

在处理异步代码时，plan 函数可用于确保运行正确数量的断言：

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

使用 wait 选项时，你可以控制测试等待预期断言的时间。例如，设置最大等待时间可以确保测试在指定的时间范围内等待异步断言完成：

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

注意：如果指定了 wait 超时，它仅在测试函数执行完毕后才开始倒计时。

context.runOnly(shouldRunOnlyTests)#

• shouldRunOnlyTests <boolean> 是否只运行带有 only 选项的测试。

如果 shouldRunOnlyTests 为真值，测试上下文将只运行设置了 only 选项的测试。否则，所有测试都将运行。如果 Node.js 不是用 --test-only 命令行选项启动的，则此函数为空操作。

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 }),
  ]);
}); copy

context.signal#

• 类型：<AbortSignal>

可用于在测试被中止时中止测试子任务。

test('top level test', async (t) => {
  await fetch('some/uri', { signal: t.signal });
}); copy

context.skip([message])#

• message <string> 可选的跳过消息。

此函数使测试的输出指示该测试被跳过。如果提供了 message，它将包含在输出中。调用 skip() 不会终止测试函数的执行。此函数不返回值。

test('top level test', (t) => {
  // Make sure to return here as well if the test contains additional logic.
  t.skip('this is skipped');
}); copy

context.todo([message])#

• message <string> 可选的 TODO 消息。

此函数向测试的输出添加一个 TODO 指令。如果提供了 message，它将包含在输出中。调用 todo() 不会终止测试函数的执行。此函数不返回值。

test('top level test', (t) => {
  // This test is marked as `TODO`
  t.todo('this is a todo');
}); copy

context.test([name][, options][, fn])#

• name <string> 子测试的名称，在报告测试结果时显示。默认值： fn 的 name 属性，如果 fn 没有名称，则为 '<anonymous>'。
• options <Object> 子测试的配置选项。支持以下属性：
  • concurrency <number> | <boolean> | <null> 如果提供一个数字，则在应用程序线程内将并行运行那么多数量的测试。如果为 true，将并行运行所有子测试。如果为 false，一次只运行一个测试。如果未指定，子测试将从其父测试继承此值。默认值： null。
  • only <boolean> 如果为真值，并且测试上下文配置为只运行 only 测试，则此测试将被运行。否则，该测试将被跳过。默认值： false。
  • signal <AbortSignal> 允许中止正在进行的测试。
  • skip <boolean> | <string> 如果为真值，则跳过该测试。如果提供一个字符串，该字符串将作为跳过测试的原因显示在测试结果中。默认值： false。
  • todo <boolean> | <string> 如果为真值，则将测试标记为 TODO。如果提供一个字符串，该字符串将作为测试为 TODO 的原因显示在测试结果中。默认值： false。
  • timeout <number> 测试将在多少毫秒后失败。如果未指定，子测试将从其父级继承此值。默认值： Infinity。
  • plan <number> 预计在测试中运行的断言和子测试的数量。如果测试中运行的断言数量与计划中指定的数量不匹配，测试将失败。默认值： undefined。
• fn <Function> | <AsyncFunction> 被测试的函数。此函数的第一个参数是 TestContext 对象。如果测试使用回调，则回调函数作为第二个参数传递。默认值： 一个空操作函数。
• 返回：<Promise> 在测试完成后以 undefined 兑现。

此函数用于在当前测试下创建子测试。此函数的行为与顶层 test() 函数相同。

test('top level test', async (t) => {
  await t.test(
    'This is a subtest',
    { only: false, skip: false, concurrency: 1, todo: false, plan: 1 },
    (t) => {
      t.assert.ok('some relevant assertion here');
    },
  );
}); copy

context.waitFor(condition[, options])#

• condition <Function> | <AsyncFunction> 一个断言函数，它会周期性地被调用，直到它成功完成或定义的轮询超时。成功完成定义为不抛出错误或拒绝。此函数不接受任何参数，并允许返回任何值。
• options <Object> 轮询操作的可选配置对象。支持以下属性：
  • interval <number> 在一次不成功的 condition 调用后，再次尝试之前等待的毫秒数。默认值： 50。
  • timeout <number> 轮询超时时间（以毫秒为单位）。如果在此时间耗尽时 condition 仍未成功，则会发生错误。默认值： 1000。
• 返回：<Promise> 以 condition 返回的值兑现。

此方法轮询一个 condition 函数，直到该函数成功返回或操作超时。

context.filePath#

创建当前测试套件的测试文件的绝对路径。如果一个测试文件导入了其他生成测试套件的模块，导入的套件将返回根测试文件的路径。

context.name#

测试套件的名称。

context.signal#

• 类型：<AbortSignal>

可用于在测试被中止时中止测试子任务。