| id | title |
|---|---|
configuration |
Configuring Jest |
Jest's configuration can be defined in the package.json file of your project,
or through a jest.config.js file or through the --config <path/to/js|json>
option. If you'd like to use your package.json to store Jest's config, the
"jest" key should be used on the top level so Jest will know how to find your
settings:
{
"name": "my-project",
"jest": {
"verbose": true
}
}Or through JavaScript:
// jest.config.js
module.exports = {
verbose: true,
};Please keep in mind that the resulting configuration must be JSON-serializable.
When using the --config option, the JSON file must not contain a "jest" key:
{
"bail": true,
"verbose": true
}These options let you control Jest's behavior in your package.json file. The
Jest philosophy is to work great by default, but sometimes you just need more
configuration power.
<AUTOGENERATED_TABLE_OF_CONTENTS>
Default: false
This option is disabled by default. If you are introducing Jest to a large
organization with an existing codebase but few tests, enabling this option can
be helpful to introduce unit tests gradually. Modules can be explicitly
auto-mocked using jest.mock(moduleName).
Note: Core modules, like fs, are not mocked by default. They can be mocked
explicitly, like jest.mock('fs').
Note: Automocking has a performance cost most noticeable in large projects. See here for details and a workaround.
Default: false
Respect Browserify's
"browser" field
in package.json when resolving modules. Some modules export different versions
based on whether they are operating in Node or a browser.
Default: false
By default, Jest runs all tests and produces all errors into the console upon completion. The bail config option can be used here to have Jest stop running tests after the first failure.
Default: "/tmp/<path>"
The directory where Jest should store its cached dependency information.
Jest attempts to scan your dependency tree once (up-front) and cache it in order to ease some of the filesystem raking that needs to happen while running tests. This config option lets you customize where Jest stores that cache data on disk.
Default: false
Indicates whether the coverage information should be collected while executing the test. Because this retrofits all executed files with coverage collection statements, it may significantly slow down your tests.
Default: undefined
An array of glob patterns indicating a set of files for which coverage information should be collected. If a file matches the specified glob pattern, coverage information will be collected for it even if no tests exist for this file and it's never required in the test suite.
Example:
{
"collectCoverageFrom": [
"**/*.{js,jsx}",
"!**/node_modules/**",
"!**/vendor/**"
]
}This will collect coverage information for all the files inside the project's
rootDir, except the ones that match **/node_modules/** or **/vendor/**.
Note: This option requires collectCoverage to be set to true or Jest to be
invoked with --coverage.
Default: undefined
The directory where Jest should output its coverage files.
Default: ["/node_modules/"]
An array of regexp pattern strings that are matched against all file paths before executing the test. If the file path matches any of the patterns, coverage information will be skipped.
These pattern strings match against the full path. Use the <rootDir> string
token to include the path to your project's root directory to prevent it from
accidentally ignoring all of your files in different environments that may have
different root directories. Example:
["<rootDir>/build/", "<rootDir>/node_modules/"].
Default: ["json", "lcov", "text"]
A list of reporter names that Jest uses when writing coverage reports. Any istanbul reporter can be used.
Note: Setting this option overwrites the default values. Add "text" or
"text-summary" to see a coverage summary in the console output.
Default: undefined
This will be used to configure minimum threshold enforcement for coverage
results. Thresholds can be specified as global, as a
glob, and as a directory or
file path. If thresholds aren't met, jest will fail. Thresholds specified as a
positive number are taken to be the minimum percentage required. Thresholds
specified as a negative number represent the maximum number of uncovered
entities allowed.
For example, with the following configuration jest will fail if there is less than 80% branch, line, and function coverage, or if there are more than 10 uncovered statements:
{
...
"jest": {
"coverageThreshold": {
"global": {
"branches": 80,
"functions": 80,
"lines": 80,
"statements": -10
}
}
}
}If globs or paths are specified alongside global, coverage data for matching
paths will be subtracted from overall coverage and thresholds will be applied
independently. Thresholds for globs are applied to all files matching the glob.
If the file specified by path is not found, error is returned.
For example, with the following configuration:
{
...
"jest": {
"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 will fail if:
- The
./src/componentsdirectory has less than 40% branch or statement coverage. - One of the files matching the
./src/reducers/**/*.jsglob has less than 90% statement coverage. - The
./src/api/very-important-module.jsfile has less than 100% coverage. - Every remaining file combined has less than 50% coverage (
global).
Default: ['']
Test files are normally ignored from collecting code coverage. With this option, you can overwrite this behavior and include otherwise ignored files in code coverage.
For example, if you have tests in source files named with .t.js extension as
following:
// sum.t.js
export function sum(a, b) {
return a + b;
}
if (process.env.NODE_ENV === 'test') {
test('sum', () => {
expect(sum(1, 2)).toBe(3);
});
}You can collect coverage from those files with setting forceCoverageMatch.
{
...
"jest": {
"forceCoverageMatch": ["**/*.t.js"]
}
}Default: {}
A set of global variables that need to be available in all test environments.
For example, the following would create a global __DEV__ variable set to
true in all test environments:
{
...
"jest": {
"globals": {
"__DEV__": true
}
}
}Note that, if you specify a global reference value (like an object or array)
here, and some code mutates that value in the midst of running a test, that
mutation will not be persisted across test runs for other test files. In
addition the globals object must be json-serializable, so it can't be used to
specify global functions. For that you should use setupFiles.
Default: undefined
This option allows the use of a custom global setup module which exports an async function that is triggered once before all test suites.
Default: undefined
This option allows the use of a custom global teardown module which exports an async function that is triggered once after all test suites.
Default: false
If you have transformers configured that emit
source maps, Jest will use them to try and map code coverage against the
original source code when writing reports and
checking thresholds. This is done on a best-effort
basis as some compile-to-JavaScript languages may provide more accurate source
maps than others. This can also be resource-intensive. If Jest is taking a long
time to calculate coverage at the end of a test run, try setting this option to
false.
Both inline source maps and source maps returned directly from a transformer are
supported. Source map URLs are not supported because Jest may not be able to
locate them. To return source maps from a transformer, the process function
can return an object like the following. The map property may either be the
source map object, or the source map object as a string.
return {
code: 'the code',
map: 'the source map',
};Default: ["js", "json", "jsx", "node"]
An array of file extensions your modules use. If you require modules without specifying a file extension, these are the extensions Jest will look for.
If you are using TypeScript this should be ["js", "jsx", "json", "ts", "tsx"],
check ts-jest's documentation.
Default: ["node_modules"]
An array of directory names to be searched recursively up from the requiring
module's location. Setting this option will override the default, if you wish
to still search node_modules for packages include it along with any other
options: ["node_modules", "bower_components"]
Default: 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.
Example:
{
"moduleNameMapper": {
"^image![a-zA-Z0-9$_-]+$": "GlobalImageStub",
"^[./a-zA-Z0-9$_-]+\\.png$": "<rootDir>/RelativeImageStub.js",
"module_name_(.*)": "<rootDir>/substituted_module_$1.js"
}
}The order in which the mappings are defined matters. Patterns are checked one by one until one fits. The most specific rule should be listed first.
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.
Default: []
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.
These pattern strings match against the full path. Use the <rootDir> string
token to include the path to your project's root directory to prevent it from
accidentally ignoring all of your files in different environments that may have
different root directories. Example: ["<rootDir>/build/"].
Default: []
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/"].
Default: false
Activates notifications for test results.
Default: always
Specifies notification mode. Requires notify: true.
always: always send a notification.failure: send a notification when tests fail.success: send a notification when tests pass.change: send a notification when the status changed.success-change: send a notification when tests pass or once when it fails.failure-success: send a notification when tests fails or once when it passes.
Default: 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.
Default: 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.
The projects feature can also be used to run multiple configurations or multiple runners. For this purpose you can pass an array of configuration objects. For example, to run both tests and ESLint (via jest-runner-eslint) in the same invocation of Jest:
{
"projects": [
{
"displayName": "test"
},
{
"displayName": "lint",
"runner": "jest-runner-eslint",
"testMatch": ["<rootDir>/**/*.js"]
}
]
}Default: 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.
Default: undefined
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
Default: 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.
Default: 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().
Default: undefined
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],
"rootDir": [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.
Default: false
Automatically restore mock state between every test. Equivalent to calling
jest.restoreAllMocks() between each test. This will lead to any mocks having
their fake implementations removed and restores their initial implementation.
Default: The root of the directory containing your jest's config file or
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"].
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. This applies also when searching for manual mocks for
modules from node_modules (__mocks__ will need to live in one of the
roots).
Note: By default, roots has a single entry <rootDir> but there are cases
where you may want to have multiple roots within one project, for example
roots: ["<rootDir>/src/", "<rootDir>/tests/"].
Default: "jest-runner"
This option allows you to use a custom runner instead of Jest's default test runner. Examples of runners include:
To write a test-runner, export a class with which accepts globalConfig in the
constructor, and has a runTests method with the signature:
async runTests(
tests: Array<Test>,
watcher: TestWatcher,
onStart: OnTestStart,
onResult: OnTestSuccess,
onFailure: OnTestFailure,
options: TestRunnerOptions,
): Promise<void>Default: []
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.
Default: undefined
The path to a module that runs some code to configure or set up the testing
framework before each test. 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.
Default: []
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.
Default: "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-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 setup, teardown and
runScript methods. You can also pass variables from this module to your test
suites by assigning them to this.global object – this will make them
available in your test suites as global variables.
Note: TestEnvironment is sandboxed. Each test suite will trigger setup/teardown in their own TestEnvironment.
Example:
// my-custom-environment
const NodeEnvironment = require('jest-environment-node');
class CustomEnvironment extends NodeEnvironment {
constructor(config) {
super(config);
}
async setup() {
await super.setup();
await someSetupTasks();
this.global.someGlobalObject = createGlobalObject();
}
async teardown() {
this.global.someGlobalObject = destroyGlobalObject();
await someTeardownTasks();
await super.teardown();
}
runScript(script) {
return super.runScript(script);
}
}// my-test-suite
let someGlobalObject;
beforeAll(() => {
someGlobalObject = global.someGlobalObject;
});Default: {}
Test environment options that will be passed to the testEnvironment. The
relevant options depend on the environment. For example you can override options
given to jsdom such as
{userAgent: "Agent/007"}.
(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.
Default: ["/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.
These pattern strings match against the full path. Use the <rootDir> string
token to include the path to your project's root directory to prevent it from
accidentally ignoring all of your files in different environments that may have
different root directories. Example:
["<rootDir>/build/", "<rootDir>/node_modules/"].
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], 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 testDefault: 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 and return it:
{
"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,
"location": {
"column": number,
"line": number
}
},
...
],
"perfStats": {
"start": epoch,
"end": epoch
},
"testFilePath": absolute path to test file,
"coverage": {}
},
...
]
}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.
Default: about:blank
This option sets the URL for the jsdom environment. It is reflected in
properties such as location.href.
Default: 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.
Default: 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 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
Default: ["/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.
These pattern strings match against the full path. Use the <rootDir> string
token to include the path to your project's root directory to prevent it from
accidentally ignoring all of your files in different environments that may have
different root directories.
Example: ["<rootDir>/bower_components/", "<rootDir>/node_modules/"].
Sometimes it happens (especially in React Native or TypeScript projects) that
3rd party modules are published as untranspiled. Since all files inside
node_modules are not transformed by default, Jest will not understand the code
in these modules, resulting in syntax errors. To overcome this, you may use
transformIgnorePatterns to whitelist such modules. You'll find a good example
of this use case in
React Native Guide.
Default: []
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.
Default: false
Indicates whether each individual test should be reported during the run. All errors will also still be shown on the bottom after execution.
Default: []
An array of RegExp patterns that are matched against all source file paths before re-running tests in watch mode. If the file path matches any of the patterns, when it is updated, it will not trigger a re-run of tests.
These patterns match against the full path. Use the <rootDir> string token to
include the path to your project's root directory to prevent it from
accidentally ignoring all of your files in different environments that may have
different root directories. Example: ["<rootDir>/node_modules/"].