Параметры командной строки Jest

Средство запуска командной строки jest имеет ряд полезных параметров. Выполните команду jest --help, чтобы просмотреть все доступные параметры. Многие из приведённых ниже параметров можно также использовать вместе, чтобы запускать тесты именно так, как вам нужно. Любой параметр конфигурации Jest можно также задать через CLI.

Краткий обзор:

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

Запустить все тесты (по умолчанию):

jest

Запустить только тесты, указанные с помощью шаблона или имени файла:

jest my-test #or
jest path/to/my-test.js

Запустить тесты, связанные с изменёнными файлами на основе hg/git (незафиксированные файлы):

jest -o

Запустить тесты, связанные с path/to/fileA.js и path/to/fileB.js:

jest --findRelatedTests path/to/fileA.js path/to/fileB.js

Запустить тесты, соответствующие этому имени спецификации (в основном, сопоставление с именем в describe или test).

jest -t name-of-spec

Запустить в режиме наблюдения:

jest --watch #runs jest -o by default
jest --watchAll #runs all tests

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

Использование с менеджером пакетов

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

Вместо:

jest -u -t="ColorPicker"

можно использовать:

npm test -- -u -t="ColorPicker"

yarn test -u -t="ColorPicker"

pnpm test -u -t="ColorPicker"

bun run test -u -t "ColorPicker"

Поддержка аргументов в camelCase и формате с дефисами

Jest поддерживает аргументы как в формате camelCase, так и в формате с дефисами. Следующие примеры дадут одинаковый результат:

jest --collect-coverage
jest --collectCoverage

Аргументы также можно сочетать:

jest --update-snapshot --detectOpenHandles

Параметры

Справочник

jest <regexForTestFiles>

Если запустить jest с аргументом, этот аргумент будет трактоваться как регулярное выражение для сопоставления с файлами проекта. Наборы тестов можно запускать, указав шаблон. Будут выбраны и выполнены только файлы, соответствующие шаблону. В зависимости от используемого терминала этот аргумент может потребоваться заключить в кавычки: jest "my.*(complex)?pattern". В Windows в качестве разделителя пути необходимо использовать / либо экранировать \ как \\.

--bail[=<n>]

Псевдоним: -b. Немедленно завершает выполнение набора тестов после n неудачного набора тестов. По умолчанию — 1.

--cache

Использовать ли кэш. По умолчанию включено. Отключить кэш можно с помощью --no-cache.

Чтобы проверить кэш, используйте --showConfig и посмотрите значение cacheDirectory. Чтобы очистить кэш, используйте --clearCache.

--changedFilesWithAncestor

Запускает тесты, связанные с текущими изменениями и изменениями, внесёнными в последнем коммите. Работает аналогично --onlyChanged.

--changedSince

Запускает тесты, связанные с изменениями, внесёнными после указанной ветки или хеша коммита. Если текущая ветка разошлась с указанной веткой, проверяются только локальные изменения. Работает аналогично --onlyChanged.

--ci

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

--clearCache

Удаляет каталог кэша Jest и завершает работу, не запуская тесты. Удаляется cacheDirectory, если указан этот параметр, или каталог кэша Jest по умолчанию. Каталог кэша по умолчанию можно узнать, вызвав jest --showConfig.

--clearMocks

Автоматически очищает вызовы, экземпляры, контексты и результаты моков перед каждым тестом. Эквивалентно вызову jest.clearAllMocks() перед каждым тестом. При этом реализации моков, если они были заданы, не удаляются.

--collectCoverageFrom=<glob>

Шаблон glob относительно rootDir, соответствующий файлам, для которых нужно собрать данные о покрытии.

--collectTests

Находит и выводит все наборы тестов и имена тестов, не выполняя их. Jest загружает каждый файл тестов, вычисляет блоки describe верхнего уровня для регистрации тестов, а затем завершает работу, не выполняя код тестов и хуки жизненного цикла.

Результат представляет собой дерево путей к файлам с вложенными именами describe и тестов, за которым следует сводка общего количества. Пропущенные тесты и тесты со статусом todo помечаются соответствующим образом, а для каждого файла, при загрузке которого возникла ошибка, выводится сообщение об ошибке (код завершения будет ненулевым):

path/to/my.test.ts
  My suite
    passes
    skips [skipped]
    write later [todo]

Test suites: 1
Tests:       3 total, 1 runnable, 1 skipped, 1 todo

Параметризованные тесты, объявленные с помощью test.each / describe.each, разворачиваются в отдельные записи для каждого варианта. Каждый собранный тест классифицируется так же, как и при обычном запуске:

• тест, который должен был бы запуститься, указывается в категории passed и помечается как wouldRun: true (он был выбран, но не выполнялся);
• test.skip, тесты внутри пропущенного блока describe, тесты, исключённые параметром test.only, и тесты, исключённые параметром --testNamePattern, указываются как pending;
• test.todo указывается как todo.

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

Для получения машиночитаемого вывода используйте --json. JSON имеет ту же структуру, что и при обычном запуске, включая numTotalTests, numPassedTests, numPendingTests и numTodoTests; каждый результат проверки содержит описанный выше флаг wouldRun.

--colors

Принудительно включает цветовую подсветку результатов тестов, даже если stdout не является TTY.

--config=<path>

Псевдоним: -c. Путь к файлу конфигурации Jest, задающему поиск и выполнение тестов. Если в конфигурации не задан rootDir, каталог, содержащий файл конфигурации, считается rootDir проекта. Вместо этого также можно указать значение в формате JSON, которое Jest будет использовать в качестве конфигурации.

--coverage[=<boolean>]

Псевдоним: --collectCoverage. Указывает, что нужно собрать информацию о покрытии тестами и вывести отчёт. При необходимости передайте <boolean>, чтобы переопределить параметр конфигурации.

--coverageDirectory=<path>

Каталог, в который Jest должен записать файлы покрытия.

--coverageProvider=<provider>

Указывает, какой поставщик инструментирования кода использовать для сбора покрытия. Допустимые значения: babel (по умолчанию) или v8.

--debug

Выводит отладочную информацию о конфигурации Jest.

--detectOpenHandles

Пытается собрать и вывести сведения об открытых дескрипторах, мешающих Jest корректно завершить работу. Используйте этот параметр, если вам приходится применять --forceExit, чтобы Jest завершил работу, и вы хотите выяснить причину. Этот параметр подразумевает --runInBand, поэтому тесты выполняются последовательно. Реализован с помощью async_hooks. Этот параметр значительно снижает производительность и предназначен только для отладки.

--env=<environment>

Среда выполнения для всех тестов. Можно указать любой файл или модуль Node.js. Примеры: jsdom, node или path/to/my-environment.js.

--errorOnDeprecated

При вызове устаревших API генерирует исключения с полезными сообщениями об ошибках. Помогает упростить процесс обновления.

--expand

Псевдоним: -e. Используйте этот флаг, чтобы показывать полные различия и ошибки вместо патча.

--filter=<file>

Путь к модулю, экспортирующему функцию фильтрации. Эта асинхронная функция получает список путей к тестам, который можно изменить, чтобы исключить тесты из запуска, и должна вернуть объект формы { filtered: Array<string> }, содержащий тесты, которые должен запускать Jest. Особенно полезна в сочетании с инфраструктурой тестирования для фильтрации известных нестабильных тестов.

// This filter when applied will only run tests ending in .spec.js (not the best way to do it, but it's just an example):
const filteringFunction = testPath => testPath.endsWith('.spec.js');

module.exports = testPaths => {
  const allowedPaths = testPaths.filter(filteringFunction); // ["path1.spec.js", "path2.spec.js", etc]

  return {
    filtered: allowedPaths,
  };
};

--findRelatedTests <spaceSeparatedListOfSourceFiles>

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

--forceExit

Принудительно завершает работу Jest после выполнения всех тестов. Полезно, если ресурсы, созданные кодом тестов, невозможно корректно освободить.

--help

Показывает справочную информацию, аналогичную этой странице.

--ignoreProjects <project1> ... <projectN>

Не запускает тесты указанных проектов. Для определения каждого проекта Jest использует атрибут displayName в конфигурации. Если вы используете этот параметр, необходимо указать displayName для всех проектов.

--injectGlobals

Добавляет глобальные объекты Jest (expect, test, describe, beforeEach и т. д.) в глобальное окружение. Если установить значение false, следует импортировать их из @jest/globals, например:

import {expect, jest, test} from '@jest/globals';

jest.useFakeTimers();

test('some test', () => {
  expect(Date.now()).toBe(0);
});

--json

Выводит результаты тестов в формате JSON. В этом режиме весь остальной вывод тестов и сообщения пользователя направляются в stderr.

--lastCommit

Запускает все тесты, на которые повлияли изменения файлов в последнем коммите. Работает аналогично --onlyChanged.

--listTests

Выводит список всех файлов тестов, которые Jest запустил бы с заданными аргументами, и завершает работу.

--logHeapUsage

Выводит информацию об использовании кучи после каждого теста. Полезно для отладки утечек памяти. Используйте вместе с --runInBand и --expose-gc в Node.js.

--maxConcurrency=<num>

Не позволяет Jest одновременно выполнять больше указанного количества тестов. Влияет только на тесты, использующие test.concurrent.

--maxWorkers=<num>|<string>

Псевдоним: -w. Задаёт максимальное количество рабочих процессов, создаваемых пулом для выполнения тестов. При однократном запуске по умолчанию используется число ядер компьютера минус одно для основного потока. В режиме наблюдения по умолчанию используется половина доступных ядер, чтобы Jest работал незаметно и не перегружал компьютер. Этот параметр может пригодиться в средах с ограниченными ресурсами, например в CI, но для большинства случаев достаточно значений по умолчанию.

В средах с переменным количеством доступных процессоров можно использовать конфигурацию на основе процентов: --maxWorkers=50%

--noStackTrace

Отключает вывод трассировки стека в результатах тестов.

--notify

Включает системные уведомления ОС о результатах тестов. Полезно, если вы хотите полностью сосредоточиться на тестировании JavaScript. Для отображения уведомлений Jest требуется пакет node-notifier, который нужно установить отдельно.

--onlyChanged

Псевдоним: -o. Пытается определить, какие тесты запускать, исходя из того, какие файлы изменились в текущем репозитории. Работает только при запуске тестов в репозитории git/hg и требует статического графа зависимостей (то есть без динамических вызовов require).

--onlyFailures

Псевдоним: -f. Запускает тесты, завершившиеся с ошибкой при предыдущем выполнении.

--openHandlesTimeout=<milliseconds>

Если --detectOpenHandles и --forceExit отключены, Jest выведет предупреждение, если процесс не завершился корректно за указанное количество миллисекунд. Значение 0 отключает предупреждение. По умолчанию — 1000.

--outputFile=<filename>

Записывает результаты тестов в файл, если также указан параметр --json. Возвращаемая структура JSON описана в testResultsProcessor.

--passWithNoTests

Позволяет набору тестов завершиться успешно, если файлы не найдены.

--projects <path1> ... <pathN>

Запускает тесты одного или нескольких проектов, найденных по указанным путям; также поддерживаются шаблоны путей. Этот параметр CLI соответствует параметру конфигурации projects.

--randomize

Перемешивает порядок тестов в файле. Перемешивание зависит от начального значения (seed). Подробнее см. в разделе --seed=<num>.

При включении этого параметра отображается значение seed. Эквивалентно указанию параметра CLI --showSeed.

jest --randomize --seed 1234

--reporters

Запускает тесты с указанными репортерами. Параметры репортеров нельзя задавать через CLI. Пример с несколькими репортерами:

jest --reporters="default" --reporters="jest-junit"

--resetMocks

Автоматически сбрасывает состояние моков перед каждым тестом. Эквивалентно вызову jest.resetAllMocks() перед каждым тестом. В результате у всех моков удаляются фиктивные реализации, но исходные реализации не восстанавливаются.

--restoreMocks

Автоматически восстанавливает состояние и реализацию моков перед каждым тестом. Эквивалентно вызову jest.restoreAllMocks() перед каждым тестом. В результате у всех моков удаляются фиктивные реализации и восстанавливаются исходные реализации.

--roots

Список путей к каталогам, в которых Jest должен искать файлы.

--runInBand

Псевдоним: -i. Запускает все тесты последовательно в текущем процессе, а не создаёт пул рабочих дочерних процессов для выполнения тестов. Может быть полезно для отладки.

--runTestsByPath

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

Например, при следующей структуре файлов:

__tests__
└── t1.test.js # test
└── t2.test.js # test

При запуске с шаблоном тесты не найдены:

jest --runTestsByPath __tests__/t

Вывод:

No tests found

Однако при передаче точного пути будет выполнен только указанный тест:

jest --runTestsByPath __tests__/t1.test.js

Вывод:

PASS __tests__/t1.test.js

--seed=<num>

Задаёт начальное значение, которое можно получить в файле теста с помощью jest.getSeed(). Значение seed должно быть в диапазоне от -0x80000000 до 0x7fffffff включительно (-2147483648 (-(2 ** 31)) и 2147483647 (2 ** 31 - 1) в десятичной системе счисления).

jest --seed=1324

--selectProjects <project1> ... <projectN>

Запускает тесты указанных проектов. Для определения каждого проекта Jest использует атрибут displayName в конфигурации. Если вы используете этот параметр, необходимо указать displayName для всех проектов.

--setupFilesAfterEnv <path1> ... <pathN>

Список путей к модулям, выполняющим код для настройки или подготовки среды тестирования перед каждым файлом тестов. Обратите внимание: файлы, импортированные скриптами настройки, не будут замокированы во время тестирования.

--shard

Фрагмент набора тестов, который нужно выполнить; задаётся в формате (?<shardIndex>\d+)/(?<shardCount>\d+).

shardIndex указывает, какой фрагмент выбрать, а shardCount задаёт количество фрагментов, на которые нужно разделить набор.

Значения shardIndex и shardCount должны быть положительными числами, начиная с 1, а shardIndex должно быть меньше или равно shardCount.

Если указан параметр shard, настроенный testSequencer должен реализовывать метод shard.

Например, чтобы разделить набор на три фрагмента, каждый из которых запускает треть тестов:

jest --shard=1/3
jest --shard=2/3
jest --shard=3/3

--showConfig

Выводит конфигурацию Jest и завершает работу.

--showSeed

Выводит значение seed в сводке отчёта о тестах. Подробнее см. в разделе --seed=<num>.

Также можно задать в конфигурации. См. showSeed.

--silent

Запретить вывод сообщений тестами в консоль.

--testEnvironmentOptions=<json string>

Строка JSON с параметрами, которые будут переданы в testEnvironment. Необходимые параметры зависят от среды.

--testLocationInResults

Добавляет поле location в результаты тестов. Полезно, если вы хотите указать расположение теста в репортёре.

{
  "column": 4,
  "line": 5
}

--testMatch glob1 ... globN

Шаблоны glob, которые Jest использует для поиска файлов тестов. Подробности см. в конфигурации testMatch.

--testNamePattern=<regex>

Псевдоним: -t. Запустить только тесты, имена которых соответствуют регулярному выражению. Например, если вы хотите запустить только тесты, связанные с авторизацией, с именами вроде 'GET /api/posts with auth', используйте jest -t=auth.

--testPathIgnorePatterns=<regex>|[array]

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

Чтобы передать массив, используйте экранированные круглые скобки и регулярные выражения, разделённые пробелами, например \(/node_modules/ /tests/e2e/\). Также можно опустить скобки, объединив регулярные выражения в одно, например /node_modules/|/tests/e2e/. Эти два примера эквивалентны.

--testPathPatterns=<regex>

Строка с шаблоном регулярного выражения, которая сопоставляется со всеми путями к тестам перед запуском теста. В Windows в качестве разделителя пути необходимо использовать / или экранировать \ как \\.

--testRunner=<path>

Позволяет указать собственный раннер тестов.

--testSequencer=<path>

Позволяет указать собственный секвенсор тестов. Подробности см. в конфигурации testSequencer.

--testTimeout=<number>

Тайм-аут теста по умолчанию в миллисекундах. Значение по умолчанию: 5000.

--updateSnapshot

Псевдоним: -u. Используйте этот флаг, чтобы повторно записать все снимки, не прошедшие во время этого запуска тестов. Можно использовать вместе с шаблоном набора тестов или с --testNamePattern для повторной записи снимков.

--useStderr

Перенаправить весь вывод в stderr.

--verbose

Отображать результаты отдельных тестов с иерархией набора тестов.

--version

Псевдоним: -v. Вывести версию и завершить работу.

--waitForUnhandledRejections

Даёт один цикл событий на обработку rejectionHandled, uncaughtException или unhandledRejection.

Без этого флага Jest может сообщать о ложноположительных ошибках (например, сообщать об отклонённом промисе, который был обработан) или не сообщать о действительно необработанном отклонении (либо сообщать о нём для другого тестового случая).

Этот параметр может заметно замедлить выполнение быстрых наборов тестов.

--watch

Отслеживать изменения файлов и повторно запускать тесты, связанные с изменёнными файлами. Если вы хотите повторно запускать все тесты при изменении файла, используйте вместо этого параметр --watchAll.

--watchAll

Отслеживать изменения файлов и повторно запускать все тесты при любых изменениях. Если вы хотите повторно запускать только тесты, зависящие от изменённых файлов, используйте параметр --watch.

--watchman

Использовать ли watchman для обхода файловой системы. По умолчанию true. Отключите с помощью --no-watchman.

--workerGracefulExitTimeout=<number>

Тайм-аут в миллисекундах, в течение которого рабочие процессы должны завершиться корректно после выполнения тестов. Рабочие процессы, не завершившиеся вовремя, принудительно завершаются. Значение по умолчанию: 500.

--workerThreads

Использовать ли потоки-воркеры для параллельного выполнения. По умолчанию используются дочерние процессы.