Настройка Jest

Философия Jest — отлично работать по умолчанию, но иногда вам просто нужны более широкие возможности настройки.

Рекомендуется задавать конфигурацию в отдельном файле JavaScript, TypeScript или JSON. Файл будет найден автоматически, если он называется jest.config.js|ts|mjs|mts|cjs|cts|json. Чтобы передать явный путь к файлу, можно использовать флаг --config.

const {defineConfig} = require('jest');

module.exports = defineConfig({
  // ... Specify options here.
});

/** @jest-config-loader ts-node */
// or
/** @jest-config-loader esbuild-register */

import {defineConfig} from 'jest';

export default defineConfig({
  // ... Specify options here.
});

const {defineConfig} = require('jest');
const {defaults} = require('jest-config');

module.exports = defineConfig({
  moduleDirectories: [...defaults.moduleDirectories, 'bower_components'],
});

/** @jest-config-loader ts-node */
// or
/** @jest-config-loader esbuild-register */

import {defineConfig} from 'jest';
import {defaults} from 'jest-config';

export default defineConfig({
  moduleDirectories: [...defaults.moduleDirectories, 'bower_components'],
});

export default config;

const {defineConfig, mergeConfig} = require('jest');
const jestConfig = require('./jest.config');

module.exports = mergeConfig(
  jestConfig,
  defineConfig({
    // ... Specify options here.
  }),
);

/** @jest-config-loader ts-node */
// or
/** @jest-config-loader esbuild-register */

import {defineConfig, mergeConfig} from 'jest';
import jestConfig from './jest.config';

export default mergeConfig(
  jestConfig,
  defineConfig({
    // ... Specify options here.
  }),
);

const {defineConfig, mergeConfig} = require('jest');
const jestConfig = require('./jest.config');

module.exports = defineConfig(() =>
  mergeConfig(
    jestConfig,
    defineConfig({
      // ... Specify options here.
    }),
  ),
);

/** @jest-config-loader ts-node */
// or
/** @jest-config-loader esbuild-register */

import {defineConfig, mergeConfig} from 'jest';
import jestConfig from './jest.config';

export default defineConfig(() =>
  mergeConfig(
    jestConfig,
    defineConfig({
      // ... Specify options here.
    }),
  ),
);

{
  "bail": 1,
  "verbose": true
}

{
  "name": "my-project",
  "jest": {
    "verbose": true
  }
}

{
  "name": "my-project",
  "jest": "./path/to/config.json"
}

/** @jest-config-loader ts-node */
// or
/** @jest-config-loader esbuild-register */

import {defineConfig} from 'jest';

export default defineConfig({
  verbose: true,
});

/** @jest-config-loader ts-node */
/** @jest-config-loader-options {"transpileOnly": true} */

import type {defineConfig} from 'jest';

export default defineConfig({
  verbose: true,
});

Параметры

Справочник

automock [boolean]

По умолчанию: false

Этот параметр указывает Jest автоматически создавать моки всех модулей, импортируемых в тестах. Для всех используемых в тестах модулей будет создана замещающая реализация с сохранением поверхности API.

Пример:

export default {
  authorize: () => 'token',
  isAuthorized: secret => secret === 'wizard',
};

import utils from '../utils';

test('if utils mocked automatically', () => {
  // Public methods of `utils` are now mock functions
  expect(utils.authorize.mock).toBeTruthy();
  expect(utils.isAuthorized.mock).toBeTruthy();

  // You can provide them with your own implementation
  // or pass the expected return value
  utils.authorize.mockReturnValue('mocked_token');
  utils.isAuthorized.mockReturnValue(true);

  expect(utils.authorize()).toBe('mocked_token');
  expect(utils.isAuthorized('not_wizard')).toBeTruthy();
});

bail [number | boolean]

По умолчанию: 0

По умолчанию Jest выполняет все тесты и выводит все ошибки в консоль по завершении. Параметр конфигурации bail позволяет остановить выполнение тестов после n сбоев. Значение bail true эквивалентно значению bail 1.

cacheDirectory [string]

По умолчанию: "/tmp/<path>"

Каталог, в котором Jest должен хранить кэш сведений о зависимостях.

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

clearMocks [boolean]

По умолчанию: false

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

collectCoverage [boolean]

По умолчанию: false

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

Jest поставляется с двумя провайдерами сбора данных о покрытии: babel (по умолчанию) и v8. Подробнее см. параметр coverageProvider.

collectCoverageFrom [array]

По умолчанию: undefined

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

const {defineConfig} = require('jest');

module.exports = defineConfig({
  collectCoverageFrom: [
    '**/*.{js,jsx}',
    '!**/node_modules/**',
    '!**/vendor/**',
  ],
});

import {defineConfig} from 'jest';

export default defineConfig({
  collectCoverageFrom: [
    '**/*.{js,jsx}',
    '!**/node_modules/**',
    '!**/vendor/**',
  ],
});

Это позволит собрать данные о покрытии для всех файлов в каталоге rootDir проекта, кроме файлов, соответствующих шаблонам **/node_modules/** или **/vendor/**.

=============================== Coverage summary ===============================
Statements   : Unknown% ( 0/0 )
Branches     : Unknown% ( 0/0 )
Functions    : Unknown% ( 0/0 )
Lines        : Unknown% ( 0/0 )
================================================================================
Jest: Coverage data for global was not found.

coverageDirectory [string]

По умолчанию: undefined

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

coveragePathIgnorePatterns [array<string>]

По умолчанию: ["/node_modules/"]

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

Эти строки-шаблоны проверяются на соответствие полному пути. Используйте строковый токен <rootDir>, чтобы включить путь к корневому каталогу проекта и не допустить случайного игнорирования всех файлов в разных средах, где корневые каталоги могут отличаться. Пример: ["<rootDir>/build/", "<rootDir>/node_modules/"].

coverageProvider [string]

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

coverageReporters [array<string | [string, options]>]

По умолчанию: ["clover", "json", "lcov", "text"]

Список названий репортеров, которые Jest использует при создании отчетов о покрытии. Можно использовать любой репортер istanbul.

Дополнительные параметры можно передать в виде кортежа. Например, можно скрыть строки отчета о покрытии для всех файлов с полным покрытием:

const {defineConfig} = require('jest');

module.exports = defineConfig({
  coverageReporters: ['clover', 'json', 'lcov', ['text', {skipFull: true}]],
});

import {defineConfig} from 'jest';

export default defineConfig({
  coverageReporters: ['clover', 'json', 'lcov', ['text', {skipFull: true}]],
});

Подробнее о структуре объекта options см. тип CoverageReporterWithOptions в определениях типов.

coverageThreshold [object]

По умолчанию: undefined

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

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

• Если задано отрицательное число, оно будет трактоваться как максимальное допустимое количество непокрытых элементов.

Например, при следующей конфигурации Jest завершится с ошибкой, если покрытие ветвей, строк и функций составляет менее 80% или если имеется более 10 непокрытых инструкций:

const {defineConfig} = require('jest');

module.exports = defineConfig({
  coverageThreshold: {
    global: {
      // Requires 80% branch coverage
      branches: 80,
      // Requires 80% function coverage
      functions: 80,
      // Requires 80% line coverage
      lines: 80,
      // Require that no more than 10 statements are uncovered
      statements: -10,
    },
  },
});

import {defineConfig} from 'jest';

export default defineConfig({
  coverageThreshold: {
    global: {
      // Requires 80% branch coverage
      branches: 80,
      // Requires 80% function coverage
      functions: 80,
      // Requires 80% line coverage
      lines: 80,
      // Require that no more than 10 statements are uncovered
      statements: -10,
    },
  },
});

coverageThreshold.global.lines [number]

Глобальный порог для строк.

coverageThreshold.global.functions [number]

Глобальный порог для функций.

coverageThreshold.global.statements [number]

Глобальный порог для инструкций.

coverageThreshold.global.branches [number]

Глобальный порог для ветвей.

coverageThreshold[glob-pattern] [object]

По умолчанию: undefined

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

const {defineConfig} = require('jest');

module.exports = defineConfig({
  coverageThreshold: {
    global: {
      branches: 50,
      functions: 50,
      lines: 50,
      statements: 50,
    },
    './src/components/': {
      branches: 40,
      statements: 40,
    },
    './src/reducers/**/*.js': {
      statements: 90,
    },
    './src/api/very-important-module.js': {
      branches: 100,
      functions: 100,
      lines: 100,
      statements: 100,
    },
  },
});

import {defineConfig} from 'jest';

export default defineConfig({
  coverageThreshold: {
    global: {
      branches: 50,
      functions: 50,
      lines: 50,
      statements: 50,
    },
    './src/components/': {
      branches: 40,
      statements: 40,
    },
    './src/reducers/**/*.js': {
      statements: 90,
    },
    './src/api/very-important-module.js': {
      branches: 100,
      functions: 100,
      lines: 100,
      statements: 100,
    },
  },
});

Jest завершится с ошибкой, если:

• В каталоге ./src/components покрытие ветвей/инструкций составляет менее 40%.
• Для одного из файлов, соответствующих шаблону glob ./src/reducers/**/*.js, покрытие инструкций составляет менее 90%.
• Для файла ./src/api/very-important-module.js покрытие составляет менее 100%.
• Покрытие всех файлов, не соответствующих ./src/components, ./src/reducers/**/*.js или ./src/api/very-important-module.js, составляет менее 50% (global).

dependencyExtractor [string]

По умолчанию: undefined

Этот параметр позволяет использовать пользовательский извлекатель зависимостей. Это должен быть модуль Node.js, экспортирующий объект с функцией extract. Например:

const crypto = require('crypto');
const fs = require('fs');

module.exports = {
  extract(code, filePath, defaultExtract) {
    const deps = defaultExtract(code, filePath);
    // Scan the file and add dependencies in `deps` (which is a `Set`)
    return deps;
  },
  getCacheKey() {
    return crypto
      .createHash('md5')
      .update(fs.readFileSync(__filename))
      .digest('hex');
  },
};

Функция extract должна возвращать итерируемый объект (Array, Set и т. д.) с зависимостями, найденными в коде.

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

displayName [string, object]

по умолчанию: undefined

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

const {defineConfig} = require('jest');

module.exports = defineConfig({
  displayName: 'CLIENT',
});

import {defineConfig} from 'jest';

export default defineConfig({
  displayName: 'CLIENT',
});

В качестве альтернативы можно передать объект со свойствами name и color. Это позволяет настроить цвет фона для displayName. Если значение displayName является строкой, по умолчанию используется белый цвет. Для задания цвета Jest использует библиотеку chalk. Поэтому Jest поддерживает все допустимые значения цветов, поддерживаемые chalk.

const {defineConfig} = require('jest');

module.exports = defineConfig({
  displayName: {
    name: 'CLIENT',
    color: 'blue',
  },
});

import {defineConfig} from 'jest';

export default defineConfig({
  displayName: {
    name: 'CLIENT',
    color: 'blue',
  },
});

errorOnDeprecated [boolean]

По умолчанию: false

Вызывайте устаревшие API с выдачей информативных сообщений об ошибках. Это упрощает процесс обновления.

extensionsToTreatAsEsm [array<string>]

По умолчанию: []

Jest будет запускать файлы .mjs и .js с ближайшим полем type в package.json, установленным в module, как модули ECMAScript. Если есть другие файлы, которые должны запускаться с использованием нативного ESM, укажите здесь их расширения.

const {defineConfig} = require('jest');

module.exports = defineConfig({
  extensionsToTreatAsEsm: ['.ts'],
});

import {defineConfig} from 'jest';

export default defineConfig({
  extensionsToTreatAsEsm: ['.ts'],
});

fakeTimers [object]

По умолчанию: {}

Фальшивые таймеры могут быть полезны, когда фрагмент кода задаёт длительную задержку, окончания которой не хочется ждать во время теста. Дополнительные сведения см. в руководстве по фальшивым таймерам и документации API.

Этот параметр задаёт конфигурацию фальшивых таймеров по умолчанию для всех тестов. Вызов jest.useFakeTimers() в файле теста использует эти параметры или переопределяет их, если передан объект конфигурации. Например, можно указать Jest сохранить исходную реализацию process.nextTick() и изменить ограничение на количество рекурсивных таймеров, которые будут запущены:

const {defineConfig} = require('jest');

module.exports = defineConfig({
  fakeTimers: {
    doNotFake: ['nextTick'],
    timerLimit: 1000,
  },
});

import {defineConfig} from 'jest';

export default defineConfig({
  fakeTimers: {
    doNotFake: ['nextTick'],
    timerLimit: 1000,
  },
});

// install fake timers for this file using the options from Jest configuration
jest.useFakeTimers();

test('increase the limit of recursive timers for this and following tests', () => {
  jest.useFakeTimers({timerLimit: 5000});
  // ...
});

const {defineConfig} = require('jest');

module.exports = defineConfig({
  fakeTimers: {
    enableGlobally: true,
  },
});

import {defineConfig} from 'jest';

export default defineConfig({
  fakeTimers: {
    enableGlobally: true,
  },
});

Параметры конфигурации:

type FakeableAPI =
  | 'Date'
  | 'hrtime'
  | 'nextTick'
  | 'performance'
  | 'queueMicrotask'
  | 'requestAnimationFrame'
  | 'cancelAnimationFrame'
  | 'requestIdleCallback'
  | 'cancelIdleCallback'
  | 'setImmediate'
  | 'clearImmediate'
  | 'setInterval'
  | 'clearInterval'
  | 'setTimeout'
  | 'clearTimeout';

type ModernFakeTimersConfig = {
  /**
   * If set to `true` all timers will be advanced automatically by 20 milliseconds
   * every 20 milliseconds. A custom time delta may be provided by passing a number.
   * The default is `false`.
   */
  advanceTimers?: boolean | number;
  /**
   * List of names of APIs that should not be faked. The default is `[]`, meaning
   * all APIs are faked.
   */
  doNotFake?: Array<FakeableAPI>;
  /** Whether fake timers should be enabled for all test files. The default is `false`. */
  enableGlobally?: boolean;
  /**
   * Use the old fake timers implementation instead of one backed by `@sinonjs/fake-timers`.
   * The default is `false`.
   */
  legacyFakeTimers?: boolean;
  /** Sets current system time to be used by fake timers, in milliseconds. The default is `Date.now()`. */
  now?: number;
  /** Maximum number of recursive timers that will be run. The default is `100_000` timers. */
  timerLimit?: number;
};

const {defineConfig} = require('jest');

module.exports = defineConfig({
  fakeTimers: {
    enableGlobally: true,
    legacyFakeTimers: true,
  },
});

import {defineConfig} from 'jest';

export default defineConfig({
  fakeTimers: {
    enableGlobally: true,
    legacyFakeTimers: true,
  },
});

forceCoverageMatch [array<string>]

По умолчанию: ['']

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

Например, если тесты находятся в исходных файлах с расширением .t.js, как показано ниже:

export function sum(a, b) {
  return a + b;
}

if (process.env.NODE_ENV === 'test') {
  test('sum', () => {
    expect(sum(1, 2)).toBe(3);
  });
}

Покрытие кода для этих файлов можно собирать, задав forceCoverageMatch.

const {defineConfig} = require('jest');

module.exports = defineConfig({
  forceCoverageMatch: ['**/*.t.js'],
});

import {defineConfig} from 'jest';

export default defineConfig({
  forceCoverageMatch: ['**/*.t.js'],
});

globals [object]

По умолчанию: {}

Набор глобальных переменных, доступных во всех тестовых средах.

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

const {defineConfig} = require('jest');

module.exports = defineConfig({
  globals: {
    __DEV__: true,
  },
});

import {defineConfig} from 'jest';

export default defineConfig({
  globals: {
    __DEV__: true,
  },
});

globalSetup [string]

По умолчанию: undefined

Этот параметр позволяет использовать пользовательский модуль глобальной настройки, который должен экспортировать функцию (синхронную или асинхронную). Функция будет вызвана один раз перед запуском всех файлов тестов и получит два аргумента: globalConfig и projectConfig Jest.

module.exports = async function (globalConfig, projectConfig) {
  console.log(globalConfig.testPathPatterns);
  console.log(projectConfig.cache);

  // Set reference to mongod in order to close the server during teardown.
  globalThis.__MONGOD__ = mongod;
};

module.exports = async function (globalConfig, projectConfig) {
  console.log(globalConfig.testPathPatterns);
  console.log(projectConfig.cache);

  await globalThis.__MONGOD__.stop();
};

globalTeardown [string]

По умолчанию: undefined

Этот параметр позволяет использовать пользовательский модуль глобальной очистки, который должен экспортировать функцию (синхронную или асинхронную). Функция будет вызвана один раз после выполнения всех файлов тестов и получит два аргумента: globalConfig и projectConfig Jest.

haste [object]

По умолчанию: undefined

Этот параметр используется для настройки поведения jest-haste-map — внутренней системы Jest для обхода файлов и кэширования. Поддерживаются следующие параметры:

type HasteConfig = {
  /** Whether to hash files using SHA-1. */
  computeSha1?: boolean;
  /** The platform to use as the default, e.g. 'ios'. */
  defaultPlatform?: string | null;
  /**
   * Force use of Node's `fs` APIs (via `fdir`) rather than shelling out to
   * the system `find` binary. Defaults to `false` on Linux/macOS.
   *
   * **Consider setting this to `true`**: `find(1)` receives no ignore
   * predicate, so it traverses ignored directories (e.g. `node_modules`,
   * `.git`) in full and discards the results afterward. The Node `fs` crawler
   * prunes those subtrees at `readdir` time. For most projects where
   * `node_modules` dwarfs source files, this makes the Node crawler faster
   * in practice despite `find(1)` being native code. A future Jest version
   * may flip this default.
   */
  forceNodeFilesystemAPI?: boolean;
  /**
   * Whether to follow symlinks when crawling for files.
   *   This option cannot be used in projects which use watchman.
   *   Projects with `watchman` set to true will error if this option is set to true.
   */
  enableSymlinks?: boolean;
  /** Path to a custom implementation of Haste. */
  hasteImplModulePath?: string;
  /** All platforms to target, e.g ['ios', 'android']. */
  platforms?: Array<string>;
  /** Whether to throw an error on module collision. */
  throwOnModuleCollision?: boolean;
  /** Custom HasteMap module */
  hasteMapModulePath?: string;
  /** Whether to retain all files, allowing e.g. search for tests in `node_modules`. */
  retainAllFiles?: boolean;
};

injectGlobals [boolean]

По умолчанию: true

Добавлять глобальные объекты 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);
});

maxConcurrency [number]

По умолчанию: 5

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

maxWorkers [number | string]

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

Для сред с переменным количеством доступных процессоров можно использовать конфигурацию на основе процентов:

const {defineConfig} = require('jest');

module.exports = defineConfig({
  maxWorkers: '50%',
});

import {defineConfig} from 'jest';

export default defineConfig({
  maxWorkers: '50%',
});

moduleDirectories [array<string>]

По умолчанию: ["node_modules"]

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

const {defineConfig} = require('jest');

module.exports = defineConfig({
  moduleDirectories: ['node_modules', 'bower_components'],
});

import {defineConfig} from 'jest';

export default defineConfig({
  moduleDirectories: ['node_modules', 'bower_components'],
});

moduleFileExtensions [array<string>]

По умолчанию: ["js", "mjs", "cjs", "jsx", "ts", "mts", "cts", "tsx", "json", "node"]

Массив расширений файлов, используемых вашими модулями. Если вы импортируете модули, не указывая расширение файла, Jest будет искать файлы с этими расширениями в указанном порядке.

Рекомендуем размещать слева расширения, которые чаще всего используются в вашем проекте. Поэтому, если вы используете TypeScript, стоит переместить "ts" и/или "tsx" в начало массива.

moduleNameMapper [object<string, string | array<string>>]

По умолчанию: null

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

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

Используйте строковый маркер <rootDir> для ссылки на значение rootDir, если нужно использовать пути к файлам.

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

const {defineConfig} = require('jest');

module.exports = defineConfig({
  moduleNameMapper: {
    '^image![a-zA-Z0-9$_-]+$': 'GlobalImageStub',
    '^[./a-zA-Z0-9$_-]+\\.png$': '<rootDir>/RelativeImageStub.js',
    'module_name_(.*)': '<rootDir>/substituted_module_$1.js',
    'assets/(.*)': [
      '<rootDir>/images/$1',
      '<rootDir>/photos/$1',
      '<rootDir>/recipes/$1',
    ],
  },
});

import {defineConfig} from 'jest';

export default defineConfig({
  moduleNameMapper: {
    '^image![a-zA-Z0-9$_-]+$': 'GlobalImageStub',
    '^[./a-zA-Z0-9$_-]+\\.png$': '<rootDir>/RelativeImageStub.js',
    'module_name_(.*)': '<rootDir>/substituted_module_$1.js',
    'assets/(.*)': [
      '<rootDir>/images/$1',
      '<rootDir>/photos/$1',
      '<rootDir>/recipes/$1',
    ],
  },
});

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

modulePathIgnorePatterns [array<string>]

По умолчанию: []

Массив строк с шаблонами регулярных выражений, которые проверяются для всех путей модулей до того, как загрузчик модулей сочтет эти пути «видимыми». Если путь заданного модуля соответствует любому из шаблонов, этот модуль нельзя будет require() в тестовой среде.

Эти строки-шаблоны проверяются по полному пути. Используйте строковый маркер <rootDir>, чтобы указать путь к корневому каталогу проекта и не допустить случайного исключения всех файлов в средах, где корневые каталоги могут различаться.

const {defineConfig} = require('jest');

module.exports = defineConfig({
  modulePathIgnorePatterns: ['<rootDir>/build/'],
});

import {defineConfig} from 'jest';

export default defineConfig({
  modulePathIgnorePatterns: ['<rootDir>/build/'],
});

modulePaths [array<string>]

По умолчанию: []

Альтернативный способ задания переменной среды NODE_PATH. modulePaths — это массив абсолютных путей к дополнительным местам поиска модулей. Используйте строковый маркер <rootDir>, чтобы указать путь к корневому каталогу проекта.

const {defineConfig} = require('jest');

module.exports = defineConfig({
  modulePaths: ['<rootDir>/app/'],
});

import {defineConfig} from 'jest';

export default defineConfig({
  modulePaths: ['<rootDir>/app/'],
});

notify [boolean]

По умолчанию: false

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

npm install --save-dev node-notifier

yarn add --dev node-notifier

pnpm add --save-dev node-notifier

bun add --dev node-notifier

notifyMode [string]

По умолчанию: failure-change

Задает режим уведомлений. Требуется notify: true.

Режимы

• always: всегда отправлять уведомление.
• failure: отправлять уведомление при сбое тестов.
• success: отправлять уведомление при успешном прохождении тестов.
• change: отправлять уведомление при изменении состояния.
• success-change: отправлять уведомление при успешном прохождении тестов или один раз при сбое.
• failure-change: отправлять уведомление при сбое тестов или один раз при успешном прохождении.

openHandlesTimeout [number]

По умолчанию: 1000

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

preset [string]

По умолчанию: undefined

Предустановка, используемая в качестве основы конфигурации Jest. Предустановка должна указывать на npm-модуль, в корне которого находится файл jest-preset.json, jest-preset.js, jest-preset.cjs или jest-preset.mjs.

Например, эта предустановка foo-bar/jest-preset.js будет использоваться следующим образом:

const {defineConfig} = require('jest');

module.exports = defineConfig({
  preset: 'foo-bar',
});

import {defineConfig} from 'jest';

export default defineConfig({
  preset: 'foo-bar',
});

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

const {defineConfig} = require('jest');

module.exports = defineConfig({
  preset: './node_modules/foo-bar/jest-preset.js',
});

import {defineConfig} from 'jest';

export default defineConfig({
  preset: './node_modules/foo-bar/jest-preset.js',
});

prettierPath [string]

По умолчанию: 'prettier'

Задает путь к модулю Node.js prettier, используемому для обновления встроенных снимков.

projects [array<string | ProjectConfig>]

По умолчанию: undefined

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

const {defineConfig} = require('jest');

module.exports = defineConfig({
  projects: ['<rootDir>', '<rootDir>/examples/*'],
});

import {defineConfig} from 'jest';

export default defineConfig({
  projects: ['<rootDir>', '<rootDir>/examples/*'],
});

В этом примере Jest запускается как в корневом каталоге, так и во всех папках каталога examples. В одном экземпляре Jest можно запускать неограниченное количество проектов.

Функцию проектов также можно использовать для запуска нескольких конфигураций или нескольких исполнителей. Для этого можно передать массив объектов конфигурации. Например, чтобы запустить тесты и ESLint (с помощью jest-runner-eslint) за один запуск Jest:

const {defineConfig} = require('jest');

module.exports = defineConfig({
  projects: [
    {
      displayName: 'test',
    },
    {
      displayName: 'lint',
      runner: 'jest-runner-eslint',
      testMatch: ['<rootDir>/**/*.js'],
    },
  ],
});

import {defineConfig} from 'jest';

export default defineConfig({
  projects: [
    {
      displayName: 'test',
    },
    {
      displayName: 'lint',
      runner: 'jest-runner-eslint',
      testMatch: ['<rootDir>/**/*.js'],
    },
  ],
});

import type {GlobalConfig, ProjectConfig} from 'jest';

randomize [boolean]

По умолчанию: false

Аналог флага --randomize, который задаёт случайный порядок тестов в файле.

reporters [array<moduleName | [moduleName, options]>]

По умолчанию: undefined

Используйте этот параметр конфигурации, чтобы добавить репортёры в Jest. Он должен содержать список имён репортёров; дополнительные параметры можно передать репортёру в виде кортежа:

const {defineConfig} = require('jest');

module.exports = defineConfig({
  reporters: [
    'default',
    ['<rootDir>/custom-reporter.js', {banana: 'yes', pineapple: 'no'}],
  ],
});

import {defineConfig} from 'jest';

export default defineConfig({
  reporters: [
    'default',
    ['<rootDir>/custom-reporter.js', {banana: 'yes', pineapple: 'no'}],
  ],
});

Репортёр по умолчанию

Если указаны пользовательские репортёры, стандартный репортёр Jest будет заменён. Чтобы сохранить его, в качестве имени репортёра необходимо передать 'default':

const {defineConfig} = require('jest');

module.exports = defineConfig({
  reporters: [
    'default',
    ['jest-junit', {outputDirectory: 'reports', outputName: 'report.xml'}],
  ],
});

import {defineConfig} from 'jest';

export default defineConfig({
  reporters: [
    'default',
    ['jest-junit', {outputDirectory: 'reports', outputName: 'report.xml'}],
  ],
});

Репортёр GitHub Actions

Если включить встроенный репортёр GitHub Actions в список, он добавит к изменённым файлам аннотации с сообщениями об ошибках тестов и (если используется с 'silent: false') выведет журналы с функциями группировки GitHub для удобной навигации. Обратите внимание: в этом случае не следует использовать 'default', поскольку эту задачу уже выполняет 'github-actions'. Поэтому не забудьте также включить 'summary'. Если вам нужны только аннотации, оставьте репортёр без параметров, поскольку значение по умолчанию для 'silent' — 'true':

const {defineConfig} = require('jest');

module.exports = defineConfig({
  reporters: [['github-actions', {silent: false}], 'summary'],
});

import {defineConfig} from 'jest';

export default defineConfig({
  reporters: [['github-actions', {silent: false}], 'summary'],
});

Сводный репортёр

Сводный репортёр выводит краткую сводку по всем тестам. Он входит в состав стандартного репортёра, поэтому будет включён, если в список добавлен 'default'. Например, его можно использовать как самостоятельный репортёр вместо стандартного или вместе с Silent Reporter:

const {defineConfig} = require('jest');

module.exports = defineConfig({
  reporters: ['jest-silent-reporter', 'summary'],
});

import {defineConfig} from 'jest';

export default defineConfig({
  reporters: ['jest-silent-reporter', 'summary'],
});

Репортёр summary принимает параметры. Поскольку он входит в состав репортёра default, параметры можно передать и ему.

const {defineConfig} = require('jest');

module.exports = defineConfig({
  reporters: [['default', {summaryThreshold: 10}]],
});

import {defineConfig} from 'jest';

export default defineConfig({
  reporters: [['default', {summaryThreshold: 10}]],
});

Параметр summaryThreshold работает следующим образом: если общее количество наборов тестов превышает этот порог, после выполнения всех тестов будет выведена подробная сводка по всем неудачным тестам. Значение по умолчанию — 20.

Пользовательские репортёры

Модуль пользовательского репортёра должен экспортировать класс, который принимает globalConfig, reporterOptions и reporterContext в качестве аргументов конструктора:

class CustomReporter {
  constructor(globalConfig, reporterOptions, reporterContext) {
    this._globalConfig = globalConfig;
    this._options = reporterOptions;
    this._context = reporterContext;
  }

  onRunComplete(testContexts, results) {
    console.log('Custom reporter output:');
    console.log('global config:', this._globalConfig);
    console.log('options for this reporter from Jest config:', this._options);
    console.log('reporter context passed from test scheduler:', this._context);
  }

  // Optionally, reporters can force Jest to exit with non zero code by returning
  // an `Error` from `getLastError()` method.
  getLastError() {
    if (this._shouldFail) {
      return new Error('Custom error reported!');
    }
  }
}

module.exports = CustomReporter;

resetMocks [boolean]

По умолчанию: false

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

resetModules [boolean]

По умолчанию: false

По умолчанию каждый файл тестов получает собственный независимый реестр модулей. Включение resetModules идёт ещё дальше и сбрасывает реестр модулей перед запуском каждого отдельного теста. Это полезно для изоляции модулей в каждом тесте, чтобы локальное состояние модулей не конфликтовало между тестами. То же самое можно сделать программно с помощью jest.resetModules().

resolver [string]

По умолчанию: undefined

Этот параметр позволяет использовать пользовательский резолвер. Резолвер должен быть модулем, который экспортирует либо:

1. функцию, принимающую строку в качестве первого аргумента (путь для разрешения) и объект параметров в качестве второго аргумента. Функция должна возвращать путь к разрешаемому модулю или выбрасывать ошибку, если модуль не найден. либо
2. объект, содержащий свойства async и/или sync. Свойство sync должно быть функцией описанной выше формы, а свойство async также должно быть функцией, принимающей те же аргументы, но возвращающей промис, который разрешается путём к модулю или отклоняется с ошибкой.

Резолвер можно написать как в формате CommonJS, так и в формате ES-модуля, в том числе с использованием await на верхнем уровне. ES-модуль может экспортировать функцию или объект sync/async как экспорт default либо предоставлять sync и async в качестве именованных экспортов.

Объект параметров, передаваемый резолверам, имеет следующую структуру:

type ResolverOptions = {
  /** Directory to begin resolving from. */
  basedir: string;
  /** List of export conditions. */
  conditions?: Array<string>;
  /** Instance of default resolver. */
  defaultResolver: (path: string, options: ResolverOptions) => string;
  /** List of file extensions to search in order. */
  extensions?: Array<string>;
  /** List of directory names to be looked up for modules recursively. */
  moduleDirectory?: Array<string>;
  /** List of `require.paths` to use if nothing is found in `node_modules`. */
  paths?: Array<string>;
  /** Current root directory. */
  rootDir?: string;
};

Например, если вы хотите учитывать поле "browser" Browserify, можно использовать следующий резолвер:

const browserResolve = require('browser-resolve');

module.exports = browserResolve.sync;

И добавьте его в конфигурацию Jest:

const {defineConfig} = require('jest');

module.exports = defineConfig({
  resolver: '<rootDir>/resolver.js',
});

import {defineConfig} from 'jest';

export default defineConfig({
  resolver: '<rootDir>/resolver.js',
});

jest-resolve в Jest опирается на unrs-resolver. Мы можем передавать дополнительные параметры, например изменять mainFields для разрешения модулей. Например, для проектов React Native можно использовать такую конфигурацию:

module.exports = (path, options) => {
  // Call the defaultResolver, so we leverage its cache, error handling, etc.
  return options.defaultResolver(path, {
    ...options,
    // `unrs-resolver` option: https://github.com/unrs/unrs-resolver#main-field
    mainFields: ['react-native', 'main'],
  });
};

Также можно использовать defaultResolver, чтобы реализовать «предварительный обработчик», позволяющий изменить способ, которым стандартный резолвер разрешает модули. Предположим, например, что проект TypeScript должен обращаться к файлам .js во время выполнения, но запускает Jest для файлов .ts.

module.exports = (path, options) => {
  // Dynamic imports within our codebase that reference .js need to reference
  // .ts during tests.
  if (
    !options.basedir.includes('node_modules') &&
    path.endsWith('.js') &&
    (path.startsWith('../') || path.startsWith('./'))
  ) {
    path = path.replace(/\.js$/, '.ts');
  }

  // Call the defaultResolver, so we leverage its cache, error handling, etc.
  return options.defaultResolver(path, options);
};

restoreMocks [boolean]

По умолчанию: false

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

rootDir [string]

По умолчанию: корень каталога, содержащего файл конфигурации Jest, или package.json, или pwd, если package.json не найден

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

Часто здесь задают 'src' или 'lib' — в зависимости от того, где в репозитории хранится код.

roots [array<string>]

По умолчанию: ["<rootDir>"]

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

Иногда требуется, чтобы Jest искал файлы только в одном подкаталоге (например, если в репозитории есть каталог src/), и при этом не имел доступа к остальной части репозитория.

runtime [string]

По умолчанию: "jest-runtime"

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

Модуль среды выполнения должен экспортировать класс, расширяющий стандартный класс Jest Runtime, либо реализующий совместимый интерфейс с такой же сигнатурой конструктора и теми же методами.

Пример:

const {default: Runtime} = require('jest-runtime');

class CustomRuntime extends Runtime {
  //...custom logic
}

module.exports = CustomRuntime;

import Runtime from 'jest-runtime';

export default class CustomRuntime extends Runtime {
  //...custom logic
}

Добавьте пользовательскую среду выполнения в конфигурацию Jest:

const {defineConfig} = require('jest');

module.exports = defineConfig({
  runtime: './custom-runtime.js',
});

import {defineConfig} from 'jest';

export default defineConfig({
  runtime: './custom-runtime.ts',
});

runner [string | [string, object]]

По умолчанию: "jest-runner"

Этот параметр позволяет использовать пользовательский исполнитель вместо стандартного исполнителя тестов Jest. Примеры таких исполнителей:

• jest-runner-eslint
• jest-runner-mocha
• jest-runner-tsc
• jest-runner-prettier

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

const {defineConfig} = require('jest');

module.exports = defineConfig({
  runner: ['jest-runner-custom', {myOption: true, timeout: 5000}],
});

import {defineConfig} from 'jest';

export default defineConfig({
  runner: ['jest-runner-custom', {myOption: true, timeout: 5000}],
});

Чтобы написать собственный исполнитель тестов, экспортируйте класс, расширяющий один из базовых исполнителей из jest-runner (CallbackTestRunner или EmittingTestRunner) и реализующий метод runTests. При использовании конфигурации в виде кортежа объект параметров передаётся третьим аргументом конструктора:

const {CallbackTestRunner} = require('jest-runner');

class MyRunner extends CallbackTestRunner {
  constructor(globalConfig, context, options) {
    super(globalConfig, context);
    this._runnerOptions = options;
  }

  async runTests(tests, watcher, onStart, onResult, onFailure, options) {
    // implement test execution using this._runnerOptions
  }
}

module.exports = MyRunner;

import type {Config} from '@jest/types';
import type {
  CallbackTestRunner,
  OnTestFailure,
  OnTestStart,
  OnTestSuccess,
  Test,
  TestRunnerContext,
  TestRunnerOptions,
  TestWatcher,
} from 'jest-runner';

export default class MyRunner extends CallbackTestRunner {
  constructor(
    globalConfig: Config.GlobalConfig,
    context: TestRunnerContext,
    private readonly _runnerOptions?: Record<string, unknown>,
  ) {
    super(globalConfig, context);
  }

  async runTests(
    tests: Array<Test>,
    watcher: TestWatcher,
    onStart: OnTestStart,
    onResult: OnTestSuccess,
    onFailure: OnTestFailure,
    options: TestRunnerOptions,
  ): Promise<void> {
    // implement test execution using this._runnerOptions
  }
}

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

sandboxInjectedGlobals [array<string>]

По умолчанию: undefined

Тестовые файлы выполняются внутри vm, что замедляет вызовы свойств глобального контекста (например, Math). С помощью этого параметра можно указать дополнительные свойства, которые будут определены внутри vm для более быстрого доступа.

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

const {defineConfig} = require('jest');

module.exports = defineConfig({
  sandboxInjectedGlobals: ['Math'],
});

import {defineConfig} from 'jest';

export default defineConfig({
  sandboxInjectedGlobals: ['Math'],
});

setupFiles [array]

По умолчанию: []

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

setupFilesAfterEnv [array]

По умолчанию: []

Список путей к модулям, выполняющим код для настройки тестовой среды перед запуском каждого тестового файла. Поскольку setupFiles выполняется до установки тестовой платформы в среде, этот файл скрипта позволяет запустить код сразу после установки тестовой платформы, но до выполнения самого тестового кода.

Иными словами, модули setupFilesAfterEnv предназначены для кода, повторяющегося в каждом тестовом файле. После установки тестовой платформы в модулях становятся доступны глобальные объекты Jest, объект jest и expect. Например, можно добавить дополнительные матчеры из библиотеки jest-extended или вызвать хуки настройки и очистки:

const matchers = require('jest-extended');
expect.extend(matchers);

afterEach(() => {
  jest.useRealTimers();
});

const {defineConfig} = require('jest');

module.exports = defineConfig({
  setupFilesAfterEnv: ['<rootDir>/setup-jest.js'],
});

import {defineConfig} from 'jest';

export default defineConfig({
  setupFilesAfterEnv: ['<rootDir>/setup-jest.js'],
});

showSeed [boolean]

По умолчанию: false

Эквивалент флага --showSeed, который выводит начальное значение в сводке отчёта о тестировании.

slowTestThreshold [number]

По умолчанию: 5

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

snapshotFormat [object]

По умолчанию: {escapeString: false, printBasicPrototype: false}

Позволяет переопределять отдельные параметры форматирования снапшотов, описанные в файле readme pretty-format, за исключением compareKeys и plugins. Например, при такой конфигурации форматировщик снапшотов не будет выводить префикс для "Object" и "Array":

const {defineConfig} = require('jest');

module.exports = defineConfig({
  snapshotFormat: {
    printBasicPrototype: false,
  },
});

import {defineConfig} from 'jest';

export default defineConfig({
  snapshotFormat: {
    printBasicPrototype: false,
  },
});

test('does not show prototypes for object and array inline', () => {
  const object = {
    array: [{hello: 'Danger'}],
  };
  expect(object).toMatchInlineSnapshot(`
    {
      "array": [
        {
          "hello": "Danger",
        },
      ],
    }
  `);
});

snapshotResolver [string]

По умолчанию: undefined

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

module.exports = {
  // resolves from test to snapshot path
  resolveSnapshotPath: (testPath, snapshotExtension) =>
    testPath.replace('__tests__', '__snapshots__') + snapshotExtension,

  // resolves from snapshot to test path
  resolveTestPath: (snapshotFilePath, snapshotExtension) =>
    snapshotFilePath
      .replace('__snapshots__', '__tests__')
      .slice(0, -snapshotExtension.length),

  // Example test path, used for preflight consistency check of the implementation above
  testPathForConsistencyCheck: 'some/__tests__/example.test.js',
};

snapshotSerializers [array<string>]

По умолчанию: []

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

В Jest есть сериализаторы по умолчанию для встроенных типов JavaScript, элементов HTML (Jest 20.0.0+), ImmutableJS (Jest 20.0.0+) и элементов React. Подробнее см. в руководстве по тестированию снапшотов.

module.exports = {
  serialize(val, config, indentation, depth, refs, printer) {
    return `Pretty foo: ${printer(val.foo, config, indentation, depth, refs)}`;
  },

  test(val) {
    return val && Object.prototype.hasOwnProperty.call(val, 'foo');
  },
};

import type {Plugin} from 'pretty-format';

const plugin: Plugin = {
  serialize(val, config, indentation, depth, refs, printer): string {
    return `Pretty foo: ${printer(val.foo, config, indentation, depth, refs)}`;
  },

  test(val): boolean {
    return val && Object.prototype.hasOwnProperty.call(val, 'foo');
  },
};

export default plugin;

printer — это функция, которая сериализует значение с помощью существующих плагинов.

Добавьте custom-serializer в конфигурацию Jest:

const {defineConfig} = require('jest');

module.exports = defineConfig({
  snapshotSerializers: ['path/to/custom-serializer.js'],
});

import {defineConfig} from 'jest';

export default defineConfig({
  snapshotSerializers: ['path/to/custom-serializer.ts'],
});

В итоге тесты будут выглядеть так:

test(() => {
  const bar = {
    foo: {
      x: 1,
      y: 2,
    },
  };

  expect(bar).toMatchSnapshot();
});

Созданный снапшот:

Pretty foo: Object {
  "x": 1,
  "y": 2,
}

testEnvironment [node | jsdom | string]

По умолчанию: node

Тестовая среда, которая будет использоваться для тестирования. В Jest по умолчанию используется среда Node.js. Если вы разрабатываете веб-приложение, вместо неё можно использовать среду, имитирующую браузер, с помощью jsdom.

Добавив в начало файла блок комментария @jest-environment, можно указать другую среду, которая будет использоваться для всех тестов в этом файле:

• Со встроенными средами:

/**
 * @jest-environment jsdom
 */

test('use jsdom in this test file', () => {
  const element = document.createElement('div');
  expect(element).not.toBeNull();
});

/**
 * @jest-environment jsdom
 */

test('use jsdom in this test file', () => {
  const element = document.createElement('div');
  expect(element).not.toBeNull();
});

• С пользовательской средой:

/**
 * @jest-environment ./my-custom-environment.js
 */

test('use jsdom in this test file', () => {
  const element = document.createElement('div');
  expect(element).not.toBeNull();
});

/**
 * @jest-environment ./my-custom-environment.ts
 */

test('use jsdom in this test file', () => {
  const element = document.createElement('div');
  expect(element).not.toBeNull();
});

Также можно определить собственную среду. Если используется не встроенная среда, Jest попытается загрузить либо файл по указанному пути, либо пакет, имя которого задано в testEnvironment. Этот файл или пакет должен экспортировать объект следующей структуры: JestEnvironment:

/**
 * @implements {import('@jest/environment').JestEnvironment}
 */
class CustomEnvironment {
  constructor(config, context) {
    const {projectConfig} = config;
    // Implement the constructor
  }

  // Example of a method
  getVmContext() {
    return null;
  }
  // Implement the required methods here
}

module.exports = CustomEnvironment;

import type {
  EnvironmentContext,
  JestEnvironment,
  JestEnvironmentConfig,
} from '@jest/environment';

export default class CustomEnvironment implements JestEnvironment {
  constructor(config: JestEnvironmentConfig, context: EnvironmentContext) {
    const {projectConfig} = config;
    // Implement the constructor
  }

  // Example of a method
  getVmContext() {
    return null;
  }
  // Implement the required methods here
}

Кроме того, Jest предоставляет builtinEnvironments через пакеты jest-environment-node и jest-environment-jsdom, если вы хотите просто расширить их. Подробнее о расширении сред читайте в нашем руководстве.

testEnvironmentOptions [Object]

По умолчанию: {}

Параметры тестовой среды, которые будут переданы в testEnvironment. Набор параметров зависит от используемой среды.

Параметры среды Node

При использовании среды node можно настроить различные параметры, передаваемые в runInContext. К ним относятся:

• globalsCleanup ('on' | 'soft' | 'off'): управляет очисткой глобальных переменных между файлами тестов. По умолчанию: 'soft'. См. раздел Очистка глобальных переменных ниже.
• Все параметры, перечисленные в документации vm.runInContext

Очистка глобальных переменных

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

Параметр globalsCleanup управляет удалением:

• 'on': свойства удаляются. Код, который обращается к такому свойству после завершения файла тестов, получает undefined.
• 'soft' (по умолчанию): свойства сохраняются, но чтение или запись любого из них вызывает предупреждение об устаревании JEST-01. Ничего не ломается, поэтому это позволяет постепенно перейти к 'on'.
• 'off': очистка не выполняется и предупреждения не выводятся.

Если вы видите предупреждение JEST-01, значит, какой-то код сохраняет ссылку на глобальную переменную после завершения создавшего её файла тестов. Освободите эту ссылку или отключите очистку:

const {defineConfig} = require('jest');

module.exports = defineConfig({
  testEnvironment: 'node',
  testEnvironmentOptions: {
    globalsCleanup: 'off',
  },
});

Режим устанавливается один раз для каждого рабочего процесса — при создании в нём первой тестовой среды. Поэтому блок комментария @jest-environment-options для отдельного файла действует, только если этот файл является первым, который запускает рабочий процесс.

Параметры среды JSDOM

При использовании среды jsdom можно настроить различные параметры, передаваемые в jsdom. К ним относятся:

• url — URL страницы (влияет на window.location и относительные URL). По умолчанию: "http://localhost"
• userAgent — строка user agent. По умолчанию: стандартная строка user agent
• Все параметры, перечисленные в документации jsdom

Например, можно переопределить параметры, передаваемые в jsdom:

const {defineConfig} = require('jest');

module.exports = defineConfig({
  testEnvironment: 'jsdom',
  testEnvironmentOptions: {
    html: '<html lang="en-US"></html>',
    url: 'https://jestjs.io/',
    userAgent: 'Agent/007',
  },
});

import {defineConfig} from 'jest';

export default defineConfig({
  testEnvironment: 'jsdom',
  testEnvironmentOptions: {
    html: '<html lang="en-US"></html>',
    url: 'https://jestjs.io/',
    userAgent: 'Agent/007',
  },
});

Пользовательские условия экспорта

Параметры testEnvironmentOptions позволяют задавать customExportConditions, которые определяют, какие версии библиотеки загружаются из exports в package.json.

Для встроенных сред по умолчанию заданы следующие значения:

• Для jest-environment-jsdom значением по умолчанию является ['browser']
• Для jest-environment-node значением по умолчанию является ['node', 'node-addons']

Например, можно переопределить customExportConditions, передаваемые в jsdom:

const {defineConfig} = require('jest');

module.exports = defineConfig({
  testEnvironment: 'jsdom',
  testEnvironmentOptions: {
    customExportConditions: ['react-native'],
  },
});

import {defineConfig} from 'jest';

export default defineConfig({
  testEnvironment: 'jsdom',
  testEnvironmentOptions: {
    customExportConditions: ['react-native'],
  },
});

Эти параметры также можно передать в блоке комментария, как и testEnvironment. Строка с параметрами должна иметь формат, разбираемый с помощью JSON.parse:

/**
 * @jest-environment jsdom
 * @jest-environment-options {"url": "https://jestjs.io/"}
 */

test('use jsdom and set the URL in this test file', () => {
  expect(window.location.href).toBe('https://jestjs.io/');
});

Можно объединить несколько параметров:

/**
 * @jest-environment jsdom
 * @jest-environment-options {"url": "https://example.com/", "userAgent": "Custom Agent"}
 */

test('use custom URL and user agent', () => {
  expect(window.location.href).toBe('https://example.com/');
  expect(window.navigator.userAgent).toContain('Custom Agent');
});

testFailureExitCode [number]

По умолчанию: 1

Код завершения, который Jest возвращает при неудачном прохождении теста.

testMatch [array<string>]

(по умолчанию: [ "**/__tests__/**/*.?([mc])[jt]s?(x)", "**/?(*.)+(spec|test).?([mc])[jt]s?(x)" ])

Шаблоны glob, которые Jest использует для поиска файлов тестов. По умолчанию он ищет файлы .js, .jsx, .ts и .tsx в папках __tests__, а также файлы с суффиксами .test или .spec (например, Component.test.js или Component.spec.js). Также будут найдены файлы с именами test.js или spec.js.

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

См. также testRegex [string | array<string>], но обратите внимание, что нельзя указать оба параметра.

testPathIgnorePatterns [array<string>]

По умолчанию: ["/node_modules/"]

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

Эти строки шаблонов проверяются на соответствие полному пути. Используйте строковый токен <rootDir>, чтобы включить путь к корневому каталогу проекта и не допустить случайного игнорирования всех файлов в разных средах, где корневые каталоги могут различаться. Пример: ["<rootDir>/build/", "<rootDir>/node_modules/"].

testRegex [string | array<string>]

По умолчанию: (/__tests__/.*|(\\.|/)(test|spec))\\.[mc]?[jt]sx?$

Шаблон или шаблоны, которые Jest использует для обнаружения файлов тестов. По умолчанию он ищет файлы .js, .jsx, .ts и .tsx в каталогах __tests__, а также любые файлы с суффиксом .test или .spec (например, Component.test.js или Component.spec.js). Кроме того, будут найдены файлы с именами test.js или spec.js. См. также testMatch [array<string>], но обратите внимание, что нельзя указать оба параметра.

Ниже показана визуализация регулярного выражения по умолчанию:

├── __tests__
│   └── component.spec.js # test
│   └── anything # test
├── package.json # not test
├── foo.test.js # test
├── bar.spec.jsx # test
└── component.js # not test

testResultsProcessor [string]

По умолчанию: undefined

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

{
  "success": boolean,
  "startTime": epoch,
  "numTotalTestSuites": number,
  "numPassedTestSuites": number,
  "numFailedTestSuites": number,
  "numRuntimeErrorTestSuites": number,
  "numTotalTests": number,
  "numPassedTests": number,
  "numFailedTests": number,
  "numPendingTests": number,
  "numTodoTests": number,
  "openHandles": Array<Error>,
  "testResults": [{
    "numFailingTests": number,
    "numPassingTests": number,
    "numPendingTests": number,
    "testResults": [{
      "title": string (message in it block),
      "status": "failed" | "pending" | "passed",
      "ancestorTitles": [string (message in describe blocks)],
      "failureMessages": [string],
      "numPassingAsserts": number,
      "location": {
        "column": number,
        "line": number
      },
      "duration": number | null,
      "startAt": epoch | null
    },
    ...
    ],
    "perfStats": {
      "end": epoch,
      "loadTestEnvironmentEnd": epoch,
      "loadTestEnvironmentStart": epoch,
      "runtime": number,
      "setupAfterEnvEnd": epoch,
      "setupAfterEnvStart": epoch,
      "setupFilesEnd": epoch,
      "setupFilesStart": epoch,
      "slow": boolean,
      "start": epoch
    },
    "testFilePath": absolute path to test file,
    "coverage": {}
  },
  "testExecError:" (exists if there was a top-level failure) {
    "message": string
    "stack": string
  }
  ...
  ]
}

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

testRunner [string]

По умолчанию: jest-circus/runner

Этот параметр позволяет использовать пользовательский исполнитель тестов. По умолчанию используется jest-circus. Чтобы задать пользовательский исполнитель тестов, укажите путь к его реализации.

Модуль исполнителя тестов должен экспортировать функцию со следующей сигнатурой:

function testRunner(
  globalConfig: GlobalConfig,
  config: ProjectConfig,
  environment: Environment,
  runtime: Runtime,
  testPath: string,
): Promise<TestResult>;

Пример такой функции можно найти в нашем пакете исполнителя тестов по умолчанию jasmine2.

testSequencer [string]

По умолчанию: @jest/test-sequencer

Этот параметр позволяет использовать пользовательский упорядочиватель вместо стандартного упорядочивателя Jest.

Например, можно отсортировать пути к тестам в алфавитном порядке:

const Sequencer = require('@jest/test-sequencer').default;

class CustomSequencer extends Sequencer {
  /**
   * Select tests for shard requested via --shard=shardIndex/shardCount
   * Sharding is applied before sorting
   */
  shard(tests, {shardIndex, shardCount}) {
    const shardSize = Math.ceil(tests.length / shardCount);
    const shardStart = shardSize * (shardIndex - 1);
    const shardEnd = shardSize * shardIndex;

    return [...tests]
      .sort((a, b) => (a.path > b.path ? 1 : -1))
      .slice(shardStart, shardEnd);
  }

  /**
   * Sort test to determine order of execution
   * Sorting is applied after sharding
   */
  sort(tests) {
    // Test structure information
    // https://github.com/jestjs/jest/blob/6b8b1404a1d9254e7d5d90a8934087a9c9899dab/packages/jest-runner/src/types.ts#L17-L21
    const copyTests = [...tests];
    return copyTests.sort((testA, testB) => (testA.path > testB.path ? 1 : -1));
  }
}

module.exports = CustomSequencer;

Добавьте custom-sequencer в конфигурацию Jest:

const {defineConfig} = require('jest');

module.exports = defineConfig({
  testSequencer: 'path/to/custom-sequencer.js',
});

import {defineConfig} from 'jest';

export default defineConfig({
  testSequencer: 'path/to/custom-sequencer.js',
});

testTimeout [number]

По умолчанию: 5000

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

transform [object<string, pathToTransformer | [pathToTransformer, object]>]

По умолчанию: {"\\.[jt]sx?$": "babel-jest"}

Сопоставление регулярных выражений с путями к трансформерам. В качестве второго аргумента можно дополнительно передать кортеж с параметрами конфигурации: {filePattern: ['path-to-transformer', {options}]}. Например, вот как можно настроить babel-jest для нестандартного поведения: {'\\.js$': ['babel-jest', {rootMode: 'upward'}]}.

Jest запускает код вашего проекта как JavaScript, поэтому трансформер необходим, если вы используете синтаксис, который Node не поддерживает из коробки (например, JSX, TypeScript, шаблоны Vue). По умолчанию Jest использует трансформер babel-jest, который загружает конфигурацию Babel вашего проекта и преобразует все файлы, соответствующие регулярному выражению /\.[jt]sx?$/ (иначе говоря, любые файлы .js, .jsx, .ts или .tsx). Кроме того, babel-jest внедряет плагин Babel, необходимый для подъёма объявлений моков, о котором говорится в разделе Мокирование ES-модулей.

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

const {defineConfig} = require('jest');

module.exports = defineConfig({
  transform: {
    '\\.[jt]sx?$': 'babel-jest',
    '\\.css$': 'some-css-transformer',
  },
});

import {defineConfig} from 'jest';

export default defineConfig({
  transform: {
    '\\.[jt]sx?$': 'babel-jest',
    '\\.css$': 'some-css-transformer',
  },
});

transformIgnorePatterns [array<string>]

По умолчанию: ["/node_modules/", "\\.pnp\\.[^\\\/]+$"]

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

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

const {defineConfig} = require('jest');

module.exports = defineConfig({
  transformIgnorePatterns: ['/node_modules/(?!(foo|bar)/)', '/bar/'],
});

import {defineConfig} from 'jest';

export default defineConfig({
  transformIgnorePatterns: ['/node_modules/(?!(foo|bar)/)', '/bar/'],
});

Первый шаблон будет соответствовать файлам внутри /node_modules (и, следовательно, не преобразовывать их), кроме файлов в /node_modules/foo/ и /node_modules/bar/. Второй шаблон будет соответствовать файлам в любом пути, содержащем /bar/ (и, следовательно, не преобразовывать их). В результате применения обоих шаблонов файлы в /node_modules/bar/ не будут преобразованы, поскольку они соответствуют второму шаблону, несмотря на то, что исключены первым.

Иногда (особенно в проектах React Native или TypeScript) сторонние модули публикуются без транспиляции. Поскольку по умолчанию файлы в node_modules не преобразуются, Jest не сможет обработать код в этих модулях, что приведёт к синтаксическим ошибкам. Чтобы решить эту проблему, можно использовать transformIgnorePatterns и разрешить транспиляцию таких модулей. Хороший пример этого случая приведён в руководстве по React Native.

Эти строки шаблонов проверяются на соответствие полному пути. Используйте строковый токен <rootDir>, чтобы включить путь к корневому каталогу проекта и не допустить случайного игнорирования всех файлов в разных средах, где корневые каталоги могут различаться.

const {defineConfig} = require('jest');

module.exports = defineConfig({
  transformIgnorePatterns: [
    '<rootDir>/bower_components/',
    '<rootDir>/node_modules/',
  ],
});

import {defineConfig} from 'jest';

export default defineConfig({
  transformIgnorePatterns: [
    '<rootDir>/bower_components/',
    '<rootDir>/node_modules/',
  ],
});

const {defineConfig} = require('jest');

module.exports = defineConfig({
  transformIgnorePatterns: [
    '<rootDir>/node_modules/.pnpm/(?!(package-a|@scope\\+pkg-b)@)',
    /* if config file is under '~/packages/lib-a/' */
    `${path.join(
      __dirname,
      '../..',
    )}/node_modules/.pnpm/(?!(package-a|@scope\\+pkg-b)@)`,
    /* or using relative pattern to match the second 'node_modules/' in 'node_modules/.pnpm/@scope+pkg-b@x.x.x/node_modules/@scope/pkg-b/' */
    'node_modules/(?!.pnpm|package-a|@scope/pkg-b)',
  ],
});

import {defineConfig} from 'jest';

export default defineConfig({
  transformIgnorePatterns: [
    '<rootDir>/node_modules/.pnpm/(?!(package-a|@scope\\+pkg-b)@)',
    /* if config file is under '~/packages/lib-a/' */
    `${path.join(
      __dirname,
      '../..',
    )}/node_modules/.pnpm/(?!(package-a|@scope\\+pkg-b)@)`,
    /* or using relative pattern to match the second 'node_modules/' in 'node_modules/.pnpm/@scope+pkg-b@x.x.x/node_modules/@scope/pkg-b/' */
    'node_modules/(?!.pnpm|package-a|@scope/pkg-b)',
  ],
});

unmockedModulePathPatterns [array<string>]

По умолчанию: []

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

Это полезно для некоторых часто используемых «вспомогательных» модулей, которые почти всегда применяются как детали реализации (например, underscore, lodash и т. д.). Как правило, рекомендуется по возможности сократить этот список и всегда явно вызывать jest.mock()/jest.unmock() в отдельных тестах. Явная настройка для каждого теста значительно упрощает другим читателям понимание того, в какой среде будет выполняться тест.

Это значение можно переопределить в отдельных тестах, явно вызвав jest.mock() в начале файла теста.

verbose [boolean]

По умолчанию: false или true, если запускается только один файл теста

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

waitForUnhandledRejections [boolean]

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

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

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

watchPathIgnorePatterns [array<string>]

По умолчанию: []

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

Эти шаблоны сопоставляются с полным путём. Используйте строковый токен <rootDir>, чтобы добавить путь к корневому каталогу проекта и не допустить случайного игнорирования всех файлов в средах с другими корневыми каталогами. Пример: ["<rootDir>/node_modules/"].

Даже если здесь ничего не указано, наблюдатель будет игнорировать изменения в каталогах систем контроля версий (.git, .hg, .sl). По умолчанию отслеживаются другие скрытые файлы и каталоги, то есть те, имена которых начинаются с точки (.). Не забудьте экранировать точку при добавлении таких файлов в watchPathIgnorePatterns, поскольку она является специальным символом RegExp.

const {defineConfig} = require('jest');

module.exports = defineConfig({
  watchPathIgnorePatterns: ['<rootDir>/\\.tmp/', '<rootDir>/bar/'],
});

import {defineConfig} from 'jest';

export default defineConfig({
  watchPathIgnorePatterns: ['<rootDir>/\\.tmp/', '<rootDir>/bar/'],
});

watchPlugins [array<string | [string, Object]>]

По умолчанию: []

Этот параметр позволяет использовать пользовательские плагины наблюдения. Подробнее о плагинах наблюдения читайте здесь.

Примеры плагинов наблюдения:

• jest-watch-master
• jest-watch-select-projects
• jest-watch-suspend
• jest-watch-typeahead
• jest-watch-yarn-workspaces

watchman [boolean]

По умолчанию: true

Использовать ли watchman для обхода файлов.

workerGracefulExitTimeout [number]

По умолчанию: 500

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

Увеличьте это значение, если вашей тестовой среде требуется больше времени на завершение работы (например, при использовании --detectOpenHandles или если рабочие процессы удерживают ресурсы в течение длительного времени).

const {defineConfig} = require('jest');

module.exports = defineConfig({
  workerGracefulExitTimeout: 2000,
});

import {defineConfig} from 'jest';

export default defineConfig({
  workerGracefulExitTimeout: 2000,
});

workerIdleMemoryLimit [number|string]

По умолчанию: undefined

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

После выполнения теста проверяется использование памяти рабочим процессом. Если оно превышает указанное значение, процесс завершается и запускается заново. Ограничение можно задать несколькими способами; полученное значение преобразуется в целое число с помощью Math.floor:

• <= 1 — предполагается, что значение задано в процентах от системной памяти. Так, значение 0.5 задаёт для рабочего процесса ограничение памяти, равное половине объёма системной памяти
• \> 1 — предполагается, что значение задано в байтах. Согласно предыдущему правилу, если вам по какой-то причине нужно задать значение в 1 байт, используйте 1.1.
• С единицами измерения
  • 50% — как и выше, процент от общего объёма системной памяти
  • 100KB, 65MB и т. д. — единицы измерения для указания фиксированного ограничения памяти.
    • K / KB — килобайты (x1000)
    • KiB — кибибайты (x1024)
    • M / MB — мегабайты
    • MiB — мебибайты
    • G / GB — гигабайты
    • GiB — гибибайты

const {defineConfig} = require('jest');

module.exports = defineConfig({
  workerIdleMemoryLimit: 0.2,
});

import {defineConfig} from 'jest';

export default defineConfig({
  workerIdleMemoryLimit: 0.2,
});

// [string]

Этот параметр разрешает комментарии в package.json. Укажите текст комментария в качестве значения этого ключа:

{
  "name": "my-project",
  "jest": {
    "//": "Comment goes here",
    "verbose": true
  }
}

workerThreads

По умолчанию: false

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

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