diff --git a/CHANGELOG.md b/CHANGELOG.md index 5f5e645f4dfb..4cff3ea6efa0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,8 +13,9 @@ ### Chore & Maintenance - `[docs]` Updated docs to indicate that `jest-environment-jsdom` is a separate package [#12828](https://github.com/facebook/jest/issues/12828) -- `[jest-haste-map]` Bump `walker` version ([#12324](https://github.com/facebook/jest/pull/12324)) - `[docs]` Document the comments used by coverage providers [#12835](https://github.com/facebook/jest/issues/12835) +- `[docs]` Use `docusaurus-remark-plugin-tab-blocks` to format tabs with code examples ([#12859](https://github.com/facebook/jest/pull/12859)) +- `[jest-haste-map]` Bump `walker` version ([#12324](https://github.com/facebook/jest/pull/12324)) ### Performance diff --git a/docs/Configuration.md b/docs/Configuration.md index 26769132330e..389169ccc708 100644 --- a/docs/Configuration.md +++ b/docs/Configuration.md @@ -3,9 +3,6 @@ id: configuration title: Configuring Jest --- -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - The Jest philosophy is to work great by default, but sometimes you just need more configuration power. It is recommended to define the configuration in a dedicated JavaScript, TypeScript or JSON file. The file will be discovered automatically, if it is named `jest.config.js|ts|mjs|cjs|json`. You can use [`--config`](CLI.md#--configpath) flag to pass an explicit path to the file. @@ -18,10 +15,7 @@ Keep in mind that the resulting configuration object must always be JSON-seriali The configuration file should simply export an object: - - - -```js +```js tab /** @type {import('jest').Config} */ const config = { verbose: true, @@ -30,11 +24,7 @@ const config = { module.exports = config; ``` - - - - -```ts +```ts tab import type {Config} from 'jest'; const config: Config = { @@ -44,15 +34,9 @@ const config: Config = { export default config; ``` - - - Or a function returning an object: - - - -```js +```js tab /** @returns {Promise} */ module.exports = async () => { return { @@ -61,11 +45,7 @@ module.exports = async () => { }; ``` - - - - -```ts +```ts tab import type {Config} from 'jest'; export default async (): Promise => { @@ -75,9 +55,6 @@ export default async (): Promise => { }; ``` - - - :::tip To read TypeScript configuration files Jest requires [`ts-node`](https://npmjs.com/package/ts-node). Make sure it is installed in your project. @@ -110,10 +87,7 @@ Alternatively Jest's configuration can be defined through the `"jest"` key in th You can retrieve Jest's defaults from `jest-config` to extend them if needed: - - - -```js +```js tab const {defaults} = require('jest-config'); /** @type {import('jest').Config} */ @@ -124,11 +98,7 @@ const config = { module.exports = config; ``` - - - - -```ts +```ts tab import type {Config} from 'jest'; import {defaults} from 'jest-config'; @@ -139,9 +109,6 @@ const config: Config = { export default config; ``` - - - ::: import TOCInline from '@theme/TOCInline'; @@ -233,10 +200,7 @@ Default: `undefined` An array of [glob patterns](https://github.com/micromatch/micromatch) 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. - - - -```js +```js tab /** @type {import('jest').Config} */ const config = { collectCoverageFrom: [ @@ -249,11 +213,7 @@ const config = { module.exports = config; ``` - - - - -```ts +```ts tab import type {Config} from 'jest'; const config: Config = { @@ -267,9 +227,6 @@ const config: Config = { export default config; ``` - - - This will collect coverage information for all the files inside the project's `rootDir`, except the ones that match `**/node_modules/**` or `**/vendor/**`. :::tip @@ -336,10 +293,7 @@ Setting this option overwrites the default values. Add `"text"` or `"text-summar Additional options can be passed using the tuple form. For example, you may hide coverage report lines for all fully-covered files: - - - -```js +```js tab /** @type {import('jest').Config} */ const config = { coverageReporters: ['clover', 'json', 'lcov', ['text', {skipFull: true}]], @@ -348,11 +302,7 @@ const config = { module.exports = config; ``` - - - - -```ts +```ts tab import type {Config} from 'jest'; const config: Config = { @@ -362,9 +312,6 @@ const config: Config = { export default config; ``` - - - For more information about the options object shape refer to `CoverageReporterWithOptions` type in the [type definitions](https://github.com/facebook/jest/tree/main/packages/jest-types/src/Config.ts). ### `coverageThreshold` \[object] @@ -375,10 +322,7 @@ This will be used to configure minimum threshold enforcement for coverage result 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: - - - -```js +```js tab /** @type {import('jest').Config} */ const config = { coverageThreshold: { @@ -394,11 +338,7 @@ const config = { module.exports = config; ``` - - - - -```ts +```ts tab import type {Config} from 'jest'; const config: Config = { @@ -415,17 +355,11 @@ const config: Config = { export default config; ``` - - - 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, an error is returned. For example, with the following configuration: - - - -```js +```js tab /** @type {import('jest').Config} */ const config = { coverageThreshold: { @@ -454,11 +388,7 @@ const config = { module.exports = config; ``` - - - - -```ts +```ts tab import type {Config} from 'jest'; const config: Config = { @@ -488,9 +418,6 @@ const config: Config = { export default config; ``` - - - Jest will fail if: - The `./src/components` directory has less than 40% branch or statement coverage. @@ -533,10 +460,7 @@ default: `undefined` Allows for a label to be printed alongside a test while it is running. This becomes more useful in multi-project repositories where there can be many jest configuration files. This visually tells which project a test belongs to. - - - -```js +```js tab /** @type {import('jest').Config} */ const config = { displayName: 'CLIENT', @@ -545,11 +469,7 @@ const config = { module.exports = config; ``` - - - - -```ts +```ts tab import type {Config} from 'jest'; const config: Config = { @@ -559,15 +479,9 @@ const config: Config = { export default config; ``` - - - Alternatively, an object with the properties `name` and `color` can be passed. This allows for a custom configuration of the background color of the displayName. `displayName` defaults to white when its value is a string. Jest uses [`chalk`](https://github.com/chalk/chalk) to provide the color. As such, all of the valid options for colors supported by `chalk` are also supported by Jest. - - - -```js +```js tab /** @type {import('jest').Config} */ const config = { displayName: { @@ -579,11 +493,7 @@ const config = { module.exports = config; ``` - - - - -```ts +```ts tab import type {Config} from 'jest'; const config: Config = { @@ -596,9 +506,6 @@ const config: Config = { export default config; ``` - - - ### `errorOnDeprecated` \[boolean] Default: `false` @@ -611,10 +518,7 @@ 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. - - - -```js +```js tab /** @type {import('jest').Config} */ const config = { extensionsToTreatAsEsm: ['.ts'], @@ -623,11 +527,7 @@ const config = { module.exports = config; ``` - - - - -```ts +```ts tab import type {Config} from 'jest'; const config: Config = { @@ -637,9 +537,6 @@ const config: Config = { export default config; ``` - - - :::caution Jest's ESM support is still experimental, see [its docs for more details](ECMAScriptModules.md). @@ -654,10 +551,7 @@ The fake timers may be useful when a piece of code sets a long timeout that we d This option provides the default configuration of fake timers for all tests. Calling `jest.useFakeTimers()` in a test file will use these options or will override them if a configuration object is passed. For example, you can tell Jest to keep the original implementation of `process.nextTick()` and adjust the limit of recursive timers that will be run: - - - -```js +```js tab /** @type {import('jest').Config} */ const config = { fakeTimers: { @@ -669,11 +563,7 @@ const config = { module.exports = config; ``` - - - - -```ts +```ts tab import type {Config} from 'jest'; const config: Config = { @@ -686,9 +576,6 @@ const config: Config = { export default config; ``` - - - ```js title="fakeTime.test.js" // install fake timers for this file using the options from Jest configuration jest.useFakeTimers(); @@ -703,10 +590,7 @@ test('increase the limit of recursive timers for this and following tests', () = Instead of including `jest.useFakeTimers()` in each test file, you can enable fake timers globally for all tests in your Jest configuration: - - - -```js +```js tab /** @type {import('jest').Config} */ const config = { fakeTimers: { @@ -717,11 +601,7 @@ const config = { module.exports = config; ``` - - - - -```ts +```ts tab import type {Config} from 'jest'; const config: Config = { @@ -733,9 +613,6 @@ const config: Config = { export default config; ``` - - - ::: Configuration options: @@ -788,10 +665,7 @@ type ModernFakeTimersConfig = { For some reason you might have to use legacy implementation of fake timers. Here is how to enable it globally (additional options are not supported): - - - -```js +```js tab /** @type {import('jest').Config} */ const config = { fakeTimers: { @@ -803,11 +677,7 @@ const config = { module.exports = config; ``` - - - - -```ts +```ts tab import type {Config} from 'jest'; const config: Config = { @@ -820,9 +690,6 @@ const config: Config = { export default config; ``` - - - ::: ### `forceCoverageMatch` \[array<string>] @@ -847,10 +714,7 @@ if (process.env.NODE_ENV === 'test') { You can collect coverage from those files with setting `forceCoverageMatch`. - - - -```js +```js tab /** @type {import('jest').Config} */ const config = { forceCoverageMatch: ['**/*.t.js'], @@ -859,11 +723,7 @@ const config = { module.exports = config; ``` - - - - -```ts +```ts tab import type {Config} from 'jest'; const config: Config = { @@ -873,9 +733,6 @@ const config: Config = { export default config; ``` - - - ### `globals` \[object] Default: `{}` @@ -884,10 +741,7 @@ 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: - - - -```js +```js tab /** @type {import('jest').Config} */ const config = { globals: { @@ -898,11 +752,7 @@ const config = { module.exports = config; ``` - - - - -```ts +```ts tab import type {Config} from 'jest'; const config: Config = { @@ -914,9 +764,6 @@ const config: Config = { export default config; ``` - - - 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`. ### `globalSetup` \[string] @@ -1035,10 +882,7 @@ Specifies the maximum number of workers the worker-pool will spawn for running t For environments with variable CPUs available, you can use percentage based configuration: - - - -```js +```js tab /** @type {import('jest').Config} */ const config = { maxWorkers: '50%', @@ -1047,11 +891,7 @@ const config = { module.exports = config; ``` - - - - -```ts +```ts tab import type {Config} from 'jest'; const config: Config = { @@ -1061,19 +901,13 @@ const config: Config = { export default config; ``` - - - ### `moduleDirectories` \[array<string>] 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: - - - -```js +```js tab /** @type {import('jest').Config} */ const config = { moduleDirectories: ['node_modules', 'bower_components'], @@ -1082,11 +916,7 @@ const config = { module.exports = config; ``` - - - - -```ts +```ts tab import type {Config} from 'jest'; const config: Config = { @@ -1096,9 +926,6 @@ const config: Config = { export default config; ``` - - - ### `moduleFileExtensions` \[array<string>] Default: `["js", "mjs", "cjs", "jsx", "ts", "tsx", "json", "node"]` @@ -1119,10 +946,7 @@ Use `` string token to refer to [`rootDir`](#rootdir-string) value if y Additionally, you can substitute captured regex groups using numbered backreferences. - - - -```js +```js tab /** @type {import('jest').Config} */ const config = { moduleNameMapper: { @@ -1140,11 +964,7 @@ const config = { module.exports = config; ``` - - - - -```ts +```ts tab import type {Config} from 'jest'; const config: Config = { @@ -1163,9 +983,6 @@ const config: Config = { export default config; ``` - - - 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. :::info @@ -1182,10 +999,7 @@ An array of regexp pattern strings that are matched against all module paths bef These pattern strings match against the full path. Use the `` 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. - - - -```js +```js tab /** @type {import('jest').Config} */ const config = { modulePathIgnorePatterns: ['/build/'], @@ -1194,11 +1008,7 @@ const config = { module.exports = config; ``` - - - - -```ts +```ts tab import type {Config} from 'jest'; const config: Config = { @@ -1208,19 +1018,13 @@ const config: Config = { export default config; ``` - - - ### `modulePaths` \[array<string>] 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 `` string token to include the path to your project's root directory. - - - -```js +```js tab /** @type {import('jest').Config} */ const config = { modulePaths: ['/app/'], @@ -1229,11 +1033,7 @@ const config = { module.exports = config; ``` - - - - -```ts +```ts tab import type {Config} from 'jest'; const config: Config = { @@ -1243,9 +1043,6 @@ const config: Config = { export default config; ``` - - - ### `notify` \[boolean] Default: `false` @@ -1287,10 +1084,7 @@ A preset that is used as a base for Jest's configuration. A preset should point For example, this preset `foo-bar/jest-preset.js` will be configured as follows: - - - -```js +```js tab /** @type {import('jest').Config} */ const config = { preset: 'foo-bar', @@ -1299,11 +1093,7 @@ const config = { module.exports = config; ``` - - - - -```ts +```ts tab import type {Config} from 'jest'; const config: Config = { @@ -1313,15 +1103,9 @@ const config: Config = { export default config; ``` - - - Presets may also be relative to filesystem paths: - - - -```js +```js tab /** @type {import('jest').Config} */ const config = { preset: './node_modules/foo-bar/jest-preset.js', @@ -1330,11 +1114,7 @@ const config = { module.exports = config; ``` - - - - -```ts +```ts tab import type {Config} from 'jest'; const config: Config = { @@ -1344,9 +1124,6 @@ const config: Config = { export default config; ``` - - - :::info Note that if you also have specified [`rootDir`](#rootdir-string) that the resolution of this file will be relative to that root directory. @@ -1365,10 +1142,7 @@ 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. - - - -```js +```js tab /** @type {import('jest').Config} */ const config = { projects: ['', '/examples/*'], @@ -1377,11 +1151,7 @@ const config = { module.exports = config; ``` - - - - -```ts +```ts tab import type {Config} from 'jest'; const config: Config = { @@ -1391,17 +1161,11 @@ const config: Config = { export default config; ``` - - - 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](#runner-string). For this purpose, you can pass an array of configuration objects. For example, to run both tests and ESLint (via [jest-runner-eslint](https://github.com/jest-community/jest-runner-eslint)) in the same invocation of Jest: - - - -```js +```js tab /** @type {import('jest').Config} */ const config = { projects: [ @@ -1419,11 +1183,7 @@ const config = { module.exports = config; ``` - - - - -```ts +```ts tab import type {Config} from 'jest'; const config: Config = { @@ -1442,9 +1202,6 @@ const config: Config = { export default config; ``` - - - :::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. @@ -1457,10 +1214,7 @@ Default: `undefined` Use this configuration option to add reporters to Jest. It must be a list of reporter names, additional options can be passed to a reporter using the tuple form: - - - -```js +```js tab /** @type {import('jest').Config} */ const config = { reporters: [ @@ -1472,11 +1226,7 @@ const config = { module.exports = config; ``` - - - - -```ts +```ts tab import type {Config} from 'jest'; const config: Config = { @@ -1489,17 +1239,11 @@ const config: Config = { export default config; ``` - - - #### Default Reporter If custom reporters are specified, the default Jest reporter will be overridden. If you wish to keep it, `'default'` must be passed as a reporters name: - - - -```js +```js tab /** @type {import('jest').Config} */ const config = { reporters: [ @@ -1511,11 +1255,7 @@ const config = { module.exports = config; ``` - - - - -```ts +```ts tab import type {Config} from 'jest'; const config: Config = { @@ -1528,17 +1268,11 @@ const config: Config = { export default config; ``` - - - #### GitHub Actions Reporter If included in the list, the built-in GitHub Actions Reporter will annotate changed files with test failure messages: - - - -```js +```js tab /** @type {import('jest').Config} */ const config = { reporters: ['default', 'github-actions'], @@ -1547,11 +1281,7 @@ const config = { module.exports = config; ``` - - - - -```ts +```ts tab import type {Config} from 'jest'; const config: Config = { @@ -1561,17 +1291,11 @@ const config: Config = { export default config; ``` - - - #### Summary Reporter Summary reporter prints out summary of all tests. It is a part of default reporter, hence it will be enabled if `'default'` is included in the list. For instance, you might want to use it as stand-alone reporter instead of the default one, or together with [Silent Reporter](https://github.com/rickhanlonii/jest-silent-reporter): - - - -```js +```js tab /** @type {import('jest').Config} */ const config = { reporters: ['jest-silent-reporter', 'summary'], @@ -1580,11 +1304,7 @@ const config = { module.exports = config; ``` - - - - -```ts +```ts tab import type {Config} from 'jest'; const config: Config = { @@ -1594,9 +1314,6 @@ const config: Config = { export default config; ``` - - - #### Custom Reporters :::tip @@ -1696,10 +1413,7 @@ module.exports = browserResolve.sync; And add it to Jest configuration: - - - -```js +```js tab /** @type {import('jest').Config} */ const config = { resolver: '/resolver.js', @@ -1708,11 +1422,7 @@ const config = { module.exports = config; ``` - - - - -```ts +```ts tab import type {Config} from 'jest'; const config: Config = { @@ -1722,9 +1432,6 @@ const config: Config = { export default config; ``` - - - By combining `defaultResolver` and `packageFilter` we can implement a `package.json` "pre-processor" that allows us to change how the default resolver will resolve modules. For example, imagine we want to use the field `"module"` if it is present, otherwise fallback to `"main"`: ```js @@ -1826,10 +1533,7 @@ Test files run inside a [vm](https://nodejs.org/api/vm.html), which slows calls For example, if your tests call `Math` often, you can pass it by setting `sandboxInjectedGlobals`. - - - -```js +```js tab /** @type {import('jest').Config} */ const config = { sandboxInjectedGlobals: ['Math'], @@ -1838,11 +1542,7 @@ const config = { module.exports = config; ``` - - - - -```ts +```ts tab import type {Config} from 'jest'; const config: Config = { @@ -1852,9 +1552,6 @@ const config: Config = { export default config; ``` - - - :::note This option has no effect if you use [native ESM](ECMAScriptModules.md). @@ -1890,10 +1587,7 @@ afterEach(() => { }); ``` - - - -```js +```js tab /** @type {import('jest').Config} */ const config = { setupFilesAfterEnv: ['/setup-jest.js'], @@ -1902,11 +1596,7 @@ const config = { module.exports = config; ``` - - - - -```ts +```ts tab import type {Config} from 'jest'; const config: Config = { @@ -1916,9 +1606,6 @@ const config: Config = { export default config; ``` - - - ### `slowTestThreshold` \[number] Default: `5` @@ -1931,10 +1618,7 @@ Default: `undefined` Allows overriding specific snapshot formatting options documented in the [pretty-format readme](https://www.npmjs.com/package/pretty-format#usage-with-options), with the exceptions of `compareKeys` and `plugins`. For example, this config would have the snapshot formatter not print a prefix for "Object" and "Array": - - - -```js +```js tab /** @type {import('jest').Config} */ const config = { snapshotFormat: { @@ -1945,11 +1629,7 @@ const config = { module.exports = config; ``` - - - - -```ts +```ts tab import type {Config} from 'jest'; const config: Config = { @@ -1961,9 +1641,6 @@ const config: Config = { export default config; ``` - - - ```js title="some.test.js" test('does not show prototypes for object and array inline', () => { const object = { @@ -2028,10 +1705,7 @@ module.exports = { Add `custom-serializer` to your Jest configuration: - - - -```js +```js tab /** @type {import('jest').Config} */ const config = { snapshotSerializers: ['path/to/custom-serializer.js'], @@ -2040,11 +1714,7 @@ const config = { module.exports = config; ``` - - - - -```ts +```ts tab import type {Config} from 'jest'; const config: Config = { @@ -2054,9 +1724,6 @@ const config: Config = { export default config; ``` - - - Finally tests would look as follows: ```js @@ -2390,10 +2057,7 @@ module.exports = CustomSequencer; Add `custom-sequencer` to your Jest configuration: - - - -```js +```js tab /** @type {import('jest').Config} */ const config = { testSequencer: 'path/to/custom-sequencer.js', @@ -2402,11 +2066,7 @@ const config = { module.exports = config; ``` - - - - -```ts +```ts tab import type {Config} from 'jest'; const config: Config = { @@ -2416,9 +2076,6 @@ const config: Config = { export default config; ``` - - - ### `testTimeout` \[number] Default: `5000` @@ -2441,10 +2098,7 @@ Keep in mind that a transformer only runs once per file unless the file has chan Remember to include the default `babel-jest` transformer explicitly, if you wish to use it alongside with additional code preprocessors: - - - -```js +```js tab /** @type {import('jest').Config} */ const config = { transform: { @@ -2456,11 +2110,7 @@ const config = { module.exports = config; ``` - - - - -```ts +```ts tab import type {Config} from 'jest'; const config: Config = { @@ -2473,9 +2123,6 @@ const config: Config = { export default config; ``` - - - ::: ### `transformIgnorePatterns` \[array<string>] @@ -2486,10 +2133,7 @@ An array of regexp pattern strings that are matched against all source file path Providing regexp patterns that overlap with each other may result in files not being transformed that you expected to be transformed. For example: - - - -```js +```js tab /** @type {import('jest').Config} */ const config = { transformIgnorePatterns: ['/node_modules/(?!(foo|bar)/)', '/bar/'], @@ -2498,11 +2142,7 @@ const config = { module.exports = config; ``` - - - - -```ts +```ts tab import type {Config} from 'jest'; const config: Config = { @@ -2512,19 +2152,13 @@ const config: Config = { export default config; ``` - - - The first pattern will match (and therefore not transform) files inside `/node_modules` except for those in `/node_modules/foo/` and `/node_modules/bar/`. The second pattern will match (and therefore not transform) files inside any path with `/bar/` in it. With the two together, files in `/node_modules/bar/` will not be transformed because it does match the second pattern, even though it was excluded by the first. Sometimes it happens (especially in React Native or TypeScript projects) that 3rd party modules are published as untranspiled code. 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 allow transpiling such modules. You'll find a good example of this use case in [React Native Guide](/docs/tutorial-react-native#transformignorepatterns-customization). These pattern strings match against the full path. Use the `` 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. - - - -```js +```js tab /** @type {import('jest').Config} */ const config = { transformIgnorePatterns: [ @@ -2536,11 +2170,7 @@ const config = { module.exports = config; ``` - - - - -```ts +```ts tab import type {Config} from 'jest'; const config: Config = { @@ -2553,9 +2183,6 @@ const config: Config = { export default config; ``` - - - ### `unmockedModulePathPatterns` \[array<string>] Default: `[]` @@ -2582,10 +2209,7 @@ These patterns match against the full path. Use the `` string token to Even if nothing is specified here, the watcher will ignore changes to the version control folders (.git, .hg). Other hidden files and directories, i.e. those that begin with a dot (`.`), are watched by default. Remember to escape the dot when you add them to `watchPathIgnorePatterns` as it is a special RegExp character. - - - -```js +```js tab /** @type {import('jest').Config} */ const config = { watchPathIgnorePatterns: ['/\\.tmp/', '/bar/'], @@ -2594,11 +2218,7 @@ const config = { module.exports = config; ``` - - - - -```ts +```ts tab import type {Config} from 'jest'; const config: Config = { @@ -2608,9 +2228,6 @@ const config: Config = { export default config; ``` - - - ### `watchPlugins` \[array<string | \[string, Object]>] Default: `[]` diff --git a/docs/MockFunctionAPI.md b/docs/MockFunctionAPI.md index 0ac4de121f65..b7ba592c6009 100644 --- a/docs/MockFunctionAPI.md +++ b/docs/MockFunctionAPI.md @@ -25,9 +25,6 @@ import TOCInline from '@theme/TOCInline'; ## Reference -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - ### `mockFn.getMockName()` Returns the mock name string set by calling `mockFn.mockName(value)`. @@ -159,10 +156,7 @@ Accepts a function that should be used as the implementation of the mock. The mo ::: - - - -```js +```js tab const mockFn = jest.fn(scalar => 42 + scalar); mockFn(0); // 42 @@ -174,11 +168,7 @@ mockFn(2); // 38 mockFn(3); // 39 ``` - - - - -```js +```ts tab const mockFn = jest.fn((scalar: number) => 42 + scalar); mockFn(0); // 42 @@ -190,15 +180,9 @@ mockFn(2); // 38 mockFn(3); // 39 ``` - - - `.mockImplementation()` can also be used to mock class constructors: - - - -```js title="SomeClass.js" +```js tab={"span":2} title="SomeClass.js" module.exports = class SomeClass { method(a, b) {} }; @@ -222,11 +206,7 @@ some.method('a', 'b'); console.log('Calls to method: ', mockMethod.mock.calls); ``` - - - - -```ts title="SomeClass.ts" +```ts tab={"span":2} title="SomeClass.ts" export class SomeClass { method(a: string, b: string): void {} } @@ -250,17 +230,11 @@ some.method('a', 'b'); console.log('Calls to method: ', mockMethod.mock.calls); ``` - - - ### `mockFn.mockImplementationOnce(fn)` Accepts a function that will be used as an implementation of the mock for one call to the mocked function. Can be chained so that multiple function calls produce different results. - - - -```js +```js tab const mockFn = jest .fn() .mockImplementationOnce(cb => cb(null, true)) @@ -270,11 +244,7 @@ mockFn((err, val) => console.log(val)); // true mockFn((err, val) => console.log(val)); // false ``` - - - - -```ts +```ts tab const mockFn = jest .fn<(cb: (a: null, b: boolean) => void) => void>() .mockImplementationOnce(cb => cb(null, true)) @@ -284,9 +254,6 @@ mockFn((err, val) => console.log(val)); // true mockFn((err, val) => console.log(val)); // false ``` - - - When the mocked function runs out of implementations defined with `.mockImplementationOnce()`, it will execute the default implementation set with `jest.fn(() => defaultValue)` or `.mockImplementation(() => defaultValue)` if they were called: ```js @@ -336,10 +303,7 @@ jest.fn(function () { Accepts a value that will be returned whenever the mock function is called. - - - -```js +```js tab const mock = jest.fn(); mock.mockReturnValue(42); @@ -349,11 +313,7 @@ mock.mockReturnValue(43); mock(); // 43 ``` - - - - -```ts +```ts tab const mock = jest.fn<() => number>(); mock.mockReturnValue(42); @@ -363,17 +323,11 @@ mock.mockReturnValue(43); mock(); // 43 ``` - - - ### `mockFn.mockReturnValueOnce(value)` Accepts a value that will be returned for one call to the mock function. Can be chained so that successive calls to the mock function return different values. When there are no more `mockReturnValueOnce` values to use, calls will return a value specified by `mockReturnValue`. - - - -```js +```js tab const mockFn = jest .fn() .mockReturnValue('default') @@ -386,11 +340,7 @@ mockFn(); // 'default' mockFn(); // 'default' ``` - - - - -```ts +```ts tab const mockFn = jest .fn<() => string>() .mockReturnValue('default') @@ -403,9 +353,6 @@ mockFn(); // 'default' mockFn(); // 'default' ``` - - - ### `mockFn.mockResolvedValue(value)` Syntactic sugar function for: @@ -416,10 +363,7 @@ jest.fn().mockImplementation(() => Promise.resolve(value)); Useful to mock async functions in async tests: - - - -```js +```js tab test('async test', async () => { const asyncMock = jest.fn().mockResolvedValue(43); @@ -427,11 +371,7 @@ test('async test', async () => { }); ``` - - - - -```ts +```ts tab test('async test', async () => { const asyncMock = jest.fn<() => Promise>().mockResolvedValue(43); @@ -439,9 +379,6 @@ test('async test', async () => { }); ``` - - - ### `mockFn.mockResolvedValueOnce(value)` Syntactic sugar function for: @@ -452,10 +389,7 @@ jest.fn().mockImplementationOnce(() => Promise.resolve(value)); Useful to resolve different values over multiple async calls: - - - -```js +```js tab test('async test', async () => { const asyncMock = jest .fn() @@ -470,11 +404,7 @@ test('async test', async () => { }); ``` - - - - -```ts +```ts tab test('async test', async () => { const asyncMock = jest .fn<() => Promise>() @@ -489,9 +419,6 @@ test('async test', async () => { }); ``` - - - ### `mockFn.mockRejectedValue(value)` Syntactic sugar function for: @@ -502,10 +429,7 @@ jest.fn().mockImplementation(() => Promise.reject(value)); Useful to create async mock functions that will always reject: - - - -```js +```js tab test('async test', async () => { const asyncMock = jest .fn() @@ -515,11 +439,7 @@ test('async test', async () => { }); ``` - - - - -```ts +```ts tab test('async test', async () => { const asyncMock = jest .fn<() => Promise>() @@ -529,9 +449,6 @@ test('async test', async () => { }); ``` - - - ### `mockFn.mockRejectedValueOnce(value)` Syntactic sugar function for: @@ -542,10 +459,7 @@ jest.fn().mockImplementationOnce(() => Promise.reject(value)); Useful together with `.mockResolvedValueOnce()` or to reject with different exceptions over multiple async calls: - - - -```js +```js tab test('async test', async () => { const asyncMock = jest .fn() @@ -557,11 +471,7 @@ test('async test', async () => { }); ``` - - - - -```ts +```ts tab test('async test', async () => { const asyncMock = jest .fn<() => Promise>() @@ -573,9 +483,6 @@ test('async test', async () => { }); ``` - - - ## TypeScript Usage :::tip diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js index 8d57541950c8..66e88609525a 100644 --- a/website/docusaurus.config.js +++ b/website/docusaurus.config.js @@ -56,6 +56,7 @@ module.exports = { sidebarPath: path.resolve(__dirname, './sidebars.json'), remarkPlugins: [ [require('@docusaurus/remark-plugin-npm2yarn'), {sync: true}], + require('docusaurus-remark-plugin-tab-blocks'), ], }, blog: { diff --git a/website/package.json b/website/package.json index a64446b8fdce..c6e2b9569e9a 100644 --- a/website/package.json +++ b/website/package.json @@ -35,6 +35,7 @@ "@docusaurus/preset-classic": "^2.0.0-beta.17", "@docusaurus/remark-plugin-npm2yarn": "^2.0.0-beta.17", "clsx": "^1.1.1", + "docusaurus-remark-plugin-tab-blocks": "^1.0.0", "globby": "^11.0.1", "react": "17.0.2", "react-dom": "^17.0.1", diff --git a/website/versioned_docs/version-28.0/MockFunctionAPI.md b/website/versioned_docs/version-28.0/MockFunctionAPI.md index 0ac4de121f65..b7ba592c6009 100644 --- a/website/versioned_docs/version-28.0/MockFunctionAPI.md +++ b/website/versioned_docs/version-28.0/MockFunctionAPI.md @@ -25,9 +25,6 @@ import TOCInline from '@theme/TOCInline'; ## Reference -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - ### `mockFn.getMockName()` Returns the mock name string set by calling `mockFn.mockName(value)`. @@ -159,10 +156,7 @@ Accepts a function that should be used as the implementation of the mock. The mo ::: - - - -```js +```js tab const mockFn = jest.fn(scalar => 42 + scalar); mockFn(0); // 42 @@ -174,11 +168,7 @@ mockFn(2); // 38 mockFn(3); // 39 ``` - - - - -```js +```ts tab const mockFn = jest.fn((scalar: number) => 42 + scalar); mockFn(0); // 42 @@ -190,15 +180,9 @@ mockFn(2); // 38 mockFn(3); // 39 ``` - - - `.mockImplementation()` can also be used to mock class constructors: - - - -```js title="SomeClass.js" +```js tab={"span":2} title="SomeClass.js" module.exports = class SomeClass { method(a, b) {} }; @@ -222,11 +206,7 @@ some.method('a', 'b'); console.log('Calls to method: ', mockMethod.mock.calls); ``` - - - - -```ts title="SomeClass.ts" +```ts tab={"span":2} title="SomeClass.ts" export class SomeClass { method(a: string, b: string): void {} } @@ -250,17 +230,11 @@ some.method('a', 'b'); console.log('Calls to method: ', mockMethod.mock.calls); ``` - - - ### `mockFn.mockImplementationOnce(fn)` Accepts a function that will be used as an implementation of the mock for one call to the mocked function. Can be chained so that multiple function calls produce different results. - - - -```js +```js tab const mockFn = jest .fn() .mockImplementationOnce(cb => cb(null, true)) @@ -270,11 +244,7 @@ mockFn((err, val) => console.log(val)); // true mockFn((err, val) => console.log(val)); // false ``` - - - - -```ts +```ts tab const mockFn = jest .fn<(cb: (a: null, b: boolean) => void) => void>() .mockImplementationOnce(cb => cb(null, true)) @@ -284,9 +254,6 @@ mockFn((err, val) => console.log(val)); // true mockFn((err, val) => console.log(val)); // false ``` - - - When the mocked function runs out of implementations defined with `.mockImplementationOnce()`, it will execute the default implementation set with `jest.fn(() => defaultValue)` or `.mockImplementation(() => defaultValue)` if they were called: ```js @@ -336,10 +303,7 @@ jest.fn(function () { Accepts a value that will be returned whenever the mock function is called. - - - -```js +```js tab const mock = jest.fn(); mock.mockReturnValue(42); @@ -349,11 +313,7 @@ mock.mockReturnValue(43); mock(); // 43 ``` - - - - -```ts +```ts tab const mock = jest.fn<() => number>(); mock.mockReturnValue(42); @@ -363,17 +323,11 @@ mock.mockReturnValue(43); mock(); // 43 ``` - - - ### `mockFn.mockReturnValueOnce(value)` Accepts a value that will be returned for one call to the mock function. Can be chained so that successive calls to the mock function return different values. When there are no more `mockReturnValueOnce` values to use, calls will return a value specified by `mockReturnValue`. - - - -```js +```js tab const mockFn = jest .fn() .mockReturnValue('default') @@ -386,11 +340,7 @@ mockFn(); // 'default' mockFn(); // 'default' ``` - - - - -```ts +```ts tab const mockFn = jest .fn<() => string>() .mockReturnValue('default') @@ -403,9 +353,6 @@ mockFn(); // 'default' mockFn(); // 'default' ``` - - - ### `mockFn.mockResolvedValue(value)` Syntactic sugar function for: @@ -416,10 +363,7 @@ jest.fn().mockImplementation(() => Promise.resolve(value)); Useful to mock async functions in async tests: - - - -```js +```js tab test('async test', async () => { const asyncMock = jest.fn().mockResolvedValue(43); @@ -427,11 +371,7 @@ test('async test', async () => { }); ``` - - - - -```ts +```ts tab test('async test', async () => { const asyncMock = jest.fn<() => Promise>().mockResolvedValue(43); @@ -439,9 +379,6 @@ test('async test', async () => { }); ``` - - - ### `mockFn.mockResolvedValueOnce(value)` Syntactic sugar function for: @@ -452,10 +389,7 @@ jest.fn().mockImplementationOnce(() => Promise.resolve(value)); Useful to resolve different values over multiple async calls: - - - -```js +```js tab test('async test', async () => { const asyncMock = jest .fn() @@ -470,11 +404,7 @@ test('async test', async () => { }); ``` - - - - -```ts +```ts tab test('async test', async () => { const asyncMock = jest .fn<() => Promise>() @@ -489,9 +419,6 @@ test('async test', async () => { }); ``` - - - ### `mockFn.mockRejectedValue(value)` Syntactic sugar function for: @@ -502,10 +429,7 @@ jest.fn().mockImplementation(() => Promise.reject(value)); Useful to create async mock functions that will always reject: - - - -```js +```js tab test('async test', async () => { const asyncMock = jest .fn() @@ -515,11 +439,7 @@ test('async test', async () => { }); ``` - - - - -```ts +```ts tab test('async test', async () => { const asyncMock = jest .fn<() => Promise>() @@ -529,9 +449,6 @@ test('async test', async () => { }); ``` - - - ### `mockFn.mockRejectedValueOnce(value)` Syntactic sugar function for: @@ -542,10 +459,7 @@ jest.fn().mockImplementationOnce(() => Promise.reject(value)); Useful together with `.mockResolvedValueOnce()` or to reject with different exceptions over multiple async calls: - - - -```js +```js tab test('async test', async () => { const asyncMock = jest .fn() @@ -557,11 +471,7 @@ test('async test', async () => { }); ``` - - - - -```ts +```ts tab test('async test', async () => { const asyncMock = jest .fn<() => Promise>() @@ -573,9 +483,6 @@ test('async test', async () => { }); ``` - - - ## TypeScript Usage :::tip diff --git a/website/versioned_docs/version-28.1/MockFunctionAPI.md b/website/versioned_docs/version-28.1/MockFunctionAPI.md index 0ac4de121f65..b7ba592c6009 100644 --- a/website/versioned_docs/version-28.1/MockFunctionAPI.md +++ b/website/versioned_docs/version-28.1/MockFunctionAPI.md @@ -25,9 +25,6 @@ import TOCInline from '@theme/TOCInline'; ## Reference -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - ### `mockFn.getMockName()` Returns the mock name string set by calling `mockFn.mockName(value)`. @@ -159,10 +156,7 @@ Accepts a function that should be used as the implementation of the mock. The mo ::: - - - -```js +```js tab const mockFn = jest.fn(scalar => 42 + scalar); mockFn(0); // 42 @@ -174,11 +168,7 @@ mockFn(2); // 38 mockFn(3); // 39 ``` - - - - -```js +```ts tab const mockFn = jest.fn((scalar: number) => 42 + scalar); mockFn(0); // 42 @@ -190,15 +180,9 @@ mockFn(2); // 38 mockFn(3); // 39 ``` - - - `.mockImplementation()` can also be used to mock class constructors: - - - -```js title="SomeClass.js" +```js tab={"span":2} title="SomeClass.js" module.exports = class SomeClass { method(a, b) {} }; @@ -222,11 +206,7 @@ some.method('a', 'b'); console.log('Calls to method: ', mockMethod.mock.calls); ``` - - - - -```ts title="SomeClass.ts" +```ts tab={"span":2} title="SomeClass.ts" export class SomeClass { method(a: string, b: string): void {} } @@ -250,17 +230,11 @@ some.method('a', 'b'); console.log('Calls to method: ', mockMethod.mock.calls); ``` - - - ### `mockFn.mockImplementationOnce(fn)` Accepts a function that will be used as an implementation of the mock for one call to the mocked function. Can be chained so that multiple function calls produce different results. - - - -```js +```js tab const mockFn = jest .fn() .mockImplementationOnce(cb => cb(null, true)) @@ -270,11 +244,7 @@ mockFn((err, val) => console.log(val)); // true mockFn((err, val) => console.log(val)); // false ``` - - - - -```ts +```ts tab const mockFn = jest .fn<(cb: (a: null, b: boolean) => void) => void>() .mockImplementationOnce(cb => cb(null, true)) @@ -284,9 +254,6 @@ mockFn((err, val) => console.log(val)); // true mockFn((err, val) => console.log(val)); // false ``` - - - When the mocked function runs out of implementations defined with `.mockImplementationOnce()`, it will execute the default implementation set with `jest.fn(() => defaultValue)` or `.mockImplementation(() => defaultValue)` if they were called: ```js @@ -336,10 +303,7 @@ jest.fn(function () { Accepts a value that will be returned whenever the mock function is called. - - - -```js +```js tab const mock = jest.fn(); mock.mockReturnValue(42); @@ -349,11 +313,7 @@ mock.mockReturnValue(43); mock(); // 43 ``` - - - - -```ts +```ts tab const mock = jest.fn<() => number>(); mock.mockReturnValue(42); @@ -363,17 +323,11 @@ mock.mockReturnValue(43); mock(); // 43 ``` - - - ### `mockFn.mockReturnValueOnce(value)` Accepts a value that will be returned for one call to the mock function. Can be chained so that successive calls to the mock function return different values. When there are no more `mockReturnValueOnce` values to use, calls will return a value specified by `mockReturnValue`. - - - -```js +```js tab const mockFn = jest .fn() .mockReturnValue('default') @@ -386,11 +340,7 @@ mockFn(); // 'default' mockFn(); // 'default' ``` - - - - -```ts +```ts tab const mockFn = jest .fn<() => string>() .mockReturnValue('default') @@ -403,9 +353,6 @@ mockFn(); // 'default' mockFn(); // 'default' ``` - - - ### `mockFn.mockResolvedValue(value)` Syntactic sugar function for: @@ -416,10 +363,7 @@ jest.fn().mockImplementation(() => Promise.resolve(value)); Useful to mock async functions in async tests: - - - -```js +```js tab test('async test', async () => { const asyncMock = jest.fn().mockResolvedValue(43); @@ -427,11 +371,7 @@ test('async test', async () => { }); ``` - - - - -```ts +```ts tab test('async test', async () => { const asyncMock = jest.fn<() => Promise>().mockResolvedValue(43); @@ -439,9 +379,6 @@ test('async test', async () => { }); ``` - - - ### `mockFn.mockResolvedValueOnce(value)` Syntactic sugar function for: @@ -452,10 +389,7 @@ jest.fn().mockImplementationOnce(() => Promise.resolve(value)); Useful to resolve different values over multiple async calls: - - - -```js +```js tab test('async test', async () => { const asyncMock = jest .fn() @@ -470,11 +404,7 @@ test('async test', async () => { }); ``` - - - - -```ts +```ts tab test('async test', async () => { const asyncMock = jest .fn<() => Promise>() @@ -489,9 +419,6 @@ test('async test', async () => { }); ``` - - - ### `mockFn.mockRejectedValue(value)` Syntactic sugar function for: @@ -502,10 +429,7 @@ jest.fn().mockImplementation(() => Promise.reject(value)); Useful to create async mock functions that will always reject: - - - -```js +```js tab test('async test', async () => { const asyncMock = jest .fn() @@ -515,11 +439,7 @@ test('async test', async () => { }); ``` - - - - -```ts +```ts tab test('async test', async () => { const asyncMock = jest .fn<() => Promise>() @@ -529,9 +449,6 @@ test('async test', async () => { }); ``` - - - ### `mockFn.mockRejectedValueOnce(value)` Syntactic sugar function for: @@ -542,10 +459,7 @@ jest.fn().mockImplementationOnce(() => Promise.reject(value)); Useful together with `.mockResolvedValueOnce()` or to reject with different exceptions over multiple async calls: - - - -```js +```js tab test('async test', async () => { const asyncMock = jest .fn() @@ -557,11 +471,7 @@ test('async test', async () => { }); ``` - - - - -```ts +```ts tab test('async test', async () => { const asyncMock = jest .fn<() => Promise>() @@ -573,9 +483,6 @@ test('async test', async () => { }); ``` - - - ## TypeScript Usage :::tip diff --git a/yarn.lock b/yarn.lock index acc31e9b7e18..eeda9e91758d 100644 --- a/yarn.lock +++ b/yarn.lock @@ -9152,6 +9152,16 @@ __metadata: languageName: node linkType: hard +"docusaurus-remark-plugin-tab-blocks@npm:^1.0.0": + version: 1.0.0 + resolution: "docusaurus-remark-plugin-tab-blocks@npm:1.0.0" + dependencies: + unist-util-is: ^4.0.0 + unist-util-visit: ^2.0.0 + checksum: 3c6877b1b66f7dab70991c3707165e8bfd73bc3255fb7a66af52a926ea9b7c20e8a82cc112737a27b5afaecd7c0868c2684d86a68c8a442d17ef36192b7cc6bc + languageName: node + linkType: hard + "dom-accessibility-api@npm:^0.5.9": version: 0.5.13 resolution: "dom-accessibility-api@npm:0.5.13" @@ -13752,6 +13762,7 @@ __metadata: "@docusaurus/remark-plugin-npm2yarn": ^2.0.0-beta.17 "@types/react": ^17.0.3 clsx: ^1.1.1 + docusaurus-remark-plugin-tab-blocks: ^1.0.0 globby: ^11.0.1 graphql: ^16.3.0 graphql-request: ^4.0.0