Configuring Jest
Jest's configuration can be defined in the package.json
file of your project, through a jest.config.js
file or through the --config <path/to/js|json>
option. Если вы предпочитаете использовать файл package.json
для хранения конфигурации Jest, то необходимо использовать ключ "jest" на верхнем уровне, чтобы Jest смог отыскать необходимые настройки:
{ "name": "my-project", "jest": { "verbose": true } }
Или с помощью JavaScript:
// jest.config.js module.exports = { verbose: true, };
Пожалуйста, имейте в виду, что полученная конфигурация должна быть JSON-сериализируемой.
При использовании флага --config, JSON файл с конфигурацией не должен содержать ключа "jest":
{ "bail": true, "verbose": true }
Параметры #
Следующие параметры позволяют разработчику контролировать поведение Jest при указании в package.json
. Философия Jest заключается в том, чтобы идеально функционировать по умолчанию, но время от времени разработчику может понадобиться больше возможностей для конфигурации.
Справка #
automock
[boolean] #
Значение по умолчанию: false
Данная опция отключена по умолчанию. Если вы применяете Jest в большой организации с существующей базой кода, но небольшим количеством тестов, то указание данной опции может помочь ввести тесты постепенно. К модулям может быть применен автоматический мокинг при использовании jest.mock(имяМодуля)
.
Заметка: К модулям ядра, таким как fs
, мокинг по умолчанию не применяется, но если требуется, то к ним можно явно применить мокинг, к примеру так jest.mock('fs')
.
Заметка: Автоматический мокинг может влиять на производительность в больших проектах. Смотрите подробности о деталях и обходном пути.
browser
[boolean] #
Значение по умолчанию: false
Учитывать Browserify "browser"
поле в package.json
при разрешении модулей. Некоторые модули экспортируют различные версии основываясь на том оперируют ли он в Node или в браузере.
bail
[boolean] #
Значение по умолчанию: false
По умолчанию Jest запускает все тесты и отображает все возникшие ошибки в консоли при завершении. Опция bail может быть использована, чтобы указать Jest на необходимость отменить запуск последующих тестов при возникновении первой ошибки.
cacheDirectory
[string] #
По умолчанию: «/tmp/<путь>»
Директория, в которой Jest следует хранить кэшированные сведения о зависимостях.
Jest предпринимает попытку единожды просканировать дерево зависимостей (предварительно) и сохранить кэш с данными о них, чтобы облегчить проход файловой системы, который происходит при запуске тестов. Данная опция позволяет разработчику указать где именно в файловой системе следует хранить кэшированные данные.
collectCoverage
[boolean] #
Значение по умолчанию: false
Указывает следует ли собирать информацию о тестовом покрытии при выполнении тестов. Из-за того, что данный процесс вносит информацию о покрытии во все выполненные файлы, ваши тесты могут быть существенно замедлены.
collectCoverageFrom
[array] #
Значение по умолчанию: undefined
Массив glob patterns, который указывает, для каких файлов необходимо собирать информацию о покрытии. Если файл соответсвует шаблону указанному в массиве, то информация о покрытии будет собираться для него, даже если тестов для этого файла не существует и сам он не встречается в наборе тестов.
Пример:
{ "collectCoverageFrom" : ["**/*.{js,jsx}", "!**/node_modules/**", "!**/vendor/**"] }
В этом примере, информация о покрытии будет собираться для всех файлов внутри проекта rootDir
, за исключением тех, которые соответствуют **/node_modules/**
или **/vendor/**
.
Примечание: Для работы этой опции требуется установить опцию collectCoverage
в значение true или запустить Jest с ключом --coverage
.
coverageDirectory
[string] #
Значение по умолчанию: undefined
Каталог, куда Jest будет сохранять файлы с информацией о покрытии.
coveragePathIgnorePatterns
[array<string>] #
Значение по умолчанию: ["/node_modules/"]
Массив строк регулярный выражений, по которым проверяется соответствие путей файлов перед выполнением тестов. Если путь к файлу соответствует какому-либо шаблону, то информация о покрытии этого файла собираться не будет.
Эти строки шаблонов проверяют на соответствие полный путь. Используйте маркер <rootDir>
в путях к корневой директории вашего проекта для предотвращения случайного игнорирования всех ваших файлов в различных окружениях, которые могут иметь другую корневую директорию. Пример: [«<rootDir>/build/», «<rootDir>/node_modules/»]
.
coverageReporters
[array<string>] #
Значение по умолчанию: ["json", "lcov", "text"]
Список названий форматов отчета, которые Jest использует для написания отчетов о покрытии. Может использоваться любой формат из istanbul reporter.
Примечание: Этот параметр перезаписывает значения по умолчанию. Добавьте "text"
или "text-summary"
, чтобы увидеть в консоли краткое содержание о покрытии.
coverageThreshold
[object] #
Значение по умолчанию: undefined
Эта опция используется для настройки минимального значения порога для результатов покрытия. Если пороговые значения не будут выполнены, то Jest будет возвращать ошибку. Пороговые значения, которые указаны как положительное число, считаются минимальным процентом. Отрицательные пороговые значения говорят о максимальном допустимом количестве непокрытых объектов.
Например: при значении 90, подразумевается, что минимальная сумма покрытия составляет 90%. При значении -10, подразумевается, что разрешено не более 10 непокрытых сущностей.
{ ... "jest": { "coverageThreshold": { "global": { "branches": 50, "functions": 50, "lines": 50, "statements": 50 } } } }
globals
[object] #
Значение по умолчанию: {}
Набор глобальных переменных, которые необходимы во всех тестовых средах.
Например, следующий код инициализирует глобальную переменную __DEV__
в true
во всех тестовых средах:
{ ... "jest": { "globals": { "__DEV__": true } } }
Обратите внимание, что, если значение глобальной переменной будет ссылочным типом (к примеру объект или массив), и где-то в коде это значение будет изменяться в момент, когда тесты запущены, то данные изменения не будут сохранены в тестовых прогонах для других тестовых файлов.
mapCoverage
[boolean] #
доступно в версиях Jest 20.0.0+ #
Значение по умолчанию: false
Если у вас есть настроенные конвертеры, которые выдают source maps, то Jest будет пробовать сопоставить их покрытие с оригинальным исходным кодом при составлении отчетов и проверки порогов. Это будет сделано наилучшим образом, поскольку некоторые компилируемые в JavaScript языки могут предоставить более точные source maps, чем другие. Данный процесс может быть ресурсоемким. Если Jest занимает много времени для расчета покрытия в конце выполнения теста, то попробуйте установить этот параметр в значение false
.
Поддерживаются, как встроенные source maps, так и те, которые непосредственно вернул конвертер. Source map по URL адресу не поддерживается, так как Jest не сможет получить их расположение. Чтобы вернуть source maps из конвертера, process
функция может возвращать объект следующего формата. Свойство map
может быть объектом source map или source map в формате JSON строки.
return { code: 'the code', map: 'the source map', };
moduleFileExtensions
[array<string>] #
Значение по умолчанию: ["js", "json", "jsx", "node"]
Массив расширений файлов используемых модулей. Если вы импортируете модули без расширения файла, то указанные расширения будут использоваться Jest для поиска.
Если вы используете TypeScript, то значение этой опции должно быть таким: ["js", "jsx", "json", "ts", "tsx"]
moduleDirectories
[array<string>] #
Значение по умолчанию: ["node_modules"]
Массив имен каталогов для рекурсивного поиска местоположения импортируемых модулей. Установка этого параметра будет переопределять значение по умолчанию. Если вы по-прежнему хотите искать модули в других каталогах наряду с каталогом node_modules
, то значение должно быть таким: ["node_modules", "bower_components"]
moduleNameMapper
[object<string, string>] #
Значение по умолчанию: null
A map from regular expressions to module names that allow to stub out resources, like images or styles with a single module.
Modules that are mapped to an alias are unmocked by default, regardless of whether automocking is enabled or not.
Use <rootDir>
string token to refer to rootDir
value if you want to use file paths.
Additionally, you can substitute captured regex groups using numbered backreferences.
Пример:
{ "moduleNameMapper": { "^image![a-zA-Z0-9$_-]+$": "GlobalImageStub", "^[./a-zA-Z0-9$_-]+\.png$": "<rootDir>/RelativeImageStub.js", "module_name_(.*)": "<rootDir>/substituted_module_$1.js" } }
Note: If you provide module name without boundaries ^$
it may cause hard to spot errors. E.g. relay
will replace all modules which contain relay
as a substring in its name: relay
, react-relay
and graphql-relay
will all be pointed to your stub.
modulePathIgnorePatterns
[array<string>] #
Значение по умолчанию: []
An array of regexp pattern strings that are matched against all module paths before those paths are to be considered 'visible' to the module loader. If a given module's path matches any of the patterns, it will not be require()
-able in the test environment.
Эти строки шаблонов проверяют на соответствие полный путь. Используйте маркер <rootDir>
в путях к корневой директории вашего проекта для предотвращения случайного игнорирования всех ваших файлов в различных окружениях, которые могут иметь другую корневую директорию. Example: ["<rootDir>/build/"]
.
modulePaths
[array<string>] #
Значение по умолчанию: []
An alternative API to setting the NODE_PATH
env variable, modulePaths
is an array of absolute paths to additional locations to search when resolving modules. Use the <rootDir>
string token to include the path to your project's root directory. Example: ["<rootDir>/app/"]
.
notify
[boolean] #
Значение по умолчанию: false
Активирует уведомления для результатов теста.
preset
[string] #
Значение по умолчанию: undefined
A preset that is used as a base for Jest's configuration. A preset should point to an npm module that exports a jest-preset.json
module on its top level.
projects
[array<string>] #
Значение по умолчанию: undefined
When the projects
configuration is provided with an array of paths or glob patterns, Jest will run tests in all of the specified projects at the same time. This is great for monorepos or when working on multiple projects at the same time.
{ "projects": [ "<rootDir>", "<rootDir>/examples/*" ] }
This example configuration will run Jest in the root directory as well as in every folder in the examples directory. You can have an unlimited amount of projects running in the same Jest instance.
clearMocks
[boolean] #
Значение по умолчанию: false
Automatically clear mock calls and instances between every test. Equivalent to calling jest.clearAllMocks()
between each test. This does not remove any mock implementation that may have been provided.
reporters
[array<modulename | [modulename, options]>] #
Значение по умолчанию: undefined
доступно в версиях Jest 20.0.0+ #
Use this configuration option to add custom reporters to Jest. A custom reporter is a class that implements onRunStart
, onTestStart
, onTestResult
, onRunComplete
methods that will be called when any of those events occurs.
If custom reporters are specified, the default Jest reporters will be overridden. To keep default reporters, default
can be passed as a module name.
This will override default reporters:
{ "reporters": [ "<rootDir>/my-custom-reporter.js" ] }
This will use custom reporter in addition to default reporters that Jest provides:
{ "reporters": [ "default", "<rootDir>/my-custom-reporter.js" ] }
Additionally, custom reporters can be configured by passing an options
object as a second argument:
{ "reporters": [ "default", ["<rootDir>/my-custom-reporter.js", {"banana": "yes", "pineapple": "no"}] ] }
Custom reporter modules must define a class that takes a GlobalConfig
and reporter options as constructor arguments:
Example reporter:
// my-custom-reporter.js class MyCustomReporter { constructor(globalConfig, options) { this._globalConfig = globalConfig; this._options = options; } onRunComplete(contexts, results) { console.log('Custom reporter output:'); console.log('GlobalConfig: ', this._globalConfig); console.log('Options: ', this._options); } } module.exports = MyCustomReporter;
Custom reporters can also force Jest to exit with non-0 code by returning an Error from getLastError()
methods
class MyCustomReporter { // ... getLastError() { if (this._shouldFail) { return new Error('my-custom-reporter.js reported an error'); } } }
For the full list of methods and argument types see Reporter
type in types/TestRunner.js
resetMocks
[boolean] #
Значение по умолчанию: false
Automatically reset mock state between every test. Equivalent to calling jest.resetAllMocks()
between each test. This will lead to any mocks having their fake implementations removed but does not restore their initial implementation.
resetModules
[boolean] #
Значение по умолчанию: false
If enabled, the module registry for every test file will be reset before running each individual test. This is useful to isolate modules for every test so that local module state doesn't conflict between tests. This can be done programmatically using jest.resetModules()
.
resolver
[string] #
Значение по умолчанию: undefined
доступно в версиях Jest 20.0.0+ #
This option allows the use of a custom resolver. This resolver must be a node module that exports a function expecting a string as the first argument for the path to resolve and an object with the following structure as the second argument:
{ "basedir": string, "browser": bool, "extensions": [string], "moduleDirectory": [string], "paths": [string] }
The function should either return a path to the module that should be resolved or throw an error if the module can't be found.
rootDir
[string] #
Default: The root of the directory containing the package.json
or the pwd
if no package.json
is found
The root directory that Jest should scan for tests and modules within. If you put your Jest config inside your package.json
and want the root directory to be the root of your repo, the value for this config param will default to the directory of the package.json
.
Oftentimes, you'll want to set this to 'src'
or 'lib'
, corresponding to where in your repository the code is stored.
Note that using '<rootDir>'
as a string token in any other path-based config settings will refer back to this value. So, for example, if you want your setupFiles
config entry to point at the env-setup.js
file at the root of your project, you could set its value to ["<rootDir>/env-setup.js"]
.
roots
[array<string>] #
Default: ["<rootDir>"]
A list of paths to directories that Jest should use to search for files in.
There are times where you only want Jest to search in a single sub-directory (such as cases where you have a src/
directory in your repo), but prevent it from accessing the rest of the repo.
Note: While rootDir
is mostly used as a token to be re-used in other configuration options, roots
is used by the internals of Jest to locate test files and source files. By default, roots
has a single entry <rootDir>
but there are cases where you want to have multiple roots within one project, for example roots: ["<rootDir>/src/", "<rootDir>/tests/"]
.
setupFiles
[array] #
Значение по умолчанию: []
The paths to modules that run some code to configure or set up the testing environment before each test. Since every test runs in its own environment, these scripts will be executed in the testing environment immediately before executing the test code itself.
It's worth noting that this code will execute before setupTestFrameworkScriptFile
.
setupTestFrameworkScriptFile
[string] #
Значение по умолчанию: undefined
Путь к модулю, который исполняет некоторый код для конфигурирования или установки платформы тестирования перед каждым тестом. Since setupFiles
executes before the test framework is installed in the environment, this script file presents you the opportunity of running some code immediately after the test framework has been installed in the environment.
For example, Jest ships with several plug-ins to jasmine
that work by monkey-patching the jasmine API. If you wanted to add even more jasmine plugins to the mix (or if you wanted some custom, project-wide matchers for example), you could do so in this module.
snapshotSerializers
[array<string>] #
Значение по умолчанию: []
A list of paths to snapshot serializer modules Jest should use for snapshot testing.
Jest has default serializers for built-in JavaScript types, HTML elements (Jest 20.0.0+), ImmutableJS (Jest 20.0.0+) and for React elements. See snapshot test tutorial for more information.
Example serializer module:
// my-serializer-module module.exports = { print(val, serialize, indent) { return 'Pretty foo: ' + serialize(val.foo); }, test(val) { return val && val.hasOwnProperty('foo'); }, };
serialize
is a function that serializes a value using existing plugins.
To use my-serializer-module
as a serializer, configuration would be as follows:
{ ... "jest": { "snapshotSerializers": ["my-serializer-module"] } }
Finally tests would look as follows:
test(() => { const bar = { foo: { x: 1, y: 2, }, }; expect(bar).toMatchSnapshot(); });
Rendered snapshot:
Pretty foo: Object { "x": 1, "y": 2, }
To make a dependency explicit instead of implicit, you can call expect.addSnapshotSerializer
to add a module for an individual test file instead of adding its path to snapshotSerializers
in Jest configuration.
testEnvironment
[string] #
Значение по умолчанию: "jsdom"
The test environment that will be used for testing. The default environment in Jest is a browser-like environment through jsdom. If you are building a node service, you can use the node
option to use a node-like environment instead.
If some tests require another environment, you can add a @jest-environment
docblock.
доступно в версиях Jest 20.0.0+ #
/** * @jest-environment jsdom */ test('use jsdom in this test file', () => { const element = document.createElement('div'); expect(element).not.toBeNull(); });
You can create your own module that will be used for setting up the test environment. The module must export a class with runScript
and dispose
methods. See the node or jsdom environments as examples.
testMatch
[array<string>] #
доступно в версиях Jest 19.0.0+ #
(default: [ '**/__tests__/**/*.js?(x)', '**/?(*.)(spec|test).js?(x)' ]
)
The glob patterns Jest uses to detect test files. By default it looks for .js
and .jsx
files inside of __tests__
folders, as well as any files with a suffix of .test
or .spec
(e.g. Component.test.js
or Component.spec.js
). It will also find files called test.js
or spec.js
.
See the micromatch package for details of the patterns you can specify.
See also testRegex
[string], but note that you cannot specify both options.
testPathIgnorePatterns
[array<string>] #
Значение по умолчанию: ["/node_modules/"]
An array of regexp pattern strings that are matched against all test paths before executing the test. If the test path matches any of the patterns, it will be skipped.
Эти строки шаблонов проверяют на соответствие полный путь. Используйте маркер <rootDir>
в путях к корневой директории вашего проекта для предотвращения случайного игнорирования всех ваших файлов в различных окружениях, которые могут иметь другую корневую директорию. Пример: [«<rootDir>/build/», «<rootDir>/node_modules/»]
.
testRegex
[string] #
Default: (/__tests__/.*|(\\.|/)(test|spec))\\.jsx?$
The pattern Jest uses to detect test files. By default it looks for .js
and .jsx
files inside of __tests__
folders, as well as any files with a suffix of .test
or .spec
(e.g. Component.test.js
or Component.spec.js
). It will also find files called test.js
or spec.js
. See also testMatch
[array<string>], but note that you cannot specify both options.
The following is a visualization of the default regex:
├── __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
This option allows the use of a custom results processor. This processor must be a node module that exports a function expecting an object with the following structure as the first argument:
{ "success": bool, "startTime": epoch, "numTotalTestSuites": number, "numPassedTestSuites": number, "numFailedTestSuites": number, "numRuntimeErrorTestSuites": number, "numTotalTests": number, "numPassedTests": number, "numFailedTests": number, "numPendingTests": number, "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 }, ... ], "perfStats": { "start": epoch, "end": epoch }, "testFilePath": absolute path to test file, "coverage": {} }, ... ] }
testRunner
[string] #
Default: jasmine2
This option allows use of a custom test runner. The default is jasmine2. A custom test runner can be provided by specifying a path to a test runner implementation.
The test runner module must export a function with the following signature:
function testRunner( config: Config, environment: Environment, runtime: Runtime, testPath: string, ): Promise<TestResult>
An example of such function can be found in our default jasmine2 test runner package.
testURL
[string] #
Default: about:blank
This option sets the URL for the jsdom environment. It is reflected in properties such as location.href
.
timers
[string] #
Значение по умолчанию: real
Setting this value to fake
allows the use of fake timers for functions such as setTimeout
. Fake timers are useful when a piece of code sets a long timeout that we don't want to wait for in a test.
transform
[object<string, string>] #
Значение по умолчанию: undefined
A map from regular expressions to paths to transformers. A transformer is a module that provides a synchronous function for transforming source files. For example, if you wanted to be able to use a new language feature in your modules or tests that isn't yet supported by node, you might plug in one of many compilers that compile a future version of JavaScript to a current one. Example: see the examples/typescript example or the webpack tutorial.
Examples of such compilers include babel, typescript, and async-to-gen.
Note: a transformer is only ran once per file unless the file has changed. During development of a transformer it can be useful to run Jest with --no-cache
or to frequently delete Jest's cache.
Note: if you are using the babel-jest
transformer and want to use an additional code preprocessor, keep in mind that when "transform" is overwritten in any way the babel-jest
is not loaded automatically anymore. If you want to use it to compile JavaScript code it has to be explicitly defined. See babel-jest plugin
transformIgnorePatterns
[array<string>] #
Значение по умолчанию: ["/node_modules/"]
An array of regexp pattern strings that are matched against all source file paths before transformation. If the test path matches any of the patterns, it will not be transformed.
Эти строки шаблонов проверяют на соответствие полный путь. Используйте маркер <rootDir>
в путях к корневой директории вашего проекта для предотвращения случайного игнорирования всех ваших файлов в различных окружениях, которые могут иметь другую корневую директорию. Example: ["<rootDir>/bower_components/", "<rootDir>/node_modules/"]
.
unmockedModulePathPatterns
[array<string>] #
Значение по умолчанию: []
An array of regexp pattern strings that are matched against all modules before the module loader will automatically return a mock for them. If a module's path matches any of the patterns in this list, it will not be automatically mocked by the module loader.
This is useful for some commonly used 'utility' modules that are almost always used as implementation details almost all the time (like underscore/lo-dash, etc). It's generally a best practice to keep this list as small as possible and always use explicit jest.mock()
/jest.unmock()
calls in individual tests. Explicit per-test setup is far easier for other readers of the test to reason about the environment the test will run in.
It is possible to override this setting in individual tests by explicitly calling jest.mock()
at the top of the test file.
verbose
[boolean] #
Значение по умолчанию: false
Указывает, следует ли, во время выполнения делать отчет для каждого теста. Все ошибки будут также показаны в конце после выполнения.