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>

可用於在測試被中止時中止測試子任務。