diff --git a/docs/Configuration.md b/docs/Configuration.md index 038a2917e832..7f9fa35a1b43 100644 --- a/docs/Configuration.md +++ b/docs/Configuration.md @@ -124,9 +124,13 @@ test('if utils mocked automatically', () => { }); ``` -_Note: Node modules are automatically mocked when you have a manual mock in place (e.g.: `__mocks__/lodash.js`). More info [here](manual-mocks#mocking-node-modules)._ +:::note + +Node modules are automatically mocked when you have a manual mock in place (e.g.: `__mocks__/lodash.js`). More info [here](ManualMocks.md#mocking-node-modules). -_Note: Core modules, like `fs`, are not mocked by default. They can be mocked explicitly, like `jest.mock('fs')`._ +Node.js core modules, like `fs`, are not mocked by default. They can be mocked explicitly, like `jest.mock('fs')`. + +::: ### `bail` \[number | boolean] @@ -174,9 +178,17 @@ Example: This will collect coverage information for all the files inside the project's `rootDir`, except the ones that match `**/node_modules/**` or `**/vendor/**`. -_Note: Each glob pattern is applied in the order they are specified in the config. (For example `["!**/__tests__/**", "**/*.js"]` will not exclude `__tests__` because the negation is overwritten with the second pattern. In order to make the negated glob work in this example it has to come after `**/*.js`.)_ +:::tip + +Each glob pattern is applied in the order they are specified in the config. For example `["!**/__tests__/**", "**/*.js"]` will not exclude `__tests__` because the negation is overwritten with the second pattern. In order to make the negated glob work in this example it has to come after `**/*.js`. + +::: + +:::note + +This option requires `collectCoverage` to be set to `true` or Jest to be invoked with `--coverage`. -_Note: This option requires `collectCoverage` to be set to true or Jest to be invoked with `--coverage`._ +:::
Help: @@ -222,7 +234,11 @@ Default: `["clover", "json", "lcov", "text"]` A list of reporter names that Jest uses when writing coverage reports. Any [istanbul reporter](https://github.com/istanbuljs/istanbuljs/tree/master/packages/istanbul-reports/lib) 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._ +:::tip + +Setting this option overwrites the default values. Add `"text"` or `"text-summary"` to see a coverage summary in the console output. + +::: Additional options can be passed using the tuple form. For example, you may hide coverage report lines for all fully-covered files: @@ -364,7 +380,11 @@ Default: `[]` Jest will run `.mjs` and `.js` files with nearest `package.json`'s `type` field set to `module` as ECMAScript Modules. If you have any other files that should run with native ESM, you need to specify their file extension here. -> Note: Jest's ESM support is still experimental, see [its docs for more details](ECMAScriptModules.md). +:::caution + +Jest's ESM support is still experimental, see [its docs for more details](ECMAScriptModules.md). + +::: ```json { @@ -433,11 +453,15 @@ Default: `undefined` This option allows the use of a custom global setup module, which must export a function (it can be sync or async). The function will be triggered once before all test suites and it will receive two arguments: Jest's [`globalConfig`](https://github.com/facebook/jest/blob/main/packages/jest-types/src/Config.ts#L282) and [`projectConfig`](https://github.com/facebook/jest/blob/main/packages/jest-types/src/Config.ts#L347). -_Note: A global setup module configured in a project (using multi-project runner) will be triggered only when you run at least one test from this project._ +:::info + +A global setup module configured in a project (using multi-project runner) will be triggered only when you run at least one test from this project. -_Note: Any global variables that are defined through `globalSetup` can only be read in `globalTeardown`. You cannot retrieve globals defined here in your test suites._ +Any global variables that are defined through `globalSetup` can only be read in `globalTeardown`. You cannot retrieve globals defined here in your test suites. -_Note: While code transformation is applied to the linked setup-file, Jest will **not** transform any code in `node_modules`. This is due to the need to load the actual transformers (e.g. `babel` or `typescript`) to perform transformation._ +While code transformation is applied to the linked setup-file, Jest will **not** transform any code in `node_modules`. This is due to the need to load the actual transformers (e.g. `babel` or `typescript`) to perform transformation. + +::: ```js title="setup.js" module.exports = async function (globalConfig, projectConfig) { @@ -464,9 +488,13 @@ Default: `undefined` This option allows the use of a custom global teardown module which must export a function (it can be sync or async). The function will be triggered once after all test suites and it will receive two arguments: Jest's [`globalConfig`](https://github.com/facebook/jest/blob/main/packages/jest-types/src/Config.ts#L282) and [`projectConfig`](https://github.com/facebook/jest/blob/main/packages/jest-types/src/Config.ts#L347). -_Note: A global teardown module configured in a project (using multi-project runner) will be triggered only when you run at least one test from this project._ +:::info + +A global teardown module configured in a project (using multi-project runner) will be triggered only when you run at least one test from this project. -_Note: The same caveat concerning transformation of `node_modules` as for `globalSetup` applies to `globalTeardown`._ +The same caveat concerning transformation of `node_modules` as for `globalSetup` applies to `globalTeardown`. + +::: ### `haste` \[object] @@ -517,7 +545,11 @@ test('some test', () => { }); ``` -_Note: This option is only supported using the default `jest-circus`. test runner_ +:::note + +This option is only supported using the default `jest-circus`. test runner. + +::: ### `maxConcurrency` \[number] @@ -576,7 +608,11 @@ Example: 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. This is true for arrays of module names as well. -_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._ +:::info + +If you provide module names 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>] @@ -674,7 +710,11 @@ The projects feature can also be used to run multiple configurations or multiple } ``` -_Note: When using multi-project runner, it's recommended to add a `displayName` for each project. This will show the `displayName` of a project next to its tests._ +:::tip + +When using multi-project runner, it's recommended to add a `displayName` for each project. This will show the `displayName` of a project next to its tests. + +::: ### `reporters` \[array<moduleName | \[moduleName, options]>] @@ -785,7 +825,11 @@ The options object provided to resolvers has the shape: } ``` -Note: the `defaultResolver` passed as an option is the Jest default resolver which might be useful when you write your custom one. It takes the same arguments as your custom synchronous one, e.g. `(request, options)` and returns a string or throws. +:::tip + +The `defaultResolver` passed as an option is the Jest default resolver which might be useful when you write your custom one. It takes the same arguments as your custom synchronous one, e.g. `(request, options)` and returns a string or throws. + +::: For example, if you want to respect Browserify's [`"browser"` field](https://github.com/browserify/browserify-handbook/blob/master/readme.markdown#browser-field), you can use the following configuration: @@ -858,9 +902,13 @@ 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`)._ +:::info -_Note: By default, `roots` has a single entry `` but there are cases where you may want to have multiple roots within one project, for example `roots: ["/src/", "/tests/"]`._ +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`). + +By default, `roots` has a single entry `` but there are cases where you may want to have multiple roots within one project, for example `roots: ["/src/", "/tests/"]`. + +::: ### `runner` \[string] @@ -873,7 +921,11 @@ This option allows you to use a custom runner instead of Jest's default test run - [`jest-runner-tsc`](https://github.com/azz/jest-runner-tsc) - [`jest-runner-prettier`](https://github.com/keplersj/jest-runner-prettier) -_Note: The `runner` property value can omit the `jest-runner-` prefix of the package name._ +:::info + +The `runner` property value can omit the `jest-runner-` prefix of the package name. + +::: To write a test-runner, export a class with which accepts `globalConfig` in the constructor, and has a `runTests` method with the signature: @@ -941,7 +993,11 @@ If you want a path to be [relative to the root directory of your project](#rootd 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 these modules. -_Note: `setupTestFrameworkScriptFile` is deprecated in favor of `setupFilesAfterEnv`._ +:::info + +`setupTestFrameworkScriptFile` is deprecated in favor of `setupFilesAfterEnv`. + +::: Example `setupFilesAfterEnv` array in a jest.config.js: @@ -1120,7 +1176,11 @@ To use this class as your custom environment, refer to it by its full path withi */ ``` -_Note: TestEnvironment is sandboxed. Each test suite will trigger setup/teardown in their own TestEnvironment._ +:::info + +TestEnvironment is sandboxed. Each test suite will trigger setup/teardown in their own TestEnvironment. + +::: Example: @@ -1205,7 +1265,11 @@ Default: `1` The exit code Jest returns on test failure. -_Note: This does not change the exit code in the case of Jest errors (e.g. invalid configuration)._ +:::info + +This does not change the exit code in the case of Jest errors (e.g. invalid configuration). + +::: ### `testMatch` \[array<string>] @@ -1217,7 +1281,11 @@ See the [micromatch](https://github.com/micromatch/micromatch) package for detai See also [`testRegex` [string | array<string>]](#testregex-string--arraystring), but note that you cannot specify both options. -_Note: Each glob pattern is applied in the order they are specified in the config. (For example `["!**/__fixtures__/**", "**/__tests__/**/*.js"]` will not exclude `__fixtures__` because the negation is overwritten with the second pattern. In order to make the negated glob work in this example it has to come after `**/__tests__/**/*.js`.)_ +:::tip + +Each glob pattern is applied in the order they are specified in the config. For example `["!**/__fixtures__/**", "**/__tests__/**/*.js"]` will not exclude `__fixtures__` because the negation is overwritten with the second pattern. In order to make the negated glob work in this example it has to come after `**/__tests__/**/*.js`. + +::: ### `testPathIgnorePatterns` \[array<string>] @@ -1245,7 +1313,11 @@ The following is a visualization of the default regex: └── component.js # not test ``` -_Note: `testRegex` will try to detect test files using the **absolute file path**, therefore, having a folder with a name that matches it will run all the files as tests_ +:::info + +`testRegex` will try to detect test files using the **absolute file path**, therefore, having a folder with a name that matches it will run all the files as tests. + +::: ### `testResultsProcessor` \[string] @@ -1408,9 +1480,13 @@ Examples of such compilers include: You can pass configuration to a transformer like `{filePattern: ['path-to-transformer', {options}]}` For example, to configure babel-jest for non-default behavior, `{"\\.js$": ['babel-jest', {rootMode: "upward"}]}` -_Note: a transformer is only run once per file unless the file has changed. During the development of a transformer it can be useful to run Jest with `--no-cache` to frequently [delete Jest's cache](Troubleshooting.md#caching-issues)._ +:::tip + +A transformer is only run once per file unless the file has changed. During the development of a transformer it can be useful to run Jest with `--no-cache` to frequently [delete Jest's cache](Troubleshooting.md#caching-issues). + +When adding additional code transformers, this will overwrite the default config and `babel-jest` is no longer automatically loaded. If you want to use it to compile JavaScript or TypeScript, it has to be explicitly defined by adding `{"\\.[jt]sx?$": "babel-jest"}` to the transform property. See [babel-jest plugin](https://github.com/facebook/jest/tree/main/packages/babel-jest#setup). -_Note: when adding additional code transformers, this will overwrite the default config and `babel-jest` is no longer automatically loaded. If you want to use it to compile JavaScript or Typescript, it has to be explicitly defined by adding `{"\\.[jt]sx?$": "babel-jest"}` to the transform property. See [babel-jest plugin](https://github.com/facebook/jest/tree/main/packages/babel-jest#setup)_ +::: A transformer must be an object with at least a `process` function, and it's also recommended to include a `getCacheKey` function. If your transformer is written in ESM you should have a default export with that object. @@ -1495,7 +1571,11 @@ Examples of watch plugins include: - [`jest-watch-typeahead`](https://github.com/jest-community/jest-watch-typeahead) - [`jest-watch-yarn-workspaces`](https://github.com/cameronhunter/jest-watch-directories/tree/master/packages/jest-watch-yarn-workspaces) -_Note: The values in the `watchPlugins` property value can omit the `jest-watch-` prefix of the package name._ +:::info + +The values in the `watchPlugins` property value can omit the `jest-watch-` prefix of the package name. + +::: ### `watchman` \[boolean]