Модель выполнения средства запуска тестов

Если включена изоляция на уровне процессов, каждый соответствующий тестовый файл выполняется в отдельном дочернем процессе. Максимальное количество одновременно работающих дочерних процессов задаётся флагом --test-concurrency. Если дочерний процесс завершается с кодом выхода 0, тест считается пройденным. В противном случае тест считается не пройденным. Тестовые файлы должны выполняться в Node.js, но не обязаны использовать внутри модуль node:test.

Каждый тестовый файл выполняется как обычный скрипт. То есть если сам тестовый файл использует node:test для определения тестов, все эти тесты будут выполняться в одном потоке приложения независимо от значения параметра concurrency у test().

Если изоляция на уровне процессов отключена, каждый соответствующий тестовый файл импортируется в процесс средства запуска тестов. После загрузки всех тестовых файлов тесты верхнего уровня выполняются с параллелизмом, равным единице. Поскольку все тестовые файлы выполняются в одном контексте, тесты могут взаимодействовать друг с другом способами, невозможными при включённой изоляции. Например, если тест зависит от глобального состояния, тест из другого файла может изменить это состояние.

Средства формирования отчётов о покрытии

Средства формирования отчётов 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'] }); будут мокированы функции setTimeout в модулях node:timers и node:timers/promises, а также в глобальном контексте Node.js.

Примечание: Этот API пока не поддерживает деструктуризацию функций, таких как import { setTimeout } from 'node:timers'.

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

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

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

Та же функциональность мокирования доступна в свойстве mock объекта TestContext каждого теста. Преимущество мокирования через контекст теста заключается в том, что средство запуска тестов автоматически восстанавливает всю функциональность мокирования таймеров после завершения теста.

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

Даты

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

Если начальная эпоха не задана, начальная дата будет соответствовать значению 0 эпохи Unix. Это 1 января 1970 года, 00:00:00 UTC. Начальную дату можно задать, передав свойство now методу .enable(). Это значение будет использоваться как начальная дата для замокированного объекта 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);
});

Метод .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);
});

Таймеры, запланированные на момент времени в прошлом, не сработают при вызове setTime(). Чтобы выполнить эти таймеры, можно использовать метод .tick(), чтобы перевести время вперёд от нового момента.

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

test('setTime does not execute timers', (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 still not executed
  assert.strictEqual(fn.mock.callCount(), 0);
  // Advance in time to execute the timer
  context.mock.timers.tick(0);
  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);
});

Вызов .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);
});

Пользовательские средства формирования отчетов

Флаг --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;

Пример пользовательского средства формирования отчетов с использованием функции-генератора:

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

Значение, передаваемое в --test-reporter, должно быть строкой, подобной строке, используемой в import() в коде JavaScript, или значением, указанным для --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>

Геттер, возвращающий копию внутреннего массива, используемого для отслеживания вызовов мока. Каждая запись в массиве — это объект со следующими свойствами.

• 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 — это геттер, создающий копию внутреннего массива отслеживания вызовов.

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>

Геттер, возвращающий копию внутреннего массива, используемого для отслеживания обращений (чтения/записи) к свойству-моку. Каждая запись в массиве — это объект со следующими свойствами:

• type <string> Либо 'get', либо 'set', указывающее тип обращения.
• value <any> Значение, которое было прочитано (для 'get') или записано (для 'set').
• stack <Error> Объект Error, стек которого можно использовать для определения места вызова функции-мока.

ctx.accessCount()

• Возвращает: <integer> Количество обращений к свойству (чтений или записей).

Эта функция возвращает количество обращений к свойству. Она работает эффективнее, чем проверка ctx.accesses.length, поскольку ctx.accesses — это геттер, создающий копию внутреннего массива отслеживания обращений.

ctx.mockImplementation(value)

• value <any> Новое значение, которое будет установлено в качестве значения свойства-мока.

Эта функция используется для изменения значения, возвращаемого геттером свойства-мока.

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] рассматривается как геттер. Этот параметр нельзя использовать вместе с параметром setter. По умолчанию: false.
  • setter <boolean> Если true, object[methodName] рассматривается как сеттер. Этот параметр нельзя использовать вместе с параметром getter. По умолчанию: false.
  • times <integer> Число раз, которое имитация будет использовать поведение implementation. После того как имитируемый метод будет вызван times раз, он автоматически восстановит исходное поведение. Это значение должно быть целым числом больше нуля. По умолчанию: Infinity.
• Возвращает: <Proxy> Имитируемый метод. Имитируемый метод содержит специальное свойство mock, являющееся экземпляром MockFunctionContext, которое можно использовать для проверки и изменения поведения имитируемого метода.

Эта функция используется для создания имитации существующего метода объекта. В следующем примере показано, как создаётся имитация существующего метода объекта.

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> Строка, идентифицирующая модуль для имитации.
• options <Object> Необязательные параметры конфигурации модуля-имитации. Поддерживаются следующие свойства:
  • cache <boolean> Если false, каждый вызов require() или import() создаёт новый модуль-имитацию. Если true, последующие вызовы возвращают ту же имитацию модуля, которая помещается в кэш CommonJS. По умолчанию: false.
  • defaultExport <any> Необязательное значение, используемое в качестве экспорта по умолчанию имитируемого модуля. Если это значение не указано, имитации ESM не содержат экспорта по умолчанию. Если имитируется модуль CommonJS или встроенный модуль, это значение используется как значение module.exports. Если это значение не указано, в имитациях CJS и встроенных модулей в качестве значения module.exports используется пустой объект.
  • namedExports <Object> Необязательный объект, ключи и значения которого используются для создания именованных экспортов имитируемого модуля. Если имитируется модуль CommonJS или встроенный модуль, эти значения копируются в module.exports. Поэтому, если имитация создана с именованными экспортами и экспортом по умолчанию, не являющимся объектом, при использовании её как модуля CJS или встроенного модуля будет выброшено исключение.
• Возвращает: <MockModuleContext> Объект, который можно использовать для управления имитацией.

Эта функция используется для имитации экспортов модулей ECMAScript, модулей CommonJS, модулей JSON и встроенных модулей Node.js. Ссылки на исходный модуль, полученные до создания имитации, не затрагиваются. Чтобы включить имитацию модулей, Node.js необходимо запустить с флагом командной строки --experimental-test-module-mocks.

В следующем примере показано, как создаётся имитация модуля.

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> Объект, значение свойства которого имитируется.
• propertyName <string> | <symbol> Идентификатор имитируемого свойства объекта object.
• value <any> Необязательное значение, используемое в качестве имитируемого значения для object[propertyName]. По умолчанию: исходное значение свойства.
• Возвращает: <Proxy> Прокси для имитируемого объекта. Имитируемый объект содержит специальное свойство mock, являющееся экземпляром MockPropertyContext, которое можно использовать для проверки и изменения поведения имитируемого свойства.

Создаёт имитацию значения свойства объекта. Это позволяет отслеживать и контролировать доступ к определённому свойству, в том числе количество его чтений (геттер) и записей (сеттер), а также восстанавливать исходное значение после имитации.

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, и отвязывает имитации от экземпляра MockTracker. После отвязки имитации по-прежнему можно использовать, но экземпляр MockTracker больше нельзя использовать для сброса их поведения или взаимодействия с ними иным образом.

После завершения каждого теста эта функция вызывается для MockTracker контекста теста. Если глобальный MockTracker используется активно, рекомендуется вызывать эту функцию вручную.

mock.restoreAll()

Эта функция восстанавливает поведение по умолчанию всех имитаций, ранее созданных этим MockTracker. В отличие от mock.reset(), mock.restoreAll() не отвязывает имитации от экземпляра MockTracker.

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

Эта функция является синтаксическим сокращением для MockTracker.method, где options.setter установлено в true.

timers.enable([enableOptions])

Включает имитацию указанных таймеров.

• enableOptions <Object> Необязательные параметры конфигурации для включения имитации таймеров. Поддерживаются следующие свойства:
  • apis <Array> Необязательный массив с таймерами для имитации. В настоящее время поддерживаются следующие значения таймеров: 'setInterval', 'setTimeout', 'setImmediate' и 'Date'. По умолчанию: ['setInterval', 'setTimeout', 'setImmediate', 'Date']. Если массив не указан, по умолчанию будут имитироваться все API, связанные со временем ('setInterval', 'clearInterval', 'setTimeout', 'clearTimeout', 'setImmediate', 'clearImmediate' и 'Date').
  • now <number> | <Date> Необязательное число или объект Date, задающий начальное время (в миллисекундах), которое будет использоваться в качестве значения для Date.now(). По умолчанию: 0.

Примечание: При включении имитации для конкретного таймера соответствующая функция очистки также будет неявно имитироваться.

Примечание: Имитация Date повлияет на поведение имитируемых таймеров, поскольку они используют одни и те же внутренние часы.

Пример использования без задания начального времени:

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

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

В приведенном выше примере включается имитация таймера setInterval, а функция clearInterval неявно имитируется. Имитироваться будут только функции setInterval и clearInterval из node:timers, node:timers/promises и globalThis.

Пример использования с заданным начальным временем

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

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

Пример использования с заданным в качестве времени начальным объектом 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() });

Кроме того, если вызвать mock.timers.enable() без параметров:

Будут имитироваться все таймеры ('setInterval', 'clearInterval', 'setTimeout', 'clearTimeout', 'setImmediate' и 'clearImmediate'). Будут имитироваться функции setInterval, clearInterval, setTimeout, clearTimeout, setImmediate и clearImmediate из node:timers, node:timers/promises и globalThis. Кроме того, будет имитироваться глобальный объект Date.

timers.reset()

Эта функция восстанавливает поведение по умолчанию для всех имитаций, ранее созданных данным экземпляром MockTimers, и отвязывает имитации от экземпляра MockTracker.

Примечание: После завершения каждого теста эта функция вызывается для MockTracker контекста теста.

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

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

timers[Symbol.dispose]()

Вызывает timers.reset().

timers.tick([milliseconds])

Переводит время вперед для всех имитируемых таймеров.

• milliseconds <number> Время в миллисекундах, на которое нужно перевести таймеры вперед. По умолчанию: 1.

Примечание: Это отличается от поведения setTimeout в Node.js, поскольку принимаются только положительные числа. В Node.js setTimeout с отрицательными числами поддерживается только для совместимости с веб-платформой.

В следующем примере имитируется функция 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);
});

Также функцию .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);
});

Перевод времени вперед с помощью .tick также переведет время вперед для любого объекта Date, созданного после включения имитации (если Date также настроен для имитации).

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

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

  context.mock.timers.enable({ apis: ['setTimeout', 'Date'] });
  setTimeout(fn, 9999);

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

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

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

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

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

timers.runAll()

Немедленно запускает все ожидающие имитируемые таймеры. Если объект Date также имитируется, он также переведет объект 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);
});

Примечание: Функция runAll() предназначена специально для запуска таймеров в контексте имитации таймеров. Она не влияет на системные часы реального времени или фактические таймеры вне среды имитации.

timers.setTime(milliseconds)

Задает текущую метку времени Unix, которая будет использоваться в качестве точки отсчета для любых имитируемых объектов Date.

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

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

Событие: '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> Номер столбца, в котором определён тест, или undefined, если тест был запущен через REPL.
  • details <Object> Дополнительные метаданные выполнения.
    • passed <boolean> Успешно ли выполнен тест.
    • duration_ms <number> Длительность выполнения теста в миллисекундах.
    • error <Error> | <undefined> Ошибка, оборачивающая ошибку, выброшенную тестом, если он завершился неудачно.
      • cause <Error> Исходная ошибка, выброшенная тестом.
    • type <string> | <undefined> Тип теста, указывающий, является ли он группой тестов.
  • file <string> | <undefined> Путь к файлу теста или undefined, если тест был запущен через REPL.
  • line <number> | <undefined> Номер строки, в которой определён тест, или undefined, если тест был запущен через REPL.
  • 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> Номер столбца, в котором определён тест, или undefined, если тест был запущен через REPL.
  • file <string> | <undefined> Путь к файлу теста, undefined, если тест был запущен через REPL.
  • line <number> | <undefined> Номер строки, в которой определён тест, или undefined, если тест был запущен через REPL.
  • name <string> Название теста.
  • nesting <number> Уровень вложенности теста.
  • type <string> Тип теста. Это либо 'suite', либо 'test'.

Событие генерируется, когда тест извлекается из очереди, непосредственно перед его выполнением. Не гарантируется, что это событие будет сгенерировано в том же порядке, в котором определены тесты. Соответствующее событие, упорядоченное по объявлению, — 'test:start'.

Событие: 'test:diagnostic'

• data <Object>
  • column <number> | <undefined> Номер столбца, в котором определён тест, или undefined, если тест был запущен через REPL.
  • file <string> | <undefined> Путь к файлу теста, undefined, если тест был запущен через REPL.
  • line <number> | <undefined> Номер строки, в которой определён тест, или undefined, если тест был запущен через REPL.
  • message <string> Диагностическое сообщение.
  • nesting <number> Уровень вложенности теста.
  • level <string> Уровень серьёзности диагностического сообщения. Возможные значения:
    • 'info': информационные сообщения.
    • 'warn': предупреждения.
    • 'error': ошибки.

Событие генерируется при вызове context.diagnostic. Гарантируется, что это событие будет сгенерировано в том же порядке, в котором определены тесты.

Событие: 'test:enqueue'

• data <Object>
  • column <number> | <undefined> Номер столбца, в котором определён тест, или undefined, если тест был запущен через REPL.
  • file <string> | <undefined> Путь к файлу теста, undefined, если тест был запущен через REPL.
  • line <number> | <undefined> Номер строки, в которой определён тест, или undefined, если тест был запущен через REPL.
  • name <string> Название теста.
  • nesting <number> Уровень вложенности теста.
  • type <string> Тип теста. Это либо 'suite', либо 'test'.

Событие генерируется, когда тест ставится в очередь на выполнение.

Событие: 'test:fail'

• data <Object>
  • column <number> | <undefined> Номер столбца, в котором определён тест, или undefined, если тест был запущен через REPL.
  • details <Object> Дополнительные метаданные выполнения.
    • duration_ms <number> Продолжительность теста в миллисекундах.
    • error <Error> Ошибка, оборачивающая ошибку, выброшенную тестом.
      • cause <Error> Фактическая ошибка, выброшенная тестом.
    • type <string> | <undefined> Тип теста, указывающий, является ли он набором тестов.
    • attempt <number> | <undefined> Номер попытки запуска теста; присутствует только при использовании флага --test-rerun-failures.
  • file <string> | <undefined> Путь к файлу теста, undefined, если тест был запущен через REPL.
  • line <number> | <undefined> Номер строки, в которой определён тест, или undefined, если тест был запущен через REPL.
  • 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> Номер столбца, в котором определён тест, или undefined, если тест был запущен через REPL.
  • 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> Путь к файлу теста или undefined, если тест был запущен через REPL.
  • line <number> | <undefined> Номер строки, в которой определён тест, или undefined, если тест был запущен через REPL.
  • 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> Номер столбца, в котором определён тест, или undefined, если тест был запущен через REPL.
  • file <string> | <undefined> Путь к файлу теста или undefined, если тест был запущен через REPL.
  • line <number> | <undefined> Номер строки, в которой определён тест, или undefined, если тест был запущен через REPL.
  • nesting <number> Уровень вложенности теста.
  • count <number> Количество выполненных вложенных тестов.

Создаётся, когда все вложенные тесты для данного теста завершены. Это событие гарантированно создаётся в том же порядке, в котором определены тесты.

Событие: 'test:start'

• data <Object>
  • column <number> | <undefined> Номер столбца, в котором определён тест, или undefined, если тест был запущен через REPL.
  • file <string> | <undefined> Путь к файлу теста или undefined, если тест был запущен через REPL.
  • line <number> | <undefined> Номер строки, в которой определён тест, или undefined, если тест был запущен через REPL.
  • 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) => {
      // 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}`));
  // 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) => {
      // 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.passed

• Тип: <boolean> false до выполнения теста, например в хуке beforeEach.

Указывает, успешно ли выполнен тест.

context.error

• Тип: <Error> | <null>

Причина сбоя теста/варианта; обёрнута и доступна через context.error.cause.

context.attempt

• Тип: <number>

Количество попыток выполнения теста.

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> Имя под-теста, отображаемое при выводе результатов тестирования. По умолчанию: свойство name объекта fn или '<anonymous>', если у fn нет имени.
• 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.fullName

Имя набора тестов и каждого из его предков, разделённые >.

context.name

Имя набора тестов.

context.signal

• Тип: <AbortSignal>

Можно использовать для прерывания подзадач теста, если выполнение теста было прервано.