Подтесты

Метод test() контекста теста позволяет создавать подтесты. Этот метод ведет себя идентично функции верхнего уровня test(). Следующий пример демонстрирует создание теста верхнего уровня с двумя подтестами.

test('top level test', async (t) => {
  await t.test('subtest 1', (t) => {
    assert.strictEqual(1, 1);
  });

  await t.test('subtest 2', (t) => {
    assert.strictEqual(2, 2);
  });
}); copy

В этом примере используется await, чтобы гарантировать, что оба подтеста завершены. Это необходимо, так как родительские тесты не ожидают завершения своих подтестов. Любые подтесты, которые еще не завершены, когда их родительский тест завершается, отменяются и рассматриваются как неудачные. Любые неудачи подтестов приводят к неудаче родительского теста.

Пропуск тестов

Отдельные тесты можно пропустить, передав параметр skip в тест или вызвав метод skip() контекста теста, как показано в следующем примере.

// The skip option is used, but no message is provided.
test('skip option', { skip: true }, (t) => {
  // This code is never executed.
});

// The skip option is used, and a message is provided.
test('skip option with message', { skip: 'this is skipped' }, (t) => {
  // This code is never executed.
});

test('skip() method', (t) => {
  // Make sure to return here as well if the test contains additional logic.
  t.skip();
});

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

describe/it синтаксис

Запуск тестов также можно выполнить с помощью describe для объявления набора и it для объявления теста. Набор используется для организации и группировки связанных тестов. it является сокращением для test().

describe('A thing', () => {
  it('should work', () => {
    assert.strictEqual(1, 1);
  });

  it('should be ok', () => {
    assert.strictEqual(2, 2);
  });

  describe('a nested thing', () => {
    it('should work', () => {
      assert.strictEqual(3, 3);
    });
  });
}); copy

describe и it импортируются из модуля node:test.

MJS-модули

import { describe, it } from 'node:test';

CJS-модули

const { describe, it } = require('node:test');

only тесты

Если Node.js запускается с опцией командной строки --test-only, можно пропустить все тесты верхнего уровня, кроме выбранного подмножества, передав параметр only тестам, которые необходимо запустить. При запуске теста с параметром only также запускаются все подтесты. Метод runOnly() контекста теста может быть использован для реализации такого же поведения на уровне подтеста.

// Assume Node.js is run with the --test-only command-line option.
// The 'only' option is set, so this test is run.
test('this test is run', { only: true }, async (t) => {
  // Within this test, all subtests are run by default.
  await t.test('running subtest');

  // The test context can be updated to run subtests with the 'only' option.
  t.runOnly(true);
  await t.test('this subtest is now skipped');
  await t.test('this subtest is run', { only: true });

  // Switch the context back to execute all tests.
  t.runOnly(false);
  await t.test('this subtest is now run');

  // Explicitly do not run these tests.
  await t.test('skipped subtest 3', { only: false });
  await t.test('skipped subtest 4', { skip: true });
});

// The 'only' option is not set, so this test is skipped.
test('this test is not run', () => {
  // This code is not run.
  throw new Error('fail');
}); copy

Фильтрация тестов по имени

Опция командной строки --test-name-pattern может быть использована для запуска только тех тестов, чьи имена соответствуют заданному шаблону. Шаблоны имен тестов интерпретируются как JavaScript-регулярные выражения. Параметр --test-name-pattern может быть указан несколько раз для запуска вложенных тестов. Для каждого выполняемого теста также выполняются соответствующие хуки тестов, такие как beforeEach().

Приведенный ниже тестовый файл, запустив Node.js с опцией --test-name-pattern="test [1-3]", заставит запускатель тестов выполнить test 1, test 2, и test 3. Если test 1 не соответствовал шаблону имени теста, его подтесты не выполнялись бы, несмотря на соответствие шаблону. Тот же набор тестов также можно выполнить, передав --test-name-pattern несколько раз (например, --test-name-pattern="test 1", --test-name-pattern="test 2", и т. д.).

test('test 1', async (t) => {
  await t.test('test 2');
  await t.test('test 3');
});

test('Test 4', async (t) => {
  await t.test('Test 5');
  await t.test('test 6');
}); copy

Шаблоны имен тестов также можно задавать с помощью литералов регулярных выражений. Это позволяет использовать флаги регулярных выражений. В предыдущем примере запуск Node.js с --test-name-pattern="/test [4-5]/i" соответствовал бы Test 4 и Test 5, так как шаблон нечувствителен к регистру.

Шаблоны имен тестов не изменяют набор файлов, которые выполняет запускатель тестов.

Внеплановая асинхронная активность

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

В следующем примере тест завершается с двумя операциями setImmediate() еще в процессе выполнения. Первый setImmediate() пытается создать новый подтест. Поскольку родительский тест уже завершился и вывел свои результаты, новый подтест немедленно помечается как неудачный и сообщается позже в <Поток тестов>.

Второй setImmediate() создаёт событие uncaughtException. События uncaughtException и unhandledRejection, исходящие из завершенного теста, помечаются как неудачные модулем test и сообщаются как диагностические предупреждения на верхнем уровне потоком <TestsStream>.

test('a test that creates asynchronous activity', (t) => {
  setImmediate(() => {
    t.test('subtest that is created too late', (t) => {
      throw new Error('error1');
    });
  });

  setImmediate(() => {
    throw new Error('error2');
  });

  // The test finishes after this line.
}); copy

Режим отслеживания

Запускатель тестов Node.js поддерживает режим отслеживания изменений, передавая флаг --watch:

node --test --watch copy

В режиме отслеживания запускатель тестов будет отслеживать изменения в тестовых файлах и их зависимостях. При обнаружении изменения запускатель тестов повторно выполнит тесты, затронутые этим изменением. Запускатель тестов будет продолжать работу до завершения процесса.

Запуск тестов из командной строки

Запускатель тестов Node.js можно вызвать из командной строки, передав флаг --test:

node --test copy

По умолчанию Node.js будет рекурсивно искать в текущем каталоге файлы исходного кода JavaScript, соответствующие определённой схеме именования. Соответствующие файлы выполняются как тестовые файлы. Более подробную информацию о ожидаемой схеме именования и поведении тестовых файлов можно найти в разделе «Модель выполнения запускателя тестов».

В качестве альтернативы можно указать один или несколько путей в качестве последнего аргумента(ов) команды Node.js, как показано ниже.

node --test test1.js test2.mjs custom_test_dir/ copy

В этом примере запускатель тестов выполнит файлы test1.js и test2.mjs. Запускатель тестов также рекурсивно найдёт тестовые файлы в каталоге custom_test_dir/ для выполнения.

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

При поиске тестовых файлов для выполнения запускатель тестов действует следующим образом:

• Любые файлы, явно указанные пользователем, выполняются.
• Если пользователь явно не указал пути, текущая рабочая директория рекурсивно проверяется на наличие файлов, как указано в следующих шагах.
• node_modules каталоги пропускаются, если явно не указаны пользователем.
• Если встречен каталог с именем test, запускатель тестов будет рекурсивно искать в нем все файлы .js, .cjs, и .mjs. Все эти файлы рассматриваются как тестовые файлы и не обязательно должны соответствовать определенной схеме именования, описанной ниже. Это сделано для того, чтобы предоставить возможность проектам, которые размещают все свои тесты в одном каталоге test.
• Во всех других каталогах файлы .js, .cjs, и .mjs с соответствием следующим шаблонам рассматриваются как тестовые файлы:
  • ^test$ - Файлы, основанные на имени строки 'test'. Примеры: test.js, test.cjs, test.mjs.
  • ^test-.+ - Файлы, чье имя начинается со строки 'test-' за которой следуют одна или несколько букв. Примеры: test-example.js, test-another-example.mjs.
  • .+[\.\-\_]test$ - Файлы, чье имя заканчивается на .test, -test, или _test, предваряемые одной или несколькими буквами. Примеры: example.test.js, example-test.cjs, example_test.mjs.
  • Другие типы файлов, понимаемые Node.js, такие как .node и .json, не выполняются автоматически запускателем тестов, но поддерживаются, если указаны явно в командной строке.

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

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

Сбор покрытия кода

Когда Node.js запускается с флагом командной строки --experimental-test-coverage, собирается покрытие кода, и статистика сообщается после завершения всех тестов. Если переменная среды NODE_V8_COVERAGE используется для указания директории покрытия кода, сгенерированные файлы покрытия V8 записываются в эту директорию. Модули ядра Node.js и файлы в директориях node_modules/ не включаются в отчет о покрытии. Если покрытие включено, отчет о покрытии отправляется любым отчетчикам о тестах через событие 'test:coverage'.

Покрытие можно отключить на ряде строк, используя следующий синтаксис комментария:

/* node:coverage disable */
if (anAlwaysFalseCondition) {
  // Code in this branch will never be executed, but the lines are ignored for
  // coverage purposes. All lines following the 'disable' comment are ignored
  // until a corresponding 'enable' comment is encountered.
  console.log('this is never executed');
}
/* node:coverage enable */ copy

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

/* node:coverage ignore next */
if (anAlwaysFalseCondition) { console.log('this is never executed'); }

/* node:coverage ignore next 3 */
if (anAlwaysFalseCondition) {
  console.log('this is never executed');
} copy

Функциональность покрытия кода исполняемого файла тестов имеет следующие ограничения, которые будут устранены в будущей версии Node.js:

• Не поддерживаются карты исходного кода.
• Исключение определенных файлов или директорий из отчета о покрытии не поддерживается.

Мокирование

Модуль node:test поддерживает мокирование во время тестирования через глобальный объект mock. Следующий пример создает шпион для функции, которая складывает два числа. Затем шпион используется для утверждения, что функция была вызвана как ожидалось.

MJS модули

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

test('spies on a function', () => {
  const sum = mock.fn((a, b) => {
    return a + b;
  });

  assert.strictEqual(sum.mock.calls.length, 0);
  assert.strictEqual(sum(3, 4), 7);
  assert.strictEqual(sum.mock.calls.length, 1);

  const call = sum.mock.calls[0];
  assert.deepStrictEqual(call.arguments, [3, 4]);
  assert.strictEqual(call.result, 7);
  assert.strictEqual(call.error, undefined);

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

CJS модули

'use strict';
const assert = require('node:assert');
const { mock, test } = require('node:test');

test('spies on a function', () => {
  const sum = mock.fn((a, b) => {
    return a + b;
  });

  assert.strictEqual(sum.mock.calls.length, 0);
  assert.strictEqual(sum(3, 4), 7);
  assert.strictEqual(sum.mock.calls.length, 1);

  const call = sum.mock.calls[0];
  assert.deepStrictEqual(call.arguments, [3, 4]);
  assert.strictEqual(call.result, 7);
  assert.strictEqual(call.error, undefined);

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

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

test('spies on an object method', (t) => {
  const number = {
    value: 5,
    add(a) {
      return this.value + a;
    },
  };

  t.mock.method(number, 'add');
  assert.strictEqual(number.add.mock.calls.length, 0);
  assert.strictEqual(number.add(3), 8);
  assert.strictEqual(number.add.mock.calls.length, 1);

  const call = number.add.mock.calls[0];

  assert.deepStrictEqual(call.arguments, [3]);
  assert.strictEqual(call.result, 8);
  assert.strictEqual(call.target, undefined);
  assert.strictEqual(call.this, number);
}); copy

Отчетчики о тестах

Модуль node:test поддерживает передачу флагов --test-reporter исполняемому файлу тестов для использования определенного отчетчика.

Поддерживаются следующие встроенные отчетчики:

• tap Отчетчик tap выводит результаты тестов в формате TAP.

• spec Отчетчик spec выводит результаты тестов в удобочитаемом формате.

• dot Отчетчик dot выводит результаты тестов в компактном формате, где каждый пройденный тест представлен ., а каждый неудавшийся тест — X.

Когда stdout является TTY, отчетчик spec используется по умолчанию. В противном случае, отчетчик tap используется по умолчанию.

Отчетчики доступны через модуль node:test/reporters:

MJS модули

import { tap, spec, dot } from 'node:test/reporters';

CJS модули

const { tap, spec, dot } = require('node:test/reporters');

Пользовательские отчетчики

--test-reporter можно использовать для указания пути к пользовательскому отчетчику. Пользовательский отчетчик — это модуль, который экспортирует значение, принимаемое функцией stream.compose. Отчетчики должны преобразовывать события, испускаемые <TestsStream>.

Пример пользовательского отчетчика с использованием <stream.Transform>:

MJS модули

import { Transform } from 'node:stream';

const customReporter = new Transform({
  writableObjectMode: true,
  transform(event, encoding, callback) {
    switch (event.type) {
      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':
        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;

CJS модули

const { Transform } = require('node:stream');

const customReporter = new Transform({
  writableObjectMode: true,
  transform(event, encoding, callback) {
    switch (event.type) {
      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':
        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;

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

MJS модули

export default async function * customReporter(source) {
  for await (const event of source) {
    switch (event.type) {
      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';
        break;
      case 'test:diagnostic':
        yield `${event.data.message}\n`;
        break;
      case 'test:coverage': {
        const { totalLineCount } = event.data.summary.totals;
        yield `total line count: ${totalLineCount}\n`;
        break;
      }
    }
  }
}

CJS модули

module.exports = async function * customReporter(source) {
  for await (const event of source) {
    switch (event.type) {
      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':
        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.

Несколько отчетчиков

Флаг --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, если не указано иное.

run([options])

• options <Объект> Параметры конфигурации для запуска тестов. Поддерживаются следующие свойства:
  • concurrency <число> | <логическое> Если указано число, столько процессов тестов будет запущено параллельно, где каждый процесс соответствует одному файлу тестов. Если true, os.availableParallelism() - 1 файлов тестов будут запущены параллельно. Если false, будет запускаться только один файл тестов за раз. По умолчанию: false.
  • files: <Массив> Массив, содержащий список файлов для запуска. По умолчанию соответствие файлам из модели выполнения исполняемого файла тестов.
  • inspectPort <число> | <Функция> Устанавливает порт инспектора процесса дочернего процесса тестов. Это может быть число или функция, которая не принимает аргументы и возвращает число. Если предоставлено нулевое значение, каждый процесс получает свой порт, увеличивающийся с порта основного процесса с process.debugPort. По умолчанию: undefined.
  • setup <Функция> Функция, принимающая экземпляр TestsStream и которая может использоваться для настройки слушателей до запуска любых тестов. По умолчанию: undefined.
  • signal <AbortSignal> Разрешает прерывание выполнения процесса тестирования.
  • testNamePatterns <строка> | <RegExp> | <Массив> Строка, RegExp или массив RegExp, которые могут использоваться для запуска только тех тестов, чьи имена соответствуют предоставленному шаблону. Шаблоны имен тестов интерпретируются как JavaScript регулярные выражения. Для каждого исполняемого теста также выполняются любые соответствующие хуки теста, такие как beforeEach(). По умолчанию: undefined.
  • timeout <число> Количество миллисекунд, в течение которых выполнение теста не должно прерываться. Если не указано, подтесты наследуют это значение от своего родителя. По умолчанию: Infinity.
  • watch <логическое> Флаг, определяющий, запускать ли в режиме слежения. По умолчанию: false.
• Возвращает: <TestsStream>

MJS модули

import { tap } from 'node:test/reporters';
import process from 'node:process';

run({ files: [path.resolve('./tests/test.js')] })
  .compose(tap)
  .pipe(process.stdout);

CJS модули

const { tap } = require('node:test/reporters');

run({ files: [path.resolve('./tests/test.js')] })
  .compose(tap)
  .pipe(process.stdout);

test([name][, options][, fn])

• name <строка> Название теста, отображаемое при сообщении о результатах. По умолчанию: свойство name объекта fn, или '<anonymous>', если у fn нет имени.
• options <Объект> Параметры конфигурации для теста. Поддерживаются следующие свойства:
  • concurrency <число> | <логическое> Если указано число, столько тестов будет запущено параллельно в потоке приложения. Если true, все запланированные асинхронные тесты выполняются одновременно в потоке. Если false, один тест выполняется за раз. Если не указано, подтесты наследуют это значение от родительского теста. По умолчанию: false.
  • only <логическое> Если имеет истинное значение, и контекст теста настроен на запуск only тестов, то этот тест будет запущен. В противном случае тест пропускается. По умолчанию: false.
  • signal <AbortSignal> Позволяет прервать текущий тест.
  • skip <логическое> | <строка> Если имеет истинное значение, тест пропускается. Если указана строка, эта строка отображается в результатах теста как причина пропуска. По умолчанию: false.
  • todo <логическое> | <строка> Если имеет истинное значение, тест помечен как TODO. Если указана строка, эта строка отображается в результатах теста как причина, почему тест помечен как TODO. По умолчанию: false.
  • timeout <число> Количество миллисекунд, после которого тест будет считаться проваленным. Если не указано, подтесты наследуют это значение от родительского теста. По умолчанию: Infinity.
• fn <Функция> | <Асинхронная функция> Функция, которая тестируется. Первый аргумент этой функции — объект TestContext. Если тест использует колбэки, функция колбэка передаётся вторым аргументом. По умолчанию: функция-пустышка.
• Возвращает: <Promise> Успешно разрешается, когда тест завершается, или сразу, если тест запускается внутри describe().

Функция test() — это значение, импортированное из модуля test. Каждый вызов этой функции приводит к сообщению о тесте в <TestsStream>.

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

test() возвращает Promise, который разрешается, когда тест завершается. Если test() вызывается внутри блока describe(), он разрешается сразу. Значение возврата обычно можно игнорировать для тестов верхнего уровня. Однако значение возврата из подтестов необходимо использовать, чтобы предотвратить завершение родительского теста раньше и отмену подтеста, как показано в следующем примере.

test('top level test', async (t) => {
  // The setTimeout() in the following subtest would cause it to outlive its
  // parent test if 'await' is removed on the next line. Once the parent test
  // completes, it will cancel any outstanding subtests.
  await t.test('longer running subtest', async (t) => {
    return new Promise((resolve, reject) => {
      setTimeout(resolve, 1000);
    });
  });
}); copy

Параметр timeout можно использовать для провала теста, если его выполнение занимает более timeout миллисекунд. Однако это не надёжный механизм для отмены тестов, так как работающий тест может заблокировать поток приложения и тем самым помешать запланированной отмене.

test.skip([name][, options][, fn])

Сокращение для пропуска теста, то же, что и test([name], { skip: true }[, fn]).

test.todo([name][, options][, fn])

Сокращение для обозначения теста как TODO, то же, что и test([name], { todo: true }[, fn]).

test.only([name][, options][, fn])

Сокращение для обозначения теста как only, то же, что и test([name], { only: true }[, fn]).

describe([name][, options][, fn])

• name <строка> Название набора, отображаемое при сообщении о результатах теста. По умолчанию: свойство name объекта fn, или '<anonymous>', если у fn нет имени.
• options <Объект> Параметры конфигурации для набора. Поддерживает те же параметры, что и test([name][, options][, fn]).
• fn <Функция> | <Асинхронная функция> Функция, объявляющая все подтесты и поднаборы. Первый аргумент этой функции — объект SuiteContext. По умолчанию: функция-пустышка.
• Возвращает: <Promise> Немедленно выполняется с undefined.

Функция describe(), импортированная из модуля node:test. Каждый вызов этой функции создаёт подтест. После вызова функций describe верхнего уровня, все тесты и наборы верхнего уровня будут выполнены.

describe.skip([name][, options][, fn])

Сокращение для пропуска набора, то же, что и describe([name], { skip: true }[, fn]).

describe.todo([name][, options][, fn])

Сокращение для обозначения набора как TODO, то же, что и describe([name], { todo: true }[, fn]).

describe.only([name][, options][, fn])

Сокращение для обозначения набора как only, то же, что и describe([name], { only: true }[, fn]).

it([name][, options][, fn])

Сокращение для test().

Функция it() импортирована из модуля node:test.

it.skip([name][, options][, fn])

Сокращение для пропуска теста, то же, что и it([name], { skip: true }[, fn]).

it.todo([name][, options][, fn])

Сокращение для обозначения теста как TODO, то же, что и it([name], { todo: true }[, fn]).

it.only([name][, options][, fn])

Сокращение для обозначения теста как only, то же, что и it([name], { only: true }[, fn]).

before([fn][, options])

• fn <Функция> | <Асинхронная функция> Функция-хук. Если хук использует колбэки, функция колбэка передаётся вторым аргументом. По умолчанию: функция-пустышка.
• options <Объект> Параметры конфигурации для хука. Поддерживаются следующие свойства:
  • signal <AbortSignal> Позволяет прервать текущий хук.
  • timeout <число> Количество миллисекунд, после которого хук будет считаться проваленным. Если не указано, подтесты наследуют это значение от родительского теста. По умолчанию: Infinity.

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

describe('tests', async () => {
  before(() => console.log('about to run some test'));
  it('is a subtest', () => {
    assert.ok('some relevant assertion here');
  });
}); copy

after([fn][, options])

• fn <Функция> | <AsyncFunction> Функция-обработчик. Если обработчик использует колбэки, функция-колбэк передаётся в качестве второго аргумента. По умолчанию: функция-пустышка.
• options <Объект> Параметры конфигурации для обработчика. Поддерживаются следующие свойства:
  • signal <AbortSignal> Позволяет прервать выполнение обработчика.
  • timeout <число> Количество миллисекунд, через которое обработчик завершится с ошибкой. Если не указано, подтесты наследуют это значение от родительского теста. По умолчанию: Infinity.

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

describe('tests', async () => {
  after(() => console.log('finished running tests'));
  it('is a subtest', () => {
    assert.ok('some relevant assertion here');
  });
}); copy

beforeEach([fn][, options])

• fn <Функция> | <AsyncFunction> Функция-обработчик. Если обработчик использует колбэки, функция-колбэк передаётся в качестве второго аргумента. По умолчанию: функция-пустышка.
• options <Объект> Параметры конфигурации для обработчика. Поддерживаются следующие свойства:
  • signal <AbortSignal> Позволяет прервать выполнение обработчика.
  • timeout <число> Количество миллисекунд, через которое обработчик завершится с ошибкой. Если не указано, подтесты наследуют это значение от родительского теста. По умолчанию: Infinity.

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

describe('tests', async () => {
  beforeEach(() => console.log('about to run a test'));
  it('is a subtest', () => {
    assert.ok('some relevant assertion here');
  });
}); copy

afterEach([fn][, options])

• fn <Функция> | <AsyncFunction> Функция-обработчик. Если обработчик использует колбэки, функция-колбэк передаётся в качестве второго аргумента. По умолчанию: функция-пустышка.
• options <Объект> Параметры конфигурации для обработчика. Поддерживаются следующие свойства:
  • signal <AbortSignal> Позволяет прервать выполнение обработчика.
  • timeout <число> Количество миллисекунд, через которое обработчик завершится с ошибкой. Если не указано, подтесты наследуют это значение от родительского теста. По умолчанию: Infinity.

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

describe('tests', async () => {
  afterEach(() => console.log('finished running a test'));
  it('is a subtest', () => {
    assert.ok('some relevant assertion here');
  });
}); copy

Класс: MockFunctionContext

Класс MockFunctionContext используется для проверки или изменения поведения моков, созданных через API MockTracker.

ctx.calls

• <Массив>

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

• arguments <Массив> Массив аргументов, переданных функции-моку.
• error <любое> Если функция-моки бросила исключение, это свойство содержит значение исключения. По умолчанию: undefined.
• result <любое> Значение, возвращённое функцией-моком.
• stack <Ошибка> Объект типа Error с стеком вызовов, позволяющим определить место вызова функции-мока.
• target <Функция> | <не определено> Если функция-моки — конструктор, это поле содержит создаваемый класс. В противном случае значение будет undefined.
• this <любое> Значение this функции-мока.

ctx.callCount()

• Возвращает: <целое число> Количество вызовов этого мока.

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

ctx.mockImplementation(implementation)

• implementation <Функция> | <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 <Функция> | <AsyncFunction> Функция, которая будет использоваться в качестве реализации мока для вызова, номер которого указан в onCall.
• onCall <целое число> Номер вызова, который будет использовать 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()

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

Класс: MockTracker

Класс MockTracker используется для управления функцией подмены. Модуль запуска тестов предоставляет экспорт верхнего уровня mock, который является экземпляром MockTracker. Каждый тест также предоставляет свой собственный экземпляр MockTracker через свойство контекста теста mock.

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

• original <Функция> | <Асинхронная функция> Необязательная функция для создания подстановки. По умолчанию: функция без действий.
• implementation <Функция> | <Асинхронная функция> Необязательная функция, используемая в качестве реализации подстановки для original. Это полезно для создания подстановок, которые демонстрируют одно поведение для определённого числа вызовов, а затем восстанавливают поведение original. По умолчанию: функция, указанная в original.
• options <Объект> Необязательные параметры конфигурации для функции подстановки. Поддерживаются следующие свойства:
  • times <целое число> Количество раз, когда подстановка будет использовать поведение implementation. После того, как функция подстановки была вызвана times раз, она автоматически восстановит поведение original. Это значение должно быть целым числом, большим нуля. По умолчанию: Infinity.
• Возвращает: <Прокси> Подставленная функция. Подставленная функция содержит специальное свойство 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 <Объект> Объект, метод которого подменяется.
• methodName <строка> | <символ> Идентификатор метода в object для подстановки. Если object[methodName] не является функцией, выбрасывается ошибка.
• implementation <Функция> | <Асинхронная функция> Необязательная функция, используемая в качестве реализации подстановки для object[methodName]. По умолчанию: исходный метод, указанный в object[methodName].
• options <Объект> Необязательные параметры конфигурации для подставленного метода. Поддерживаются следующие свойства:
  • getter <логическое значение> Если true, object[methodName] обрабатывается как метод-геттер. Этот параметр не может использоваться с параметром setter. По умолчанию: false.
  • setter <логическое значение> Если true, object[methodName] обрабатывается как метод-сеттер. Этот параметр не может использоваться с параметром getter. По умолчанию: false.
  • times <целое число> Количество раз, когда подстановка будет использовать поведение implementation. После того, как подставленный метод был вызван times раз, он автоматически восстановит исходное поведение. Это значение должно быть целым числом, большим нуля. По умолчанию: Infinity.
• Возвращает: <Прокси> Подставленный метод. Подставленный метод содержит специальное свойство 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.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);
}); 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.

Класс: TestsStream

• Расширяет <ReadableStream>

Успешное вызов метода run() вернёт новый объект <TestsStream>, транслирующий серию событий, представляющих выполнение тестов. TestsStream будут излучать события в порядке их определения.

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

• data <Объект>
  • summary <Объект> Объект, содержащий отчёт о покрытии кода.
    • files <Массив> Массив отчётов о покрытии для отдельных файлов. Каждый отчёт — объект со следующей структурой:
      • path <строка> Абсолютный путь к файлу.
      • totalLineCount <число> Общее количество строк.
      • totalBranchCount <число> Общее количество ветвей.
      • totalFunctionCount <число> Общее количество функций.
      • coveredLineCount <число> Количество покрытых строк.
      • coveredBranchCount <число> Количество покрытых ветвей.
      • coveredFunctionCount <число> Количество покрытых функций.
      • coveredLinePercent <число> Процент покрытых строк.
      • coveredBranchPercent <число> Процент покрытых ветвей.
      • coveredFunctionPercent <число> Процент покрытых функций.
      • uncoveredLineNumbers <Массив> Массив целых чисел, представляющих номера строк, которые не покрыты.
    • totals <Объект> Объект, содержащий сводку по покрытию для всех файлов.
      • totalLineCount <число> Общее количество строк.
      • totalBranchCount <число> Общее количество ветвей.
      • totalFunctionCount <число> Общее количество функций.
      • coveredLineCount <число> Количество покрытых строк.
      • coveredBranchCount <число> Количество покрытых ветвей.
      • coveredFunctionCount <число> Количество покрытых функций.
      • coveredLinePercent <число> Процент покрытых строк.
      • coveredBranchPercent <число> Процент покрытых ветвей.
      • coveredFunctionPercent <число> Процент покрытых функций.
    • workingDirectory <строка> Рабочий каталог на момент начала измерения покрытия кода. Это полезно для отображения относительных путей в случае, если тесты изменили рабочий каталог процесса Node.js.
  • nesting <число> Уровень вложенности теста.

Выдаётся, когда включено измерение покрытия кода и все тесты завершены.

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

• data <Объект>
  • file <строка> | <неопределено> Путь к файлу теста, undefined если тест был запущен через REPL.
  • name <строка> Название теста.
  • nesting <число> Уровень вложенности теста.

Выдаётся, когда тест удалён из очереди перед выполнением.

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

• data <Объект>
  • file <строка> | <неопределено> Путь к файлу теста, undefined если тест был запущен через REPL.
  • message <строка> Сообщение диагностики.
  • nesting <число> Уровень вложенности теста.

Выдаётся, когда вызван context.diagnostic.

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

• data <Объект>
  • file <строка> | <неопределено> Путь к файлу теста, undefined если тест был запущен через REPL.
  • name <строка> Название теста.
  • nesting <число> Уровень вложенности теста.

Выдаётся, когда тест помещён в очередь для выполнения.

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

• data <Object>
  • details <Object> Дополнительные метаданные выполнения.
    • duration <number> Продолжительность теста в миллисекундах.
    • error <Error> Ошибка, сгенерированная тестом.
  • file <string> | <undefined> Путь к файлу теста, undefined если тест выполнялся через REPL.
  • name <string> Название теста.
  • nesting <number> Уровень вложенности теста.
  • testNumber <number> Порядковый номер теста.
  • todo <string> | <boolean> | <undefined> Присутствует, если вызывается context.todo
  • skip <string> | <boolean> | <undefined> Присутствует, если вызывается context.skip

Выпускается, когда тест завершается с ошибкой.

Event: 'test:pass'

• data <Object>
  • details <Object> Дополнительные метаданные выполнения.
    • duration <number> Продолжительность теста в миллисекундах.
  • file <string> | <undefined> Путь к файлу теста, undefined если тест выполнялся через REPL.
  • name <string> Название теста.
  • nesting <number> Уровень вложенности теста.
  • testNumber <number> Порядковый номер теста.
  • todo <string> | <boolean> | <undefined> Присутствует, если вызывается context.todo
  • skip <string> | <boolean> | <undefined> Присутствует, если вызывается context.skip

Выпускается, когда тест пройден.

Event: 'test:plan'

• data <Object>
  • file <string> | <undefined> Путь к файлу теста, undefined если тест выполнялся через REPL.
  • nesting <number> Уровень вложенности теста.
  • count <number> Количество подтестов, которые были выполнены.

Выпускается, когда все подтесты завершены для данного теста.

Event: 'test:start'

• data <Object>
  • file <string> | <undefined> Путь к файлу теста, undefined если тест выполнялся через REPL.
  • name <string> Название теста.
  • nesting <number> Уровень вложенности теста.

Выпускается, когда тест начинает сообщать о своём статусе и статусе своих подтестов. Этот событие гарантированно выпускается в том же порядке, что и определение тестов.

Event: 'test:stderr'

• data <Object>
  • file <string> Путь к файлу теста.
  • message <string> Сообщение, выведенное в stderr.

Выпускается, когда выполняемый тест записывает в stderr. Это событие выпускается только если --test флаг передан.

Event: 'test:stdout'

• data <Object>
  • file <string> Путь к файлу теста.
  • message <string> Сообщение, выведенное в stdout.

Выпускается, когда выполняемый тест записывает в stdout. Это событие выпускается только если --test флаг передан.

Event: 'test:watch:drained'

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

Класс: TestContext

Экземпляр TestContext передаётся каждой тестовой функции для взаимодействия с запуском тестов. Однако, конструктор TestContext не доступен как часть API.

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

• fn <Функция> | <Асинхронная функция> Функция-хук. Первым аргументом этой функции является объект TestContext. Если хук использует обратные вызовы, функция обратного вызова передаётся в качестве второго аргумента. По умолчанию: функция-пустышка.
• options <Объект> Параметры конфигурации для хука. Поддерживаются следующие свойства:
  • signal <AbortSignal> Позволяет прервать выполняемый хук.
  • timeout <число> Количество миллисекунд, через которое хук завершится с ошибкой. Если не указано, субтесты унаследуют это значение от родительского теста. По умолчанию: Infinity.

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

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

• fn <Функция> | <Асинхронная функция> Функция-хук. Первым аргументом этой функции является объект TestContext. Если хук использует обратные вызовы, функция обратного вызова передаётся в качестве второго аргумента. По умолчанию: функция-пустышка.
• options <Объект> Параметры конфигурации для хука. Поддерживаются следующие свойства:
  • signal <AbortSignal> Позволяет прервать выполняемый хук.
  • timeout <число> Количество миллисекунд, через которое хук завершится с ошибкой. Если не указано, субтесты унаследуют это значение от родительского теста. По умолчанию: 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 <Функция> | <Асинхронная функция> Функция-хук. Первым аргументом этой функции является объект TestContext. Если хук использует обратные вызовы, функция обратного вызова передаётся в качестве второго аргумента. По умолчанию: функция-пустышка.
• options <Объект> Параметры конфигурации для хука. Поддерживаются следующие свойства:
  • signal <AbortSignal> Позволяет прервать выполняемый хук.
  • timeout <число> Количество миллисекунд, через которое хук завершится с ошибкой. Если не указано, субтесты унаследуют это значение от родительского теста. По умолчанию: 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 <Функция> | <Асинхронная функция> Функция-хук. Первым аргументом этой функции является объект TestContext. Если хук использует обратные вызовы, функция обратного вызова передаётся в качестве второго аргумента. По умолчанию: функция-пустышка.
• options <Объект> Параметры конфигурации для хука. Поддерживаются следующие свойства:
  • signal <AbortSignal> Позволяет прервать выполняемый хук.
  • timeout <число> Количество миллисекунд, через которое хук завершится с ошибкой. Если не указано, субтесты унаследуют это значение от родительского теста. По умолчанию: 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.diagnostic(message)

• message <строка> Сообщение для отчётности.

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

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

context.name

Имя теста.

context.runOnly(shouldRunOnlyTests)

• shouldRunOnlyTests <логическое> Выполнять только тесты 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 <строка> Необязательное сообщение для пропуска.

Эта функция вызывает вывод, который показывает тест как пропущенный. Если 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 <строка> Необязательное 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.
• 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 },
    (t) => {
      assert.ok('some relevant assertion here');
    },
  );
}); copy

Класс: SuiteContext

Экземпляр SuiteContext передаётся каждой функции набора тестов для взаимодействия с исполнителем тестов. Однако, конструктор SuiteContext не экспортируется в API.

context.name

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

context.signal

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