test

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

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

Эта функция используется для изменения поведения существующей имитации.

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

Эта функция используется для изменения поведения существующей имитации на один вызов. После вызова 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);
});

Сбрасывает историю вызовов имитирующей функции.

Восстанавливает исходное поведение имитирующей функции. После вызова этой функции имитацию по-прежнему можно использовать.

Восстанавливает исходную реализацию имитирующего модуля.

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

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

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

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

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

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

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

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

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

Пример использования с начальным значением времени в виде объекта Date

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

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

Все таймеры ('setInterval', 'clearInterval', 'Date', 'setImmediate', 'clearImmediate', 'setTimeout' и 'clearTimeout') будут имитироваться.

Функции setInterval, clearInterval, setTimeout и clearTimeout из node:timers, node:timers/promises и globalThis будут имитироваться. Конструктор Date из globalThis также будет имитироваться.

Если начальная эпоха не задана, начальная дата будет соответствовать значению 0 эпохи Unix. Это January 1st, 1970, 00:00:00 UTC. Начальную дату можно задать, передав свойство now в метод .enable(). Это значение будет использоваться как начальная дата для имитируемого объекта Date. Оно может быть положительным целым числом или другим объектом Date.

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

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

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

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

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

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

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

Примечание: Это отличается от поведения 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);
});

Кроме того, функцию .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 twoSeconds = 3000;
  context.mock.timers.tick(twoSeconds);
  context.mock.timers.tick(twoSeconds);
  context.mock.timers.tick(twoSeconds);

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

Эта функция используется для создания имитирующей функции.

В следующем примере создаётся имитирующая функция, увеличивающая счётчик на единицу при каждом вызове. Параметр 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);
});

Эта функция представляет собой синтаксический сахар для MockTracker.method, где options.getter установлено в true.

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

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.calls.length, 0);
  assert.strictEqual(number.subtract(3), 2);
  assert.strictEqual(number.subtract.mock.calls.length, 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);
});

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

Доступно только при использовании флага --experimental-test-module-mocks.

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

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

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

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

Абсолютный путь к файлу теста, создавшему текущий набор. Если файл теста импортирует дополнительные модули, создающие наборы тестов, импортированные наборы будут возвращать путь к корневому файлу теста.

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

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

Объект, содержащий методы проверки, связанные с контекстом теста. Функции верхнего уровня из модуля node:assert доступны здесь для создания планов тестирования.

Примечание: Некоторые функции из node:assert содержат проверки типов. Если вызывать их через объект assert TestContext, параметр контекста в сигнатуре тестовой функции необходимо явно типизировать (то есть снабдить параметр аннотацией типа); в противном случае компилятор TypeScript выдаст ошибку:

import { test, type TestContext } from 'node:test';

// The test function's context parameter must have a type annotation.
test('example', (t: TestContext) => {
  t.assert.deepStrictEqual(actual, expected);
});

// Omitting the type annotation will result in a compilation error.
test('example', t => {
  t.assert.deepStrictEqual(actual, expected); // Error: 't' needs an explicit type annotation.
});

Абсолютный путь к файлу тестов, в котором был создан текущий тест. Если файл тестов импортирует дополнительные модули, создающие тесты, импортированные тесты будут возвращать путь к корневому файлу тестов.

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

Для каждого теста создаётся собственный экземпляр MockTracker.

Имя теста.

Эта функция используется для создания вложенных тестов в рамках текущего теста. Она работает так же, как функция верхнего уровня test.

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

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

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

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

Эта функция используется для вывода диагностических данных. Любая диагностическая информация добавляется в конец результатов теста. Функция не возвращает значение.

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

Используется для задания ожидаемого количества проверок и вложенных тестов, которые должны быть выполнены в рамках теста. Если число выполненных проверок и вложенных тестов не совпадёт с ожидаемым, тест завершится с ошибкой.

Чтобы отслеживать проверки, необходимо использовать функции assert из context.assert, а не импортировать их из модуля node:assert.

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

При работе с асинхронным кодом можно использовать функцию 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();
  });
});

Если 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 }),
  ]);
});

Эта функция помечает тест как пропущенный в выводе. Если указано 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');
});

Эта функция добавляет в вывод теста директиву TODO. Если указано message, оно будет включено в вывод. Вызов todo() не прекращает выполнение тестовой функции. Функция не возвращает значение.

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

Этот метод периодически вызывает функцию condition, пока она не выполнится успешно или не истечёт время ожидания.