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

Если включена изоляция тестов на уровне процесса, каждый подходящий файл тестов выполняется в отдельном дочернем процессе. Максимальное число одновременно работающих дочерних процессов контролируется флагом --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);
});

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

Вызов .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: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: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: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: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>

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

• 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. Если это значение не задано, для module.exports в заглушках CJS и встроенных модулей используется пустой объект.
  • 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> Тип теста, указывающий, является ли он набором тестов.
  • 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> Тип теста, указывающий, является ли он набором тестов.
  • 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'

Генерируется, когда в режиме наблюдения больше не остаётся тестов в очереди на выполнение.

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> Имя вложенного теста, отображаемое в результатах тестирования. По умолчанию: Свойство 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.name

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

context.signal

• Тип: <AbortSignal>

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