From 1417041d5a322b3649dafe3dc5d3e8a0980ed911 Mon Sep 17 00:00:00 2001 From: rickhanlonii Date: Sat, 8 Sep 2018 13:59:39 -0400 Subject: [PATCH] Add 23.4 and 23.5 docs --- .github/ISSUE_TEMPLATE/bug.md | 1 - .github/ISSUE_TEMPLATE/feature.md | 1 - .github/ISSUE_TEMPLATE/question.md | 1 - .github/ISSUE_TEMPLATE/regression.md | 1 - .../version-23.4/BypassingModuleMocks.md | 61 + .../version-23.4/Configuration.md | 912 +++++++++++++ .../versioned_docs/version-23.4/ExpectAPI.md | 1149 ++++++++++++++++ .../version-23.4/SnapshotTesting.md | 293 +++++ website/versioned_docs/version-23.5/CLI.md | 296 +++++ .../version-23.5/Configuration.md | 930 +++++++++++++ .../versioned_docs/version-23.5/ExpectAPI.md | 1153 +++++++++++++++++ .../versioned_docs/version-23.5/GlobalAPI.md | 658 ++++++++++ .../version-23.5/SnapshotTesting.md | 320 +++++ .../version-23.5/TutorialAsync.md | 167 +++ .../version-23.5/TutorialReact.md | 311 +++++ .../version-23.5/WatchPlugins.md | 231 ++++ .../version-23.4-sidebars.json | 41 + website/versions.json | 2 + 18 files changed, 6524 insertions(+), 4 deletions(-) create mode 100644 website/versioned_docs/version-23.4/BypassingModuleMocks.md create mode 100644 website/versioned_docs/version-23.4/Configuration.md create mode 100644 website/versioned_docs/version-23.4/ExpectAPI.md create mode 100644 website/versioned_docs/version-23.4/SnapshotTesting.md create mode 100644 website/versioned_docs/version-23.5/CLI.md create mode 100644 website/versioned_docs/version-23.5/Configuration.md create mode 100644 website/versioned_docs/version-23.5/ExpectAPI.md create mode 100644 website/versioned_docs/version-23.5/GlobalAPI.md create mode 100644 website/versioned_docs/version-23.5/SnapshotTesting.md create mode 100644 website/versioned_docs/version-23.5/TutorialAsync.md create mode 100644 website/versioned_docs/version-23.5/TutorialReact.md create mode 100644 website/versioned_docs/version-23.5/WatchPlugins.md create mode 100644 website/versioned_sidebars/version-23.4-sidebars.json diff --git a/.github/ISSUE_TEMPLATE/bug.md b/.github/ISSUE_TEMPLATE/bug.md index 5c184eeee2b6..98869e6759f9 100644 --- a/.github/ISSUE_TEMPLATE/bug.md +++ b/.github/ISSUE_TEMPLATE/bug.md @@ -1,5 +1,4 @@ --- - name: 🐛 Bug report about: Create a report to help us improve --- diff --git a/.github/ISSUE_TEMPLATE/feature.md b/.github/ISSUE_TEMPLATE/feature.md index 7b468c5c15eb..e310fb3a3f3a 100644 --- a/.github/ISSUE_TEMPLATE/feature.md +++ b/.github/ISSUE_TEMPLATE/feature.md @@ -1,5 +1,4 @@ --- - name: 🚀 Feature Proposal about: Submit a proposal for a new feature --- diff --git a/.github/ISSUE_TEMPLATE/question.md b/.github/ISSUE_TEMPLATE/question.md index 05dca9039446..de47a8a74a8a 100644 --- a/.github/ISSUE_TEMPLATE/question.md +++ b/.github/ISSUE_TEMPLATE/question.md @@ -1,5 +1,4 @@ --- - name: 💬 Questions / Help about: If you have questions, please check our Discord or StackOverflow --- diff --git a/.github/ISSUE_TEMPLATE/regression.md b/.github/ISSUE_TEMPLATE/regression.md index 5dbe9e5c1cbc..7a957734f4c8 100644 --- a/.github/ISSUE_TEMPLATE/regression.md +++ b/.github/ISSUE_TEMPLATE/regression.md @@ -1,5 +1,4 @@ --- - name: 💥 Regression Report about: Report unexpected behavior that worked in previous versions --- diff --git a/website/versioned_docs/version-23.4/BypassingModuleMocks.md b/website/versioned_docs/version-23.4/BypassingModuleMocks.md new file mode 100644 index 000000000000..c80538def7c6 --- /dev/null +++ b/website/versioned_docs/version-23.4/BypassingModuleMocks.md @@ -0,0 +1,61 @@ +--- +id: version-23.4-bypassing-module-mocks +title: Bypassing module mocks +original_id: bypassing-module-mocks +--- + +Jest allows you to mock out whole modules in your tests, which can be useful for testing your code is calling functions from that module correctly. However, sometimes you may want to use parts of a mocked module in your _test file_, in which case you want to access the original implementation, rather than a mocked version. + +Consider writing a test case for this `createUser` function: + +```javascript +// createUser.js +import fetch from 'node-fetch'; + +export const createUser = async () => { + const response = await fetch('http://website.com/users', {method: 'POST'}); + const userId = await response.text(); + return userId; +}; +``` + +Your test will want to mock the `fetch` function so that we can be sure that it gets called without actually making the network request. However, you'll also need to mock the return value of `fetch` with a `Response` (wrapped in a `Promise`), as our function uses it to grab the created user's ID. So you might initially try writing a test like this: + +```javascript +jest.mock('node-fetch'); + +import fetch, {Response} from 'node-fetch'; + +import {createUser} from './createUser'; + +test('createUser calls fetch with the right args and returns the user id', async () => { + fetch.mockReturnValue(Promise.resolve(new Response('4'))); + + const userId = await createUser(); + + expect(fetch).toHaveBeenCalledTimes(1); + expect(fetch).toHaveBeenCalledWith('http://website.com/users', { + method: 'POST', + }); + expect(userId).toBe('4'); +}); +``` + +However, if you ran that test you would find that the `createUser` function would fail, throwing the error: `TypeError: response.text is not a function`. This is because the `Response` class you've imported from `node-fetch` has been mocked (due to the `jest.mock` call at the top of the test file) so it no longer behaves the way it should. + +To get around problems like this, Jest provides the `jest.requireActual` helper. To make the above test work, make the following change to the imports in the test file: + +```javascript +// BEFORE +jest.mock('node-fetch'); +import fetch, {Response} from 'node-fetch'; +``` + +```javascript +// AFTER +jest.mock('node-fetch'); +import fetch from 'node-fetch'; +const {Response} = jest.requireActual('node-fetch'); +``` + +This allows your test file to import the actual `Response` object from `node-fetch`, rather than a mocked version. This means the test will now pass correctly. diff --git a/website/versioned_docs/version-23.4/Configuration.md b/website/versioned_docs/version-23.4/Configuration.md new file mode 100644 index 000000000000..913588df18c1 --- /dev/null +++ b/website/versioned_docs/version-23.4/Configuration.md @@ -0,0 +1,912 @@ +--- +id: version-23.4-configuration +title: Configuring Jest +original_id: configuration +--- + +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 ` 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: + +```json +{ + "name": "my-project", + "jest": { + "verbose": true + } +} +``` + +Or through JavaScript: + +```js +// 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: + +```json +{ + "bail": true, + "verbose": true +} +``` + +## Options + +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. + +### Defaults + +You can retrieve Jest's default options to expand them if needed: + +```js +// jest.config.js +const {defaults} = require('jest-config'); +module.exports = { + // ... + moduleFileExtensions: [...defaults.moduleFileExtensions, 'ts', 'tsx'], + // ... +}; +``` + + + +--- + +## Reference + +### `automock` [boolean] + +Default: `false` + +This option tells Jest that all imported modules in your tests should be mocked automatically. All modules used in your tests will have a replacement implementation, keeping the API surface. + +Example: + +```js +// utils.js +export default { + authorize: () => { + return 'token'; + }, + isAuthorized: secret => secret === 'wizard', +}; +``` + +```js +//__tests__/automocking.test.js +import utils from '../utils'; + +test('if utils mocked automatically', () => { + // Public methods of `utils` are now mock functions + expect(utils.authorize.mock).toBeTruthy(); + expect(utils.isAuthorized.mock).toBeTruthy(); + + // You can provide them with your own implementation + // or just pass the expected return value + utils.authorize.mockReturnValue('mocked_token'); + utils.isAuthorized.mockReturnValue(true); + + expect(utils.authorize()).toBe('mocked_token'); + expect(utils.isAuthorized('not_wizard')).toBeTruthy(); +}); +``` + +_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](troubleshooting.html#tests-are-slow-when-leveraging-automocking) for details and a workaround._ + +### `bail` [boolean] + +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. + +### `browser` [boolean] + +Default: `false` + +Respect Browserify's [`"browser"` field](https://github.com/substack/browserify-handbook#browser-field) in `package.json` when resolving modules. Some modules export different versions based on whether they are operating in Node or a browser. + +### `cacheDirectory` [string] + +Default: `"/tmp/"` + +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. + +### `clearMocks` [boolean] + +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. + +### `collectCoverage` [boolean] + +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. + +### `collectCoverageFrom` [array] + +Default: `undefined` + +An array of [glob patterns](https://github.com/jonschlinkert/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. + +Example: + +```json +{ + "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`._ + +### `coverageDirectory` [string] + +Default: `undefined` + +The directory where Jest should output its coverage files. + +### `coveragePathIgnorePatterns` [array] + +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 `` 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: `["/build/", "/node_modules/"]`. + +### `coverageReporters` [array] + +Default: `["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._ + +### `coverageThreshold` [object] + +Default: `undefined` + +This will be used to configure minimum threshold enforcement for coverage results. Thresholds can be specified as `global`, as a [glob](https://github.com/isaacs/node-glob#glob-primer), 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: + +```json +{ + ... + "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: + +```json +{ + ... + "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/components` directory has less than 40% branch or statement coverage. +- One of the files matching the `./src/reducers/**/*.js` glob has less than 90% statement coverage. +- The `./src/api/very-important-module.js` file has less than 100% coverage. +- Every remaining file combined has less than 50% coverage (`global`). + +### `errorOnDeprecated` [boolean] + +Default: `false` + +Make calling deprecated APIs throw helpful error messages. Useful for easing the upgrade process. + +### `forceCoverageMatch` [array] + +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: + +```javascript +// 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`. + +```json +{ + ... + "jest": { + "forceCoverageMatch": ["**/*.t.js"] + } +} +``` + +### `globals` [object] + +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: + +```json +{ + ... + "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`. + +### `globalSetup` [string] + +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. This function gets Jest's `globalConfig` object as a parameter. + +### `globalTeardown` [string] + +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. This function gets Jest's `globalConfig` object as a parameter. + +### `moduleDirectories` [array] + +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"]` + +### `moduleFileExtensions` [array] + +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](https://github.com/kulshekhar/ts-jest). + +### `moduleNameMapper` [object] + +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 `` string token to refer to [`rootDir`](#rootdir-string) value if you want to use file paths. + +Additionally, you can substitute captured regex groups using numbered backreferences. + +Example: + +```json +{ + "moduleNameMapper": { + "^image![a-zA-Z0-9$_-]+$": "GlobalImageStub", + "^[./a-zA-Z0-9$_-]+\\.png$": "/RelativeImageStub.js", + "module_name_(.*)": "/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._ + +### `modulePathIgnorePatterns` [array] + +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 `` 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: `["/build/"]`. + +### `modulePaths` [array] + +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. Example: `["/app/"]`. + +### `notify` [boolean] + +Default: `false` + +Activates notifications for test results. + +### `notifyMode` [string] + +Default: `always` + +Specifies notification mode. Requires `notify: true`. + +#### Modes + +- `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. + +### `preset` [string] + +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` or `jest-preset.js` module at its top level. + +Presets may also be relative filesystem paths. + +```json +{ + "preset": "./node_modules/foo-bar/jest-preset.js" +} +``` + +### `prettierPath` [string] + +Default: `'prettier'` + +Sets the path to the [`prettier`](https://prettier.io/) node module used to update inline snapshots. + +### `projects` [array] + +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. + +```json +{ + "projects": ["", "/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](#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: + +```json +{ + "projects": [ + { + "displayName": "test" + }, + { + "displayName": "lint", + "runner": "jest-runner-eslint", + "testMatch": ["/**/*.js"] + } + ] +} +``` + +_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._ + +### `reporters` [array] + +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: + +```json +{ + "reporters": ["/my-custom-reporter.js"] +} +``` + +This will use custom reporter in addition to default reporters that Jest provides: + +```json +{ + "reporters": ["default", "/my-custom-reporter.js"] +} +``` + +Additionally, custom reporters can be configured by passing an `options` object as a second argument: + +```json +{ + "reporters": [ + "default", + ["/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: + +```js +// 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 + +```js +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](https://github.com/facebook/jest/blob/master/types/TestRunner.js) + +### `resetMocks` [boolean] + +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. + +### `resetModules` [boolean] + +Default: `false` + +By default, each test file gets its own independent module registry. Enabling `resetModules` goes a step further and resets the module registry 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()`](#jest-resetmodules). + +### `resolver` [string] + +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: + +```json +{ + "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. + +### `restoreMocks` [boolean] + +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. + +### `rootDir` [string] + +Default: The root of the directory containing your jest's [config file](#) _or_ the `package.json` _or_ the [`pwd`](http://en.wikipedia.org/wiki/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 `''` 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`](#setupfiles-array) config entry to point at the `env-setup.js` file at the root of your project, you could set its value to `["/env-setup.js"]`._ + +### `roots` [array] + +Default: `[""]` + +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 `` but there are cases where you may want to have multiple roots within one project, for example `roots: ["/src/", "/tests/"]`._ + +### `runner` [string] + +Default: `"jest-runner"` + +This option allows you to use a custom runner instead of Jest's default test runner. Examples of runners include: + +- [`jest-runner-eslint`](https://github.com/jest-community/jest-runner-eslint) +- [`jest-runner-mocha`](https://github.com/rogeliog/jest-runner-mocha) +- [`jest-runner-tsc`](https://github.com/azz/jest-runner-tsc) +- [`jest-runner-prettier`](https://github.com/keplersj/jest-runner-prettier) + +To write a test-runner, export a class with which accepts `globalConfig` in the constructor, and has a `runTests` method with the signature: + +```ts +async runTests( + tests: Array, + watcher: TestWatcher, + onStart: OnTestStart, + onResult: OnTestSuccess, + onFailure: OnTestFailure, + options: TestRunnerOptions, +): Promise +``` + +If you need to restrict your test-runner to only run in serial rather then being executed in parallel your class should have the property `isSerial` to be set as `true`. + +### `setupFiles` [array] + +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`](#setuptestframeworkscriptfile-string). + +### `setupTestFrameworkScriptFile` [string] + +Default: `undefined` + +The path to a module that runs some code to configure or set up the testing framework before each test. Since [`setupFiles`](#setupfiles-array) 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. + +If you want this path to be [relative to the root directory of your project](#rootdir-string), please include `` inside the path string, like `"/a-configs-folder"`. + +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] + +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](TutorialReactNative.md#snapshot-test) for more information. + +Example serializer module: + +```js +// 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: + +```json +{ + ... + "jest": { + "snapshotSerializers": ["my-serializer-module"] + } +} +``` + +Finally tests would look as follows: + +```js +test(() => { + const bar = { + foo: { + x: 1, + y: 2, + }, + }; + + expect(bar).toMatchSnapshot(); +}); +``` + +Rendered snapshot: + +```json +Pretty foo: Object { + "x": 1, + "y": 2, +} +``` + +To make a dependency explicit instead of implicit, you can call [`expect.addSnapshotSerializer`](ExpectAPI.md#expectaddsnapshotserializerserializer) to add a module for an individual test file instead of adding its path to `snapshotSerializers` in Jest configuration. + +### `testEnvironment` [string] + +Default: `"jsdom"` + +The test environment that will be used for testing. The default environment in Jest is a browser-like environment through [jsdom](https://github.com/tmpvar/jsdom). If you are building a node service, you can use the `node` option to use a node-like environment instead. + +By adding a `@jest-environment` docblock at the top of the file, you can specify another environment to be used for all tests in that file: + +```js +/** + * @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: + +```js +// 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); + } +} +``` + +```js +// my-test-suite +let someGlobalObject; + +beforeAll(() => { + someGlobalObject = global.someGlobalObject; +}); +``` + +### `testEnvironmentOptions` [Object] + +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](https://github.com/tmpvar/jsdom) such as `{userAgent: "Agent/007"}`. + +### `testMatch` [array] + +(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](https://github.com/jonschlinkert/micromatch) package for details of the patterns you can specify. + +See also [`testRegex` [string]](#testregex-string), but note that you cannot specify both options. + +### `testPathIgnorePatterns` [array] + +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 `` 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: `["/build/", "/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]](#testmatch-array-string), but note that you cannot specify both options. + +The following is a visualization of the default regex: + +```bash +├── __tests__ +│ └── component.spec.js # test +│ └── anything # test +├── package.json # not test +├── foo.test.js # test +├── bar.spec.jsx # test +└── component.js # not test +``` + +_Note: `testRegex` will try to detect test files using the **absolute file path** therefore having a folder with name that match it will run all the files as tests_ + +### `testResultsProcessor` [string] + +Default: `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: + +```json +{ + "success": bool, + "startTime": epoch, + "numTotalTestSuites": number, + "numPassedTestSuites": number, + "numFailedTestSuites": number, + "numRuntimeErrorTestSuites": number, + "numTotalTests": number, + "numPassedTests": number, + "numFailedTests": number, + "numPendingTests": number, + "openHandles": Array, + "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": {} + }, + ... + ] +} +``` + +### `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: + +```ts +function testRunner( + config: Config, + environment: Environment, + runtime: Runtime, + testPath: string, +): Promise; +``` + +An example of such function can be found in our default [jasmine2 test runner package](https://github.com/facebook/jest/blob/master/packages/jest-jasmine2/src/index.js). + +### `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] + +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. + +### `transform` [object] + +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](https://github.com/facebook/jest/blob/master/examples/typescript/package.json#L16) example or the [webpack tutorial](Webpack.md). + +Examples of such compilers include [Babel](https://babeljs.io/), [TypeScript](http://www.typescriptlang.org/) and [async-to-gen](http://github.com/leebyron/async-to-gen#jest). + +_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](Troubleshooting.md#caching-issues)._ + +_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](https://github.com/facebook/jest/tree/master/packages/babel-jest#setup)_ + +### `transformIgnorePatterns` [array] + +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 `` 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: `["/bower_components/", "/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](https://jestjs.io/docs/en/tutorial-react-native#transformignorepatterns-customization). + +### `unmockedModulePathPatterns` [array] + +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. + +### `verbose` [boolean] + +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. + +### `watchPathIgnorePatterns` [array] + +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 `` 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: `["/node_modules/"]`. diff --git a/website/versioned_docs/version-23.4/ExpectAPI.md b/website/versioned_docs/version-23.4/ExpectAPI.md new file mode 100644 index 000000000000..7b2dc31bbd3c --- /dev/null +++ b/website/versioned_docs/version-23.4/ExpectAPI.md @@ -0,0 +1,1149 @@ +--- +id: version-23.4-expect +title: Expect +original_id: expect +--- + +When you're writing tests, you often need to check that values meet certain conditions. `expect` gives you access to a number of "matchers" that let you validate different things. + +## Methods + + + +--- + +## Reference + +### `expect(value)` + +The `expect` function is used every time you want to test a value. You will rarely call `expect` by itself. Instead, you will use `expect` along with a "matcher" function to assert something about a value. + +It's easier to understand this with an example. Let's say you have a method `bestLaCroixFlavor()` which is supposed to return the string `'grapefruit'`. Here's how you would test that: + +```js +test('the best flavor is grapefruit', () => { + expect(bestLaCroixFlavor()).toBe('grapefruit'); +}); +``` + +In this case, `toBe` is the matcher function. There are a lot of different matcher functions, documented below, to help you test different things. + +The argument to `expect` should be the value that your code produces, and any argument to the matcher should be the correct value. If you mix them up, your tests will still work, but the error messages on failing tests will look strange. + +### `expect.extend(matchers)` + +You can use `expect.extend` to add your own matchers to Jest. For example, let's say that you're testing a number theory library and you're frequently asserting that numbers are divisible by other numbers. You could abstract that into a `toBeDivisibleBy` matcher: + +```js +expect.extend({ + toBeDivisibleBy(received, argument) { + const pass = received % argument == 0; + if (pass) { + return { + message: () => + `expected ${received} not to be divisible by ${argument}`, + pass: true, + }; + } else { + return { + message: () => `expected ${received} to be divisible by ${argument}`, + pass: false, + }; + } + }, +}); + +test('even and odd numbers', () => { + expect(100).toBeDivisibleBy(2); + expect(101).not.toBeDivisibleBy(2); + expect({apples: 6, bananas: 3}).toEqual({ + apples: expect.toBeDivisibleBy(2), + bananas: expect.not.toBeDivisibleBy(2), + }); +}); +``` + +`expect.extends` also supports async matchers. Async matchers return a Promise so you will need to await the returned value. Let's use an example matcher to illustrate the usage of them. We are going to implement a very similar matcher than `toBeDivisibleBy`, only difference is that the divisible number is going to be pulled from an external source. + +```js +expect.extend({ + async toBeDivisibleByExternalValue(received) { + const externalValue = await getExternalValueFromRemoteSource(); + const pass = received % externalValue == 0; + if (pass) { + return { + message: () => + `expected ${received} not to be divisible by ${externalValue}`, + pass: true, + }; + } else { + return { + message: () => + `expected ${received} to be divisible by ${externalValue}`, + pass: false, + }; + } + }, +}); + +test('is divisible by external value', async () => { + await expect(100).toBeDivisibleByExternalValue(); + await expect(101).not.toBeDivisibleByExternalValue(); +}); +``` + +Matchers should return an object (or a Promise of an object) with two keys. `pass` indicates whether there was a match or not, and `message` provides a function with no arguments that returns an error message in case of failure. Thus, when `pass` is false, `message` should return the error message for when `expect(x).yourMatcher()` fails. And when `pass` is true, `message` should return the error message for when `expect(x).not.yourMatcher()` fails. + +These helper functions can be found on `this` inside a custom matcher: + +#### `this.isNot` + +A boolean to let you know this matcher was called with the negated `.not` modifier allowing you to flip your assertion. + +#### `this.equals(a, b)` + +This is a deep-equality function that will return `true` if two objects have the same values (recursively). + +#### `this.utils` + +There are a number of helpful tools exposed on `this.utils` primarily consisting of the exports from [`jest-matcher-utils`](https://github.com/facebook/jest/tree/master/packages/jest-matcher-utils). + +The most useful ones are `matcherHint`, `printExpected` and `printReceived` to format the error messages nicely. For example, take a look at the implementation for the `toBe` matcher: + +```js +const diff = require('jest-diff'); +expect.extend({ + toBe(received, expected) { + const pass = Object.is(received, expected); + + const message = pass + ? () => + this.utils.matcherHint('.not.toBe') + + '\n\n' + + `Expected value to not be (using Object.is):\n` + + ` ${this.utils.printExpected(expected)}\n` + + `Received:\n` + + ` ${this.utils.printReceived(received)}` + : () => { + const diffString = diff(expected, received, { + expand: this.expand, + }); + return ( + this.utils.matcherHint('.toBe') + + '\n\n' + + `Expected value to be (using Object.is):\n` + + ` ${this.utils.printExpected(expected)}\n` + + `Received:\n` + + ` ${this.utils.printReceived(received)}` + + (diffString ? `\n\nDifference:\n\n${diffString}` : '') + ); + }; + + return {actual: received, message, pass}; + }, +}); +``` + +This will print something like this: + +```bash + expect(received).toBe(expected) + + Expected value to be (using Object.is): + "banana" + Received: + "apple" +``` + +When an assertion fails, the error message should give as much signal as necessary to the user so they can resolve their issue quickly. You should craft a precise failure message to make sure users of your custom assertions have a good developer experience. + +### `expect.anything()` + +`expect.anything()` matches anything but `null` or `undefined`. You can use it inside `toEqual` or `toBeCalledWith` instead of a literal value. For example, if you want to check that a mock function is called with a non-null argument: + +```js +test('map calls its argument with a non-null argument', () => { + const mock = jest.fn(); + [1].map(x => mock(x)); + expect(mock).toBeCalledWith(expect.anything()); +}); +``` + +### `expect.any(constructor)` + +`expect.any(constructor)` matches anything that was created with the given constructor. You can use it inside `toEqual` or `toBeCalledWith` instead of a literal value. For example, if you want to check that a mock function is called with a number: + +```js +function randocall(fn) { + return fn(Math.floor(Math.random() * 6 + 1)); +} + +test('randocall calls its callback with a number', () => { + const mock = jest.fn(); + randocall(mock); + expect(mock).toBeCalledWith(expect.any(Number)); +}); +``` + +### `expect.arrayContaining(array)` + +`expect.arrayContaining(array)` matches a received array which contains all of the elements in the expected array. That is, the expected array is a **subset** of the received array. Therefore, it matches a received array which contains elements that are **not** in the expected array. + +You can use it instead of a literal value: + +- in `toEqual` or `toBeCalledWith` +- to match a property in `objectContaining` or `toMatchObject` + +```js +describe('arrayContaining', () => { + const expected = ['Alice', 'Bob']; + it('matches even if received contains additional elements', () => { + expect(['Alice', 'Bob', 'Eve']).toEqual(expect.arrayContaining(expected)); + }); + it('does not match if received does not contain expected elements', () => { + expect(['Bob', 'Eve']).not.toEqual(expect.arrayContaining(expected)); + }); +}); +``` + +```js +describe('Beware of a misunderstanding! A sequence of dice rolls', () => { + const expected = [1, 2, 3, 4, 5, 6]; + it('matches even with an unexpected number 7', () => { + expect([4, 1, 6, 7, 3, 5, 2, 5, 4, 6]).toEqual( + expect.arrayContaining(expected), + ); + }); + it('does not match without an expected number 2', () => { + expect([4, 1, 6, 7, 3, 5, 7, 5, 4, 6]).not.toEqual( + expect.arrayContaining(expected), + ); + }); +}); +``` + +### `expect.assertions(number)` + +`expect.assertions(number)` verifies that a certain number of assertions are called during a test. This is often useful when testing asynchronous code, in order to make sure that assertions in a callback actually got called. + +For example, let's say that we have a function `doAsync` that receives two callbacks `callback1` and `callback2`, it will asynchronously call both of them in an unknown order. We can test this with: + +```js +test('doAsync calls both callbacks', () => { + expect.assertions(2); + function callback1(data) { + expect(data).toBeTruthy(); + } + function callback2(data) { + expect(data).toBeTruthy(); + } + + doAsync(callback1, callback2); +}); +``` + +The `expect.assertions(2)` call ensures that both callbacks actually get called. + +### `expect.hasAssertions()` + +`expect.hasAssertions()` verifies that at least one assertion is called during a test. This is often useful when testing asynchronous code, in order to make sure that assertions in a callback actually got called. + +For example, let's say that we have a few functions that all deal with state. `prepareState` calls a callback with a state object, `validateState` runs on that state object, and `waitOnState` returns a promise that waits until all `prepareState` callbacks complete. We can test this with: + +```js +test('prepareState prepares a valid state', () => { + expect.hasAssertions(); + prepareState(state => { + expect(validateState(state)).toBeTruthy(); + }); + return waitOnState(); +}); +``` + +The `expect.hasAssertions()` call ensures that the `prepareState` callback actually gets called. + +### `expect.not.arrayContaining(array)` + +`expect.not.arrayContaining(array)` matches a received array which contains none of the elements in the expected array. That is, the expected array **is not a subset** of the received array. + +It is the inverse of `expect.arrayContaining`. + +```js +describe('not.arrayContaining', () => { + const expected = ['Samantha']; + + it('matches if the actual array does not contain the expected elements', () => { + expect(['Alice', 'Bob', 'Eve']).toEqual( + expect.not.arrayContaining(expected), + ); + }); +}); +``` + +### `expect.not.objectContaining(object)` + +`expect.not.objectContaining(object)` matches any received object that does not recursively match the expected properties. That is, the expected object **is not a subset** of the received object. Therefore, it matches a received object which contains properties that are **not** in the expected object. + +It is the inverse of `expect.objectContaining`. + +```js +describe('not.objectContaining', () => { + const expected = {foo: 'bar'}; + + it('matches if the actual object does not contain expected key: value pairs', () => { + expect({bar: 'baz'}).toEqual(expect.not.objectContaining(expected)); + }); +}); +``` + +### `expect.not.stringContaining(string)` + +`expect.not.stringContaining(string)` matches the received string that does not contain the exact expected string. + +It is the inverse of `expect.stringContaining`. + +```js +describe('not.stringContaining', () => { + const expected = 'Hello world!'; + + it('matches if the actual string does not contain the expected substring', () => { + expect('How are you?').toEqual(expect.not.stringContaining(expected)); + }); +}); +``` + +### `expect.not.stringMatching(string | regexp)` + +`expect.not.stringMatching(string | regexp)` matches the received string that does not match the expected regexp. + +It is the inverse of `expect.stringMatching`. + +```js +describe('not.stringMatching', () => { + const expected = /Hello world!/; + + it('matches if the actual string does not match the expected regex', () => { + expect('How are you?').toEqual(expect.not.stringMatching(expected)); + }); +}); +``` + +### `expect.objectContaining(object)` + +`expect.objectContaining(object)` matches any received object that recursively matches the expected properties. That is, the expected object is a **subset** of the received object. Therefore, it matches a received object which contains properties that are **not** in the expected object. + +Instead of literal property values in the expected object, you can use matchers, `expect.anything()`, and so on. + +For example, let's say that we expect an `onPress` function to be called with an `Event` object, and all we need to verify is that the event has `event.x` and `event.y` properties. We can do that with: + +```js +test('onPress gets called with the right thing', () => { + const onPress = jest.fn(); + simulatePresses(onPress); + expect(onPress).toBeCalledWith( + expect.objectContaining({ + x: expect.any(Number), + y: expect.any(Number), + }), + ); +}); +``` + +### `expect.stringContaining(string)` + +`expect.stringContaining(string)` matches the received string that contains the exact expected string. + +### `expect.stringMatching(string | regexp)` + +`expect.stringMatching(string | regexp)` matches the received string that matches the expected regexp. + +You can use it instead of a literal value: + +- in `toEqual` or `toBeCalledWith` +- to match an element in `arrayContaining` +- to match a property in `objectContaining` or `toMatchObject` + +This example also shows how you can nest multiple asymmetric matchers, with `expect.stringMatching` inside the `expect.arrayContaining`. + +```js +describe('stringMatching in arrayContaining', () => { + const expected = [ + expect.stringMatching(/^Alic/), + expect.stringMatching(/^[BR]ob/), + ]; + it('matches even if received contains additional elements', () => { + expect(['Alicia', 'Roberto', 'Evelina']).toEqual( + expect.arrayContaining(expected), + ); + }); + it('does not match if received does not contain expected elements', () => { + expect(['Roberto', 'Evelina']).not.toEqual( + expect.arrayContaining(expected), + ); + }); +}); +``` + +### `expect.addSnapshotSerializer(serializer)` + +You can call `expect.addSnapshotSerializer` to add a module that formats application-specific data structures. + +For an individual test file, an added module precedes any modules from `snapshotSerializers` configuration, which precede the default snapshot serializers for built-in JavaScript types and for React elements. The last module added is the first module tested. + +```js +import serializer from 'my-serializer-module'; +expect.addSnapshotSerializer(serializer); + +// affects expect(value).toMatchSnapshot() assertions in the test file +``` + +If you add a snapshot serializer in individual test files instead of to adding it to `snapshotSerializers` configuration: + +- You make the dependency explicit instead of implicit. +- You avoid limits to configuration that might cause you to eject from [create-react-app](https://github.com/facebookincubator/create-react-app). + +See [configuring Jest](Configuration.md#snapshotserializers-array-string) for more information. + +### `.not` + +If you know how to test something, `.not` lets you test its opposite. For example, this code tests that the best La Croix flavor is not coconut: + +```js +test('the best flavor is not coconut', () => { + expect(bestLaCroixFlavor()).not.toBe('coconut'); +}); +``` + +### `.resolves` + +Use `resolves` to unwrap the value of a fulfilled promise so any other matcher can be chained. If the promise is rejected the assertion fails. + +For example, this code tests that the promise resolves and that the resulting value is `'lemon'`: + +```js +test('resolves to lemon', () => { + // make sure to add a return statement + return expect(Promise.resolve('lemon')).resolves.toBe('lemon'); +}); +``` + +Note that, since you are still testing promises, the test is still asynchronous. Hence, you will need to [tell Jest to wait](TestingAsyncCode.md#promises) by returning the unwrapped assertion. + +Alternatively, you can use `async/await` in combination with `.resolves`: + +```js +test('resolves to lemon', async () => { + await expect(Promise.resolve('lemon')).resolves.toBe('lemon'); + await expect(Promise.resolve('lemon')).resolves.not.toBe('octopus'); +}); +``` + +### `.rejects` + +Use `.rejects` to unwrap the reason of a rejected promise so any other matcher can be chained. If the promise is fulfilled the assertion fails. + +For example, this code tests that the promise rejects with reason `'octopus'`: + +```js +test('rejects to octopus', () => { + // make sure to add a return statement + return expect(Promise.reject(new Error('octopus'))).rejects.toThrow( + 'octopus', + ); +}); +``` + +Note that, since you are still testing promises, the test is still asynchronous. Hence, you will need to [tell Jest to wait](TestingAsyncCode.md#promises) by returning the unwrapped assertion. + +Alternatively, you can use `async/await` in combination with `.rejects`. + +```js +test('rejects to octopus', async () => { + await expect(Promise.reject(new Error('octopus'))).rejects.toThrow('octopus'); +}); +``` + +### `.toBe(value)` + +`toBe` just checks that a value is what you expect. It uses `Object.is` to check exact equality. + +For example, this code will validate some properties of the `can` object: + +```js +const can = { + name: 'pamplemousse', + ounces: 12, +}; + +describe('the can', () => { + test('has 12 ounces', () => { + expect(can.ounces).toBe(12); + }); + + test('has a sophisticated name', () => { + expect(can.name).toBe('pamplemousse'); + }); +}); +``` + +Don't use `toBe` with floating-point numbers. For example, due to rounding, in JavaScript `0.2 + 0.1` is not strictly equal to `0.3`. If you have floating point numbers, try `.toBeCloseTo` instead. + +### `.toHaveBeenCalled()` + +Also under the alias: `.toBeCalled()` + +Use `.toHaveBeenCalled` to ensure that a mock function got called. + +For example, let's say you have a `drinkAll(drink, flavor)` function that takes a `drink` function and applies it to all available beverages. You might want to check that `drink` gets called for `'lemon'`, but not for `'octopus'`, because `'octopus'` flavor is really weird and why would anything be octopus-flavored? You can do that with this test suite: + +```js +describe('drinkAll', () => { + test('drinks something lemon-flavored', () => { + const drink = jest.fn(); + drinkAll(drink, 'lemon'); + expect(drink).toHaveBeenCalled(); + }); + + test('does not drink something octopus-flavored', () => { + const drink = jest.fn(); + drinkAll(drink, 'octopus'); + expect(drink).not.toHaveBeenCalled(); + }); +}); +``` + +### `.toHaveBeenCalledTimes(number)` + +Also under the alias: `.toBeCalledTimes(number)` + +Use `.toHaveBeenCalledTimes` to ensure that a mock function got called exact number of times. + +For example, let's say you have a `drinkEach(drink, Array)` function that takes a `drink` function and applies it to array of passed beverages. You might want to check that drink function was called exact number of times. You can do that with this test suite: + +```js +test('drinkEach drinks each drink', () => { + const drink = jest.fn(); + drinkEach(drink, ['lemon', 'octopus']); + expect(drink).toHaveBeenCalledTimes(2); +}); +``` + +### `.toHaveBeenCalledWith(arg1, arg2, ...)` + +Also under the alias: `.toBeCalledWith()` + +Use `.toHaveBeenCalledWith` to ensure that a mock function was called with specific arguments. + +For example, let's say that you can register a beverage with a `register` function, and `applyToAll(f)` should apply the function `f` to all registered beverages. To make sure this works, you could write: + +```js +test('registration applies correctly to orange La Croix', () => { + const beverage = new LaCroix('orange'); + register(beverage); + const f = jest.fn(); + applyToAll(f); + expect(f).toHaveBeenCalledWith(beverage); +}); +``` + +### `.toHaveBeenLastCalledWith(arg1, arg2, ...)` + +Also under the alias: `.lastCalledWith(arg1, arg2, ...)` + +If you have a mock function, you can use `.toHaveBeenLastCalledWith` to test what arguments it was last called with. For example, let's say you have a `applyToAllFlavors(f)` function that applies `f` to a bunch of flavors, and you want to ensure that when you call it, the last flavor it operates on is `'mango'`. You can write: + +```js +test('applying to all flavors does mango last', () => { + const drink = jest.fn(); + applyToAllFlavors(drink); + expect(drink).toHaveBeenLastCalledWith('mango'); +}); +``` + +### `.toHaveBeenNthCalledWith(nthCall, arg1, arg2, ....)` + +Also under the alias: `.nthCalledWith(nthCall, arg1, arg2, ...)` + +If you have a mock function, you can use `.toHaveBeenNthCalledWith` to test what arguments it was nth called with. For example, let's say you have a `drinkEach(drink, Array)` function that applies `f` to a bunch of flavors, and you want to ensure that when you call it, the first flavor it operates on is `'lemon'` and the second one is `'octopus'`. You can write: + +```js +test('drinkEach drinks each drink', () => { + const drink = jest.fn(); + drinkEach(drink, ['lemon', 'octopus']); + expect(drink).toHaveBeenNthCalledWith(1, 'lemon'); + expect(drink).toHaveBeenNthCalledWith(2, 'octopus'); +}); +``` + +Note: the nth argument must be positive integer starting from 1. + +### `.toHaveReturned()` + +Also under the alias: `.toReturn()` + +If you have a mock function, you can use `.toHaveReturned` to test that the mock function successfully returned (i.e., did not throw an error) at least one time. For example, let's say you have a mock `drink` that returns `true`. You can write: + +```js +test('drinks returns', () => { + const drink = jest.fn(() => true); + + drink(); + + expect(drink).toHaveReturned(); +}); +``` + +### `.toHaveReturnedTimes(number)` + +Also under the alias: `.toReturnTimes(number)` + +Use `.toHaveReturnedTimes` to ensure that a mock function returned successfully (i.e., did not throw an error) an exact number of times. Any calls to the mock function that throw an error are not counted toward the number of times the function returned. + +For example, let's say you have a mock `drink` that returns `true`. You can write: + +```js +test('drink returns twice', () => { + const drink = jest.fn(() => true); + + drink(); + drink(); + + expect(drink).toHaveReturnedTimes(2); +}); +``` + +### `.toHaveReturnedWith(value)` + +Also under the alias: `.toReturnWith(value)` + +Use `.toHaveReturnedWith` to ensure that a mock function returned a specific value. + +For example, let's say you have a mock `drink` that returns the name of the beverage that was consumed. You can write: + +```js +test('drink returns La Croix', () => { + const beverage = {name: 'La Croix'}; + const drink = jest.fn(beverage => beverage.name); + + drink(beverage); + + expect(drink).toHaveReturnedWith('La Croix'); +}); +``` + +### `.toHaveLastReturnedWith(value)` + +Also under the alias: `.lastReturnedWith(value)` + +Use `.toHaveLastReturnedWith` to test the specific value that a mock function last returned. If the last call to the mock function threw an error, then this matcher will fail no matter what value you provided as the expected return value. + +For example, let's say you have a mock `drink` that returns the name of the beverage that was consumed. You can write: + +```js +test('drink returns La Croix (Orange) last', () => { + const beverage1 = {name: 'La Croix (Lemon)'}; + const beverage2 = {name: 'La Croix (Orange)'}; + const drink = jest.fn(beverage => beverage.name); + + drink(beverage1); + drink(beverage2); + + expect(drink).toHaveLastReturnedWith('La Croix (Orange)'); +}); +``` + +### `.toHaveNthReturnedWith(nthCall, value)` + +Also under the alias: `.nthReturnedWith(nthCall, value)` + +Use `.toHaveNthReturnedWith` to test the specific value that a mock function returned for the nth call. If the nth call to the mock function threw an error, then this matcher will fail no matter what value you provided as the expected return value. + +For example, let's say you have a mock `drink` that returns the name of the beverage that was consumed. You can write: + +```js +test('drink returns expected nth calls', () => { + const beverage1 = {name: 'La Croix (Lemon)'}; + const beverage2 = {name: 'La Croix (Orange)'}; + const drink = jest.fn(beverage => beverage.name); + + drink(beverage1); + drink(beverage2); + + expect(drink).toHaveNthReturnedWith(1, 'La Croix (Lemon)'); + expect(drink).toHaveNthReturnedWith(2, 'La Croix (Orange)'); +}); +``` + +Note: the nth argument must be positive integer starting from 1. + +### `.toBeCloseTo(number, numDigits)` + +Using exact equality with floating point numbers is a bad idea. Rounding means that intuitive things fail. For example, this test fails: + +```js +test('adding works sanely with simple decimals', () => { + expect(0.2 + 0.1).toBe(0.3); // Fails! +}); +``` + +It fails because in JavaScript, `0.2 + 0.1` is actually `0.30000000000000004`. Sorry. + +Instead, use `.toBeCloseTo`. Use `numDigits` to control how many digits after the decimal point to check. For example, if you want to be sure that `0.2 + 0.1` is equal to `0.3` with a precision of 5 decimal digits, you can use this test: + +```js +test('adding works sanely with simple decimals', () => { + expect(0.2 + 0.1).toBeCloseTo(0.3, 5); +}); +``` + +The default for `numDigits` is 2, which has proved to be a good default in most cases. + +### `.toBeDefined()` + +Use `.toBeDefined` to check that a variable is not undefined. For example, if you just want to check that a function `fetchNewFlavorIdea()` returns _something_, you can write: + +```js +test('there is a new flavor idea', () => { + expect(fetchNewFlavorIdea()).toBeDefined(); +}); +``` + +You could write `expect(fetchNewFlavorIdea()).not.toBe(undefined)`, but it's better practice to avoid referring to `undefined` directly in your code. + +### `.toBeFalsy()` + +Use `.toBeFalsy` when you don't care what a value is, you just want to ensure a value is false in a boolean context. For example, let's say you have some application code that looks like: + +```js +drinkSomeLaCroix(); +if (!getErrors()) { + drinkMoreLaCroix(); +} +``` + +You may not care what `getErrors` returns, specifically - it might return `false`, `null`, or `0`, and your code would still work. So if you want to test there are no errors after drinking some La Croix, you could write: + +```js +test('drinking La Croix does not lead to errors', () => { + drinkSomeLaCroix(); + expect(getErrors()).toBeFalsy(); +}); +``` + +In JavaScript, there are six falsy values: `false`, `0`, `''`, `null`, `undefined`, and `NaN`. Everything else is truthy. + +### `.toBeGreaterThan(number)` + +To compare floating point numbers, you can use `toBeGreaterThan`. For example, if you want to test that `ouncesPerCan()` returns a value of more than 10 ounces, write: + +```js +test('ounces per can is more than 10', () => { + expect(ouncesPerCan()).toBeGreaterThan(10); +}); +``` + +### `.toBeGreaterThanOrEqual(number)` + +To compare floating point numbers, you can use `toBeGreaterThanOrEqual`. For example, if you want to test that `ouncesPerCan()` returns a value of at least 12 ounces, write: + +```js +test('ounces per can is at least 12', () => { + expect(ouncesPerCan()).toBeGreaterThanOrEqual(12); +}); +``` + +### `.toBeLessThan(number)` + +To compare floating point numbers, you can use `toBeLessThan`. For example, if you want to test that `ouncesPerCan()` returns a value of less than 20 ounces, write: + +```js +test('ounces per can is less than 20', () => { + expect(ouncesPerCan()).toBeLessThan(20); +}); +``` + +### `.toBeLessThanOrEqual(number)` + +To compare floating point numbers, you can use `toBeLessThanOrEqual`. For example, if you want to test that `ouncesPerCan()` returns a value of at most 12 ounces, write: + +```js +test('ounces per can is at most 12', () => { + expect(ouncesPerCan()).toBeLessThanOrEqual(12); +}); +``` + +### `.toBeInstanceOf(Class)` + +Use `.toBeInstanceOf(Class)` to check that an object is an instance of a class. This matcher uses `instanceof` underneath. + +```js +class A {} + +expect(new A()).toBeInstanceOf(A); +expect(() => {}).toBeInstanceOf(Function); +expect(new A()).toBeInstanceOf(Function); // throws +``` + +### `.toBeNull()` + +`.toBeNull()` is the same as `.toBe(null)` but the error messages are a bit nicer. So use `.toBeNull()` when you want to check that something is null. + +```js +function bloop() { + return null; +} + +test('bloop returns null', () => { + expect(bloop()).toBeNull(); +}); +``` + +### `.toBeTruthy()` + +Use `.toBeTruthy` when you don't care what a value is, you just want to ensure a value is true in a boolean context. For example, let's say you have some application code that looks like: + +```js +drinkSomeLaCroix(); +if (thirstInfo()) { + drinkMoreLaCroix(); +} +``` + +You may not care what `thirstInfo` returns, specifically - it might return `true` or a complex object, and your code would still work. So if you just want to test that `thirstInfo` will be truthy after drinking some La Croix, you could write: + +```js +test('drinking La Croix leads to having thirst info', () => { + drinkSomeLaCroix(); + expect(thirstInfo()).toBeTruthy(); +}); +``` + +In JavaScript, there are six falsy values: `false`, `0`, `''`, `null`, `undefined`, and `NaN`. Everything else is truthy. + +### `.toBeUndefined()` + +Use `.toBeUndefined` to check that a variable is undefined. For example, if you want to check that a function `bestDrinkForFlavor(flavor)` returns `undefined` for the `'octopus'` flavor, because there is no good octopus-flavored drink: + +```js +test('the best drink for octopus flavor is undefined', () => { + expect(bestDrinkForFlavor('octopus')).toBeUndefined(); +}); +``` + +You could write `expect(bestDrinkForFlavor('octopus')).toBe(undefined)`, but it's better practice to avoid referring to `undefined` directly in your code. + +### `.toContain(item)` + +Use `.toContain` when you want to check that an item is in an array. For testing the items in the array, this uses `===`, a strict equality check. `.toContain` can also check whether a string is a substring of another string. + +For example, if `getAllFlavors()` returns an array of flavors and you want to be sure that `lime` is in there, you can write: + +```js +test('the flavor list contains lime', () => { + expect(getAllFlavors()).toContain('lime'); +}); +``` + +### `.toContainEqual(item)` + +Use `.toContainEqual` when you want to check that an item with a specific structure and values is contained in an array. For testing the items in the array, this matcher recursively checks the equality of all fields, rather than checking for object identity. + +```js +describe('my beverage', () => { + test('is delicious and not sour', () => { + const myBeverage = {delicious: true, sour: false}; + expect(myBeverages()).toContainEqual(myBeverage); + }); +}); +``` + +### `.toEqual(value)` + +Use `.toEqual` when you want to check that two objects have the same value. This matcher recursively checks the equality of all fields, rather than checking for object identity—this is also known as "deep equal". For example, `toEqual` and `toBe` behave differently in this test suite, so all the tests pass: + +```js +const can1 = { + flavor: 'grapefruit', + ounces: 12, +}; +const can2 = { + flavor: 'grapefruit', + ounces: 12, +}; + +describe('the La Croix cans on my desk', () => { + test('have all the same properties', () => { + expect(can1).toEqual(can2); + }); + test('are not the exact same can', () => { + expect(can1).not.toBe(can2); + }); +}); +``` + +> Note: `.toEqual` won't perform a _deep equality_ check for two errors. Only the `message` property of an Error is considered for equality. It is recommended to use the `.toThrow` matcher for testing against errors. + +### `.toHaveLength(number)` + +Use `.toHaveLength` to check that an object has a `.length` property and it is set to a certain numeric value. + +This is especially useful for checking arrays or strings size. + +```js +expect([1, 2, 3]).toHaveLength(3); +expect('abc').toHaveLength(3); +expect('').not.toHaveLength(5); +``` + +### `.toMatch(regexpOrString)` + +Use `.toMatch` to check that a string matches a regular expression. + +For example, you might not know what exactly `essayOnTheBestFlavor()` returns, but you know it's a really long string, and the substring `grapefruit` should be in there somewhere. You can test this with: + +```js +describe('an essay on the best flavor', () => { + test('mentions grapefruit', () => { + expect(essayOnTheBestFlavor()).toMatch(/grapefruit/); + expect(essayOnTheBestFlavor()).toMatch(new RegExp('grapefruit')); + }); +}); +``` + +This matcher also accepts a string, which it will try to match: + +```js +describe('grapefruits are healthy', () => { + test('grapefruits are a fruit', () => { + expect('grapefruits').toMatch('fruit'); + }); +}); +``` + +### `.toMatchObject(object)` + +Use `.toMatchObject` to check that a JavaScript object matches a subset of the properties of an object. It will match received objects with properties that are **not** in the expected object. + +You can also pass an array of objects, in which case the method will return true only if each object in the received array matches (in the `toMatchObject` sense described above) the corresponding object in the expected array. This is useful if you want to check that two arrays match in their number of elements, as opposed to `arrayContaining`, which allows for extra elements in the received array. + +You can match properties against values or against matchers. + +```js +const houseForSale = { + bath: true, + bedrooms: 4, + kitchen: { + amenities: ['oven', 'stove', 'washer'], + area: 20, + wallColor: 'white', + }, +}; +const desiredHouse = { + bath: true, + kitchen: { + amenities: ['oven', 'stove', 'washer'], + wallColor: expect.stringMatching(/white|yellow/), + }, +}; + +test('the house has my desired features', () => { + expect(houseForSale).toMatchObject(desiredHouse); +}); +``` + +```js +describe('toMatchObject applied to arrays arrays', () => { + test('the number of elements must match exactly', () => { + expect([{foo: 'bar'}, {baz: 1}]).toMatchObject([{foo: 'bar'}, {baz: 1}]); + }); + + // .arrayContaining "matches a received array which contains elements that + // are *not* in the expected array" + test('.toMatchObject does not allow extra elements', () => { + expect([{foo: 'bar'}, {baz: 1}]).toMatchObject([{foo: 'bar'}]); + }); + + test('.toMatchObject is called for each elements, so extra object properties are okay', () => { + expect([{foo: 'bar'}, {baz: 1, extra: 'quux'}]).toMatchObject([ + {foo: 'bar'}, + {baz: 1}, + ]); + }); +}); +``` + +### `.toHaveProperty(keyPath, value)` + +Use `.toHaveProperty` to check if property at provided reference `keyPath` exists for an object. For checking deeply nested properties in an object you may use [dot notation](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Operators/Property_accessors) or an array containing the keyPath for deep references. + +Optionally, you can provide a `value` to check if it's equal to the value present at `keyPath` on the target object. This matcher uses 'deep equality' (like `toEqual()`) and recursively checks the equality of all fields. + +The following example contains a `houseForSale` object with nested properties. We are using `toHaveProperty` to check for the existence and values of various properties in the object. + +```js +// Object containing house features to be tested +const houseForSale = { + bath: true, + bedrooms: 4, + kitchen: { + amenities: ['oven', 'stove', 'washer'], + area: 20, + wallColor: 'white', + 'nice.oven': true, + }, +}; + +test('this house has my desired features', () => { + // Simple Referencing + expect(houseForSale).toHaveProperty('bath'); + expect(houseForSale).toHaveProperty('bedrooms', 4); + + expect(houseForSale).not.toHaveProperty('pool'); + + // Deep referencing using dot notation + expect(houseForSale).toHaveProperty('kitchen.area', 20); + expect(houseForSale).toHaveProperty('kitchen.amenities', [ + 'oven', + 'stove', + 'washer', + ]); + + expect(houseForSale).not.toHaveProperty('kitchen.open'); + + // Deep referencing using an array containing the keyPath + expect(houseForSale).toHaveProperty(['kitchen', 'area'], 20); + expect(houseForSale).toHaveProperty( + ['kitchen', 'amenities'], + ['oven', 'stove', 'washer'], + ); + expect(houseForSale).toHaveProperty(['kitchen', 'amenities', 0], 'oven'); + expect(houseForSale).toHaveProperty(['kitchen', 'nice.oven']); + expect(houseForSale).not.toHaveProperty(['kitchen', 'open']); +}); +``` + +### `.toMatchSnapshot(propertyMatchers, snapshotName)` + +This ensures that a value matches the most recent snapshot. Check out [the Snapshot Testing guide](SnapshotTesting.md) for more information. + +The optional `propertyMatchers` argument allows you to specify asymmetric matchers which are verified instead of the exact values. + +The last argument allows you option to specify a snapshot name. Otherwise, the name is inferred from the test. + +_Note: While snapshot testing is most commonly used with React components, any serializable value can be used as a snapshot._ + +### `.toMatchInlineSnapshot(propertyMatchers, inlineSnapshot)` + +Ensures that a value matches the most recent snapshot. Unlike [`.toMatchSnapshot()`](#tomatchsnapshotpropertymatchers-snapshotname), the snapshots will be written to the current source file, inline. + +Check out the section on [Inline Snapshots](./SnapshotTesting.md#inline-snapshots) for more info. + +### `.toStrictEqual(value)` + +Use `.toStrictEqual` to test that objects have the same types as well as structure. + +Differences from `.toEqual`: + +- Keys with `undefined` properties are checked. e.g. `{a: undefined, b: 2}` does not match `{b: 2}` when using `.toStrictEqual`. +- Object types are checked to be equal. e.g. A class instance with fields `a` and `b` will not equal a literal object with fields `a` and `b`. + +```js +class LaCroix { + constructor(flavor) { + this.flavor = flavor; + } +} + +describe('the La Croix cans on my desk', () => { + test('are not semantically the same', () => { + expect(new LaCroix('lemon')).toEqual({flavor: 'lemon'}); + expect(new LaCroix('lemon')).not.toStrictEqual({flavor: 'lemon'}); + }); +}); +``` + +### `.toThrow(error)` + +Also under the alias: `.toThrowError(error)` + +Use `.toThrow` to test that a function throws when it is called. For example, if we want to test that `drinkFlavor('octopus')` throws, because octopus flavor is too disgusting to drink, we could write: + +```js +test('throws on octopus', () => { + expect(() => { + drinkFlavor('octopus'); + }).toThrow(); +}); +``` + +If you want to test that a specific error gets thrown, you can provide an argument to `toThrow`. The argument can be a string that should be contained in the error message, a class for the error, or a regex that should match the error message. For example, let's say that `drinkFlavor` is coded like this: + +```js +function drinkFlavor(flavor) { + if (flavor == 'octopus') { + throw new DisgustingFlavorError('yuck, octopus flavor'); + } + // Do some other stuff +} +``` + +We could test this error gets thrown in several ways: + +```js +test('throws on octopus', () => { + function drinkOctopus() { + drinkFlavor('octopus'); + } + + // Test that the error message says "yuck" somewhere: these are equivalent + expect(drinkOctopus).toThrowError(/yuck/); + expect(drinkOctopus).toThrowError('yuck'); + + // Test the exact error message + expect(drinkOctopus).toThrowError(/^yuck, octopus flavor$/); + + // Test that we get a DisgustingFlavorError + expect(drinkOctopus).toThrowError(DisgustingFlavorError); +}); +``` + +> Note: You must wrap the code in a function, otherwise the error will not be caught and the assertion will fail. + +### `.toThrowErrorMatchingSnapshot()` + +Use `.toThrowErrorMatchingSnapshot` to test that a function throws an error matching the most recent snapshot when it is called. For example, let's say you have a `drinkFlavor` function that throws whenever the flavor is `'octopus'`, and is coded like this: + +```js +function drinkFlavor(flavor) { + if (flavor == 'octopus') { + throw new DisgustingFlavorError('yuck, octopus flavor'); + } + // Do some other stuff +} +``` + +The test for this function will look this way: + +```js +test('throws on octopus', () => { + function drinkOctopus() { + drinkFlavor('octopus'); + } + + expect(drinkOctopus).toThrowErrorMatchingSnapshot(); +}); +``` + +And it will generate the following snapshot: + +```js +exports[`drinking flavors throws on octopus 1`] = `"yuck, octopus flavor"`; +``` + +Check out [React Tree Snapshot Testing](https://jestjs.io/blog/2016/07/27/jest-14.html) for more information on snapshot testing. + +### `.toThrowErrorMatchingInlineSnapshot()` + +This matcher is much like [`.toThrowErrorMatchingSnapshot`](#tothrowerrormatchingsnapshot), except instead of writing the snapshot value to a `.snap` file, it will be written into the source code automatically. + +Check out the section on [Inline Snapshots](./SnapshotTesting.md#inline-snapshots) for more info. diff --git a/website/versioned_docs/version-23.4/SnapshotTesting.md b/website/versioned_docs/version-23.4/SnapshotTesting.md new file mode 100644 index 000000000000..61a335ffc488 --- /dev/null +++ b/website/versioned_docs/version-23.4/SnapshotTesting.md @@ -0,0 +1,293 @@ +--- +id: version-23.4-snapshot-testing +title: Snapshot Testing +original_id: snapshot-testing +--- + +Snapshot tests are a very useful tool whenever you want to make sure your UI does not change unexpectedly. + +A typical snapshot test case for a mobile app renders a UI component, takes a screenshot, then compares it to a reference image stored alongside the test. The test will fail if the two images do not match: either the change is unexpected, or the screenshot needs to be updated to the new version of the UI component. + +## Snapshot Testing with Jest + +A similar approach can be taken when it comes to testing your React components. Instead of rendering the graphical UI, which would require building the entire app, you can use a test renderer to quickly generate a serializable value for your React tree. Consider this [example test](https://github.com/facebook/jest/blob/master/examples/snapshot/__tests__/link.react.test.js) for a simple [Link component](https://github.com/facebook/jest/blob/master/examples/snapshot/Link.react.js): + +```javascript +import React from 'react'; +import Link from '../Link.react'; +import renderer from 'react-test-renderer'; + +it('renders correctly', () => { + const tree = renderer + .create(Facebook) + .toJSON(); + expect(tree).toMatchSnapshot(); +}); +``` + +The first time this test is run, Jest creates a [snapshot file](https://github.com/facebook/jest/blob/master/examples/snapshot/__tests__/__snapshots__/link.react.test.js.snap) that looks like this: + +```javascript +exports[`renders correctly 1`] = ` + + Facebook + +`; +``` + +The snapshot artifact should be committed alongside code changes, and reviewed as part of your code review process. Jest uses [pretty-format](https://github.com/facebook/jest/tree/master/packages/pretty-format) to make snapshots human-readable during code review. On subsequent test runs Jest will simply compare the rendered output with the previous snapshot. If they match, the test will pass. If they don't match, either the test runner found a bug in your code that should be fixed, or the implementation has changed and the snapshot needs to be updated. + +More information on how snapshot testing works and why we built it can be found on the [release blog post](https://jestjs.io/blog/2016/07/27/jest-14.html). We recommend reading [this blog post](http://benmccormick.org/2016/09/19/testing-with-jest-snapshots-first-impressions/) to get a good sense of when you should use snapshot testing. We also recommend watching this [egghead video](https://egghead.io/lessons/javascript-use-jest-s-snapshot-testing-feature?pl=testing-javascript-with-jest-a36c4074) on Snapshot Testing with Jest. + +### Updating Snapshots + +It's straightforward to spot when a snapshot test fails after a bug has been introduced. When that happens, go ahead and fix the issue and make sure your snapshot tests are passing again. Now, let's talk about the case when a snapshot test is failing due to an intentional implementation change. + +One such situation can arise if we intentionally change the address the Link component in our example is pointing to. + +```javascript +// Updated test case with a Link to a different address +it('renders correctly', () => { + const tree = renderer + .create(Instagram) + .toJSON(); + expect(tree).toMatchSnapshot(); +}); +``` + +In that case, Jest will print this output: + +![](/img/content/failedSnapshotTest.png) + +Since we just updated our component to point to a different address, it's reasonable to expect changes in the snapshot for this component. Our snapshot test case is failing because the snapshot for our updated component no longer matches the snapshot artifact for this test case. + +To resolve this, we will need to update our snapshot artifacts. You can run Jest with a flag that will tell it to re-generate snapshots: + +```bash +jest --updateSnapshot +``` + +Go ahead and accept the changes by running the above command. You may also use the equivalent single-character `-u` flag to re-generate snapshots if you prefer. This will re-generate snapshot artifacts for all failing snapshot tests. If we had any additional failing snapshot tests due to an unintentional bug, we would need to fix the bug before re-generating snapshots to avoid recording snapshots of the buggy behavior. + +If you'd like to limit which snapshot test cases get re-generated, you can pass an additional `--testNamePattern` flag to re-record snapshots only for those tests that match the pattern. + +You can try out this functionality by cloning the [snapshot example](https://github.com/facebook/jest/tree/master/examples/snapshot), modifying the `Link` component, and running Jest. + +### Interactive Snapshot Mode + +Failed snapshots can also be updated interactively in watch mode: + +![](/img/content/interactiveSnapshot.png) + +Once you enter Interactive Snapshot Mode, Jest will step you through the failed snapshots one test at a time and give you the opportunity to review the failed output. + +From here you can choose to update that snapshot or skip to the next: + +![](/img/content/interactiveSnapshotUpdate.gif) + +Once you're finished, Jest will give you a summary before returning back to watch mode: + +![](/img/content/interactiveSnapshotDone.png) + +### Inline Snapshots + +Inline snapshots behave identically to external snapshots (`.snap` files), except the snapshot values are written automatically back into the source code. This means you can get the benefits of automatically generated snapshots without having to switch to an external file to make sure the correct value was written. + +> Inline snapshots are powered by [Prettier](https://prettier.io). To use inline snapshots you must have `prettier` installed in your project. Your Prettier configuration will be respected when writing to test files. +> +> If you have `prettier` installed in a location where Jest can't find it, you can tell Jest how to find it using the [`"prettierPath"`](./Configuration.md#prettierpath-string) configuration property. + +**Example:** + +First, you write a test, calling `.toMatchInlineSnapshot()` with no arguments: + +```javascript +it('renders correctly', () => { + const tree = renderer + .create(Prettier) + .toJSON(); + expect(tree).toMatchInlineSnapshot(); +}); +``` + +The next time you run Jest, `tree` will be evaluated, and a snapshot will be written as an argument to `toMatchInlineSnapshot`: + +```javascript +it('renders correctly', () => { + const tree = renderer + .create(Prettier) + .toJSON(); + expect(tree).toMatchInlineSnapshot(` + + Prettier + +`); +}); +``` + +That's all there is to it! You can even update the snapshots with `--updateSnapshot` or using the `u` key in `--watch` mode. + +### Property Matchers + +Often there are fields in the object you want to snapshot which are generated (like IDs and Dates). If you try to snapshot these objects, they will force the snapshot to fail on every run: + +```javascript +it('will fail every time', () => { + const user = { + createdAt: new Date(), + id: Math.floor(Math.random() * 20), + name: 'LeBron James', + }; + + expect(user).toMatchSnapshot(); +}); + +// Snapshot +exports[`will fail every time 1`] = ` +Object { + "createdAt": 2018-05-19T23:36:09.816Z, + "id": 3, + "name": "LeBron James", +} +`; +``` + +For these cases, Jest allows providing an asymmetric matcher for any property. These matchers are checked before the snapshot is written or tested, and then saved to the snapshot file instead of the received value: + +```javascript +it('will check the matchers and pass', () => { + const user = { + createdAt: new Date(), + id: Math.floor(Math.random() * 20), + name: 'LeBron James', + }; + + expect(user).toMatchSnapshot({ + createdAt: expect.any(Date), + id: expect.any(Number), + }); +}); + +// Snapshot +exports[`will check the matchers and pass 1`] = ` +Object { + "createdAt": Any, + "id": Any, + "name": "LeBron James", +} +`; +``` + +## Best Practices + +Snapshots are a fantastic tool for identifying unexpected interface changes within your application – whether that interface is an API response, UI, logs, or error messages. As with any testing strategy, there are some best-practices you should be aware of, and guidelines you should follow, in order to use them effectively. + +### 1. Treat snapshots as code + +Commit snapshots and review them as part of your regular code review process. This means treating snapshots as you would any other type of test or code in your project. + +Ensure that your snapshots are readable by keeping them focused, short, and by using tools that enforce these stylistic conventions. + +As mentioned previously, Jest uses [`pretty-format`](https://yarnpkg.com/en/package/pretty-format) to make snapshots human-readable, but you may find it useful to introduce additional tools, like [`eslint-plugin-jest`](https://yarnpkg.com/en/package/eslint-plugin-jest) with its [`no-large-snapshots`](https://github.com/jest-community/eslint-plugin-jest/blob/master/docs/rules/no-large-snapshots.md) option, or [`snapshot-diff`](https://yarnpkg.com/en/package/snapshot-diff) with its component snapshot comparison feature, to promote committing short, focused assertions. + +The goal is to make it easy to review snapshots in pull requests, and fight against the habit of simply regenerating snapshots when test suites fail instead of examining the root causes of their failure. + +### 2. Tests should be deterministic + +Your tests should be deterministic. Running the same tests multiple times on a component that has not changed should produce the same results every time. You're responsible for making sure your generated snapshots do not include platform specific or other non-deterministic data. + +For example, if you have a [Clock](https://github.com/facebook/jest/blob/master/examples/snapshot/Clock.react.js) component that uses `Date.now()`, the snapshot generated from this component will be different every time the test case is run. In this case we can [mock the Date.now() method](MockFunctions.md) to return a consistent value every time the test is run: + +```js +Date.now = jest.fn(() => 1482363367071); +``` + +Now, every time the snapshot test case runs, `Date.now()` will return `1482363367071` consistently. This will result in the same snapshot being generated for this component regardless of when the test is run. + +### 3. Use descriptive snapshot names + +Always strive to use descriptive test and/or snapshot names for snapshots. The best names describe the expected snapshot content. This makes it easier for reviewers to verify the snapshots during review, and for anyone to know whether or not an outdated snapshot is the correct behavior before updating. + +For example, compare: + +```js +exports[` should handle some test case`] = `null`; + +exports[` should handle some other test case`] = ` +
+ Alan Turing +
+`; +``` + +To: + +```js +exports[` should render null`] = `null`; + +exports[` should render Alan Turing`] = ` +
+ Alan Turing +
+`; +``` + +Since the later describes exactly what's expected in the output, it's easy to see when it's wrong: + +```js +exports[` should render null`] = ` +
+ Alan Turing +
+`; + +exports[` should render Alan Turing`] = `null`; +``` + +## Frequently Asked Questions + +### Are snapshots written automatically on Continuous Integration (CI) systems? + +No, as of Jest 20, snapshots in Jest are not automatically written when Jest is run in a CI system without explicitly passing `--updateSnapshot`. It is expected that all snapshots are part of the code that is run on CI and since new snapshots automatically pass, they should not pass a test run on a CI system. It is recommended to always commit all snapshots and to keep them in version control. + +### Should snapshot files be committed? + +Yes, all snapshot files should be committed alongside the modules they are covering and their tests. They should be considered as part of a test, similar to the value of any other assertion in Jest. In fact, snapshots represent the state of the source modules at any given point in time. In this way, when the source modules are modified, Jest can tell what changed from the previous version. It can also provide a lot of additional context during code review in which reviewers can study your changes better. + +### Does snapshot testing only work with React components? + +[React](TutorialReact.md) and [React Native](TutorialReactNative.md) components are a good use case for snapshot testing. However, snapshots can capture any serializable value and should be used anytime the goal is testing whether the output is correct. The Jest repository contains many examples of testing the output of Jest itself, the output of Jest's assertion library as well as log messages from various parts of the Jest codebase. See an example of [snapshotting CLI output](https://github.com/facebook/jest/blob/master/e2e/__tests__/console.test.js) in the Jest repo. + +### What's the difference between snapshot testing and visual regression testing? + +Snapshot testing and visual regression testing are two distinct ways of testing UIs, and they serve different purposes. Visual regression testing tools take screenshots of web pages and compare the resulting images pixel by pixel. With Snapshot testing values are serialized, stored within text files and compared using a diff algorithm. There are different trade-offs to consider and we listed the reasons why snapshot testing was built in the [Jest blog](https://jestjs.io/blog/2016/07/27/jest-14.html#why-snapshot-testing). + +### Does snapshot testing substitute unit testing? + +Snapshot testing is only one of more than 20 assertions that ship with Jest. The aim of snapshot testing is not to replace existing unit tests, but providing additional value and making testing painless. In some scenarios, snapshot testing can potentially remove the need for unit testing for a particular set of functionalities (e.g. React components), but they can work together as well. + +### What is the performance of snapshot testing regarding speed and size of the generated files? + +Jest has been rewritten with performance in mind, and snapshot testing is not an exception. Since snapshots are stored within text files, this way of testing is fast and reliable. Jest generates a new file for each test file that invokes the `toMatchSnapshot` matcher. The size of the snapshots is pretty small: For reference, the size of all snapshot files in the Jest codebase itself is less than 300 KB. + +### How do I resolve conflicts within snapshot files? + +Snapshot files must always represent the current state of the modules they are covering. Therefore, if you are merging two branches and encounter a conflict in the snapshot files, you can either resolve the conflict manually or to update the snapshot file by running Jest and inspecting the result. + +### Is it possible to apply test-driven development principles with snapshot testing? + +Although it is possible to write snapshot files manually, that is usually not approachable. Snapshots help figuring out whether the output of the modules covered by tests is changed, rather than giving guidance to design the code in the first place. + +### Does code coverage work with snapshots testing? + +Yes, just like with any other test. diff --git a/website/versioned_docs/version-23.5/CLI.md b/website/versioned_docs/version-23.5/CLI.md new file mode 100644 index 000000000000..e1935760238b --- /dev/null +++ b/website/versioned_docs/version-23.5/CLI.md @@ -0,0 +1,296 @@ +--- +id: version-23.5-cli +title: Jest CLI Options +original_id: cli +--- + +The `jest` command line runner has a number of useful options. You can run `jest --help` to view all available options. Many of the options shown below can also be used together to run tests exactly the way you want. Every one of Jest's [Configuration](Configuration.md) options can also be specified through the CLI. + +Here is a brief overview: + +## Running from the command line + +Run all tests (default): + +```bash +jest +``` + +Run only the tests that were specified with a pattern or filename: + +```bash +jest my-test #or +jest path/to/my-test.js +``` + +Run tests related to changed files based on hg/git (uncommitted files): + +```bash +jest -o +``` + +Run tests related to `path/to/fileA.js` and `path/to/fileB.js`: + +```bash +jest --findRelatedTests path/to/fileA.js path/to/fileB.js +``` + +Run tests that match this spec name (match against the name in `describe` or `test`, basically). + +```bash +jest -t name-of-spec +``` + +Run watch mode: + +```bash +jest --watch #runs jest -o by default +jest --watchAll #runs all tests +``` + +Watch mode also enables to specify the name or path to a file to focus on a specific set of tests. + +## Using with yarn + +If you run Jest via `yarn test`, you can pass the command line arguments directly as Jest arguments. + +Instead of: + +```bash +jest -u -t="ColorPicker" +``` + +you can use: + +```bash +yarn test -u -t="ColorPicker" +``` + +## Using with npm scripts + +If you run Jest via `npm test`, you can still use the command line arguments by inserting a `--` between `npm test` and the Jest arguments. + +Instead of: + +```bash +jest -u -t="ColorPicker" +``` + +you can use: + +```bash +npm test -- -u -t="ColorPicker" +``` + +## Options + +_Note: CLI options take precedence over values from the [Configuration](Configuration.md)._ + + + +--- + +## Reference + +### `jest ` + +When you run `jest` with an argument, that argument is treated as a regular expression to match against files in your project. It is possible to run test suites by providing a pattern. Only the files that the pattern matches will be picked up and executed. Depending on your terminal, you may need to quote this argument: `jest "my.*(complex)?pattern"`. On Windows, you will need to use `/` as a path separator or escape `\` as `\\`. + +### `--bail` + +Alias: `-b`. Exit the test suite immediately upon the first failing test suite. + +### `--cache` + +Whether to use the cache. Defaults to true. Disable the cache using `--no-cache`. _Note: the cache should only be disabled if you are experiencing caching related problems. On average, disabling the cache makes Jest at least two times slower._ + +If you want to inspect the cache, use `--showConfig` and look at the `cacheDirectory` value. If you need to clear the cache, use `--clearCache`. + +### `--changedFilesWithAncestor` + +Runs tests related to the current changes and the changes made in the last commit. Behaves similarly to `--onlyChanged`. + +### `--changedSince` + +Runs tests related the changes since the provided branch. If the current branch has diverged from the given branch, then only changes made locally will be tested. Behaves similarly to `--onlyChanged`. + +### `--ci` + +When this option is provided, Jest will assume it is running in a CI environment. This changes the behavior when a new snapshot is encountered. Instead of the regular behavior of storing a new snapshot automatically, it will fail the test and require Jest to be run with `--updateSnapshot`. + +### `--clearCache` + +Deletes the Jest cache directory and then exits without running tests. Will delete `cacheDirectory` if the option is passed, or Jest's default cache directory. The default cache directory can be found by calling `jest --showConfig`. _Note: clearing the cache will reduce performance._ + +### `--collectCoverageFrom=` + +A glob pattern relative to matching the files that coverage info needs to be collected from. + +### `--colors` + +Forces test results output highlighting even if stdout is not a TTY. + +### `--config=` + +Alias: `-c`. The path to a Jest config file specifying how to find and execute tests. If no `rootDir` is set in the config, the current directory is assumed to be the rootDir for the project. This can also be a JSON-encoded value which Jest will use as configuration. + +### `--coverage` + +Indicates that test coverage information should be collected and reported in the output. This option is also aliased by `--collectCoverage`. + +### `--debug` + +Print debugging info about your Jest config. + +### `--detectOpenHandles` + +Attempt to collect and print open handles preventing Jest from exiting cleanly. Use this in cases where you need to use `--forceExit` in order for Jest to exit to potentially track down the reason. Implemented using [`async_hooks`](https://nodejs.org/api/async_hooks.html), so it only works in Node 8 and newer. + +### `--env=` + +The test environment used for all tests. This can point to any file or node module. Examples: `jsdom`, `node` or `path/to/my-environment.js`. + +### `--errorOnDeprecated` + +Make calling deprecated APIs throw helpful error messages. Useful for easing the upgrade process. + +### `--expand` + +Alias: `-e`. Use this flag to show full diffs and errors instead of a patch. + +### `--findRelatedTests ` + +Find and run the tests that cover a space separated list of source files that were passed in as arguments. Useful for pre-commit hook integration to run the minimal amount of tests necessary. Can be used together with `--coverage` to include a test coverage for the source files, no duplicate `--collectCoverageFrom` arguments needed. + +### `--forceExit` + +Force Jest to exit after all tests have completed running. This is useful when resources set up by test code cannot be adequately cleaned up. _Note: This feature is an escape-hatch. If Jest doesn't exit at the end of a test run, it means external resources are still being held on to or timers are still pending in your code. It is advised to tear down external resources after each test to make sure Jest can shut down cleanly. You can use `--detectOpenHandles` to help track it down._ + +### `--help` + +Show the help information, similar to this page. + +### `--init` + +Generate a basic configuration file. Based on your project, Jest will ask you a few questions that will help to generate a `jest.config.js` file with a short description for each option. + +### `--json` + +Prints the test results in JSON. This mode will send all other test output and user messages to stderr. + +### `--outputFile=` + +Write test results to a file when the `--json` option is also specified. + +### `--lastCommit` + +Run all tests affected by file changes in the last commit made. Behaves similarly to `--onlyChanged`. + +### `--listTests` + +Lists all tests as JSON that Jest will run given the arguments, and exits. This can be used together with `--findRelatedTests` to know which tests Jest will run. + +### `--logHeapUsage` + +Logs the heap usage after every test. Useful to debug memory leaks. Use together with `--runInBand` and `--expose-gc` in node. + +### `--maxWorkers=` + +Alias: `-w`. Specifies the maximum number of workers the worker-pool will spawn for running tests. This defaults to the number of the cores available on your machine. It may be useful to adjust this in resource limited environments like CIs but the default should be adequate for most use-cases. + +### `--noStackTrace` + +Disables stack trace in test results output. + +### `--notify` + +Activates notifications for test results. Good for when you don't want your consciousness to be able to focus on anything except JavaScript testing. + +### `--onlyChanged` + +Alias: `-o`. Attempts to identify which tests to run based on which files have changed in the current repository. Only works if you're running tests in a git/hg repository at the moment and requires a static dependency graph (ie. no dynamic requires). + +### `--passWithNoTests` + +Allows the test suite to pass when no files are found. + +### `--projects ... ` + +Run tests from one or more projects. + +### `--reporters` + +Run tests with specified reporters. [Reporter options](configuration#reporters-array-modulename-modulename-options) are not available via CLI. Example with multiple reporters: + +`jest --reporters="default" --reporters="jest-junit"` + +### `--runInBand` + +Alias: `-i`. Run all tests serially in the current process, rather than creating a worker pool of child processes that run tests. This can be useful for debugging. + +### `--setupTestFrameworkScriptFile=` + +The path to a module that runs some code to configure or set up the testing framework before each test. Beware that files imported by the setup script will not be mocked during testing. + +### `--showConfig` + +Print your Jest config and then exits. + +### `--silent` + +Prevent tests from printing messages through the console. + +### `--testNamePattern=` + +Alias: `-t`. Run only tests with a name that matches the regex. For example, suppose you want to run only tests related to authorization which will have names like `"GET /api/posts with auth"`, then you can use `jest -t=auth`. + +_Note: The regex is matched against the full name, which is a combination of the test name and all its surrounding describe blocks._ + +### `--testLocationInResults` + +Adds a `location` field to test results. Useful if you want to report the location of a test in a reporter. + +Note that `column` is 0-indexed while `line` is not. + +```json +{ + "column": 4, + "line": 5 +} +``` + +### `--testPathPattern=` + +A regexp pattern string that is matched against all tests paths before executing the test. On Windows, you will need to use `/` as a path separator or escape `\` as `\\`. + +### `--testRunner=` + +Lets you specify a custom test runner. + +### `--updateSnapshot` + +Alias: `-u`. Use this flag to re-record every snapshot that fails during this test run. Can be used together with a test suite pattern or with `--testNamePattern` to re-record snapshots. + +### `--useStderr` + +Divert all output to stderr. + +### `--verbose` + +Display individual test results with the test suite hierarchy. + +### `--version` + +Alias: `-v`. Print the version and exit. + +### `--watch` + +Watch files for changes and rerun tests related to changed files. If you want to re-run all tests when a file has changed, use the `--watchAll` option instead. + +### `--watchAll` + +Watch files for changes and rerun all tests when something changes. If you want to re-run only the tests that depend on the changed files, use the `--watch` option. + +### `--watchman` + +Whether to use watchman for file crawling. Defaults to true. Disable using `--no-watchman`. diff --git a/website/versioned_docs/version-23.5/Configuration.md b/website/versioned_docs/version-23.5/Configuration.md new file mode 100644 index 000000000000..fe7b10e2845e --- /dev/null +++ b/website/versioned_docs/version-23.5/Configuration.md @@ -0,0 +1,930 @@ +--- +id: version-23.5-configuration +title: Configuring Jest +original_id: configuration +--- + +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 ` 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: + +```json +{ + "name": "my-project", + "jest": { + "verbose": true + } +} +``` + +Or through JavaScript: + +```js +// 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: + +```json +{ + "bail": true, + "verbose": true +} +``` + +## Options + +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. + +### Defaults + +You can retrieve Jest's default options to expand them if needed: + +```js +// jest.config.js +const {defaults} = require('jest-config'); +module.exports = { + // ... + moduleFileExtensions: [...defaults.moduleFileExtensions, 'ts', 'tsx'], + // ... +}; +``` + + + +--- + +## Reference + +### `automock` [boolean] + +Default: `false` + +This option tells Jest that all imported modules in your tests should be mocked automatically. All modules used in your tests will have a replacement implementation, keeping the API surface. + +Example: + +```js +// utils.js +export default { + authorize: () => { + return 'token'; + }, + isAuthorized: secret => secret === 'wizard', +}; +``` + +```js +//__tests__/automocking.test.js +import utils from '../utils'; + +test('if utils mocked automatically', () => { + // Public methods of `utils` are now mock functions + expect(utils.authorize.mock).toBeTruthy(); + expect(utils.isAuthorized.mock).toBeTruthy(); + + // You can provide them with your own implementation + // or just pass the expected return value + utils.authorize.mockReturnValue('mocked_token'); + utils.isAuthorized.mockReturnValue(true); + + expect(utils.authorize()).toBe('mocked_token'); + expect(utils.isAuthorized('not_wizard')).toBeTruthy(); +}); +``` + +_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](troubleshooting.html#tests-are-slow-when-leveraging-automocking) for details and a workaround._ + +### `bail` [boolean] + +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. + +### `browser` [boolean] + +Default: `false` + +Respect Browserify's [`"browser"` field](https://github.com/substack/browserify-handbook#browser-field) in `package.json` when resolving modules. Some modules export different versions based on whether they are operating in Node or a browser. + +### `cacheDirectory` [string] + +Default: `"/tmp/"` + +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. + +### `clearMocks` [boolean] + +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. + +### `collectCoverage` [boolean] + +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. + +### `collectCoverageFrom` [array] + +Default: `undefined` + +An array of [glob patterns](https://github.com/jonschlinkert/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. + +Example: + +```json +{ + "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`._ + +
+ Help: + If you are seeing coverage output such as... + +``` +=============================== Coverage summary =============================== +Statements : Unknown% ( 0/0 ) +Branches : Unknown% ( 0/0 ) +Functions : Unknown% ( 0/0 ) +Lines : Unknown% ( 0/0 ) +================================================================================ +Jest: Coverage data for global was not found. +``` + +Most likely your glob patterns are not matching any files. Refer to the [micromatch](https://github.com/jonschlinkert/micromatch) documentation to ensure your globs are compatible. + +
+ +### `coverageDirectory` [string] + +Default: `undefined` + +The directory where Jest should output its coverage files. + +### `coveragePathIgnorePatterns` [array] + +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 `` 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: `["/build/", "/node_modules/"]`. + +### `coverageReporters` [array] + +Default: `["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._ + +### `coverageThreshold` [object] + +Default: `undefined` + +This will be used to configure minimum threshold enforcement for coverage results. Thresholds can be specified as `global`, as a [glob](https://github.com/isaacs/node-glob#glob-primer), 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: + +```json +{ + ... + "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: + +```json +{ + ... + "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/components` directory has less than 40% branch or statement coverage. +- One of the files matching the `./src/reducers/**/*.js` glob has less than 90% statement coverage. +- The `./src/api/very-important-module.js` file has less than 100% coverage. +- Every remaining file combined has less than 50% coverage (`global`). + +### `errorOnDeprecated` [boolean] + +Default: `false` + +Make calling deprecated APIs throw helpful error messages. Useful for easing the upgrade process. + +### `forceCoverageMatch` [array] + +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: + +```javascript +// 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`. + +```json +{ + ... + "jest": { + "forceCoverageMatch": ["**/*.t.js"] + } +} +``` + +### `globals` [object] + +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: + +```json +{ + ... + "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`. + +### `globalSetup` [string] + +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. This function gets Jest's `globalConfig` object as a parameter. + +### `globalTeardown` [string] + +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. This function gets Jest's `globalConfig` object as a parameter. + +### `moduleDirectories` [array] + +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"]` + +### `moduleFileExtensions` [array] + +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](https://github.com/kulshekhar/ts-jest). + +### `moduleNameMapper` [object] + +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 `` string token to refer to [`rootDir`](#rootdir-string) value if you want to use file paths. + +Additionally, you can substitute captured regex groups using numbered backreferences. + +Example: + +```json +{ + "moduleNameMapper": { + "^image![a-zA-Z0-9$_-]+$": "GlobalImageStub", + "^[./a-zA-Z0-9$_-]+\\.png$": "/RelativeImageStub.js", + "module_name_(.*)": "/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._ + +### `modulePathIgnorePatterns` [array] + +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 `` 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: `["/build/"]`. + +### `modulePaths` [array] + +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. Example: `["/app/"]`. + +### `notify` [boolean] + +Default: `false` + +Activates notifications for test results. + +### `notifyMode` [string] + +Default: `always` + +Specifies notification mode. Requires `notify: true`. + +#### Modes + +- `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. + +### `preset` [string] + +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` or `jest-preset.js` module at its top level. + +Presets may also be relative filesystem paths. + +```json +{ + "preset": "./node_modules/foo-bar/jest-preset.js" +} +``` + +### `prettierPath` [string] + +Default: `'prettier'` + +Sets the path to the [`prettier`](https://prettier.io/) node module used to update inline snapshots. + +### `projects` [array] + +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. + +```json +{ + "projects": ["", "/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](#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: + +```json +{ + "projects": [ + { + "displayName": "test" + }, + { + "displayName": "lint", + "runner": "jest-runner-eslint", + "testMatch": ["/**/*.js"] + } + ] +} +``` + +_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._ + +### `reporters` [array] + +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: + +```json +{ + "reporters": ["/my-custom-reporter.js"] +} +``` + +This will use custom reporter in addition to default reporters that Jest provides: + +```json +{ + "reporters": ["default", "/my-custom-reporter.js"] +} +``` + +Additionally, custom reporters can be configured by passing an `options` object as a second argument: + +```json +{ + "reporters": [ + "default", + ["/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: + +```js +// 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 + +```js +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](https://github.com/facebook/jest/blob/master/types/TestRunner.js) + +### `resetMocks` [boolean] + +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. + +### `resetModules` [boolean] + +Default: `false` + +By default, each test file gets its own independent module registry. Enabling `resetModules` goes a step further and resets the module registry 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()`](#jest-resetmodules). + +### `resolver` [string] + +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: + +```json +{ + "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. + +### `restoreMocks` [boolean] + +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. + +### `rootDir` [string] + +Default: The root of the directory containing your jest's [config file](#) _or_ the `package.json` _or_ the [`pwd`](http://en.wikipedia.org/wiki/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 `''` 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`](#setupfiles-array) config entry to point at the `env-setup.js` file at the root of your project, you could set its value to `["/env-setup.js"]`._ + +### `roots` [array] + +Default: `[""]` + +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 `` but there are cases where you may want to have multiple roots within one project, for example `roots: ["/src/", "/tests/"]`._ + +### `runner` [string] + +Default: `"jest-runner"` + +This option allows you to use a custom runner instead of Jest's default test runner. Examples of runners include: + +- [`jest-runner-eslint`](https://github.com/jest-community/jest-runner-eslint) +- [`jest-runner-mocha`](https://github.com/rogeliog/jest-runner-mocha) +- [`jest-runner-tsc`](https://github.com/azz/jest-runner-tsc) +- [`jest-runner-prettier`](https://github.com/keplersj/jest-runner-prettier) + +To write a test-runner, export a class with which accepts `globalConfig` in the constructor, and has a `runTests` method with the signature: + +```ts +async runTests( + tests: Array, + watcher: TestWatcher, + onStart: OnTestStart, + onResult: OnTestSuccess, + onFailure: OnTestFailure, + options: TestRunnerOptions, +): Promise +``` + +If you need to restrict your test-runner to only run in serial rather then being executed in parallel your class should have the property `isSerial` to be set as `true`. + +### `setupFiles` [array] + +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`](#setuptestframeworkscriptfile-string). + +### `setupTestFrameworkScriptFile` [string] + +Default: `undefined` + +The path to a module that runs some code to configure or set up the testing framework before each test. Since [`setupFiles`](#setupfiles-array) 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. + +If you want this path to be [relative to the root directory of your project](#rootdir-string), please include `` inside the path string, like `"/a-configs-folder"`. + +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] + +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](TutorialReactNative.md#snapshot-test) for more information. + +Example serializer module: + +```js +// 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: + +```json +{ + ... + "jest": { + "snapshotSerializers": ["my-serializer-module"] + } +} +``` + +Finally tests would look as follows: + +```js +test(() => { + const bar = { + foo: { + x: 1, + y: 2, + }, + }; + + expect(bar).toMatchSnapshot(); +}); +``` + +Rendered snapshot: + +```json +Pretty foo: Object { + "x": 1, + "y": 2, +} +``` + +To make a dependency explicit instead of implicit, you can call [`expect.addSnapshotSerializer`](ExpectAPI.md#expectaddsnapshotserializerserializer) to add a module for an individual test file instead of adding its path to `snapshotSerializers` in Jest configuration. + +### `testEnvironment` [string] + +Default: `"jsdom"` + +The test environment that will be used for testing. The default environment in Jest is a browser-like environment through [jsdom](https://github.com/tmpvar/jsdom). If you are building a node service, you can use the `node` option to use a node-like environment instead. + +By adding a `@jest-environment` docblock at the top of the file, you can specify another environment to be used for all tests in that file: + +```js +/** + * @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: + +```js +// 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); + } +} +``` + +```js +// my-test-suite +let someGlobalObject; + +beforeAll(() => { + someGlobalObject = global.someGlobalObject; +}); +``` + +### `testEnvironmentOptions` [Object] + +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](https://github.com/tmpvar/jsdom) such as `{userAgent: "Agent/007"}`. + +### `testMatch` [array] + +(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](https://github.com/jonschlinkert/micromatch) package for details of the patterns you can specify. + +See also [`testRegex` [string]](#testregex-string), but note that you cannot specify both options. + +### `testPathIgnorePatterns` [array] + +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 `` 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: `["/build/", "/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]](#testmatch-array-string), but note that you cannot specify both options. + +The following is a visualization of the default regex: + +```bash +├── __tests__ +│ └── component.spec.js # test +│ └── anything # test +├── package.json # not test +├── foo.test.js # test +├── bar.spec.jsx # test +└── component.js # not test +``` + +_Note: `testRegex` will try to detect test files using the **absolute file path** therefore having a folder with name that match it will run all the files as tests_ + +### `testResultsProcessor` [string] + +Default: `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: + +```json +{ + "success": bool, + "startTime": epoch, + "numTotalTestSuites": number, + "numPassedTestSuites": number, + "numFailedTestSuites": number, + "numRuntimeErrorTestSuites": number, + "numTotalTests": number, + "numPassedTests": number, + "numFailedTests": number, + "numPendingTests": number, + "openHandles": Array, + "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": {} + }, + ... + ] +} +``` + +### `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: + +```ts +function testRunner( + config: Config, + environment: Environment, + runtime: Runtime, + testPath: string, +): Promise; +``` + +An example of such function can be found in our default [jasmine2 test runner package](https://github.com/facebook/jest/blob/master/packages/jest-jasmine2/src/index.js). + +### `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] + +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. + +### `transform` [object] + +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](https://github.com/facebook/jest/blob/master/examples/typescript/package.json#L16) example or the [webpack tutorial](Webpack.md). + +Examples of such compilers include [Babel](https://babeljs.io/), [TypeScript](http://www.typescriptlang.org/) and [async-to-gen](http://github.com/leebyron/async-to-gen#jest). + +_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](Troubleshooting.md#caching-issues)._ + +_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](https://github.com/facebook/jest/tree/master/packages/babel-jest#setup)_ + +### `transformIgnorePatterns` [array] + +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 `` 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: `["/bower_components/", "/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](https://jestjs.io/docs/en/tutorial-react-native#transformignorepatterns-customization). + +### `unmockedModulePathPatterns` [array] + +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. + +### `verbose` [boolean] + +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. + +### `watchPathIgnorePatterns` [array] + +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 `` 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: `["/node_modules/"]`. diff --git a/website/versioned_docs/version-23.5/ExpectAPI.md b/website/versioned_docs/version-23.5/ExpectAPI.md new file mode 100644 index 000000000000..b7cc577442c7 --- /dev/null +++ b/website/versioned_docs/version-23.5/ExpectAPI.md @@ -0,0 +1,1153 @@ +--- +id: version-23.5-expect +title: Expect +original_id: expect +--- + +When you're writing tests, you often need to check that values meet certain conditions. `expect` gives you access to a number of "matchers" that let you validate different things. + +## Methods + + + +--- + +## Reference + +### `expect(value)` + +The `expect` function is used every time you want to test a value. You will rarely call `expect` by itself. Instead, you will use `expect` along with a "matcher" function to assert something about a value. + +It's easier to understand this with an example. Let's say you have a method `bestLaCroixFlavor()` which is supposed to return the string `'grapefruit'`. Here's how you would test that: + +```js +test('the best flavor is grapefruit', () => { + expect(bestLaCroixFlavor()).toBe('grapefruit'); +}); +``` + +In this case, `toBe` is the matcher function. There are a lot of different matcher functions, documented below, to help you test different things. + +The argument to `expect` should be the value that your code produces, and any argument to the matcher should be the correct value. If you mix them up, your tests will still work, but the error messages on failing tests will look strange. + +### `expect.extend(matchers)` + +You can use `expect.extend` to add your own matchers to Jest. For example, let's say that you're testing a number theory library and you're frequently asserting that numbers are divisible by other numbers. You could abstract that into a `toBeDivisibleBy` matcher: + +```js +expect.extend({ + toBeDivisibleBy(received, argument) { + const pass = received % argument == 0; + if (pass) { + return { + message: () => + `expected ${received} not to be divisible by ${argument}`, + pass: true, + }; + } else { + return { + message: () => `expected ${received} to be divisible by ${argument}`, + pass: false, + }; + } + }, +}); + +test('even and odd numbers', () => { + expect(100).toBeDivisibleBy(2); + expect(101).not.toBeDivisibleBy(2); + expect({apples: 6, bananas: 3}).toEqual({ + apples: expect.toBeDivisibleBy(2), + bananas: expect.not.toBeDivisibleBy(2), + }); +}); +``` + +`expect.extend` also supports async matchers. Async matchers return a Promise so you will need to await the returned value. Let's use an example matcher to illustrate the usage of them. We are going to implement a very similar matcher than `toBeDivisibleBy`, only difference is that the divisible number is going to be pulled from an external source. + +```js +expect.extend({ + async toBeDivisibleByExternalValue(received) { + const externalValue = await getExternalValueFromRemoteSource(); + const pass = received % externalValue == 0; + if (pass) { + return { + message: () => + `expected ${received} not to be divisible by ${externalValue}`, + pass: true, + }; + } else { + return { + message: () => + `expected ${received} to be divisible by ${externalValue}`, + pass: false, + }; + } + }, +}); + +test('is divisible by external value', async () => { + await expect(100).toBeDivisibleByExternalValue(); + await expect(101).not.toBeDivisibleByExternalValue(); +}); +``` + +Matchers should return an object (or a Promise of an object) with two keys. `pass` indicates whether there was a match or not, and `message` provides a function with no arguments that returns an error message in case of failure. Thus, when `pass` is false, `message` should return the error message for when `expect(x).yourMatcher()` fails. And when `pass` is true, `message` should return the error message for when `expect(x).not.yourMatcher()` fails. + +These helper functions can be found on `this` inside a custom matcher: + +#### `this.isNot` + +A boolean to let you know this matcher was called with the negated `.not` modifier allowing you to flip your assertion. + +#### `this.equals(a, b)` + +This is a deep-equality function that will return `true` if two objects have the same values (recursively). + +#### `this.utils` + +There are a number of helpful tools exposed on `this.utils` primarily consisting of the exports from [`jest-matcher-utils`](https://github.com/facebook/jest/tree/master/packages/jest-matcher-utils). + +The most useful ones are `matcherHint`, `printExpected` and `printReceived` to format the error messages nicely. For example, take a look at the implementation for the `toBe` matcher: + +```js +const diff = require('jest-diff'); +expect.extend({ + toBe(received, expected) { + const pass = Object.is(received, expected); + + const message = pass + ? () => + this.utils.matcherHint('.not.toBe') + + '\n\n' + + `Expected value to not be (using Object.is):\n` + + ` ${this.utils.printExpected(expected)}\n` + + `Received:\n` + + ` ${this.utils.printReceived(received)}` + : () => { + const diffString = diff(expected, received, { + expand: this.expand, + }); + return ( + this.utils.matcherHint('.toBe') + + '\n\n' + + `Expected value to be (using Object.is):\n` + + ` ${this.utils.printExpected(expected)}\n` + + `Received:\n` + + ` ${this.utils.printReceived(received)}` + + (diffString ? `\n\nDifference:\n\n${diffString}` : '') + ); + }; + + return {actual: received, message, pass}; + }, +}); +``` + +This will print something like this: + +```bash + expect(received).toBe(expected) + + Expected value to be (using Object.is): + "banana" + Received: + "apple" +``` + +When an assertion fails, the error message should give as much signal as necessary to the user so they can resolve their issue quickly. You should craft a precise failure message to make sure users of your custom assertions have a good developer experience. + +### `expect.anything()` + +`expect.anything()` matches anything but `null` or `undefined`. You can use it inside `toEqual` or `toBeCalledWith` instead of a literal value. For example, if you want to check that a mock function is called with a non-null argument: + +```js +test('map calls its argument with a non-null argument', () => { + const mock = jest.fn(); + [1].map(x => mock(x)); + expect(mock).toBeCalledWith(expect.anything()); +}); +``` + +### `expect.any(constructor)` + +`expect.any(constructor)` matches anything that was created with the given constructor. You can use it inside `toEqual` or `toBeCalledWith` instead of a literal value. For example, if you want to check that a mock function is called with a number: + +```js +function randocall(fn) { + return fn(Math.floor(Math.random() * 6 + 1)); +} + +test('randocall calls its callback with a number', () => { + const mock = jest.fn(); + randocall(mock); + expect(mock).toBeCalledWith(expect.any(Number)); +}); +``` + +### `expect.arrayContaining(array)` + +`expect.arrayContaining(array)` matches a received array which contains all of the elements in the expected array. That is, the expected array is a **subset** of the received array. Therefore, it matches a received array which contains elements that are **not** in the expected array. + +You can use it instead of a literal value: + +- in `toEqual` or `toBeCalledWith` +- to match a property in `objectContaining` or `toMatchObject` + +```js +describe('arrayContaining', () => { + const expected = ['Alice', 'Bob']; + it('matches even if received contains additional elements', () => { + expect(['Alice', 'Bob', 'Eve']).toEqual(expect.arrayContaining(expected)); + }); + it('does not match if received does not contain expected elements', () => { + expect(['Bob', 'Eve']).not.toEqual(expect.arrayContaining(expected)); + }); +}); +``` + +```js +describe('Beware of a misunderstanding! A sequence of dice rolls', () => { + const expected = [1, 2, 3, 4, 5, 6]; + it('matches even with an unexpected number 7', () => { + expect([4, 1, 6, 7, 3, 5, 2, 5, 4, 6]).toEqual( + expect.arrayContaining(expected), + ); + }); + it('does not match without an expected number 2', () => { + expect([4, 1, 6, 7, 3, 5, 7, 5, 4, 6]).not.toEqual( + expect.arrayContaining(expected), + ); + }); +}); +``` + +### `expect.assertions(number)` + +`expect.assertions(number)` verifies that a certain number of assertions are called during a test. This is often useful when testing asynchronous code, in order to make sure that assertions in a callback actually got called. + +For example, let's say that we have a function `doAsync` that receives two callbacks `callback1` and `callback2`, it will asynchronously call both of them in an unknown order. We can test this with: + +```js +test('doAsync calls both callbacks', () => { + expect.assertions(2); + function callback1(data) { + expect(data).toBeTruthy(); + } + function callback2(data) { + expect(data).toBeTruthy(); + } + + doAsync(callback1, callback2); +}); +``` + +The `expect.assertions(2)` call ensures that both callbacks actually get called. + +### `expect.hasAssertions()` + +`expect.hasAssertions()` verifies that at least one assertion is called during a test. This is often useful when testing asynchronous code, in order to make sure that assertions in a callback actually got called. + +For example, let's say that we have a few functions that all deal with state. `prepareState` calls a callback with a state object, `validateState` runs on that state object, and `waitOnState` returns a promise that waits until all `prepareState` callbacks complete. We can test this with: + +```js +test('prepareState prepares a valid state', () => { + expect.hasAssertions(); + prepareState(state => { + expect(validateState(state)).toBeTruthy(); + }); + return waitOnState(); +}); +``` + +The `expect.hasAssertions()` call ensures that the `prepareState` callback actually gets called. + +### `expect.not.arrayContaining(array)` + +`expect.not.arrayContaining(array)` matches a received array which contains none of the elements in the expected array. That is, the expected array **is not a subset** of the received array. + +It is the inverse of `expect.arrayContaining`. + +```js +describe('not.arrayContaining', () => { + const expected = ['Samantha']; + + it('matches if the actual array does not contain the expected elements', () => { + expect(['Alice', 'Bob', 'Eve']).toEqual( + expect.not.arrayContaining(expected), + ); + }); +}); +``` + +### `expect.not.objectContaining(object)` + +`expect.not.objectContaining(object)` matches any received object that does not recursively match the expected properties. That is, the expected object **is not a subset** of the received object. Therefore, it matches a received object which contains properties that are **not** in the expected object. + +It is the inverse of `expect.objectContaining`. + +```js +describe('not.objectContaining', () => { + const expected = {foo: 'bar'}; + + it('matches if the actual object does not contain expected key: value pairs', () => { + expect({bar: 'baz'}).toEqual(expect.not.objectContaining(expected)); + }); +}); +``` + +### `expect.not.stringContaining(string)` + +`expect.not.stringContaining(string)` matches the received string that does not contain the exact expected string. + +It is the inverse of `expect.stringContaining`. + +```js +describe('not.stringContaining', () => { + const expected = 'Hello world!'; + + it('matches if the actual string does not contain the expected substring', () => { + expect('How are you?').toEqual(expect.not.stringContaining(expected)); + }); +}); +``` + +### `expect.not.stringMatching(string | regexp)` + +`expect.not.stringMatching(string | regexp)` matches the received string that does not match the expected regexp. + +It is the inverse of `expect.stringMatching`. + +```js +describe('not.stringMatching', () => { + const expected = /Hello world!/; + + it('matches if the actual string does not match the expected regex', () => { + expect('How are you?').toEqual(expect.not.stringMatching(expected)); + }); +}); +``` + +### `expect.objectContaining(object)` + +`expect.objectContaining(object)` matches any received object that recursively matches the expected properties. That is, the expected object is a **subset** of the received object. Therefore, it matches a received object which contains properties that **are present** in the expected object. + +Instead of literal property values in the expected object, you can use matchers, `expect.anything()`, and so on. + +For example, let's say that we expect an `onPress` function to be called with an `Event` object, and all we need to verify is that the event has `event.x` and `event.y` properties. We can do that with: + +```js +test('onPress gets called with the right thing', () => { + const onPress = jest.fn(); + simulatePresses(onPress); + expect(onPress).toBeCalledWith( + expect.objectContaining({ + x: expect.any(Number), + y: expect.any(Number), + }), + ); +}); +``` + +### `expect.stringContaining(string)` + +`expect.stringContaining(string)` matches the received string that contains the exact expected string. + +### `expect.stringMatching(string | regexp)` + +`expect.stringMatching(string | regexp)` matches the received string that matches the expected regexp. + +You can use it instead of a literal value: + +- in `toEqual` or `toBeCalledWith` +- to match an element in `arrayContaining` +- to match a property in `objectContaining` or `toMatchObject` + +This example also shows how you can nest multiple asymmetric matchers, with `expect.stringMatching` inside the `expect.arrayContaining`. + +```js +describe('stringMatching in arrayContaining', () => { + const expected = [ + expect.stringMatching(/^Alic/), + expect.stringMatching(/^[BR]ob/), + ]; + it('matches even if received contains additional elements', () => { + expect(['Alicia', 'Roberto', 'Evelina']).toEqual( + expect.arrayContaining(expected), + ); + }); + it('does not match if received does not contain expected elements', () => { + expect(['Roberto', 'Evelina']).not.toEqual( + expect.arrayContaining(expected), + ); + }); +}); +``` + +### `expect.addSnapshotSerializer(serializer)` + +You can call `expect.addSnapshotSerializer` to add a module that formats application-specific data structures. + +For an individual test file, an added module precedes any modules from `snapshotSerializers` configuration, which precede the default snapshot serializers for built-in JavaScript types and for React elements. The last module added is the first module tested. + +```js +import serializer from 'my-serializer-module'; +expect.addSnapshotSerializer(serializer); + +// affects expect(value).toMatchSnapshot() assertions in the test file +``` + +If you add a snapshot serializer in individual test files instead of to adding it to `snapshotSerializers` configuration: + +- You make the dependency explicit instead of implicit. +- You avoid limits to configuration that might cause you to eject from [create-react-app](https://github.com/facebookincubator/create-react-app). + +See [configuring Jest](Configuration.md#snapshotserializers-array-string) for more information. + +### `.not` + +If you know how to test something, `.not` lets you test its opposite. For example, this code tests that the best La Croix flavor is not coconut: + +```js +test('the best flavor is not coconut', () => { + expect(bestLaCroixFlavor()).not.toBe('coconut'); +}); +``` + +### `.resolves` + +Use `resolves` to unwrap the value of a fulfilled promise so any other matcher can be chained. If the promise is rejected the assertion fails. + +For example, this code tests that the promise resolves and that the resulting value is `'lemon'`: + +```js +test('resolves to lemon', () => { + // make sure to add a return statement + return expect(Promise.resolve('lemon')).resolves.toBe('lemon'); +}); +``` + +Note that, since you are still testing promises, the test is still asynchronous. Hence, you will need to [tell Jest to wait](TestingAsyncCode.md#promises) by returning the unwrapped assertion. + +Alternatively, you can use `async/await` in combination with `.resolves`: + +```js +test('resolves to lemon', async () => { + await expect(Promise.resolve('lemon')).resolves.toBe('lemon'); + await expect(Promise.resolve('lemon')).resolves.not.toBe('octopus'); +}); +``` + +### `.rejects` + +Use `.rejects` to unwrap the reason of a rejected promise so any other matcher can be chained. If the promise is fulfilled the assertion fails. + +For example, this code tests that the promise rejects with reason `'octopus'`: + +```js +test('rejects to octopus', () => { + // make sure to add a return statement + return expect(Promise.reject(new Error('octopus'))).rejects.toThrow( + 'octopus', + ); +}); +``` + +Note that, since you are still testing promises, the test is still asynchronous. Hence, you will need to [tell Jest to wait](TestingAsyncCode.md#promises) by returning the unwrapped assertion. + +Alternatively, you can use `async/await` in combination with `.rejects`. + +```js +test('rejects to octopus', async () => { + await expect(Promise.reject(new Error('octopus'))).rejects.toThrow('octopus'); +}); +``` + +### `.toBe(value)` + +`toBe` just checks that a value is what you expect. It uses `Object.is` to check exact equality. + +For example, this code will validate some properties of the `can` object: + +```js +const can = { + name: 'pamplemousse', + ounces: 12, +}; + +describe('the can', () => { + test('has 12 ounces', () => { + expect(can.ounces).toBe(12); + }); + + test('has a sophisticated name', () => { + expect(can.name).toBe('pamplemousse'); + }); +}); +``` + +Don't use `toBe` with floating-point numbers. For example, due to rounding, in JavaScript `0.2 + 0.1` is not strictly equal to `0.3`. If you have floating point numbers, try `.toBeCloseTo` instead. + +### `.toHaveBeenCalled()` + +Also under the alias: `.toBeCalled()` + +Use `.toHaveBeenCalled` to ensure that a mock function got called. + +For example, let's say you have a `drinkAll(drink, flavor)` function that takes a `drink` function and applies it to all available beverages. You might want to check that `drink` gets called for `'lemon'`, but not for `'octopus'`, because `'octopus'` flavor is really weird and why would anything be octopus-flavored? You can do that with this test suite: + +```js +describe('drinkAll', () => { + test('drinks something lemon-flavored', () => { + const drink = jest.fn(); + drinkAll(drink, 'lemon'); + expect(drink).toHaveBeenCalled(); + }); + + test('does not drink something octopus-flavored', () => { + const drink = jest.fn(); + drinkAll(drink, 'octopus'); + expect(drink).not.toHaveBeenCalled(); + }); +}); +``` + +### `.toHaveBeenCalledTimes(number)` + +Also under the alias: `.toBeCalledTimes(number)` + +Use `.toHaveBeenCalledTimes` to ensure that a mock function got called exact number of times. + +For example, let's say you have a `drinkEach(drink, Array)` function that takes a `drink` function and applies it to array of passed beverages. You might want to check that drink function was called exact number of times. You can do that with this test suite: + +```js +test('drinkEach drinks each drink', () => { + const drink = jest.fn(); + drinkEach(drink, ['lemon', 'octopus']); + expect(drink).toHaveBeenCalledTimes(2); +}); +``` + +### `.toHaveBeenCalledWith(arg1, arg2, ...)` + +Also under the alias: `.toBeCalledWith()` + +Use `.toHaveBeenCalledWith` to ensure that a mock function was called with specific arguments. + +For example, let's say that you can register a beverage with a `register` function, and `applyToAll(f)` should apply the function `f` to all registered beverages. To make sure this works, you could write: + +```js +test('registration applies correctly to orange La Croix', () => { + const beverage = new LaCroix('orange'); + register(beverage); + const f = jest.fn(); + applyToAll(f); + expect(f).toHaveBeenCalledWith(beverage); +}); +``` + +### `.toHaveBeenLastCalledWith(arg1, arg2, ...)` + +Also under the alias: `.lastCalledWith(arg1, arg2, ...)` + +If you have a mock function, you can use `.toHaveBeenLastCalledWith` to test what arguments it was last called with. For example, let's say you have a `applyToAllFlavors(f)` function that applies `f` to a bunch of flavors, and you want to ensure that when you call it, the last flavor it operates on is `'mango'`. You can write: + +```js +test('applying to all flavors does mango last', () => { + const drink = jest.fn(); + applyToAllFlavors(drink); + expect(drink).toHaveBeenLastCalledWith('mango'); +}); +``` + +### `.toHaveBeenNthCalledWith(nthCall, arg1, arg2, ....)` + +Also under the alias: `.nthCalledWith(nthCall, arg1, arg2, ...)` + +If you have a mock function, you can use `.toHaveBeenNthCalledWith` to test what arguments it was nth called with. For example, let's say you have a `drinkEach(drink, Array)` function that applies `f` to a bunch of flavors, and you want to ensure that when you call it, the first flavor it operates on is `'lemon'` and the second one is `'octopus'`. You can write: + +```js +test('drinkEach drinks each drink', () => { + const drink = jest.fn(); + drinkEach(drink, ['lemon', 'octopus']); + expect(drink).toHaveBeenNthCalledWith(1, 'lemon'); + expect(drink).toHaveBeenNthCalledWith(2, 'octopus'); +}); +``` + +Note: the nth argument must be positive integer starting from 1. + +### `.toHaveReturned()` + +Also under the alias: `.toReturn()` + +If you have a mock function, you can use `.toHaveReturned` to test that the mock function successfully returned (i.e., did not throw an error) at least one time. For example, let's say you have a mock `drink` that returns `true`. You can write: + +```js +test('drinks returns', () => { + const drink = jest.fn(() => true); + + drink(); + + expect(drink).toHaveReturned(); +}); +``` + +### `.toHaveReturnedTimes(number)` + +Also under the alias: `.toReturnTimes(number)` + +Use `.toHaveReturnedTimes` to ensure that a mock function returned successfully (i.e., did not throw an error) an exact number of times. Any calls to the mock function that throw an error are not counted toward the number of times the function returned. + +For example, let's say you have a mock `drink` that returns `true`. You can write: + +```js +test('drink returns twice', () => { + const drink = jest.fn(() => true); + + drink(); + drink(); + + expect(drink).toHaveReturnedTimes(2); +}); +``` + +### `.toHaveReturnedWith(value)` + +Also under the alias: `.toReturnWith(value)` + +Use `.toHaveReturnedWith` to ensure that a mock function returned a specific value. + +For example, let's say you have a mock `drink` that returns the name of the beverage that was consumed. You can write: + +```js +test('drink returns La Croix', () => { + const beverage = {name: 'La Croix'}; + const drink = jest.fn(beverage => beverage.name); + + drink(beverage); + + expect(drink).toHaveReturnedWith('La Croix'); +}); +``` + +### `.toHaveLastReturnedWith(value)` + +Also under the alias: `.lastReturnedWith(value)` + +Use `.toHaveLastReturnedWith` to test the specific value that a mock function last returned. If the last call to the mock function threw an error, then this matcher will fail no matter what value you provided as the expected return value. + +For example, let's say you have a mock `drink` that returns the name of the beverage that was consumed. You can write: + +```js +test('drink returns La Croix (Orange) last', () => { + const beverage1 = {name: 'La Croix (Lemon)'}; + const beverage2 = {name: 'La Croix (Orange)'}; + const drink = jest.fn(beverage => beverage.name); + + drink(beverage1); + drink(beverage2); + + expect(drink).toHaveLastReturnedWith('La Croix (Orange)'); +}); +``` + +### `.toHaveNthReturnedWith(nthCall, value)` + +Also under the alias: `.nthReturnedWith(nthCall, value)` + +Use `.toHaveNthReturnedWith` to test the specific value that a mock function returned for the nth call. If the nth call to the mock function threw an error, then this matcher will fail no matter what value you provided as the expected return value. + +For example, let's say you have a mock `drink` that returns the name of the beverage that was consumed. You can write: + +```js +test('drink returns expected nth calls', () => { + const beverage1 = {name: 'La Croix (Lemon)'}; + const beverage2 = {name: 'La Croix (Orange)'}; + const drink = jest.fn(beverage => beverage.name); + + drink(beverage1); + drink(beverage2); + + expect(drink).toHaveNthReturnedWith(1, 'La Croix (Lemon)'); + expect(drink).toHaveNthReturnedWith(2, 'La Croix (Orange)'); +}); +``` + +Note: the nth argument must be positive integer starting from 1. + +### `.toBeCloseTo(number, numDigits)` + +Using exact equality with floating point numbers is a bad idea. Rounding means that intuitive things fail. For example, this test fails: + +```js +test('adding works sanely with simple decimals', () => { + expect(0.2 + 0.1).toBe(0.3); // Fails! +}); +``` + +It fails because in JavaScript, `0.2 + 0.1` is actually `0.30000000000000004`. Sorry. + +Instead, use `.toBeCloseTo`. Use `numDigits` to control how many digits after the decimal point to check. For example, if you want to be sure that `0.2 + 0.1` is equal to `0.3` with a precision of 5 decimal digits, you can use this test: + +```js +test('adding works sanely with simple decimals', () => { + expect(0.2 + 0.1).toBeCloseTo(0.3, 5); +}); +``` + +The default for `numDigits` is 2, which has proved to be a good default in most cases. + +### `.toBeDefined()` + +Use `.toBeDefined` to check that a variable is not undefined. For example, if you just want to check that a function `fetchNewFlavorIdea()` returns _something_, you can write: + +```js +test('there is a new flavor idea', () => { + expect(fetchNewFlavorIdea()).toBeDefined(); +}); +``` + +You could write `expect(fetchNewFlavorIdea()).not.toBe(undefined)`, but it's better practice to avoid referring to `undefined` directly in your code. + +### `.toBeFalsy()` + +Use `.toBeFalsy` when you don't care what a value is, you just want to ensure a value is false in a boolean context. For example, let's say you have some application code that looks like: + +```js +drinkSomeLaCroix(); +if (!getErrors()) { + drinkMoreLaCroix(); +} +``` + +You may not care what `getErrors` returns, specifically - it might return `false`, `null`, or `0`, and your code would still work. So if you want to test there are no errors after drinking some La Croix, you could write: + +```js +test('drinking La Croix does not lead to errors', () => { + drinkSomeLaCroix(); + expect(getErrors()).toBeFalsy(); +}); +``` + +In JavaScript, there are six falsy values: `false`, `0`, `''`, `null`, `undefined`, and `NaN`. Everything else is truthy. + +### `.toBeGreaterThan(number)` + +To compare floating point numbers, you can use `toBeGreaterThan`. For example, if you want to test that `ouncesPerCan()` returns a value of more than 10 ounces, write: + +```js +test('ounces per can is more than 10', () => { + expect(ouncesPerCan()).toBeGreaterThan(10); +}); +``` + +### `.toBeGreaterThanOrEqual(number)` + +To compare floating point numbers, you can use `toBeGreaterThanOrEqual`. For example, if you want to test that `ouncesPerCan()` returns a value of at least 12 ounces, write: + +```js +test('ounces per can is at least 12', () => { + expect(ouncesPerCan()).toBeGreaterThanOrEqual(12); +}); +``` + +### `.toBeLessThan(number)` + +To compare floating point numbers, you can use `toBeLessThan`. For example, if you want to test that `ouncesPerCan()` returns a value of less than 20 ounces, write: + +```js +test('ounces per can is less than 20', () => { + expect(ouncesPerCan()).toBeLessThan(20); +}); +``` + +### `.toBeLessThanOrEqual(number)` + +To compare floating point numbers, you can use `toBeLessThanOrEqual`. For example, if you want to test that `ouncesPerCan()` returns a value of at most 12 ounces, write: + +```js +test('ounces per can is at most 12', () => { + expect(ouncesPerCan()).toBeLessThanOrEqual(12); +}); +``` + +### `.toBeInstanceOf(Class)` + +Use `.toBeInstanceOf(Class)` to check that an object is an instance of a class. This matcher uses `instanceof` underneath. + +```js +class A {} + +expect(new A()).toBeInstanceOf(A); +expect(() => {}).toBeInstanceOf(Function); +expect(new A()).toBeInstanceOf(Function); // throws +``` + +### `.toBeNull()` + +`.toBeNull()` is the same as `.toBe(null)` but the error messages are a bit nicer. So use `.toBeNull()` when you want to check that something is null. + +```js +function bloop() { + return null; +} + +test('bloop returns null', () => { + expect(bloop()).toBeNull(); +}); +``` + +### `.toBeTruthy()` + +Use `.toBeTruthy` when you don't care what a value is, you just want to ensure a value is true in a boolean context. For example, let's say you have some application code that looks like: + +```js +drinkSomeLaCroix(); +if (thirstInfo()) { + drinkMoreLaCroix(); +} +``` + +You may not care what `thirstInfo` returns, specifically - it might return `true` or a complex object, and your code would still work. So if you just want to test that `thirstInfo` will be truthy after drinking some La Croix, you could write: + +```js +test('drinking La Croix leads to having thirst info', () => { + drinkSomeLaCroix(); + expect(thirstInfo()).toBeTruthy(); +}); +``` + +In JavaScript, there are six falsy values: `false`, `0`, `''`, `null`, `undefined`, and `NaN`. Everything else is truthy. + +### `.toBeUndefined()` + +Use `.toBeUndefined` to check that a variable is undefined. For example, if you want to check that a function `bestDrinkForFlavor(flavor)` returns `undefined` for the `'octopus'` flavor, because there is no good octopus-flavored drink: + +```js +test('the best drink for octopus flavor is undefined', () => { + expect(bestDrinkForFlavor('octopus')).toBeUndefined(); +}); +``` + +You could write `expect(bestDrinkForFlavor('octopus')).toBe(undefined)`, but it's better practice to avoid referring to `undefined` directly in your code. + +### `.toContain(item)` + +Use `.toContain` when you want to check that an item is in an array. For testing the items in the array, this uses `===`, a strict equality check. `.toContain` can also check whether a string is a substring of another string. + +For example, if `getAllFlavors()` returns an array of flavors and you want to be sure that `lime` is in there, you can write: + +```js +test('the flavor list contains lime', () => { + expect(getAllFlavors()).toContain('lime'); +}); +``` + +### `.toContainEqual(item)` + +Use `.toContainEqual` when you want to check that an item with a specific structure and values is contained in an array. For testing the items in the array, this matcher recursively checks the equality of all fields, rather than checking for object identity. + +```js +describe('my beverage', () => { + test('is delicious and not sour', () => { + const myBeverage = {delicious: true, sour: false}; + expect(myBeverages()).toContainEqual(myBeverage); + }); +}); +``` + +### `.toEqual(value)` + +Use `.toEqual` when you want to check that two objects have the same value. This matcher recursively checks the equality of all fields, rather than checking for object identity—this is also known as "deep equal". For example, `toEqual` and `toBe` behave differently in this test suite, so all the tests pass: + +```js +const can1 = { + flavor: 'grapefruit', + ounces: 12, +}; +const can2 = { + flavor: 'grapefruit', + ounces: 12, +}; + +describe('the La Croix cans on my desk', () => { + test('have all the same properties', () => { + expect(can1).toEqual(can2); + }); + test('are not the exact same can', () => { + expect(can1).not.toBe(can2); + }); +}); +``` + +> Note: `.toEqual` won't perform a _deep equality_ check for two errors. Only the `message` property of an Error is considered for equality. It is recommended to use the `.toThrow` matcher for testing against errors. + +### `.toHaveLength(number)` + +Use `.toHaveLength` to check that an object has a `.length` property and it is set to a certain numeric value. + +This is especially useful for checking arrays or strings size. + +```js +expect([1, 2, 3]).toHaveLength(3); +expect('abc').toHaveLength(3); +expect('').not.toHaveLength(5); +``` + +### `.toMatch(regexpOrString)` + +Use `.toMatch` to check that a string matches a regular expression. + +For example, you might not know what exactly `essayOnTheBestFlavor()` returns, but you know it's a really long string, and the substring `grapefruit` should be in there somewhere. You can test this with: + +```js +describe('an essay on the best flavor', () => { + test('mentions grapefruit', () => { + expect(essayOnTheBestFlavor()).toMatch(/grapefruit/); + expect(essayOnTheBestFlavor()).toMatch(new RegExp('grapefruit')); + }); +}); +``` + +This matcher also accepts a string, which it will try to match: + +```js +describe('grapefruits are healthy', () => { + test('grapefruits are a fruit', () => { + expect('grapefruits').toMatch('fruit'); + }); +}); +``` + +### `.toMatchObject(object)` + +Use `.toMatchObject` to check that a JavaScript object matches a subset of the properties of an object. It will match received objects with properties that are **not** in the expected object. + +You can also pass an array of objects, in which case the method will return true only if each object in the received array matches (in the `toMatchObject` sense described above) the corresponding object in the expected array. This is useful if you want to check that two arrays match in their number of elements, as opposed to `arrayContaining`, which allows for extra elements in the received array. + +You can match properties against values or against matchers. + +```js +const houseForSale = { + bath: true, + bedrooms: 4, + kitchen: { + amenities: ['oven', 'stove', 'washer'], + area: 20, + wallColor: 'white', + }, +}; +const desiredHouse = { + bath: true, + kitchen: { + amenities: ['oven', 'stove', 'washer'], + wallColor: expect.stringMatching(/white|yellow/), + }, +}; + +test('the house has my desired features', () => { + expect(houseForSale).toMatchObject(desiredHouse); +}); +``` + +```js +describe('toMatchObject applied to arrays arrays', () => { + test('the number of elements must match exactly', () => { + expect([{foo: 'bar'}, {baz: 1}]).toMatchObject([{foo: 'bar'}, {baz: 1}]); + }); + + // .arrayContaining "matches a received array which contains elements that + // are *not* in the expected array" + test('.toMatchObject does not allow extra elements', () => { + expect([{foo: 'bar'}, {baz: 1}]).toMatchObject([{foo: 'bar'}]); + }); + + test('.toMatchObject is called for each elements, so extra object properties are okay', () => { + expect([{foo: 'bar'}, {baz: 1, extra: 'quux'}]).toMatchObject([ + {foo: 'bar'}, + {baz: 1}, + ]); + }); +}); +``` + +### `.toHaveProperty(keyPath, value)` + +Use `.toHaveProperty` to check if property at provided reference `keyPath` exists for an object. For checking deeply nested properties in an object you may use [dot notation](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Operators/Property_accessors) or an array containing the keyPath for deep references. + +Optionally, you can provide a `value` to check if it's equal to the value present at `keyPath` on the target object. This matcher uses 'deep equality' (like `toEqual()`) and recursively checks the equality of all fields. + +The following example contains a `houseForSale` object with nested properties. We are using `toHaveProperty` to check for the existence and values of various properties in the object. + +```js +// Object containing house features to be tested +const houseForSale = { + bath: true, + bedrooms: 4, + kitchen: { + amenities: ['oven', 'stove', 'washer'], + area: 20, + wallColor: 'white', + 'nice.oven': true, + }, + 'ceiling.height': 2, +}; + +test('this house has my desired features', () => { + // Simple Referencing + expect(houseForSale).toHaveProperty('bath'); + expect(houseForSale).toHaveProperty('bedrooms', 4); + + expect(houseForSale).not.toHaveProperty('pool'); + + // Deep referencing using dot notation + expect(houseForSale).toHaveProperty('kitchen.area', 20); + expect(houseForSale).toHaveProperty('kitchen.amenities', [ + 'oven', + 'stove', + 'washer', + ]); + + expect(houseForSale).not.toHaveProperty('kitchen.open'); + + // Deep referencing using an array containing the keyPath + expect(houseForSale).toHaveProperty(['kitchen', 'area'], 20); + expect(houseForSale).toHaveProperty( + ['kitchen', 'amenities'], + ['oven', 'stove', 'washer'], + ); + expect(houseForSale).toHaveProperty(['kitchen', 'amenities', 0], 'oven'); + expect(houseForSale).toHaveProperty(['kitchen', 'nice.oven']); + expect(houseForSale).not.toHaveProperty(['kitchen', 'open']); + + // Referencing keys with dot in the key itself + expect(houseForSale).toHaveProperty(['ceiling.height'], 'tall'); +}); +``` + +### `.toMatchSnapshot(propertyMatchers, snapshotName)` + +This ensures that a value matches the most recent snapshot. Check out [the Snapshot Testing guide](SnapshotTesting.md) for more information. + +The optional `propertyMatchers` argument allows you to specify asymmetric matchers which are verified instead of the exact values. Any value will be matched exactly if not provided as a matcher. + +The last argument allows you option to specify a snapshot name. Otherwise, the name is inferred from the test. + +_Note: While snapshot testing is most commonly used with React components, any serializable value can be used as a snapshot._ + +### `.toMatchInlineSnapshot(propertyMatchers, inlineSnapshot)` + +Ensures that a value matches the most recent snapshot. Unlike [`.toMatchSnapshot()`](#tomatchsnapshotpropertymatchers-snapshotname), the snapshots will be written to the current source file, inline. + +Check out the section on [Inline Snapshots](./SnapshotTesting.md#inline-snapshots) for more info. + +### `.toStrictEqual(value)` + +Use `.toStrictEqual` to test that objects have the same types as well as structure. + +Differences from `.toEqual`: + +- Keys with `undefined` properties are checked. e.g. `{a: undefined, b: 2}` does not match `{b: 2}` when using `.toStrictEqual`. +- Object types are checked to be equal. e.g. A class instance with fields `a` and `b` will not equal a literal object with fields `a` and `b`. + +```js +class LaCroix { + constructor(flavor) { + this.flavor = flavor; + } +} + +describe('the La Croix cans on my desk', () => { + test('are not semantically the same', () => { + expect(new LaCroix('lemon')).toEqual({flavor: 'lemon'}); + expect(new LaCroix('lemon')).not.toStrictEqual({flavor: 'lemon'}); + }); +}); +``` + +### `.toThrow(error)` + +Also under the alias: `.toThrowError(error)` + +Use `.toThrow` to test that a function throws when it is called. For example, if we want to test that `drinkFlavor('octopus')` throws, because octopus flavor is too disgusting to drink, we could write: + +```js +test('throws on octopus', () => { + expect(() => { + drinkFlavor('octopus'); + }).toThrow(); +}); +``` + +If you want to test that a specific error gets thrown, you can provide an argument to `toThrow`. The argument can be a string that should be contained in the error message, a class for the error, or a regex that should match the error message. For example, let's say that `drinkFlavor` is coded like this: + +```js +function drinkFlavor(flavor) { + if (flavor == 'octopus') { + throw new DisgustingFlavorError('yuck, octopus flavor'); + } + // Do some other stuff +} +``` + +We could test this error gets thrown in several ways: + +```js +test('throws on octopus', () => { + function drinkOctopus() { + drinkFlavor('octopus'); + } + + // Test that the error message says "yuck" somewhere: these are equivalent + expect(drinkOctopus).toThrowError(/yuck/); + expect(drinkOctopus).toThrowError('yuck'); + + // Test the exact error message + expect(drinkOctopus).toThrowError(/^yuck, octopus flavor$/); + + // Test that we get a DisgustingFlavorError + expect(drinkOctopus).toThrowError(DisgustingFlavorError); +}); +``` + +> Note: You must wrap the code in a function, otherwise the error will not be caught and the assertion will fail. + +### `.toThrowErrorMatchingSnapshot()` + +Use `.toThrowErrorMatchingSnapshot` to test that a function throws an error matching the most recent snapshot when it is called. For example, let's say you have a `drinkFlavor` function that throws whenever the flavor is `'octopus'`, and is coded like this: + +```js +function drinkFlavor(flavor) { + if (flavor == 'octopus') { + throw new DisgustingFlavorError('yuck, octopus flavor'); + } + // Do some other stuff +} +``` + +The test for this function will look this way: + +```js +test('throws on octopus', () => { + function drinkOctopus() { + drinkFlavor('octopus'); + } + + expect(drinkOctopus).toThrowErrorMatchingSnapshot(); +}); +``` + +And it will generate the following snapshot: + +```js +exports[`drinking flavors throws on octopus 1`] = `"yuck, octopus flavor"`; +``` + +Check out [React Tree Snapshot Testing](https://jestjs.io/blog/2016/07/27/jest-14.html) for more information on snapshot testing. + +### `.toThrowErrorMatchingInlineSnapshot()` + +This matcher is much like [`.toThrowErrorMatchingSnapshot`](#tothrowerrormatchingsnapshot), except instead of writing the snapshot value to a `.snap` file, it will be written into the source code automatically. + +Check out the section on [Inline Snapshots](./SnapshotTesting.md#inline-snapshots) for more info. diff --git a/website/versioned_docs/version-23.5/GlobalAPI.md b/website/versioned_docs/version-23.5/GlobalAPI.md new file mode 100644 index 000000000000..756992220d08 --- /dev/null +++ b/website/versioned_docs/version-23.5/GlobalAPI.md @@ -0,0 +1,658 @@ +--- +id: version-23.5-api +title: Globals +original_id: api +--- + +In your test files, Jest puts each of these methods and objects into the global environment. You don't have to require or import anything to use them. + +## Methods + + + +--- + +## Reference + +### `afterAll(fn, timeout)` + +Runs a function after all the tests in this file have completed. If the function returns a promise or is a generator, Jest waits for that promise to resolve before continuing. + +Optionally, you can provide a `timeout` (in milliseconds) for specifying how long to wait before aborting. _Note: The default timeout is 5 seconds._ + +This is often useful if you want to clean up some global setup state that is shared across tests. + +For example: + +```js +const globalDatabase = makeGlobalDatabase(); + +function cleanUpDatabase(db) { + db.cleanUp(); +} + +afterAll(() => { + cleanUpDatabase(globalDatabase); +}); + +test('can find things', () => { + return globalDatabase.find('thing', {}, results => { + expect(results.length).toBeGreaterThan(0); + }); +}); + +test('can insert a thing', () => { + return globalDatabase.insert('thing', makeThing(), response => { + expect(response.success).toBeTruthy(); + }); +}); +``` + +Here the `afterAll` ensures that `cleanUpDatabase` is called after all tests run. + +If `afterAll` is inside a `describe` block, it runs at the end of the describe block. + +If you want to run some cleanup after every test instead of after all tests, use `afterEach` instead. + +### `afterEach(fn, timeout)` + +Runs a function after each one of the tests in this file completes. If the function returns a promise or is a generator, Jest waits for that promise to resolve before continuing. + +Optionally, you can provide a `timeout` (in milliseconds) for specifying how long to wait before aborting. _Note: The default timeout is 5 seconds._ + +This is often useful if you want to clean up some temporary state that is created by each test. + +For example: + +```js +const globalDatabase = makeGlobalDatabase(); + +function cleanUpDatabase(db) { + db.cleanUp(); +} + +afterEach(() => { + cleanUpDatabase(globalDatabase); +}); + +test('can find things', () => { + return globalDatabase.find('thing', {}, results => { + expect(results.length).toBeGreaterThan(0); + }); +}); + +test('can insert a thing', () => { + return globalDatabase.insert('thing', makeThing(), response => { + expect(response.success).toBeTruthy(); + }); +}); +``` + +Here the `afterEach` ensures that `cleanUpDatabase` is called after each test runs. + +If `afterEach` is inside a `describe` block, it only runs after the tests that are inside this describe block. + +If you want to run some cleanup just once, after all of the tests run, use `afterAll` instead. + +### `beforeAll(fn, timeout)` + +Runs a function before any of the tests in this file run. If the function returns a promise or is a generator, Jest waits for that promise to resolve before running tests. + +Optionally, you can provide a `timeout` (in milliseconds) for specifying how long to wait before aborting. _Note: The default timeout is 5 seconds._ + +This is often useful if you want to set up some global state that will be used by many tests. + +For example: + +```js +const globalDatabase = makeGlobalDatabase(); + +beforeAll(() => { + // Clears the database and adds some testing data. + // Jest will wait for this promise to resolve before running tests. + return globalDatabase.clear().then(() => { + return globalDatabase.insert({testData: 'foo'}); + }); +}); + +// Since we only set up the database once in this example, it's important +// that our tests don't modify it. +test('can find things', () => { + return globalDatabase.find('thing', {}, results => { + expect(results.length).toBeGreaterThan(0); + }); +}); +``` + +Here the `beforeAll` ensures that the database is set up before tests run. If setup was synchronous, you could just do this without `beforeAll`. The key is that Jest will wait for a promise to resolve, so you can have asynchronous setup as well. + +If `beforeAll` is inside a `describe` block, it runs at the beginning of the describe block. + +If you want to run something before every test instead of before any test runs, use `beforeEach` instead. + +### `beforeEach(fn, timeout)` + +Runs a function before each of the tests in this file runs. If the function returns a promise or is a generator, Jest waits for that promise to resolve before running the test. + +Optionally, you can provide a `timeout` (in milliseconds) for specifying how long to wait before aborting. _Note: The default timeout is 5 seconds._ + +This is often useful if you want to reset some global state that will be used by many tests. + +For example: + +```js +const globalDatabase = makeGlobalDatabase(); + +beforeEach(() => { + // Clears the database and adds some testing data. + // Jest will wait for this promise to resolve before running tests. + return globalDatabase.clear().then(() => { + return globalDatabase.insert({testData: 'foo'}); + }); +}); + +test('can find things', () => { + return globalDatabase.find('thing', {}, results => { + expect(results.length).toBeGreaterThan(0); + }); +}); + +test('can insert a thing', () => { + return globalDatabase.insert('thing', makeThing(), response => { + expect(response.success).toBeTruthy(); + }); +}); +``` + +Here the `beforeEach` ensures that the database is reset for each test. + +If `beforeEach` is inside a `describe` block, it runs for each test in the describe block. + +If you only need to run some setup code once, before any tests run, use `beforeAll` instead. + +### `describe(name, fn)` + +`describe(name, fn)` creates a block that groups together several related tests in one "test suite". For example, if you have a `myBeverage` object that is supposed to be delicious but not sour, you could test it with: + +```js +const myBeverage = { + delicious: true, + sour: false, +}; + +describe('my beverage', () => { + test('is delicious', () => { + expect(myBeverage.delicious).toBeTruthy(); + }); + + test('is not sour', () => { + expect(myBeverage.sour).toBeFalsy(); + }); +}); +``` + +This isn't required - you can just write the `test` blocks directly at the top level. But this can be handy if you prefer your tests to be organized into groups. + +You can also nest `describe` blocks if you have a hierarchy of tests: + +```js +const binaryStringToNumber = binString => { + if (!/^[01]+$/.test(binString)) { + throw new CustomError('Not a binary number.'); + } + + return parseInt(binString, 2); +}; + +describe('binaryStringToNumber', () => { + describe('given an invalid binary string', () => { + test('composed of non-numbers throws CustomError', () => { + expect(() => binaryStringToNumber('abc')).toThrowError(CustomError); + }); + + test('with extra whitespace throws CustomError', () => { + expect(() => binaryStringToNumber(' 100')).toThrowError(CustomError); + }); + }); + + describe('given a valid binary string', () => { + test('returns the correct number', () => { + expect(binaryStringToNumber('100')).toBe(4); + }); + }); +}); +``` + +### `describe.each(table)(name, fn, timeout)` + +Use `describe.each` if you keep duplicating the same test suites with different data. `describe.each` allows you to write the test suite once and pass data in. + +`describe.each` is available with two APIs: + +#### 1. `describe.each(table)(name, fn, timeout)` + +- `table`: `Array` of Arrays with the arguments that are passed into the `fn` for each row. + - _Note_ If you pass in a 1D array of primitives, internally it will be mapped to a table i.e. `[1, 2, 3] -> [[1], [2], [3]]` +- `name`: `String` the title of the test suite. + - Generate unique test titles by positionally injecting parameters with [`printf` formatting](https://nodejs.org/api/util.html#util_util_format_format_args): + - `%p` - [pretty-format](https://www.npmjs.com/package/pretty-format). + - `%s`- String. + - `%d`- Number. + - `%i` - Integer. + - `%f` - Floating point value. + - `%j` - JSON. + - `%o` - Object. + - `%#` - Index of the test case. + - `%%` - single percent sign ('%'). This does not consume an argument. +- `fn`: `Function` the suite of tests to be ran, this is the function that will receive the parameters in each row as function arguments. +- Optionally, you can provide a `timeout` (in milliseconds) for specifying how long to wait for each row before aborting. _Note: The default timeout is 5 seconds._ + +Example: + +```js +describe.each([[1, 1, 2], [1, 2, 3], [2, 1, 3]])( + '.add(%i, %i)', + (a, b, expected) => { + test(`returns ${expected}`, () => { + expect(a + b).toBe(expected); + }); + + test(`returned value not be greater than ${expected}`, () => { + expect(a + b).not.toBeGreaterThan(expected); + }); + + test(`returned value not be less than ${expected}`, () => { + expect(a + b).not.toBeLessThan(expected); + }); + }, +); +``` + +#### 2. `` describe.each`table`(name, fn, timeout) `` + +- `table`: `Tagged Template Literal` + - First row of variable name column headings separated with `|` + - One or more subsequent rows of data supplied as template literal expressions using `${value}` syntax. +- `name`: `String` the title of the test suite, use `$variable` to inject test data into the suite title from the tagged template expressions. + - To inject nested object values use you can supply a keyPath i.e. `$variable.path.to.value` +- `fn`: `Function` the suite of tests to be ran, this is the function that will receive the test data object. +- Optionally, you can provide a `timeout` (in milliseconds) for specifying how long to wait for each row before aborting. _Note: The default timeout is 5 seconds._ + +Example: + +```js +describe.each` + a | b | expected + ${1} | ${1} | ${2} + ${1} | ${2} | ${3} + ${2} | ${1} | ${3} +`('$a + $b', ({a, b, expected}) => { + test(`returns ${expected}`, () => { + expect(a + b).toBe(expected); + }); + + test(`returned value not be greater than ${expected}`, () => { + expect(a + b).not.toBeGreaterThan(expected); + }); + + test(`returned value not be less than ${expected}`, () => { + expect(a + b).not.toBeLessThan(expected); + }); +}); +``` + +### `describe.only(name, fn)` + +Also under the alias: `fdescribe(name, fn)` + +You can use `describe.only` if you want to run only one describe block: + +```js +describe.only('my beverage', () => { + test('is delicious', () => { + expect(myBeverage.delicious).toBeTruthy(); + }); + + test('is not sour', () => { + expect(myBeverage.sour).toBeFalsy(); + }); +}); + +describe('my other beverage', () => { + // ... will be skipped +}); +``` + +### `describe.only.each(table)(name, fn)` + +Also under the aliases: `fdescribe.each(table)(name, fn)` and `` fdescribe.each`table`(name, fn) `` + +Use `describe.only.each` if you want to only run specific tests suites of data driven tests. + +`describe.only.each` is available with two APIs: + +#### `describe.only.each(table)(name, fn)` + +```js +describe.only.each([[1, 1, 2], [1, 2, 3], [2, 1, 3]])( + '.add(%i, %i)', + (a, b, expected) => { + test(`returns ${expected}`, () => { + expect(a + b).toBe(expected); + }); + }, +); + +test('will not be ran', () => { + expect(1 / 0).toBe(Infinity); +}); +``` + +#### `` describe.only.each`table`(name, fn) `` + +```js +describe.only.each` + a | b | expected + ${1} | ${1} | ${2} + ${1} | ${2} | ${3} + ${2} | ${1} | ${3} +`('returns $expected when $a is added $b', ({a, b, expected}) => { + test('passes', () => { + expect(a + b).toBe(expected); + }); +}); + +test('will not be ran', () => { + expect(1 / 0).toBe(Infinity); +}); +``` + +### `describe.skip(name, fn)` + +Also under the alias: `xdescribe(name, fn)` + +You can use `describe.skip` if you do not want to run a particular describe block: + +```js +describe('my beverage', () => { + test('is delicious', () => { + expect(myBeverage.delicious).toBeTruthy(); + }); + + test('is not sour', () => { + expect(myBeverage.sour).toBeFalsy(); + }); +}); + +describe.skip('my other beverage', () => { + // ... will be skipped +}); +``` + +Using `describe.skip` is often just an easier alternative to temporarily commenting out a chunk of tests. + +### `describe.skip.each(table)(name, fn)` + +Also under the aliases: `xdescribe.each(table)(name, fn)` and `` xdescribe.each`table`(name, fn) `` + +Use `describe.skip.each` if you want to stop running a suite of data driven tests. + +`describe.skip.each` is available with two APIs: + +#### `describe.skip.each(table)(name, fn)` + +```js +describe.skip.each([[1, 1, 2], [1, 2, 3], [2, 1, 3]])( + '.add(%i, %i)', + (a, b, expected) => { + test(`returns ${expected}`, () => { + expect(a + b).toBe(expected); // will not be ran + }); + }, +); + +test('will be ran', () => { + expect(1 / 0).toBe(Infinity); +}); +``` + +#### `` describe.skip.each`table`(name, fn) `` + +```js +describe.skip.each` + a | b | expected + ${1} | ${1} | ${2} + ${1} | ${2} | ${3} + ${2} | ${1} | ${3} +`('returns $expected when $a is added $b', ({a, b, expected}) => { + test('will not be ran', () => { + expect(a + b).toBe(expected); // will not be ran + }); +}); + +test('will be ran', () => { + expect(1 / 0).toBe(Infinity); +}); +``` + +### `require.requireActual(moduleName)` + +Returns the actual module instead of a mock, bypassing all checks on whether the module should receive a mock implementation or not. + +### `require.requireMock(moduleName)` + +Returns a mock module instead of the actual module, bypassing all checks on whether the module should be required normally or not. + +### `test(name, fn, timeout)` + +Also under the alias: `it(name, fn, timeout)` + +All you need in a test file is the `test` method which runs a test. For example, let's say there's a function `inchesOfRain()` that should be zero. Your whole test could be: + +```js +test('did not rain', () => { + expect(inchesOfRain()).toBe(0); +}); +``` + +The first argument is the test name; the second argument is a function that contains the expectations to test. The third argument (optional) is `timeout` (in milliseconds) for specifying how long to wait before aborting. _Note: The default timeout is 5 seconds._ + +> Note: If a **promise is returned** from `test`, Jest will wait for the promise to resolve before letting the test complete. Jest will also wait if you **provide an argument to the test function**, usually called `done`. This could be handy when you want to test callbacks. See how to test async code [here](TestingAsyncCode.md#callbacks). + +For example, let's say `fetchBeverageList()` returns a promise that is supposed to resolve to a list that has `lemon` in it. You can test this with: + +```js +test('has lemon in it', () => { + return fetchBeverageList().then(list => { + expect(list).toContain('lemon'); + }); +}); +``` + +Even though the call to `test` will return right away, the test doesn't complete until the promise resolves as well. + +### `test.each(table)(name, fn, timeout)` + +Also under the alias: `it.each(table)(name, fn)` and `` it.each`table`(name, fn) `` + +Use `test.each` if you keep duplicating the same test with different data. `test.each` allows you to write the test once and pass data in. + +`test.each` is available with two APIs: + +#### 1. `test.each(table)(name, fn, timeout)` + +- `table`: `Array` of Arrays with the arguments that are passed into the test `fn` for each row. + - _Note_ If you pass in a 1D array of primitives, internally it will be mapped to a table i.e. `[1, 2, 3] -> [[1], [2], [3]]` +- `name`: `String` the title of the test block. + - Generate unique test titles by positionally injecting parameters with [`printf` formatting](https://nodejs.org/api/util.html#util_util_format_format_args): + - `%p` - [pretty-format](https://www.npmjs.com/package/pretty-format). + - `%s`- String. + - `%d`- Number. + - `%i` - Integer. + - `%f` - Floating point value. + - `%j` - JSON. + - `%o` - Object. + - `%#` - Index of the test case. + - `%%` - single percent sign ('%'). This does not consume an argument. +- `fn`: `Function` the test to be ran, this is the function that will receive the parameters in each row as function arguments. +- Optionally, you can provide a `timeout` (in milliseconds) for specifying how long to wait for each row before aborting. _Note: The default timeout is 5 seconds._ + +Example: + +```js +test.each([[1, 1, 2], [1, 2, 3], [2, 1, 3]])( + '.add(%i, %i)', + (a, b, expected) => { + expect(a + b).toBe(expected); + }, +); +``` + +#### 2. `` test.each`table`(name, fn, timeout) `` + +- `table`: `Tagged Template Literal` + - First row of variable name column headings separated with `|` + - One or more subsequent rows of data supplied as template literal expressions using `${value}` syntax. +- `name`: `String` the title of the test, use `$variable` to inject test data into the test title from the tagged template expressions. + - To inject nested object values use you can supply a keyPath i.e. `$variable.path.to.value` +- `fn`: `Function` the test to be ran, this is the function that will receive the test data object. +- Optionally, you can provide a `timeout` (in milliseconds) for specifying how long to wait for each row before aborting. _Note: The default timeout is 5 seconds._ + +Example: + +```js +test.each` + a | b | expected + ${1} | ${1} | ${2} + ${1} | ${2} | ${3} + ${2} | ${1} | ${3} +`('returns $expected when $a is added $b', ({a, b, expected}) => { + expect(a + b).toBe(expected); +}); +``` + +### `test.only(name, fn, timeout)` + +Also under the aliases: `it.only(name, fn, timeout)` or `fit(name, fn, timeout)` + +When you are debugging a large test file, you will often only want to run a subset of tests. You can use `.only` to specify which tests are the only ones you want to run in that test file. + +Optionally, you can provide a `timeout` (in milliseconds) for specifying how long to wait before aborting. _Note: The default timeout is 5 seconds._ + +For example, let's say you had these tests: + +```js +test.only('it is raining', () => { + expect(inchesOfRain()).toBeGreaterThan(0); +}); + +test('it is not snowing', () => { + expect(inchesOfSnow()).toBe(0); +}); +``` + +Only the "it is raining" test will run in that test file, since it is run with `test.only`. + +Usually you wouldn't check code using `test.only` into source control - you would use it just for debugging, and remove it once you have fixed the broken tests. + +### `test.only.each(table)(name, fn)` + +Also under the aliases: `it.only.each(table)(name, fn)`, `fit.each(table)(name, fn)`, `` it.only.each`table`(name, fn) `` and `` fit.each`table`(name, fn) `` + +Use `test.only.each` if you want to only run specific tests with different test data. + +`test.only.each` is available with two APIs: + +#### `test.only.each(table)(name, fn)` + +```js +test.only.each([[1, 1, 2], [1, 2, 3], [2, 1, 3]])( + '.add(%i, %i)', + (a, b, expected) => { + expect(a + b).toBe(expected); + }, +); + +test('will not be ran', () => { + expect(1 / 0).toBe(Infinity); +}); +``` + +#### `` test.only.each`table`(name, fn) `` + +```js +test.only.each` + a | b | expected + ${1} | ${1} | ${2} + ${1} | ${2} | ${3} + ${2} | ${1} | ${3} +`('returns $expected when $a is added $b', ({a, b, expected}) => { + expect(a + b).toBe(expected); +}); + +test('will not be ran', () => { + expect(1 / 0).toBe(Infinity); +}); +``` + +### `test.skip(name, fn)` + +Also under the aliases: `it.skip(name, fn)` or `xit(name, fn)` or `xtest(name, fn)` + +When you are maintaining a large codebase, you may sometimes find a test that is temporarily broken for some reason. If you want to skip running this test, but you don't want to just delete this code, you can use `test.skip` to specify some tests to skip. + +For example, let's say you had these tests: + +```js +test('it is raining', () => { + expect(inchesOfRain()).toBeGreaterThan(0); +}); + +test.skip('it is not snowing', () => { + expect(inchesOfSnow()).toBe(0); +}); +``` + +Only the "it is raining" test will run, since the other test is run with `test.skip`. + +You could simply comment the test out, but it's often a bit nicer to use `test.skip` because it will maintain indentation and syntax highlighting. + +### `test.skip.each(table)(name, fn)` + +Also under the aliases: `it.skip.each(table)(name, fn)`, `xit.each(table)(name, fn)`, `xtest.each(table)(name, fn)`, `` it.skip.each`table`(name, fn) ``, `` xit.each`table`(name, fn) `` and `` xtest.each`table`(name, fn) `` + +Use `test.skip.each` if you want to stop running a collection of data driven tests. + +`test.skip.each` is available with two APIs: + +#### `test.skip.each(table)(name, fn)` + +```js +test.skip.each([[1, 1, 2], [1, 2, 3], [2, 1, 3]])( + '.add(%i, %i)', + (a, b, expected) => { + expect(a + b).toBe(expected); // will not be ran + }, +); + +test('will be ran', () => { + expect(1 / 0).toBe(Infinity); +}); +``` + +#### `` test.skip.each`table`(name, fn) `` + +```js +test.skip.each` + a | b | expected + ${1} | ${1} | ${2} + ${1} | ${2} | ${3} + ${2} | ${1} | ${3} +`('returns $expected when $a is added $b', ({a, b, expected}) => { + expect(a + b).toBe(expected); // will not be ran +}); + +test('will be ran', () => { + expect(1 / 0).toBe(Infinity); +}); +``` diff --git a/website/versioned_docs/version-23.5/SnapshotTesting.md b/website/versioned_docs/version-23.5/SnapshotTesting.md new file mode 100644 index 000000000000..113d8d55d542 --- /dev/null +++ b/website/versioned_docs/version-23.5/SnapshotTesting.md @@ -0,0 +1,320 @@ +--- +id: version-23.5-snapshot-testing +title: Snapshot Testing +original_id: snapshot-testing +--- + +Snapshot tests are a very useful tool whenever you want to make sure your UI does not change unexpectedly. + +A typical snapshot test case for a mobile app renders a UI component, takes a screenshot, then compares it to a reference image stored alongside the test. The test will fail if the two images do not match: either the change is unexpected, or the screenshot needs to be updated to the new version of the UI component. + +## Snapshot Testing with Jest + +A similar approach can be taken when it comes to testing your React components. Instead of rendering the graphical UI, which would require building the entire app, you can use a test renderer to quickly generate a serializable value for your React tree. Consider this [example test](https://github.com/facebook/jest/blob/master/examples/snapshot/__tests__/link.react.test.js) for a simple [Link component](https://github.com/facebook/jest/blob/master/examples/snapshot/Link.react.js): + +```javascript +import React from 'react'; +import Link from '../Link.react'; +import renderer from 'react-test-renderer'; + +it('renders correctly', () => { + const tree = renderer + .create(Facebook) + .toJSON(); + expect(tree).toMatchSnapshot(); +}); +``` + +The first time this test is run, Jest creates a [snapshot file](https://github.com/facebook/jest/blob/master/examples/snapshot/__tests__/__snapshots__/link.react.test.js.snap) that looks like this: + +```javascript +exports[`renders correctly 1`] = ` + + Facebook + +`; +``` + +The snapshot artifact should be committed alongside code changes, and reviewed as part of your code review process. Jest uses [pretty-format](https://github.com/facebook/jest/tree/master/packages/pretty-format) to make snapshots human-readable during code review. On subsequent test runs Jest will simply compare the rendered output with the previous snapshot. If they match, the test will pass. If they don't match, either the test runner found a bug in your code (in this case, it's `` component) that should be fixed, or the implementation has changed and the snapshot needs to be updated. + +> Note: The snapshot is directly scoped to the data you render – in our example it's `` component with page prop passed to it. This implies that even if any other file has missing props (Say, `App.js`) in the `` component, it will still pass the test as the test doesn't know the usage of `` component and it's scoped only to the `Link.react.js`. +> Also, Rendering the same component with different props in other snapshot test will not affect the first one, as the tests don't know about each other. + +More information on how snapshot testing works and why we built it can be found on the [release blog post](https://jestjs.io/blog/2016/07/27/jest-14.html). We recommend reading [this blog post](http://benmccormick.org/2016/09/19/testing-with-jest-snapshots-first-impressions/) to get a good sense of when you should use snapshot testing. We also recommend watching this [egghead video](https://egghead.io/lessons/javascript-use-jest-s-snapshot-testing-feature?pl=testing-javascript-with-jest-a36c4074) on Snapshot Testing with Jest. + +### Updating Snapshots + +It's straightforward to spot when a snapshot test fails after a bug has been introduced. When that happens, go ahead and fix the issue and make sure your snapshot tests are passing again. Now, let's talk about the case when a snapshot test is failing due to an intentional implementation change. + +One such situation can arise if we intentionally change the address the Link component in our example is pointing to. + +```javascript +// Updated test case with a Link to a different address +it('renders correctly', () => { + const tree = renderer + .create(Instagram) + .toJSON(); + expect(tree).toMatchSnapshot(); +}); +``` + +In that case, Jest will print this output: + +![](/img/content/failedSnapshotTest.png) + +Since we just updated our component to point to a different address, it's reasonable to expect changes in the snapshot for this component. Our snapshot test case is failing because the snapshot for our updated component no longer matches the snapshot artifact for this test case. + +To resolve this, we will need to update our snapshot artifacts. You can run Jest with a flag that will tell it to re-generate snapshots: + +```bash +jest --updateSnapshot +``` + +Go ahead and accept the changes by running the above command. You may also use the equivalent single-character `-u` flag to re-generate snapshots if you prefer. This will re-generate snapshot artifacts for all failing snapshot tests. If we had any additional failing snapshot tests due to an unintentional bug, we would need to fix the bug before re-generating snapshots to avoid recording snapshots of the buggy behavior. + +If you'd like to limit which snapshot test cases get re-generated, you can pass an additional `--testNamePattern` flag to re-record snapshots only for those tests that match the pattern. + +You can try out this functionality by cloning the [snapshot example](https://github.com/facebook/jest/tree/master/examples/snapshot), modifying the `Link` component, and running Jest. + +### Interactive Snapshot Mode + +Failed snapshots can also be updated interactively in watch mode: + +![](/img/content/interactiveSnapshot.png) + +Once you enter Interactive Snapshot Mode, Jest will step you through the failed snapshots one test at a time and give you the opportunity to review the failed output. + +From here you can choose to update that snapshot or skip to the next: + +![](/img/content/interactiveSnapshotUpdate.gif) + +Once you're finished, Jest will give you a summary before returning back to watch mode: + +![](/img/content/interactiveSnapshotDone.png) + +### Inline Snapshots + +Inline snapshots behave identically to external snapshots (`.snap` files), except the snapshot values are written automatically back into the source code. This means you can get the benefits of automatically generated snapshots without having to switch to an external file to make sure the correct value was written. + +> Inline snapshots are powered by [Prettier](https://prettier.io). To use inline snapshots you must have `prettier` installed in your project. Your Prettier configuration will be respected when writing to test files. +> +> If you have `prettier` installed in a location where Jest can't find it, you can tell Jest how to find it using the [`"prettierPath"`](./Configuration.md#prettierpath-string) configuration property. + +**Example:** + +First, you write a test, calling `.toMatchInlineSnapshot()` with no arguments: + +```javascript +it('renders correctly', () => { + const tree = renderer + .create(Prettier) + .toJSON(); + expect(tree).toMatchInlineSnapshot(); +}); +``` + +The next time you run Jest, `tree` will be evaluated, and a snapshot will be written as an argument to `toMatchInlineSnapshot`: + +```javascript +it('renders correctly', () => { + const tree = renderer + .create(Prettier) + .toJSON(); + expect(tree).toMatchInlineSnapshot(` + + Prettier + +`); +}); +``` + +That's all there is to it! You can even update the snapshots with `--updateSnapshot` or using the `u` key in `--watch` mode. + +### Property Matchers + +Often there are fields in the object you want to snapshot which are generated (like IDs and Dates). If you try to snapshot these objects, they will force the snapshot to fail on every run: + +```javascript +it('will fail every time', () => { + const user = { + createdAt: new Date(), + id: Math.floor(Math.random() * 20), + name: 'LeBron James', + }; + + expect(user).toMatchSnapshot(); +}); + +// Snapshot +exports[`will fail every time 1`] = ` +Object { + "createdAt": 2018-05-19T23:36:09.816Z, + "id": 3, + "name": "LeBron James", +} +`; +``` + +For these cases, Jest allows providing an asymmetric matcher for any property. These matchers are checked before the snapshot is written or tested, and then saved to the snapshot file instead of the received value: + +```javascript +it('will check the matchers and pass', () => { + const user = { + createdAt: new Date(), + id: Math.floor(Math.random() * 20), + name: 'LeBron James', + }; + + expect(user).toMatchSnapshot({ + createdAt: expect.any(Date), + id: expect.any(Number), + }); +}); + +// Snapshot +exports[`will check the matchers and pass 1`] = ` +Object { + "createdAt": Any, + "id": Any, + "name": "LeBron James", +} +`; +``` + +Any given value that is not a matcher will be checked exactly and saved to the snapshot: + +```javascript +it('will check the values and pass', () => { + const user = { + createdAt: new Date(), + name: 'Bond... James Bond', + }; + + expect(user).toMatchSnapshot({ + createdAt: expect.any(Date), + name: 'Bond... James Bond', + }); +}); + +// Snapshot +exports[`will check the values and pass 1`] = ` +Object { + "createdAt": Any, + "name": 'Bond... James Bond', +} +`; +``` + +## Best Practices + +Snapshots are a fantastic tool for identifying unexpected interface changes within your application – whether that interface is an API response, UI, logs, or error messages. As with any testing strategy, there are some best-practices you should be aware of, and guidelines you should follow, in order to use them effectively. + +### 1. Treat snapshots as code + +Commit snapshots and review them as part of your regular code review process. This means treating snapshots as you would any other type of test or code in your project. + +Ensure that your snapshots are readable by keeping them focused, short, and by using tools that enforce these stylistic conventions. + +As mentioned previously, Jest uses [`pretty-format`](https://yarnpkg.com/en/package/pretty-format) to make snapshots human-readable, but you may find it useful to introduce additional tools, like [`eslint-plugin-jest`](https://yarnpkg.com/en/package/eslint-plugin-jest) with its [`no-large-snapshots`](https://github.com/jest-community/eslint-plugin-jest/blob/master/docs/rules/no-large-snapshots.md) option, or [`snapshot-diff`](https://yarnpkg.com/en/package/snapshot-diff) with its component snapshot comparison feature, to promote committing short, focused assertions. + +The goal is to make it easy to review snapshots in pull requests, and fight against the habit of simply regenerating snapshots when test suites fail instead of examining the root causes of their failure. + +### 2. Tests should be deterministic + +Your tests should be deterministic. Running the same tests multiple times on a component that has not changed should produce the same results every time. You're responsible for making sure your generated snapshots do not include platform specific or other non-deterministic data. + +For example, if you have a [Clock](https://github.com/facebook/jest/blob/master/examples/snapshot/Clock.react.js) component that uses `Date.now()`, the snapshot generated from this component will be different every time the test case is run. In this case we can [mock the Date.now() method](MockFunctions.md) to return a consistent value every time the test is run: + +```js +Date.now = jest.fn(() => 1482363367071); +``` + +Now, every time the snapshot test case runs, `Date.now()` will return `1482363367071` consistently. This will result in the same snapshot being generated for this component regardless of when the test is run. + +### 3. Use descriptive snapshot names + +Always strive to use descriptive test and/or snapshot names for snapshots. The best names describe the expected snapshot content. This makes it easier for reviewers to verify the snapshots during review, and for anyone to know whether or not an outdated snapshot is the correct behavior before updating. + +For example, compare: + +```js +exports[` should handle some test case`] = `null`; + +exports[` should handle some other test case`] = ` +
+ Alan Turing +
+`; +``` + +To: + +```js +exports[` should render null`] = `null`; + +exports[` should render Alan Turing`] = ` +
+ Alan Turing +
+`; +``` + +Since the later describes exactly what's expected in the output, it's easy to see when it's wrong: + +```js +exports[` should render null`] = ` +
+ Alan Turing +
+`; + +exports[` should render Alan Turing`] = `null`; +``` + +## Frequently Asked Questions + +### Are snapshots written automatically on Continuous Integration (CI) systems? + +No, as of Jest 20, snapshots in Jest are not automatically written when Jest is run in a CI system without explicitly passing `--updateSnapshot`. It is expected that all snapshots are part of the code that is run on CI and since new snapshots automatically pass, they should not pass a test run on a CI system. It is recommended to always commit all snapshots and to keep them in version control. + +### Should snapshot files be committed? + +Yes, all snapshot files should be committed alongside the modules they are covering and their tests. They should be considered as part of a test, similar to the value of any other assertion in Jest. In fact, snapshots represent the state of the source modules at any given point in time. In this way, when the source modules are modified, Jest can tell what changed from the previous version. It can also provide a lot of additional context during code review in which reviewers can study your changes better. + +### Does snapshot testing only work with React components? + +[React](TutorialReact.md) and [React Native](TutorialReactNative.md) components are a good use case for snapshot testing. However, snapshots can capture any serializable value and should be used anytime the goal is testing whether the output is correct. The Jest repository contains many examples of testing the output of Jest itself, the output of Jest's assertion library as well as log messages from various parts of the Jest codebase. See an example of [snapshotting CLI output](https://github.com/facebook/jest/blob/master/e2e/__tests__/console.test.js) in the Jest repo. + +### What's the difference between snapshot testing and visual regression testing? + +Snapshot testing and visual regression testing are two distinct ways of testing UIs, and they serve different purposes. Visual regression testing tools take screenshots of web pages and compare the resulting images pixel by pixel. With Snapshot testing values are serialized, stored within text files and compared using a diff algorithm. There are different trade-offs to consider and we listed the reasons why snapshot testing was built in the [Jest blog](https://jestjs.io/blog/2016/07/27/jest-14.html#why-snapshot-testing). + +### Does snapshot testing substitute unit testing? + +Snapshot testing is only one of more than 20 assertions that ship with Jest. The aim of snapshot testing is not to replace existing unit tests, but providing additional value and making testing painless. In some scenarios, snapshot testing can potentially remove the need for unit testing for a particular set of functionalities (e.g. React components), but they can work together as well. + +### What is the performance of snapshot testing regarding speed and size of the generated files? + +Jest has been rewritten with performance in mind, and snapshot testing is not an exception. Since snapshots are stored within text files, this way of testing is fast and reliable. Jest generates a new file for each test file that invokes the `toMatchSnapshot` matcher. The size of the snapshots is pretty small: For reference, the size of all snapshot files in the Jest codebase itself is less than 300 KB. + +### How do I resolve conflicts within snapshot files? + +Snapshot files must always represent the current state of the modules they are covering. Therefore, if you are merging two branches and encounter a conflict in the snapshot files, you can either resolve the conflict manually or to update the snapshot file by running Jest and inspecting the result. + +### Is it possible to apply test-driven development principles with snapshot testing? + +Although it is possible to write snapshot files manually, that is usually not approachable. Snapshots help figuring out whether the output of the modules covered by tests is changed, rather than giving guidance to design the code in the first place. + +### Does code coverage work with snapshots testing? + +Yes, just like with any other test. diff --git a/website/versioned_docs/version-23.5/TutorialAsync.md b/website/versioned_docs/version-23.5/TutorialAsync.md new file mode 100644 index 000000000000..9d044d1b5340 --- /dev/null +++ b/website/versioned_docs/version-23.5/TutorialAsync.md @@ -0,0 +1,167 @@ +--- +id: version-23.5-tutorial-async +title: An Async Example +original_id: tutorial-async +--- + +First, enable Babel support in Jest as documented in the [Getting Started](GettingStarted.md#using-babel) guide. + +Let's implement a simple module that fetches user data from an API and returns the user name. + +```js +// user.js +import request from './request'; + +export function getUserName(userID) { + return request('/users/' + userID).then(user => user.name); +} +``` + +In the above implementation we expect the `request.js` module to return a promise. We chain a call to `then` to receive the user name. + +Now imagine an implementation of `request.js` that goes to the network and fetches some user data: + +```js +// request.js +const http = require('http'); + +export default function request(url) { + return new Promise(resolve => { + // This is an example of an http request, for example to fetch + // user data from an API. + // This module is being mocked in __mocks__/request.js + http.get({path: url}, response => { + let data = ''; + response.on('data', _data => (data += _data)); + response.on('end', () => resolve(data)); + }); + }); +} +``` + +Because we don't want to go to the network in our test, we are going to create a manual mock for our `request.js` module in the `__mocks__` folder (the folder is case-sensitive, `__MOCKS__` will not work). It could look something like this: + +```js +// __mocks__/request.js +const users = { + 4: {name: 'Mark'}, + 5: {name: 'Paul'}, +}; + +export default function request(url) { + return new Promise((resolve, reject) => { + const userID = parseInt(url.substr('/users/'.length), 10); + process.nextTick( + () => + users[userID] + ? resolve(users[userID]) + : reject({ + error: 'User with ' + userID + ' not found.', + }), + ); + }); +} +``` + +Now let's write a test for our async functionality. + +```js +// __tests__/user-test.js +jest.mock('../request'); + +import * as user from '../user'; + +// The assertion for a promise must be returned. +it('works with promises', () => { + expect.assertions(1); + return user.getUserName(4).then(data => expect(data).toEqual('Mark')); +}); +``` + +We call `jest.mock('../request')` to tell Jest to use our manual mock. `it` expects the return value to be a Promise that is going to be resolved. You can chain as many Promises as you like and call `expect` at any time, as long as you return a Promise at the end. + +## `.resolves` + +There is a less verbose way using `resolves` to unwrap the value of a fulfilled promise together with any other matcher. If the promise is rejected, the assertion will fail. + +```js +it('works with resolves', () => { + expect.assertions(1); + return expect(user.getUserName(5)).resolves.toEqual('Paul'); +}); +``` + +## `async`/`await` + +Writing tests using the `async`/`await` syntax is easy. Here is how you'd write the same examples from before: + +```js +// async/await can be used. +it('works with async/await', async () => { + expect.assertions(1); + const data = await user.getUserName(4); + expect(data).toEqual('Mark'); +}); + +// async/await can also be used with `.resolves`. +it('works with async/await and resolves', async () => { + expect.assertions(1); + await expect(user.getUserName(5)).resolves.toEqual('Paul'); +}); +``` + +To enable async/await in your project, install [`babel-preset-env`](http://babeljs.io/docs/plugins/preset-env/) and enable the feature in your `.babelrc` file. + +## Error handling + +Errors can be handled using the `.catch` method. Make sure to add `expect.assertions` to verify that a certain number of assertions are called. Otherwise a fulfilled promise would not fail the test: + +```js +// Testing for async errors using Promise.catch. +test('tests error with promises', () => { + expect.assertions(1); + return user.getUserName(2).catch(e => + expect(e).toEqual({ + error: 'User with 2 not found.', + }), + ); +}); + +// Or using async/await. +it('tests error with async/await', async () => { + expect.assertions(1); + try { + await user.getUserName(1); + } catch (e) { + expect(e).toEqual({ + error: 'User with 1 not found.', + }); + } +}); +``` + +## `.rejects` + +The`.rejects` helper works like the `.resolves` helper. If the promise is fulfilled, the test will automatically fail. + +```js +// Testing for async errors using `.rejects`. +it('tests error with rejects', () => { + expect.assertions(1); + return expect(user.getUserName(3)).rejects.toEqual({ + error: 'User with 3 not found.', + }); +}); + +// Or using async/await with `.rejects`. +it('tests error with async/await and rejects', async () => { + expect.assertions(1); + await expect(user.getUserName(3)).rejects.toEqual({ + error: 'User with 3 not found.', + }); +}); +``` + +The code for this example is available at [examples/async](https://github.com/facebook/jest/tree/master/examples/async). + +If you'd like to test timers, like `setTimeout`, take a look at the [Timer mocks](TimerMocks.md) documentation. diff --git a/website/versioned_docs/version-23.5/TutorialReact.md b/website/versioned_docs/version-23.5/TutorialReact.md new file mode 100644 index 000000000000..d3500040ea49 --- /dev/null +++ b/website/versioned_docs/version-23.5/TutorialReact.md @@ -0,0 +1,311 @@ +--- +id: version-23.5-tutorial-react +title: Testing React Apps +original_id: tutorial-react +--- + +At Facebook, we use Jest to test [React](http://facebook.github.io/react/) applications. + +## Setup + +### Setup with Create React App + +If you are just getting started with React, we recommend using [Create React App](https://github.com/facebookincubator/create-react-app). It is ready to use and [ships with Jest](https://github.com/facebookincubator/create-react-app/blob/master/packages/react-scripts/template/README.md#running-tests)! You will only need to add `react-test-renderer` for rendering snapshots. + +Run + +```bash +yarn add --dev react-test-renderer +``` + +### Setup without Create React App + +If you have an existing application you'll need to install a few packages to make everything work well together. We are using the `babel-jest` package and the `react` babel preset to transform our code inside of the test environment. Also see [using babel](GettingStarted.md#using-babel). + +Run + +```bash +yarn add --dev jest babel-jest babel-preset-env babel-preset-react react-test-renderer +``` + +Your `package.json` should look something like this (where `` is the actual latest version number for the package). Please add the scripts and jest configuration entries: + +```json +// package.json + "dependencies": { + "react": "", + "react-dom": "" + }, + "devDependencies": { + "babel-jest": "", + "babel-preset-env": "", + "babel-preset-react": "", + "jest": "", + "react-test-renderer": "" + }, + "scripts": { + "test": "jest" + } +``` + +```json +// .babelrc +{ + "presets": ["env", "react"] +} +``` + +**And you're good to go!** + +### Snapshot Testing + +Let's create a [snapshot test](SnapshotTesting.md) for a Link component that renders hyperlinks: + +```javascript +// Link.react.js +import React from 'react'; + +const STATUS = { + HOVERED: 'hovered', + NORMAL: 'normal', +}; + +export default class Link extends React.Component { + constructor(props) { + super(props); + + this._onMouseEnter = this._onMouseEnter.bind(this); + this._onMouseLeave = this._onMouseLeave.bind(this); + + this.state = { + class: STATUS.NORMAL, + }; + } + + _onMouseEnter() { + this.setState({class: STATUS.HOVERED}); + } + + _onMouseLeave() { + this.setState({class: STATUS.NORMAL}); + } + + render() { + return ( + + {this.props.children} + + ); + } +} +``` + +Now let's use React's test renderer and Jest's snapshot feature to interact with the component and capture the rendered output and create a snapshot file: + +```javascript +// Link.react.test.js +import React from 'react'; +import Link from '../Link.react'; +import renderer from 'react-test-renderer'; + +test('Link changes the class when hovered', () => { + const component = renderer.create( + Facebook, + ); + let tree = component.toJSON(); + expect(tree).toMatchSnapshot(); + + // manually trigger the callback + tree.props.onMouseEnter(); + // re-rendering + tree = component.toJSON(); + expect(tree).toMatchSnapshot(); + + // manually trigger the callback + tree.props.onMouseLeave(); + // re-rendering + tree = component.toJSON(); + expect(tree).toMatchSnapshot(); +}); +``` + +When you run `yarn test` or `jest`, this will produce an output file like this: + +```javascript +// __tests__/__snapshots__/Link.react.test.js.snap +exports[`Link changes the class when hovered 1`] = ` + + Facebook + +`; + +exports[`Link changes the class when hovered 2`] = ` + + Facebook + +`; + +exports[`Link changes the class when hovered 3`] = ` + + Facebook + +`; +``` + +The next time you run the tests, the rendered output will be compared to the previously created snapshot. The snapshot should be committed along code changes. When a snapshot test fails, you need to inspect whether it is an intended or unintended change. If the change is expected you can invoke Jest with `jest -u` to overwrite the existing snapshot. + +The code for this example is available at [examples/snapshot](https://github.com/facebook/jest/tree/master/examples/snapshot). + +#### Snapshot Testing with Mocks, Enzyme and React 16 + +There's a caveat around snapshot testing when using Enzyme and React 16+. If you mock out a module using the following style: + +```js +jest.mock('../SomeDirectory/SomeComponent', () => 'SomeComponent'); +``` + +Then you will see warnings in the console: + +```bash +Warning: is using uppercase HTML. Always use lowercase HTML tags in React. + +# Or: +Warning: The tag is unrecognized in this browser. If you meant to render a React component, start its name with an uppercase letter. +``` + +React 16 triggers these warnings due to how it checks element types, and the mocked module fails these checks. Your options are: + +1. Render as text. This way you won't see the props passed to the mock component in the snapshot, but it's straightforward: + ```js + jest.mock('./SomeComponent', () => () => 'SomeComponent'); + ``` +2. Render as a custom element. DOM "custom elements" aren't checked for anything and shouldn't fire warnings. They are lowercase and have a dash in the name. + ```js + jest.mock('./Widget', () => 'mock-widget'); + ``` +3. Use `react-test-renderer`. The test renderer doesn't care about element types and will happily accept e.g. `SomeComponent`. You could check snapshots using the test renderer, and check component behavior separately using Enzyme. +4. Disable warnings all together (should be done in your jest setup file): + ```js + jest.mock('fbjs/lib/warning', () => require('fbjs/lib/emptyFunction')); + ``` + This shouldn't normally be your option of choice as useful warnings could be lost. However, in some cases, for example when testing react-native's components we are rendering react-native tags into the DOM and many warnings are irrelevant. Another option is to swizzling console.warn and supress specific warnings. + +### DOM Testing + +If you'd like to assert, and manipulate your rendered components you can use [Enzyme](http://airbnb.io/enzyme/) or React's [TestUtils](http://facebook.github.io/react/docs/test-utils.html). We use Enzyme for this example. + +You have to run `yarn add --dev enzyme` to use Enzyme. If you are using a React version below 15.5.0, you will also need to install `react-addons-test-utils`. + +Let's implement a simple checkbox which swaps between two labels: + +```javascript +// CheckboxWithLabel.js + +import React from 'react'; + +export default class CheckboxWithLabel extends React.Component { + constructor(props) { + super(props); + this.state = {isChecked: false}; + + // bind manually because React class components don't auto-bind + // http://facebook.github.io/react/blog/2015/01/27/react-v0.13.0-beta-1.html#autobinding + this.onChange = this.onChange.bind(this); + } + + onChange() { + this.setState({isChecked: !this.state.isChecked}); + } + + render() { + return ( + + ); + } +} +``` + +We use Enzyme's [shallow renderer](http://airbnb.io/enzyme/docs/api/shallow.html) in this example. + +```javascript +// __tests__/CheckboxWithLabel-test.js + +import React from 'react'; +import {shallow} from 'enzyme'; +import CheckboxWithLabel from '../CheckboxWithLabel'; + +test('CheckboxWithLabel changes the text after click', () => { + // Render a checkbox with label in the document + const checkbox = shallow(); + + expect(checkbox.text()).toEqual('Off'); + + checkbox.find('input').simulate('change'); + + expect(checkbox.text()).toEqual('On'); +}); +``` + +The code for this example is available at [examples/enzyme](https://github.com/facebook/jest/tree/master/examples/enzyme). + +### Custom transformers + +If you need more advanced functionality, you can also build your own transformer. Instead of using babel-jest, here is an example of using babel: + +```javascript +// custom-transformer.js +'use strict'; + +const babel = require('babel-core'); +const jestPreset = require('babel-preset-jest'); + +module.exports = { + process(src, filename) { + if (babel.util.canCompile(filename)) { + return babel.transform(src, { + filename, + presets: [jestPreset], + }); + } + return src; + }, +}; +``` + +Don't forget to install the `babel-core` and `babel-preset-jest` packages for this example to work. + +To make this work with Jest you need to update your Jest configuration with this: `"transform": {"\\.js$": "path/to/custom-transformer.js"}`. + +If you'd like to build a transformer with babel support, you can also use babel-jest to compose one and pass in your custom configuration options: + +```javascript +const babelJest = require('babel-jest'); + +module.exports = babelJest.createTransformer({ + presets: ['my-custom-preset'], +}); +``` diff --git a/website/versioned_docs/version-23.5/WatchPlugins.md b/website/versioned_docs/version-23.5/WatchPlugins.md new file mode 100644 index 000000000000..816a92a7cd2f --- /dev/null +++ b/website/versioned_docs/version-23.5/WatchPlugins.md @@ -0,0 +1,231 @@ +--- +id: version-23.5-watch-plugins +title: Watch Plugins +original_id: watch-plugins +--- + +The Jest watch plugin system provides a way to hook into specific parts of Jest and to define watch mode menu prompts that execute code on key press. Combined, these features allow you to develop interactive experiences custom for your workflow. + +## Watch Plugin Interface + +```javascript +class MyWatchPlugin { + // Add hooks to Jest lifecycle events + apply(jestHooks) {} + + // Get the prompt information for interactive plugins + getUsageInfo(globalConfig) {} + + // Executed when the key from `getUsageInfo` is input + run(globalConfig, updateConfigAndRun) {} +} +``` + +## Hooking into Jest + +To connect your watch plugin to Jest, add its path under `watchPlugins` in your Jest configuration: + +```javascript +// jest.config.js +module.exports = { + // ... + watchPlugins: ['path/to/yourWatchPlugin'], +}; +``` + +Custom watch plugins can add hooks to Jest events. These hooks can be added either with or without having an interactive key in the watch mode menu. + +### `apply(jestHooks)` + +Jest hooks can be attached by implementing the `apply` method. This method receives a `jestHooks` argument that allows the plugin to hook into specific parts of the lifecycle of a test run. + +```javascript +class MyWatchPlugin { + apply(jestHooks) {} +} +``` + +Below are the hooks available in Jest. + +#### `jestHooks.shouldRunTestSuite(testPath)` + +Returns a boolean (or `Promise` for handling asynchronous operations) to specify if a test should be run or not. + +For example: + +```javascript +class MyWatchPlugin { + apply(jestHooks) { + jestHooks.shouldRunTestSuite(testPath => { + return testPath.includes('my-keyword'); + }); + + // or a promise + jestHooks.shouldRunTestSuite(testPath => { + return Promise.resolve(testPath.includes('my-keyword')); + }); + } +} +``` + +#### `jestHooks.onTestRunComplete(results)` + +Gets called at the end of every test run. It has the test results as an argument. + +For example: + +```javascript +class MyWatchPlugin { + apply(jestHooks) { + jestHooks.onTestRunComplete(results => { + this._hasSnapshotFailure = results.snapshot.failure; + }); + } +} +``` + +#### `jestHooks.onFileChange({projects})` + +Gets called whenever there is a change in the file system + +- `projects: Array`: Includes all the test paths that Jest is watching. + +For example: + +```javascript +class MyWatchPlugin { + apply(jestHooks) { + jestHooks.onFileChange(({projects}) => { + this._projects = projects; + }); + } +} +``` + +## Watch Menu Integration + +Custom watch plugins can also add or override functionality to the watch menu by specifying a key/prompt pair in `getUsageInfo` method and a `run` method for the execution of the key. + +### `getUsageInfo(globalConfig)` + +To add a key to the watch menu, implement the `getUsageInfo` method, returning a key and the prompt: + +```javascript +class MyWatchPlugin { + getUsageInfo(globalConfig) { + return { + key: 's', + prompt: 'do something', + }; + } +} +``` + +This will add a line in the watch mode menu _(`› Press s to do something.`)_ + +```text +Watch Usage + › Press p to filter by a filename regex pattern. + › Press t to filter by a test name regex pattern. + › Press q to quit watch mode. + › Press s to do something. // <-- This is our plugin + › Press Enter to trigger a test run. +``` + +**Note**: If the key for your plugin already exists as a default key, your plugin will override that key. + +### `run(globalConfig, updateConfigAndRun)` + +To handle key press events from the key returned by `getUsageInfo`, you can implement the `run` method. This method returns a `Promise` that can be resolved when the plugin wants to return control to Jest. The `boolean` specifies if Jest should rerun the tests after it gets the control back. + +- `globalConfig`: A representation of Jest's current global configuration +- `updateConfigAndRun`: Allows you to trigger a test run while the interactive plugin is running. + +```javascript +class MyWatchPlugin { + run(globalConfig, updateConfigAndRun) { + // do something. + } +} +``` + +**Note**: If you do call `updateConfigAndRun`, your `run` method should not resolve to a truthy value, as that would trigger a double-run. + +#### Authorized configuration keys + +For stability and safety reasons, only part of the global configuration keys can be updated with `updateConfigAndRun`. The current white list is as follows: + +- [`bail`](configuration.html#bail-boolean) +- [`collectCoverage`](configuration.html#collectcoverage-boolean) +- [`collectCoverageFrom`](configuration.html#collectcoveragefrom-array) +- [`collectCoverageOnlyFrom`](configuration.html#collectcoverageonlyfrom-array) +- [`coverageDirectory`](configuration.html#coveragedirectory-string) +- [`coverageReporters`](configuration.html#coveragereporters-array) +- [`notify`](configuration.html#notify-boolean) +- [`notifyMode`](configuration.html#notifymode-string) +- [`onlyFailures`](configuration.html#onlyfailures-boolean) +- [`reporters`](configuration.html#reporters-array-modulename-modulename-options) +- [`testNamePattern`](cli.html#testnamepattern-regex) +- [`testPathPattern`](cli.html#testpathpattern-regex) +- [`updateSnapshot`](cli.html#updatesnapshot) +- [`verbose`](configuration.html#verbose-boolean) + +## Customization + +Plugins can be customized via your Jest configuration. + +```javascript +// jest.config.js +module.exports = { + // ... + watchPlugins: [ + [ + 'path/to/yourWatchPlugin', + { + key: 'k', // <- your custom key + prompt: 'show a custom prompt', + }, + ], + ], +}; +``` + +Recommended config names: + +- `key`: Modifies the plugin key. +- `prompt`: Allows user to customize the text in the plugin prompt. + +If the user provided a custom configuration, it will be passed as an argument to the plugin constructor. + +```javascript +class MyWatchPlugin { + constructor({config}) {} +} +``` + +## Choosing a good key + +Jest allows third-party plugins to override some of its built-in feature keys, but not all. Specifically, the following keys are **not overwritable** : + +- `c` (clears filter patterns) +- `i` (updates non-matching snapshots interactively) +- `q` (quits) +- `u` (updates all non-matching snapshots) +- `w` (displays watch mode usage / available actions) + +The following keys for built-in functionality **can be overwritten** : + +- `p` (test filename pattern) +- `t` (test name pattern) + +Any key not used by built-in functionality can be claimed, as you would expect. Try to avoid using keys that are difficult to obtain on various keyboards (e.g. `é`, `€`), or not visible by default (e.g. many Mac keyboards do not have visual hints for characters such as `|`, `\`, `[`, etc.) + +### When a conflict happens + +Should your plugin attempt to overwrite a reserved key, Jest will error out with a descriptive message, something like: + +> Watch plugin YourFaultyPlugin attempted to register key , that is reserved internally for quitting watch mode. Please change the configuration key for this plugin. + +Third-party plugins are also forbidden to overwrite a key reserved already by another third-party plugin present earlier in the configured plugins list (`watchPlugins` array setting). When this happens, you’ll also get an error message that tries to help you fix that: + +> Watch plugins YourFaultyPlugin and TheirFaultyPlugin both attempted to register key . Please change the key configuration for one of the conflicting plugins to avoid overlap. diff --git a/website/versioned_sidebars/version-23.4-sidebars.json b/website/versioned_sidebars/version-23.4-sidebars.json new file mode 100644 index 000000000000..cef118a6c213 --- /dev/null +++ b/website/versioned_sidebars/version-23.4-sidebars.json @@ -0,0 +1,41 @@ +{ + "version-23.4-docs": { + "Introduction": [ + "version-23.4-getting-started", + "version-23.4-using-matchers", + "version-23.4-asynchronous", + "version-23.4-setup-teardown", + "version-23.4-mock-functions", + "version-23.4-jest-platform", + "version-23.4-jest-community", + "version-23.4-more-resources" + ], + "Guides": [ + "version-23.4-snapshot-testing", + "version-23.4-tutorial-async", + "version-23.4-timer-mocks", + "version-23.4-manual-mocks", + "version-23.4-es6-class-mocks", + "version-23.4-bypassing-module-mocks", + "version-23.4-webpack", + "version-23.4-puppeteer", + "version-23.4-mongodb", + "version-23.4-watch-plugins", + "version-23.4-migration-guide", + "version-23.4-troubleshooting" + ], + "Framework Guides": [ + "version-23.4-tutorial-react", + "version-23.4-tutorial-react-native", + "version-23.4-testing-frameworks" + ], + "API Reference": [ + "version-23.4-api", + "version-23.4-expect", + "version-23.4-mock-function-api", + "version-23.4-jest-object", + "version-23.4-configuration", + "version-23.4-cli" + ] + } +} diff --git a/website/versions.json b/website/versions.json index 3e8fd743a724..cfbe4b0e72df 100644 --- a/website/versions.json +++ b/website/versions.json @@ -1,4 +1,6 @@ [ + "23.5", + "23.4", "23.3", "23.2", "23.1",