diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md index 98bbca702d84..c6b9794584a4 100644 --- a/.github/ISSUE_TEMPLATE.md +++ b/.github/ISSUE_TEMPLATE.md @@ -21,5 +21,7 @@ repository on GitHub that we can `yarn install` and `yarn test`.** **What is the expected behavior?** -**Please provide your exact Jest configuration and mention your Jest, node, -yarn/npm version and operating system.** +**Please provide your exact Jest configuration** + +**Run `npx envinfo --preset jest` in your project directory and paste the +results here** diff --git a/CHANGELOG.md b/CHANGELOG.md index f9ff2e28ca13..862db3c3d283 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,11 @@ ### Features +* `[expect]` Improve output format for mismatchedArgs in mock/spy calls. + ([#5846](https://github.com/facebook/jest/pull/5846)) +* `[jest-cli]` Add support for using `--coverage` in combination with watch + mode, `--onlyChanged`, `--findRelatedTests` and more + ([#5601](https://github.com/facebook/jest/pull/5601)) * `[jest-jasmine2]` Adds error throwing and descriptive errors to `it`/ `test` for invalid arguments. `[jest-circus]` Adds error throwing and descriptive errors to `it`/ `test` for invalid arguments @@ -16,16 +21,31 @@ ([#5670](https://github.com/facebook/jest/pull/5670)) * `[expect]` Add inverse matchers (`expect.not.arrayContaining`, etc., [#5517](https://github.com/facebook/jest/pull/5517)) +* `[expect]` `expect.extend` now also extends asymmetric matchers + ([#5503](https://github.com/facebook/jest/pull/5503)) +* `[jest-mock]` Update `spyOnProperty` to support spying on the prototype chain + ([#5753](https://github.com/facebook/jest/pull/5753)) * `[jest-mock]` Add tracking of return values in the `mock` property - ([#5738](https://github.com/facebook/jest/issues/5738)) + ([#5752](https://github.com/facebook/jest/pull/5752)) +* `[jest-mock]` Add tracking of thrown errors in the `mock` property + ([#5764](https://github.com/facebook/jest/pull/5764)) * `[expect]`Add nthCalledWith spy matcher ([#5605](https://github.com/facebook/jest/pull/5605)) * `[jest-cli]` Add `isSerial` property that runners can expose to specify that they can not run in parallel - [#5706](https://github.com/facebook/jest/pull/5706) + ([#5706](https://github.com/facebook/jest/pull/5706)) +* `[expect]` Add `.toBeCalledTimes` and `toHaveBeenNthCalledWith` aliases + ([#5826](https://github.com/facebook/jest/pull/5826)) +* `[jest-cli]` Interactive Snapshot Mode improvements + ([#5864](https://github.com/facebook/jest/pull/5864)) ### Fixes +* `[jest-runner]` Assign `process.env.JEST_WORKER_ID="1"` when in runInBand mode + ([#5860](https://github.com/facebook/jest/pull/5860)) +* `[jest-cli]` Add descriptive error message when trying to use + `globalSetup`/`globalTeardown` file that doesn't export a function. + ([#5835](https://github.com/facebook/jest/pull/5835)) * `[expect]` Do not rely on `instanceof RegExp`, since it will not work for RegExps created inside of a different VM ([#5729](https://github.com/facebook/jest/pull/5729)) @@ -45,11 +65,15 @@ ([#5702](https://github.com/facebook/jest/pull/5702)) * `[jest-mock]` Prevent `mockRejectedValue` from causing unhandled rejection ([#5720](https://github.com/facebook/jest/pull/5720)) +* `[pretty-format]` Handle React fragments better + ([#5816](https://github.com/facebook/jest/pull/5816)) ### Chore & Maintenance +* `[#5858]` Run Prettier on compiled output + ([#5858](https://github.com/facebook/jest/pull/3497)) * `[#5708]` Add fileChange hook for plugins - ([#5648](https://github.com/facebook/jest/pull/5708)) + ([#5708](https://github.com/facebook/jest/pull/5708)) * `[docs]` Add docs on using `jest.mock(...)` ([#5648](https://github.com/facebook/jest/pull/5648)) * `[docs]` Mention Jest Puppeteer Preset @@ -128,7 +152,7 @@ * `[docs]` Add a documentation note for project `displayName` configuration ([#5600](https://github.com/facebook/jest/pull/5600)) -# Chore & Maintenance +### Chore & Maintenance * `[docs]` Update automatic mocks documentation ([#5630](https://github.com/facebook/jest/pull/5630)) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7f4216384d91..b1e1176ca119 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -73,8 +73,9 @@ _Before_ submitting a pull request, please make sure the following is done… 5. If you've changed APIs, update the documentation. 6. Ensure the test suite passes via `yarn test`. To run the test suite you may - need to install Mercurial (`hg`). On macOS, this can be done using - [homebrew](http://brew.sh/): `brew install hg`. + need to install [Mercurial](https://www.mercurial-scm.org/) (`hg`). On + macOS, this can be done using [homebrew](http://brew.sh/): + `brew install hg`. ```sh brew install hg # maybe diff --git a/README.md b/README.md index c17c42750954..2aa76f06997a 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,7 @@ [![Travis Build Status](https://travis-ci.org/facebook/jest.svg?branch=master)](https://travis-ci.org/facebook/jest) [![Windows Build Status](https://ci.appveyor.com/api/projects/status/8n38o44k585hhvhd/branch/master?svg=true)](https://ci.appveyor.com/project/Daniel15/jest/branch/master) [![npm version](https://badge.fury.io/js/jest.svg)](http://badge.fury.io/js/jest) +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) 🃏 Delightful JavaScript Testing diff --git a/crowdin.yaml b/crowdin.yaml index 10f14763c74f..40a2a93b3499 100644 --- a/crowdin.yaml +++ b/crowdin.yaml @@ -43,6 +43,10 @@ files: 'vi': 'vi' 'zh-CN': 'zh-Hans' 'zh-TW': 'zh-Hant' + - + source: '/website/versioned_docs/**/*.md' + translation: '/website/translated_docs/%locale%/**/%original_file_name%' + languages_mapping: *anchor - source: '/website/i18n/en.json' translation: '/website/i18n/%locale%.json' diff --git a/docs/CLI.md b/docs/CLI.md index ad98e977b092..78b8de50915c 100644 --- a/docs/CLI.md +++ b/docs/CLI.md @@ -129,8 +129,6 @@ commit. Behaves similarly to `--onlyChanged`. ### `--changedSince` -##### available in Jest **22.2.0+** - 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`. @@ -144,8 +142,6 @@ fail the test and require Jest to be run with `--updateSnapshot`. ### `--clearCache` -##### available in Jest **22.0.0+** - 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 @@ -189,7 +185,9 @@ Alias: `-e`. Use this flag to show full diffs and errors instead of a patch. 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. +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` diff --git a/docs/Configuration.md b/docs/Configuration.md index fba056a83aac..343e6d98aaa7 100644 --- a/docs/Configuration.md +++ b/docs/Configuration.md @@ -123,6 +123,14 @@ 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` @@ -494,20 +502,10 @@ _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._ -### `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. - ### `reporters` [array] Default: `undefined` -##### available in Jest **20.0.0+** - Use this configuration option to add custom reporters to Jest. A custom reporter is a class that implements `onRunStart`, `onTestStart`, `onTestResult`, `onRunComplete` methods that will be called when any of those events occurs. @@ -606,8 +604,6 @@ programmatically using [`jest.resetModules()`](#jest-resetmodules). Default: `undefined` -##### available in Jest **20.0.0+** - This option allows the use of a custom resolver. This resolver must be a node module that exports a function expecting a string as the first argument for the path to resolve and an object with the following structure as the second @@ -677,8 +673,6 @@ where you may want to have multiple roots within one project, for example ### `runner` [string] -##### available in Jest **21.0.0+** - Default: `"jest-runner"` This option allows you to use a custom runner instead of Jest's default test @@ -816,8 +810,6 @@ you can use the `node` option to use a node-like environment instead. If some tests require another environment, you can add a `@jest-environment` docblock. -##### available in Jest **20.0.0+** - ```js /** * @jest-environment jsdom @@ -835,8 +827,6 @@ environment. The module must export a class with `setup`, `teardown` and suites by assigning them to `this.global` object – this will make them available in your test suites as global variables. -##### available in Jest **22.0.0+** - _Note: TestEnvironment is sandboxed. Each test suite will trigger setup/teardown in their own TestEnvironment._ @@ -880,8 +870,6 @@ beforeAll(() => { ### `testEnvironmentOptions` [Object] -##### available in Jest **22.0.0+** - Default: `{}` Test environment options that will be passed to the `testEnvironment`. The @@ -891,8 +879,6 @@ given to [jsdom](https://github.com/tmpvar/jsdom) such as ### `testMatch` [array] -##### available in Jest **19.0.0+** - (default: `[ '**/__tests__/**/*.js?(x)', '**/?(*.)+(spec|test).js?(x)' ]`) The glob patterns Jest uses to detect test files. By default it looks for `.js` @@ -1110,8 +1096,6 @@ errors will also still be shown on the bottom after execution. Default: `[]` -##### available in Jest **21.0.0+** - 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. diff --git a/docs/Es6ClassMocks.md b/docs/Es6ClassMocks.md index e9f8ae02ca5c..bc29bb3bcdc4 100644 --- a/docs/Es6ClassMocks.md +++ b/docs/Es6ClassMocks.md @@ -214,7 +214,7 @@ class, but does not provide a way to spy on calls. For the contrived example, the mock might look like this: ```javascript -// __mocks/sound-player.js +// __mocks__/sound-player.js export default class SoundPlayer { constructor() { console.log('Mock SoundPlayer: constructor was called'); diff --git a/docs/ExpectAPI.md b/docs/ExpectAPI.md index 784575aaab3e..8399372cfb95 100644 --- a/docs/ExpectAPI.md +++ b/docs/ExpectAPI.md @@ -68,6 +68,10 @@ expect.extend({ 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), + }); }); ``` @@ -451,8 +455,6 @@ test('the best flavor is not coconut', () => { ### `.resolves` -##### available in Jest **20.0.0+** - 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. @@ -481,8 +483,6 @@ test('resolves to lemon', async () => { ### `.rejects` -##### available in Jest **20.0.0+** - 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. @@ -567,6 +567,8 @@ describe('drinkAll', () => { ### `.toHaveBeenCalledTimes(number)` +Also under the alias: `.toBeCalledTimes(number)` + Use `.toHaveBeenCalledTimes` to ensure that a mock function got called exact number of times. @@ -622,10 +624,12 @@ test('applying to all flavors does mango last', () => { }); ``` -### `.nthCalledWith(nthCall, arg1, arg2, ....)` +### `.toHaveBeenNthCalledWith(nthCall, arg1, arg2, ....)` + +Also under the alias: `.nthCalledWith(arg1, arg2, ...)` -If you have a mock function, you can use `.nthCalledWith` to test what arguments -it was nth called with. For example, let's say you have a +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: @@ -636,8 +640,8 @@ Note that, nth argument must be positive integer starting from 1. test('drinkEach drinks each drink', () => { const drink = jest.fn(); drinkEach(drink, ['lemon', 'octopus']); - expect(drink).nthCalledWith(1, 'lemon'); - expect(drink).nthCalledWith(2, 'octopus'); + expect(drink).toHaveBeenNthCalledWith(1, 'lemon'); + expect(drink).toHaveBeenNthCalledWith(2, 'octopus'); }); ``` diff --git a/docs/JestObjectAPI.md b/docs/JestObjectAPI.md index 3169bd70244f..65dc9d6381f1 100644 --- a/docs/JestObjectAPI.md +++ b/docs/JestObjectAPI.md @@ -314,8 +314,6 @@ Returns the `jest` object for chaining. ### `jest.restoreAllMocks()` -##### available in Jest **21.1.0+** - Restores all mocks back to their original value. Equivalent to calling `.mockRestore` on every mocked function. Beware that `jest.restoreAllMocks()` only works when mock was created with `jest.spyOn`; other mocks will require you @@ -464,8 +462,6 @@ Returns the `jest` object for chaining. ### `jest.spyOn(object, methodName)` -##### available in Jest **19.0.0+** - Creates a mock function similar to `jest.fn` but also tracks calls to `object[methodName]`. Returns a Jest mock function. @@ -506,8 +502,6 @@ test('plays video', () => { ### `jest.spyOn(object, methodName, accessType?)` -##### available in Jest **22.1.0+** - Since Jest 22.1.0+, the `jest.spyOn` method takes an optional third argument of `accessType` that can be either `'get'` or `'set'`, which proves to be useful when you want to spy on a getter or a setter, respectively. diff --git a/docs/MockFunctionAPI.md b/docs/MockFunctionAPI.md index bdd383089a18..fd0d83e45a0d 100644 --- a/docs/MockFunctionAPI.md +++ b/docs/MockFunctionAPI.md @@ -18,8 +18,6 @@ implementation is given, the mock function will return `undefined` when invoked. ### `mockFn.getMockName()` -##### available in Jest **22.0.0+** - Returns the mock name string set by calling `mockFn.mockName(value)`. ### `mockFn.mock.calls` @@ -39,14 +37,30 @@ a `mock.calls` array that looks like this: ### `mockFn.mock.returnValues` An array containing values that have been returned by all calls to this mock +function. For any call to the mock that throws an error, a value of `undefined` +will be stored in `mock.returnValues`. + +For example: A mock function `f` that has been called three times, returning +`result1`, throwing an error, and then returning `result2`, would have a +`mock.returnValues` array that looks like this: + +```js +['result1', undefined, 'result2']; +``` + +### `mockFn.mock.thrownErrors` + +An array containing errors that have been thrown by all calls to this mock function. -For example: A mock function `f` that has been called twice, returning -`result1`, and then returning `result2`, would have a `mock.returnValues` array -that looks like this: +For example: A mock function `f` that has been called twice, throwing an +`Error`, and then executing successfully without an error, would have the +following `mock.thrownErrors` array: ```js -['result1', 'result2']; +f.mock.thrownErrors.length === 2; // true +f.mock.thrownErrors[0] instanceof Error; // true +f.mock.thrownErrors[1] === undefined; // true ``` ### `mockFn.mock.instances` @@ -195,8 +209,6 @@ console.log(myMockFn(), myMockFn(), myMockFn(), myMockFn()); ### `mockFn.mockName(value)` -##### available in Jest **22.0.0+** - Accepts a string to use in test result output in place of "jest.fn()" to indicate which mock function is being referenced. @@ -258,8 +270,6 @@ console.log(myMockFn(), myMockFn(), myMockFn(), myMockFn()); ### `mockFn.mockResolvedValue(value)` -##### available in Jest **22.2.0+** - Simple sugar function for: ```js @@ -278,8 +288,6 @@ test('async test', async () => { ### `mockFn.mockResolvedValueOnce(value)` -##### available in Jest **22.2.0+** - Simple sugar function for: ```js @@ -305,8 +313,6 @@ test('async test', async () => { ### `mockFn.mockRejectedValue(value)` -##### available in Jest **22.2.0+** - Simple sugar function for: ```js @@ -325,8 +331,6 @@ test('async test', async () => { ### `mockFn.mockRejectedValueOnce(value)` -##### available in Jest **22.2.0+** - Simple sugar function for: ```js diff --git a/docs/MockFunctions.md b/docs/MockFunctions.md index ae674c1b05cc..177da5cbee82 100644 --- a/docs/MockFunctions.md +++ b/docs/MockFunctions.md @@ -173,7 +173,7 @@ test('should fetch users', () => { axios.get.mockResolvedValue(resp); // or you could use the following depending on your use case: - // axios.get.mockImpementation(() => Promise.resolve(resp)) + // axios.get.mockImplementation(() => Promise.resolve(resp)) return Users.all().then(users => expect(users).toEqual(resp.data)); }); @@ -266,8 +266,6 @@ const otherObj = { ## Mock Names -##### available in Jest **22.0.0+** - You can optionally provide a name for your mock functions, which will be displayed instead of "jest.fn()" in test error output. Use this if you want to be able to quickly identify the mock function reporting an error in your test diff --git a/docs/Puppeteer.md b/docs/Puppeteer.md index f38b0427b7dd..7961476073b2 100644 --- a/docs/Puppeteer.md +++ b/docs/Puppeteer.md @@ -9,20 +9,20 @@ work smoothly with [puppeteer](https://github.com/GoogleChrome/puppeteer). ## Use Puppeteer Preset -[Jest Puppeteer Preset](https://github.com/smooth-code/jest-puppeteer) provides -all required configuration to run your tests using Puppeteer. +[Jest Puppeteer](https://github.com/smooth-code/jest-puppeteer) provides all +required configuration to run your tests using Puppeteer. -1. First install `jest-puppeteer-preset` +1. First install `jest-puppeteer` ``` -yarn add --dev jest-puppeteer-preset +yarn add --dev jest-puppeteer ``` 2. Specify preset in your Jest configuration: ```json { - "preset": "jest-puppeteer-preset" + "preset": "jest-puppeteer" } ``` diff --git a/docs/SnapshotTesting.md b/docs/SnapshotTesting.md index 1f01c626cc90..ca285458766b 100644 --- a/docs/SnapshotTesting.md +++ b/docs/SnapshotTesting.md @@ -128,13 +128,18 @@ Failed snapshots can also be updated interactively in watch mode: ![](/jest/img/content/interactiveSnapshot.png) Once you enter Interactive Snapshot Mode, Jest will step you through the failed -snapshots one test suite at a time and give you the opportunity to review the -failed output. +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: ![](/jest/img/content/interactiveSnapshotUpdate.gif) +Once you're finished, Jest will give you a summary before returning back to +watch mode: + +![](/jest/img/content/interactiveSnapshotDone.png) + ### Tests Should Be Deterministic Your tests should be deterministic. That is, running the same tests multiple diff --git a/docs/TestingAsyncCode.md b/docs/TestingAsyncCode.md index 72abbbd4febc..2a9e89b8b78a 100644 --- a/docs/TestingAsyncCode.md +++ b/docs/TestingAsyncCode.md @@ -86,8 +86,6 @@ test('the fetch fails with an error', () => { ### `.resolves` / `.rejects` -##### available in Jest **20.0.0+** - You can also use the `.resolves` matcher in your expect statement, and Jest will wait for that promise to resolve. If the promise is rejected, the test will automatically fail. @@ -136,8 +134,7 @@ test('the fetch fails with an error', async () => { }); ``` -Of course, you can combine `async` and `await` with `.resolves` or `.rejects` -(available in Jest **20.0.0+**). +Of course, you can combine `async` and `await` with `.resolves` or `.rejects`. ```js test('the data is peanut butter', async () => { diff --git a/docs/Troubleshooting.md b/docs/Troubleshooting.md index e2de98603998..2e6b5eb8ff5b 100644 --- a/docs/Troubleshooting.md +++ b/docs/Troubleshooting.md @@ -7,7 +7,8 @@ Uh oh, something went wrong? Use this guide to resolve issues with Jest. ### Tests are Failing and You Don't Know Why -Try using the debugging support built into Node. +Try using the debugging support built into Node. Note: This will only work in +Node.js 8+. Place a `debugger;` statement in any of your tests, and then, in your project's directory, run: diff --git a/docs/TutorialAsync.md b/docs/TutorialAsync.md index 19c254e89984..fc25c724db07 100644 --- a/docs/TutorialAsync.md +++ b/docs/TutorialAsync.md @@ -90,8 +90,6 @@ return a Promise at the end. ### `.resolves` -##### available in Jest **20.0.0+** - 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. @@ -159,8 +157,6 @@ it('tests error with async/await', async () => { ### `.rejects` -##### available in Jest **20.0.0+** - The`.rejects` helper works like the `.resolves` helper. If the promise is fulfilled, the test will automatically fail. diff --git a/docs/Webpack.md b/docs/Webpack.md index ade707c8964e..a78fde711c74 100644 --- a/docs/Webpack.md +++ b/docs/Webpack.md @@ -244,7 +244,7 @@ ES modules to CommonJS modules only in the `test` environment. ```json // .babelrc { - "presets": [["es2015", {"modules": false}]], + "presets": [["env", {"modules": false}]], "env": { "test": { @@ -263,7 +263,7 @@ need to enable the `dynamic-import-node` plugin. ```json // .babelrc { - "presets": [["es2015", {"modules": false}]], + "presets": [["env", {"modules": false}]], "plugins": ["syntax-dynamic-import"], diff --git a/examples/enzyme/__tests__/checkbox_with_label.test.js b/examples/enzyme/__tests__/checkbox_with_label.test.js index b0729c81711d..a8e08b42b10a 100644 --- a/examples/enzyme/__tests__/checkbox_with_label.test.js +++ b/examples/enzyme/__tests__/checkbox_with_label.test.js @@ -3,7 +3,11 @@ /* eslint-disable no-unused-vars */ import React from 'react'; -import {shallow} from 'enzyme'; +import Enzyme, {shallow} from 'enzyme'; +import Adapter from 'enzyme-adapter-react-16'; + +Enzyme.configure({adapter: new Adapter()}); + import CheckboxWithLabel from '../CheckboxWithLabel'; it('CheckboxWithLabel changes the text after click', () => { diff --git a/examples/react/__tests__/checkbox_with_label.test.js b/examples/react/__tests__/checkbox_with_label.test.js index 5371cdcf41b3..fab2050fd26b 100644 --- a/examples/react/__tests__/checkbox_with_label.test.js +++ b/examples/react/__tests__/checkbox_with_label.test.js @@ -4,7 +4,7 @@ import React from 'react'; import ReactDOM from 'react-dom'; -import TestUtils from 'react-addons-test-utils'; +import * as TestUtils from 'react-dom/test-utils'; import CheckboxWithLabel from '../CheckboxWithLabel'; it('CheckboxWithLabel changes the text after click', () => { diff --git a/examples/typescript/CheckboxWithLabel.tsx b/examples/typescript/CheckboxWithLabel.tsx index 494f6cb63bf1..1e8c59a611dc 100644 --- a/examples/typescript/CheckboxWithLabel.tsx +++ b/examples/typescript/CheckboxWithLabel.tsx @@ -2,31 +2,33 @@ import * as React from 'react' -interface CheckboxWithLabelProps extends React.Props { +interface CheckboxWithLabelProps { labelOff: string; labelOn: string; } -var CheckboxWithLabel = React.createClass( { - getInitialState: function() { - return {isChecked: false} - }, - onChange: function() { - this.setState({isChecked: !this.state.isChecked}); - }, +interface CheckboxWithLabelState { + isChecked: boolean; +} + +class CheckboxWithLabel extends React.Component { + constructor(props: CheckboxWithLabelProps) { + super(props); + this.state = {isChecked: false}; + } - render: function() { + render() { return ( ); } -}); +} export = CheckboxWithLabel; diff --git a/integration-tests/Utils.js b/integration-tests/Utils.js index bad044ad6faf..899145fafe6b 100644 --- a/integration-tests/Utils.js +++ b/integration-tests/Utils.js @@ -166,7 +166,6 @@ const cleanupStackTrace = (output: string) => { module.exports = { cleanup, - cleanupStackTrace, copyDir, createEmptyPackage, extractSummary, diff --git a/integration-tests/__tests__/__snapshots__/failures.test.js.snap b/integration-tests/__tests__/__snapshots__/failures.test.js.snap index b773dd6645e9..ccde240d4d88 100644 --- a/integration-tests/__tests__/__snapshots__/failures.test.js.snap +++ b/integration-tests/__tests__/__snapshots__/failures.test.js.snap @@ -116,7 +116,7 @@ exports[`works with async failures 1`] = ` + \\"foo\\": \\"bar\\", } - at packages/expect/build/index.js:104:76 + at packages/expect/build/index.js:160:61 " `; diff --git a/integration-tests/__tests__/__snapshots__/find_related_files.test.js.snap b/integration-tests/__tests__/__snapshots__/find_related_files.test.js.snap new file mode 100644 index 000000000000..cdddb39ad81b --- /dev/null +++ b/integration-tests/__tests__/__snapshots__/find_related_files.test.js.snap @@ -0,0 +1,54 @@ +// Jest Snapshot v1, https://goo.gl/fbAQLP + +exports[`--findRelatedTests flag generates coverage report for filename 1`] = ` +"Test Suites: 2 passed, 2 total +Tests: 2 passed, 2 total +Snapshots: 0 total +Time: <> +Ran all test suites. +" +`; + +exports[`--findRelatedTests flag generates coverage report for filename 2`] = ` +" + +PASS __tests__/a.test.js +PASS __tests__/b.test.js" +`; + +exports[`--findRelatedTests flag generates coverage report for filename 3`] = ` +"----------|----------|----------|----------|----------|-------------------| +File | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s | +----------|----------|----------|----------|----------|-------------------| +All files | 100 | 100 | 100 | 100 | | + a.js | 100 | 100 | 100 | 100 | | + b.js | 100 | 100 | 100 | 100 | | +----------|----------|----------|----------|----------|-------------------| +" +`; + +exports[`--findRelatedTests flag generates coverage report for filename 4`] = ` +"Test Suites: 1 passed, 1 total +Tests: 1 passed, 1 total +Snapshots: 0 total +Time: <> +Ran all test suites related to files matching /a.js/i. +" +`; + +exports[`--findRelatedTests flag generates coverage report for filename 5`] = ` +"PASS __tests__/a.test.js + ✓ a + +" +`; + +exports[`--findRelatedTests flag generates coverage report for filename 6`] = ` +"----------|----------|----------|----------|----------|-------------------| +File | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s | +----------|----------|----------|----------|----------|-------------------| +All files | 100 | 100 | 100 | 100 | | + a.js | 100 | 100 | 100 | 100 | | +----------|----------|----------|----------|----------|-------------------| +" +`; diff --git a/integration-tests/__tests__/__snapshots__/globals.test.js.snap b/integration-tests/__tests__/__snapshots__/globals.test.js.snap index 280ee77d5556..b3aac3749d67 100644 --- a/integration-tests/__tests__/__snapshots__/globals.test.js.snap +++ b/integration-tests/__tests__/__snapshots__/globals.test.js.snap @@ -32,7 +32,7 @@ exports[`cannot test with no implementation 1`] = ` 4 | test('test, no implementation'); 5 | - at packages/jest-jasmine2/build/jasmine/Env.js:390:15 + at packages/jest-jasmine2/build/jasmine/Env.js:405:15 at __tests__/only-constructs.test.js:3:5 " @@ -59,7 +59,7 @@ exports[`cannot test with no implementation with expand arg 1`] = ` 4 | test('test, no implementation'); 5 | - at packages/jest-jasmine2/build/jasmine/Env.js:390:15 + at packages/jest-jasmine2/build/jasmine/Env.js:405:15 at __tests__/only-constructs.test.js:3:5 " diff --git a/integration-tests/__tests__/__snapshots__/jest.config.js.test.js.snap b/integration-tests/__tests__/__snapshots__/jest.config.js.test.js.snap index 70ecdfd1763f..3c15495f9bc9 100644 --- a/integration-tests/__tests__/__snapshots__/jest.config.js.test.js.snap +++ b/integration-tests/__tests__/__snapshots__/jest.config.js.test.js.snap @@ -24,14 +24,14 @@ Ran all test suites. " `; -exports[`works with jest.conf.js 1`] = ` +exports[`works with jest.config.js 1`] = ` "PASS __tests__/a-banana.js ✓ banana " `; -exports[`works with jest.conf.js 2`] = ` +exports[`works with jest.config.js 2`] = ` "Test Suites: 1 passed, 1 total Tests: 1 passed, 1 total Snapshots: 0 total diff --git a/integration-tests/__tests__/__snapshots__/transform.test.js.snap b/integration-tests/__tests__/__snapshots__/transform.test.js.snap index 57f504e5b334..590fcf1b6b24 100644 --- a/integration-tests/__tests__/__snapshots__/transform.test.js.snap +++ b/integration-tests/__tests__/__snapshots__/transform.test.js.snap @@ -14,7 +14,7 @@ exports[`custom transformer instruments files 1`] = ` "----------|----------|----------|----------|----------|-------------------| File | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s | ----------|----------|----------|----------|----------|-------------------| -All files | Unknown | Unknown | Unknown | Unknown | | +All files | 0 | 0 | 0 | 0 | | ----------|----------|----------|----------|----------|-------------------| " `; diff --git a/integration-tests/__tests__/find_related_files.test.js b/integration-tests/__tests__/find_related_files.test.js index 18a25d08ef86..ffa924d257ff 100644 --- a/integration-tests/__tests__/find_related_files.test.js +++ b/integration-tests/__tests__/find_related_files.test.js @@ -13,7 +13,7 @@ import runJest from '../runJest'; import os from 'os'; import path from 'path'; -const {cleanup, writeFiles} = require('../Utils'); +const {cleanup, writeFiles, extractSummary} = require('../Utils'); const SkipOnWindows = require('../../scripts/SkipOnWindows'); const DIR = path.resolve(os.tmpdir(), 'find_related_tests_test'); @@ -23,23 +23,74 @@ SkipOnWindows.suite(); beforeEach(() => cleanup(DIR)); afterEach(() => cleanup(DIR)); -test('runs tests related to filename', () => { - writeFiles(DIR, { - '.watchmanconfig': '', - '__tests__/test.test.js': ` +describe('--findRelatedTests flag', () => { + test('runs tests related to filename', () => { + writeFiles(DIR, { + '.watchmanconfig': '', + '__tests__/test.test.js': ` const a = require('../a'); test('a', () => {}); `, - 'a.js': 'module.exports = {};', - 'package.json': JSON.stringify({jest: {testEnvironment: 'node'}}), + 'a.js': 'module.exports = {};', + 'package.json': JSON.stringify({jest: {testEnvironment: 'node'}}), + }); + + const {stdout} = runJest(DIR, ['a.js']); + expect(stdout).toMatch(''); + + const {stderr} = runJest(DIR, ['--findRelatedTests', 'a.js']); + expect(stderr).toMatch('PASS __tests__/test.test.js'); + + const summaryMsg = 'Ran all test suites related to files matching /a.js/i.'; + expect(stderr).toMatch(summaryMsg); }); - const {stdout} = runJest(DIR, ['a.js']); - expect(stdout).toMatch(''); + test('generates coverage report for filename', () => { + writeFiles(DIR, { + '.watchmanconfig': '', + '__tests__/a.test.js': ` + require('../a'); + require('../b'); + test('a', () => expect(1).toBe(1)); + `, + '__tests__/b.test.js': ` + require('../b'); + test('b', () => expect(1).toBe(1)); + `, + 'a.js': 'module.exports = {}', + 'b.js': 'module.exports = {}', + 'package.json': JSON.stringify({ + jest: {collectCoverage: true, testEnvironment: 'node'}, + }), + }); + + let stdout; + let stderr; - const {stderr} = runJest(DIR, ['--findRelatedTests', 'a.js']); - expect(stderr).toMatch('PASS __tests__/test.test.js'); + ({stdout, stderr} = runJest(DIR)); + let summary; + let rest; + ({summary, rest} = extractSummary(stderr)); + expect(summary).toMatchSnapshot(); + expect( + rest + .split('\n') + .map(s => s.trim()) + .sort() + .join('\n'), + ).toMatchSnapshot(); - const summaryMsg = 'Ran all test suites related to files matching /a.js/i.'; - expect(stderr).toMatch(summaryMsg); + // both a.js and b.js should be in the coverage + expect(stdout).toMatchSnapshot(); + + ({stdout, stderr} = runJest(DIR, ['--findRelatedTests', 'a.js'])); + + ({summary, rest} = extractSummary(stderr)); + + expect(summary).toMatchSnapshot(); + // should only run a.js + expect(rest).toMatchSnapshot(); + // coverage should be collected only for a.js + expect(stdout).toMatchSnapshot(); + }); }); diff --git a/integration-tests/__tests__/global_setup.test.js b/integration-tests/__tests__/global_setup.test.js index 1f957229e8e7..5c14ad22164d 100644 --- a/integration-tests/__tests__/global_setup.test.js +++ b/integration-tests/__tests__/global_setup.test.js @@ -27,3 +27,15 @@ test('globalSetup is triggered once before all test suites', () => { const setup = fs.readFileSync(path.join(DIR, files[0]), 'utf8'); expect(setup).toBe('setup'); }); + +test('jest throws an error when globalSetup does not export a function', () => { + const setupPath = path.resolve(__dirname, '../global-setup/invalid_setup.js'); + const {status, stderr} = runJest('global-setup', [ + `--globalSetup=${setupPath}`, + ]); + + expect(status).toBe(1); + expect(stderr).toMatch( + `TypeError: globalSetup file must export a function at ${setupPath}`, + ); +}); diff --git a/integration-tests/__tests__/global_teardown.test.js b/integration-tests/__tests__/global_teardown.test.js index 3c9efae86086..92e2e28486a3 100644 --- a/integration-tests/__tests__/global_teardown.test.js +++ b/integration-tests/__tests__/global_teardown.test.js @@ -34,3 +34,18 @@ test('globalTeardown is triggered once after all test suites', () => { const teardown = fs.readFileSync(path.join(DIR, files[0]), 'utf8'); expect(teardown).toBe('teardown'); }); + +test('jest throws an error when globalTeardown does not export a function', () => { + const teardownPath = path.resolve( + __dirname, + '../global-teardown/invalid_teardown.js', + ); + const {status, stderr} = runJest('global-teardown', [ + `--globalTeardown=${teardownPath}`, + ]); + + expect(status).toBe(1); + expect(stderr).toMatch( + `TypeError: globalTeardown file must export a function at ${teardownPath}`, + ); +}); diff --git a/integration-tests/__tests__/jest.config.js.test.js b/integration-tests/__tests__/jest.config.js.test.js index 78cf65e97557..d4da0512252c 100644 --- a/integration-tests/__tests__/jest.config.js.test.js +++ b/integration-tests/__tests__/jest.config.js.test.js @@ -21,7 +21,7 @@ SkipOnWindows.suite(); beforeEach(() => cleanup(DIR)); afterAll(() => cleanup(DIR)); -test('works with jest.conf.js', () => { +test('works with jest.config.js', () => { writeFiles(DIR, { '__tests__/a-banana.js': `test('banana', () => expect(1).toBe(1));`, 'jest.config.js': `module.exports = {testRegex: '.*-banana.js'};`, diff --git a/integration-tests/__tests__/only_changed.test.js b/integration-tests/__tests__/only_changed.test.js index 16ff3e633b7a..ed51ea3bd13a 100644 --- a/integration-tests/__tests__/only_changed.test.js +++ b/integration-tests/__tests__/only_changed.test.js @@ -73,6 +73,51 @@ test('run only changed files', () => { expect(stderr).toMatch(/PASS __tests__(\/|\\)file3.test.js/); }); +test('report test coverage for only changed files', () => { + writeFiles(DIR, { + '__tests__/a.test.js': ` + require('../a'); + require('../b'); + test('a', () => expect(1).toBe(1)); + `, + '__tests__/b.test.js': ` + require('../b'); + test('b', () => expect(1).toBe(1)); + `, + 'a.js': 'module.exports = {}', + 'b.js': 'module.exports = {}', + 'package.json': JSON.stringify({ + jest: { + collectCoverage: true, + coverageReporters: ['text'], + testEnvironment: 'node', + }, + }), + }); + + run(`${GIT} init`, DIR); + run(`${GIT} add .`, DIR); + run(`${GIT} commit -m "first"`, DIR); + + writeFiles(DIR, { + 'a.js': 'module.exports = {modified: true}', + }); + + let stdout; + + ({stdout} = runJest(DIR)); + + // both a.js and b.js should be in the coverage + expect(stdout).toMatch('a.js'); + expect(stdout).toMatch('b.js'); + + ({stdout} = runJest(DIR, ['-o'])); + + // coverage should be collected only for a.js + expect(stdout).toMatch('a.js'); + expect(stdout).not.toMatch('b.js'); +}); + test('onlyChanged in config is overwritten by --all or testPathPattern', () => { writeFiles(DIR, { '.watchmanconfig': '', diff --git a/integration-tests/__tests__/version.test.js b/integration-tests/__tests__/version.test.js index 1a34fbddfbd9..1836a153cc3a 100644 --- a/integration-tests/__tests__/version.test.js +++ b/integration-tests/__tests__/version.test.js @@ -22,7 +22,7 @@ SkipOnWindows.suite(); beforeEach(() => cleanup(DIR)); afterAll(() => cleanup(DIR)); -test('works with jest.conf.js', () => { +test('works with jest.config.js', () => { writeFiles(DIR, { '.watchmanconfig': '', 'package.json': '{}', diff --git a/integration-tests/global-setup/invalid_setup.js b/integration-tests/global-setup/invalid_setup.js new file mode 100644 index 000000000000..de4e062fb3c2 --- /dev/null +++ b/integration-tests/global-setup/invalid_setup.js @@ -0,0 +1 @@ +console.log('there is no exported function'); diff --git a/integration-tests/global-teardown/invalid_teardown.js b/integration-tests/global-teardown/invalid_teardown.js new file mode 100644 index 000000000000..de4e062fb3c2 --- /dev/null +++ b/integration-tests/global-teardown/invalid_teardown.js @@ -0,0 +1 @@ +console.log('there is no exported function'); diff --git a/package.json b/package.json index a56d1f3169e8..c39b78eba4b8 100644 --- a/package.json +++ b/package.json @@ -25,7 +25,8 @@ "codecov": "^3.0.0", "cross-spawn": "^6.0.4", "debug": "^3.0.1", - "enzyme": "^2.8.2", + "enzyme": "^3.3.0", + "enzyme-adapter-react-16": "^1.1.1", "eslint": "~4.13.0", "eslint-config-prettier": "^2.9.0", "eslint-plugin-babel": "^4.1.1", @@ -41,9 +42,10 @@ "glob": "^7.1.1", "graceful-fs": "^4.1.11", "immutable": "^4.0.0-rc.7", - "istanbul-api": "^1.1.0", + "istanbul-api": "^1.3.1", "istanbul-lib-coverage": "^1.0.0", "jasmine-reporters": "^2.2.0", + "jest-silent-reporter": "^0.0.4", "jquery": "^3.2.1", "karma": "^2.0.0", "karma-browserify": "^5.1.1", @@ -58,10 +60,9 @@ "prettier": "^1.11.0", "prettylint": "^1.0.0", "progress": "^2.0.0", - "react": "^15.4.2", - "react-addons-test-utils": "^15.4.2", - "react-dom": "^15.6.1", - "react-test-renderer": "^15.4.2", + "react": "^16.2.0", + "react-dom": "^16.2.0", + "react-test-renderer": "^16.2.0", "regenerator-runtime": "^0.11.0", "resolve": "^1.4.0", "rimraf": "^2.6.2", @@ -88,12 +89,12 @@ "lint": "eslint . --cache --ext js,md", "lint-es5-build": "eslint --no-eslintrc --no-ignore --env=browser packages/*/build-es5", "lint:md": "yarn --silent lint:md:ci --fix", - "lint:md:ci": "prettylint '**/*.md'", + "lint:md:ci": "prettylint '**/*.md' --ignore-path .gitignore", "postinstall": "yarn build", "publish": "yarn build-clean && yarn build && lerna publish --silent", "test-ci-es5-build-in-browser": "karma start --single-run", - "test-ci": "yarn typecheck && yarn lint && yarn lint-es5-build && yarn lint:md:ci && yarn jest-coverage -i && node scripts/mapCoverage.js && codecov", - "test-ci-partial": "yarn jest -i", + "test-ci": "yarn typecheck && yarn lint && yarn lint-es5-build && yarn lint:md:ci && yarn jest-coverage -i --reporters jest-silent-reporter && node scripts/mapCoverage.js && codecov", + "test-ci-partial": "yarn jest -i --reporters jest-silent-reporter", "test-pretty-format-perf": "node packages/pretty-format/perf/test.js", "test": "yarn typecheck && yarn lint && yarn jest", "typecheck": "flow check --include-warnings", diff --git a/packages/babel-jest/package.json b/packages/babel-jest/package.json index 20611e94fde6..43fb40558063 100644 --- a/packages/babel-jest/package.json +++ b/packages/babel-jest/package.json @@ -9,7 +9,7 @@ "license": "MIT", "main": "build/index.js", "dependencies": { - "babel-plugin-istanbul": "^4.1.5", + "babel-plugin-istanbul": "^4.1.6", "babel-preset-jest": "^22.4.1" }, "devDependencies": { diff --git a/packages/expect/README.md b/packages/expect/README.md new file mode 100644 index 000000000000..4db3e412c428 --- /dev/null +++ b/packages/expect/README.md @@ -0,0 +1,5 @@ +# expect + +This package exports the `expect` function used in +[Jest](https://facebook.github.io/jest/). You can find its documentation +[on Jest's website](https://facebook.github.io/jest/docs/en/expect.html). diff --git a/packages/expect/src/__tests__/__snapshots__/matchers.test.js.snap b/packages/expect/src/__tests__/__snapshots__/matchers.test.js.snap index 1a759e202655..cc7fc3b606e9 100644 --- a/packages/expect/src/__tests__/__snapshots__/matchers.test.js.snap +++ b/packages/expect/src/__tests__/__snapshots__/matchers.test.js.snap @@ -290,7 +290,7 @@ Received: [] Difference: -Compared values have no visual difference. Looks like you wanted to test for object/array equality with strict \`toBe\` matcher. You probably need to use \`toEqual\` instead." +Compared values have no visual difference. Looks like you wanted to test for object/array equality with the stricter \`toBe\` matcher. You probably need to use \`toEqual\` instead." `; exports[`.toBe() fails for: {"a": 1} and {"a": 1} 1`] = ` @@ -301,7 +301,7 @@ Received: {\\"a\\": 1} Difference: -Compared values have no visual difference. Looks like you wanted to test for object/array equality with strict \`toBe\` matcher. You probably need to use \`toEqual\` instead." +Compared values have no visual difference. Looks like you wanted to test for object/array equality with the stricter \`toBe\` matcher. You probably need to use \`toEqual\` instead." `; exports[`.toBe() fails for: {"a": 1} and {"a": 5} 1`] = ` @@ -329,7 +329,7 @@ Received: {} Difference: -Compared values have no visual difference. Looks like you wanted to test for object/array equality with strict \`toBe\` matcher. You probably need to use \`toEqual\` instead." +Compared values have no visual difference. Looks like you wanted to test for object/array equality with the stricter \`toBe\` matcher. You probably need to use \`toEqual\` instead." `; exports[`.toBe() fails for: -0 and 0 1`] = ` diff --git a/packages/expect/src/__tests__/__snapshots__/spy_matchers.test.js.snap b/packages/expect/src/__tests__/__snapshots__/spy_matchers.test.js.snap index 650e63d8826f..fd64c30e1931 100644 --- a/packages/expect/src/__tests__/__snapshots__/spy_matchers.test.js.snap +++ b/packages/expect/src/__tests__/__snapshots__/spy_matchers.test.js.snap @@ -34,7 +34,21 @@ exports[`lastCalledWith works with Map 2`] = ` "expect(jest.fn()).lastCalledWith(expected) Expected mock function to have been last called with: - Map {\\"a\\" => \\"b\\", \\"b\\" => \\"a\\"} as argument 1, but it was called with Map {1 => 2, 2 => 1}." + Map {\\"a\\" => \\"b\\", \\"b\\" => \\"a\\"} +as argument 1, but it was called with + Map {1 => 2, 2 => 1}. + +Difference: + +- Expected ++ Received + + Map { +- \\"a\\" => \\"b\\", +- \\"b\\" => \\"a\\", ++ 1 => 2, ++ 2 => 1, + }" `; exports[`lastCalledWith works with Set 1`] = ` @@ -48,14 +62,30 @@ exports[`lastCalledWith works with Set 2`] = ` "expect(jest.fn()).lastCalledWith(expected) Expected mock function to have been last called with: - Set {3, 4} as argument 1, but it was called with Set {1, 2}." + Set {3, 4} +as argument 1, but it was called with + Set {1, 2}. + +Difference: + +- Expected ++ Received + + Set { +- 3, +- 4, ++ 1, ++ 2, + }" `; exports[`lastCalledWith works with arguments that don't match 1`] = ` "expect(jest.fn()).lastCalledWith(expected) Expected mock function to have been last called with: - \\"bar\\" as argument 2, but it was called with \\"bar1\\"." + \\"bar\\" +as argument 2, but it was called with + \\"bar1\\"." `; exports[`lastCalledWith works with arguments that match 1`] = ` @@ -72,293 +102,472 @@ Expected mock function to not have been last called with: [\\"foo\\", \\"bar\\"]" `; -exports[`lastCalledWith works with many arguments 2`] = ` -"expect(jest.fn()).not.lastCalledWith(expected) - -Expected mock function to not have been last called with: - [\\"foo\\", \\"bar\\"]" -`; - -exports[`lastCalledWith works with many arguments 3`] = ` -"expect(jest.fn()).not.lastCalledWith(expected) - -Expected mock function to not have been last called with: - [\\"foo\\", \\"bar\\"]" -`; - -exports[`lastCalledWith works with many arguments 4`] = ` -"expect(jest.fn()).not.lastCalledWith(expected) - -Expected mock function to not have been last called with: - [\\"foo\\", \\"bar\\"]" -`; - exports[`lastCalledWith works with many arguments that don't match 1`] = ` "expect(jest.fn()).lastCalledWith(expected) Expected mock function to have been last called with: - \\"bar\\" as argument 2, but it was called with \\"bar3\\"." + \\"bar\\" +as argument 2, but it was called with + \\"bar3\\"." `; -exports[`lastCalledWith works with many arguments that don't match 2`] = ` -"expect(jest.fn()).lastCalledWith(expected) - -Expected mock function to have been last called with: - \\"bar\\" as argument 2, but it was called with \\"bar3\\"." -`; - -exports[`lastCalledWith works with many arguments that don't match 3`] = ` +exports[`lastCalledWith works with trailing undefined arguments 1`] = ` "expect(jest.fn()).lastCalledWith(expected) Expected mock function to have been last called with: - \\"bar\\" as argument 2, but it was called with \\"bar3\\"." + Did not expect argument 2 but it was called with undefined." `; -exports[`lastCalledWith works with many arguments that don't match 4`] = ` -"expect(jest.fn()).lastCalledWith(expected) +exports[`nthCalledWith should reject non integer nth value 1`] = `"nth value 0.1 must be a positive integer greater than 0"`; -Expected mock function to have been last called with: - \\"bar\\" as argument 2, but it was called with \\"bar3\\"." -`; +exports[`nthCalledWith should reject nth value smaller than 1 1`] = `"nth value 0 must be a positive integer greater than 0"`; -exports[`lastCalledWith works with trailing undefined arguments 1`] = ` -"expect(jest.fn()).lastCalledWith(expected) +exports[`nthCalledWith should replace 1st, 2nd, 3rd with first, second, third 1`] = ` +"expect(jest.fn()).nthCalledWith(expected) -Expected mock function to have been last called with: - Did not expect argument 2 but it was called with undefined." +Expected mock function first call to have been called with: +" `; -exports[`nthCalledWith nthCalledWith 1`] = ` +exports[`nthCalledWith should replace 1st, 2nd, 3rd with first, second, third 2`] = ` "expect(jest.fn()).not.nthCalledWith(expected) Expected mock function first call to not have been called with: [\\"foo1\\", \\"bar\\"]" `; -exports[`nthCalledWith nthCalledWith 2`] = ` -"expect(jest.fn()).not.nthCalledWith(expected) +exports[`nthCalledWith works only on spies or jest.fn 1`] = ` +"expect(jest.fn())[.not].nthCalledWith() -Expected mock function first call to not have been called with: - [\\"foo1\\", \\"bar\\"]" +jest.fn() value must be a mock function or spy. +Received: + function: [Function fn]" `; -exports[`nthCalledWith nthCalledWith 3`] = ` +exports[`nthCalledWith works when not called 1`] = ` +"expect(jest.fn()).nthCalledWith(expected) + +Expected mock function first call to have been called with: + [\\"foo\\", \\"bar\\"] +But it was not called." +`; + +exports[`nthCalledWith works with Immutable.js objects 1`] = ` "expect(jest.fn()).not.nthCalledWith(expected) Expected mock function first call to not have been called with: - [\\"foo1\\", \\"bar\\"]" + [Immutable.Map {\\"a\\": {\\"b\\": \\"c\\"}}, Immutable.Map {\\"a\\": {\\"b\\": \\"c\\"}}]" `; -exports[`nthCalledWith nthCalledWith 4`] = ` +exports[`nthCalledWith works with Map 1`] = ` "expect(jest.fn()).not.nthCalledWith(expected) Expected mock function first call to not have been called with: - [\\"foo1\\", \\"bar\\"]" + [Map {1 => 2, 2 => 1}]" `; -exports[`nthCalledWith should reject non integer nth value 1`] = `"nth value 0.1 must be a positive integer greater than 0"`; - -exports[`nthCalledWith should reject non integer nth value 2`] = `"nth value 0.1 must be a positive integer greater than 0"`; +exports[`nthCalledWith works with Map 2`] = ` +"expect(jest.fn()).nthCalledWith(expected) -exports[`nthCalledWith should reject non integer nth value 3`] = `"nth value 0.1 must be a positive integer greater than 0"`; +Expected mock function first call to have been called with: + Map {\\"a\\" => \\"b\\", \\"b\\" => \\"a\\"} +as argument 1, but it was called with + Map {1 => 2, 2 => 1}. -exports[`nthCalledWith should reject non integer nth value 4`] = `"nth value 0.1 must be a positive integer greater than 0"`; +Difference: -exports[`nthCalledWith should reject nth value smaller than 1 1`] = `"nth value 0 must be a positive integer greater than 0"`; +- Expected ++ Received -exports[`nthCalledWith should reject nth value smaller than 1 2`] = `"nth value 0 must be a positive integer greater than 0"`; + Map { +- \\"a\\" => \\"b\\", +- \\"b\\" => \\"a\\", ++ 1 => 2, ++ 2 => 1, + }" +`; -exports[`nthCalledWith should reject nth value smaller than 1 3`] = `"nth value 0 must be a positive integer greater than 0"`; +exports[`nthCalledWith works with Set 1`] = ` +"expect(jest.fn()).not.nthCalledWith(expected) -exports[`nthCalledWith should reject nth value smaller than 1 4`] = `"nth value 0 must be a positive integer greater than 0"`; +Expected mock function first call to not have been called with: + [Set {1, 2}]" +`; -exports[`nthCalledWith should replace 1st, 2nd, 3rd with first, second, third 1`] = ` +exports[`nthCalledWith works with Set 2`] = ` "expect(jest.fn()).nthCalledWith(expected) Expected mock function first call to have been called with: -" -`; + Set {3, 4} +as argument 1, but it was called with + Set {1, 2}. -exports[`nthCalledWith should replace 1st, 2nd, 3rd with first, second, third 2`] = ` -"expect(jest.fn()).not.nthCalledWith(expected) +Difference: -Expected mock function first call to not have been called with: - [\\"foo1\\", \\"bar\\"]" +- Expected ++ Received + + Set { +- 3, +- 4, ++ 1, ++ 2, + }" `; -exports[`nthCalledWith should replace 1st, 2nd, 3rd with first, second, third 3`] = ` +exports[`nthCalledWith works with arguments that don't match 1`] = ` "expect(jest.fn()).nthCalledWith(expected) Expected mock function first call to have been called with: -" + \\"bar\\" +as argument 2, but it was called with + \\"bar1\\"." `; -exports[`nthCalledWith should replace 1st, 2nd, 3rd with first, second, third 4`] = ` +exports[`nthCalledWith works with arguments that match 1`] = ` +"expect(jest.fn()).not.nthCalledWith(expected) + +Expected mock function first call to not have been called with: + [\\"foo\\", \\"bar\\"]" +`; + +exports[`nthCalledWith works with three calls 1`] = ` "expect(jest.fn()).not.nthCalledWith(expected) Expected mock function first call to not have been called with: [\\"foo1\\", \\"bar\\"]" `; -exports[`nthCalledWith should replace 1st, 2nd, 3rd with first, second, third 5`] = ` +exports[`nthCalledWith works with trailing undefined arguments 1`] = ` "expect(jest.fn()).nthCalledWith(expected) Expected mock function first call to have been called with: -" + Did not expect argument 2 but it was called with undefined." `; -exports[`nthCalledWith should replace 1st, 2nd, 3rd with first, second, third 6`] = ` -"expect(jest.fn()).not.nthCalledWith(expected) +exports[`toBeCalled .not fails with any argument passed 1`] = ` +"expect(received)[.not].toBeCalled() -Expected mock function first call to not have been called with: - [\\"foo1\\", \\"bar\\"]" +Matcher does not accept any arguments. +Got: + number: 555" `; -exports[`nthCalledWith should replace 1st, 2nd, 3rd with first, second, third 7`] = ` -"expect(jest.fn()).nthCalledWith(expected) +exports[`toBeCalled .not passes when called 1`] = ` +"expect(jest.fn()).toBeCalled() -Expected mock function first call to have been called with: -" +Expected mock function to have been called." `; -exports[`nthCalledWith should replace 1st, 2nd, 3rd with first, second, third 8`] = ` -"expect(jest.fn()).not.nthCalledWith(expected) +exports[`toBeCalled fails with any argument passed 1`] = ` +"expect(received)[.not].toBeCalled() -Expected mock function first call to not have been called with: - [\\"foo1\\", \\"bar\\"]" +Matcher does not accept any arguments. +Got: + number: 555" `; -exports[`nthCalledWith works when not called 1`] = ` -"expect(jest.fn()).nthCalledWith(expected) +exports[`toBeCalled passes when called 1`] = ` +"expect(jest.fn()).not.toBeCalled() -Expected mock function first call to have been called with: - [\\"foo\\", \\"bar\\"] -But it was not called." +Expected mock function not to be called but it was called with: + []" `; -exports[`nthCalledWith works with Immutable.js objects 1`] = ` -"expect(jest.fn()).not.nthCalledWith(expected) +exports[`toBeCalled works only on spies or jest.fn 1`] = ` +"expect(jest.fn())[.not].toBeCalled() -Expected mock function first call to not have been called with: - [Immutable.Map {\\"a\\": {\\"b\\": \\"c\\"}}, Immutable.Map {\\"a\\": {\\"b\\": \\"c\\"}}]" +jest.fn() value must be a mock function or spy. +Received: + function: [Function fn]" `; -exports[`nthCalledWith works with Map 1`] = ` -"expect(jest.fn()).not.nthCalledWith(expected) +exports[`toBeCalledTimes .not only accepts a number argument 1`] = ` +"expect(received)[.not].toBeCalledTimes(expected) -Expected mock function first call to not have been called with: - [Map {1 => 2, 2 => 1}]" +Expected value must be a number. +Got: + object: {}" `; -exports[`nthCalledWith works with Map 2`] = ` -"expect(jest.fn()).nthCalledWith(expected) +exports[`toBeCalledTimes .not only accepts a number argument 2`] = ` +"expect(received)[.not].toBeCalledTimes(expected) -Expected mock function first call to have been called with: - Map {\\"a\\" => \\"b\\", \\"b\\" => \\"a\\"} as argument 1, but it was called with Map {1 => 2, 2 => 1}." +Expected value must be a number. +Got: + array: []" `; -exports[`nthCalledWith works with Set 1`] = ` -"expect(jest.fn()).not.nthCalledWith(expected) +exports[`toBeCalledTimes .not only accepts a number argument 3`] = ` +"expect(received)[.not].toBeCalledTimes(expected) -Expected mock function first call to not have been called with: - [Set {1, 2}]" +Expected value must be a number. +Got: + boolean: true" `; -exports[`nthCalledWith works with Set 2`] = ` -"expect(jest.fn()).nthCalledWith(expected) +exports[`toBeCalledTimes .not only accepts a number argument 4`] = ` +"expect(received)[.not].toBeCalledTimes(expected) -Expected mock function first call to have been called with: - Set {3, 4} as argument 1, but it was called with Set {1, 2}." +Expected value must be a number. +Got: + string: \\"a\\"" `; -exports[`nthCalledWith works with arguments that don't match 1`] = ` -"expect(jest.fn()).nthCalledWith(expected) +exports[`toBeCalledTimes .not only accepts a number argument 5`] = ` +"expect(received)[.not].toBeCalledTimes(expected) -Expected mock function first call to have been called with: - \\"bar\\" as argument 2, but it was called with \\"bar1\\"." +Expected value must be a number. +Got: + map: Map {}" `; -exports[`nthCalledWith works with arguments that match 1`] = ` -"expect(jest.fn()).not.nthCalledWith(expected) +exports[`toBeCalledTimes .not only accepts a number argument 6`] = ` +"expect(received)[.not].toBeCalledTimes(expected) -Expected mock function first call to not have been called with: - [\\"foo\\", \\"bar\\"]" +Expected value must be a number. +Got: + function: [Function anonymous]" `; -exports[`nthCalledWith works with trailing undefined arguments 1`] = ` -"expect(jest.fn()).nthCalledWith(expected) +exports[`toBeCalledTimes .not passes if function called less than expected times 1`] = ` +"expect(jest.fn()).toBeCalledTimes(2) -Expected mock function first call to have been called with: - Did not expect argument 2 but it was called with undefined." +Expected mock function to have been called two times, but it was called one time." `; -exports[`toBeCalled works only on spies or jest.fn 1`] = ` -"expect(jest.fn())[.not].toBeCalled() +exports[`toBeCalledTimes .not passes if function called more than expected times 1`] = ` +"expect(jest.fn()).toBeCalledTimes(2) -jest.fn() value must be a mock function or spy. -Received: - function: [Function fn]" +Expected mock function to have been called two times, but it was called three times." `; -exports[`toBeCalled works with jest.fn 1`] = ` -"expect(jest.fn()).toBeCalled() +exports[`toBeCalledTimes only accepts a number argument 1`] = ` +"expect(received)[.not].toBeCalledTimes(expected) -Expected mock function to have been called." +Expected value must be a number. +Got: + object: {}" `; -exports[`toBeCalled works with jest.fn 2`] = ` -"expect(jest.fn()).not.toBeCalled() +exports[`toBeCalledTimes only accepts a number argument 2`] = ` +"expect(received)[.not].toBeCalledTimes(expected) -Expected mock function not to be called but it was called with: - []" +Expected value must be a number. +Got: + array: []" `; -exports[`toBeCalled works with jest.fn 3`] = ` -"expect(received)[.not].toBeCalled() +exports[`toBeCalledTimes only accepts a number argument 3`] = ` +"expect(received)[.not].toBeCalledTimes(expected) -Matcher does not accept any arguments. +Expected value must be a number. Got: - number: 555" + boolean: true" `; -exports[`toBeCalledWith works only on spies or jest.fn 1`] = ` -"expect(jest.fn())[.not].toBeCalledWith() +exports[`toBeCalledTimes only accepts a number argument 4`] = ` +"expect(received)[.not].toBeCalledTimes(expected) + +Expected value must be a number. +Got: + string: \\"a\\"" +`; + +exports[`toBeCalledTimes only accepts a number argument 5`] = ` +"expect(received)[.not].toBeCalledTimes(expected) + +Expected value must be a number. +Got: + map: Map {}" +`; + +exports[`toBeCalledTimes only accepts a number argument 6`] = ` +"expect(received)[.not].toBeCalledTimes(expected) + +Expected value must be a number. +Got: + function: [Function anonymous]" +`; + +exports[`toBeCalledTimes passes if function called equal to expected times 1`] = ` +"expect(jest.fn()).not.toBeCalledTimes(2) + +Expected mock function not to be called two times, but it was called exactly two times." +`; + +exports[`toBeCalledTimes works only on spies or jest.fn 1`] = ` +"expect(jest.fn())[.not].toBeCalledTimes() jest.fn() value must be a mock function or spy. Received: function: [Function fn]" `; -exports[`toHaveBeenCalled works only on spies or jest.fn 1`] = ` -"expect(jest.fn())[.not].toHaveBeenCalled() +exports[`toBeCalledWith works only on spies or jest.fn 1`] = ` +"expect(jest.fn())[.not].toBeCalledWith() jest.fn() value must be a mock function or spy. Received: function: [Function fn]" `; -exports[`toHaveBeenCalled works with jest.fn 1`] = ` +exports[`toBeCalledWith works when not called 1`] = ` +"expect(jest.fn()).toBeCalledWith(expected) + +Expected mock function to have been called with: + [\\"foo\\", \\"bar\\"] +But it was not called." +`; + +exports[`toBeCalledWith works with Immutable.js objects 1`] = ` +"expect(jest.fn()).not.toBeCalledWith(expected) + +Expected mock function not to have been called with: + [Immutable.Map {\\"a\\": {\\"b\\": \\"c\\"}}, Immutable.Map {\\"a\\": {\\"b\\": \\"c\\"}}]" +`; + +exports[`toBeCalledWith works with Map 1`] = ` +"expect(jest.fn()).not.toBeCalledWith(expected) + +Expected mock function not to have been called with: + [Map {1 => 2, 2 => 1}]" +`; + +exports[`toBeCalledWith works with Map 2`] = ` +"expect(jest.fn()).toBeCalledWith(expected) + +Expected mock function to have been called with: + Map {\\"a\\" => \\"b\\", \\"b\\" => \\"a\\"} +as argument 1, but it was called with + Map {1 => 2, 2 => 1}. + +Difference: + +- Expected ++ Received + + Map { +- \\"a\\" => \\"b\\", +- \\"b\\" => \\"a\\", ++ 1 => 2, ++ 2 => 1, + }" +`; + +exports[`toBeCalledWith works with Set 1`] = ` +"expect(jest.fn()).not.toBeCalledWith(expected) + +Expected mock function not to have been called with: + [Set {1, 2}]" +`; + +exports[`toBeCalledWith works with Set 2`] = ` +"expect(jest.fn()).toBeCalledWith(expected) + +Expected mock function to have been called with: + Set {3, 4} +as argument 1, but it was called with + Set {1, 2}. + +Difference: + +- Expected ++ Received + + Set { +- 3, +- 4, ++ 1, ++ 2, + }" +`; + +exports[`toBeCalledWith works with arguments that don't match 1`] = ` +"expect(jest.fn()).toBeCalledWith(expected) + +Expected mock function to have been called with: + \\"bar\\" +as argument 2, but it was called with + \\"bar1\\"." +`; + +exports[`toBeCalledWith works with arguments that match 1`] = ` +"expect(jest.fn()).not.toBeCalledWith(expected) + +Expected mock function not to have been called with: + [\\"foo\\", \\"bar\\"]" +`; + +exports[`toBeCalledWith works with many arguments 1`] = ` +"expect(jest.fn()).not.toBeCalledWith(expected) + +Expected mock function not to have been called with: + [\\"foo\\", \\"bar\\"]" +`; + +exports[`toBeCalledWith works with many arguments that don't match 1`] = ` +"expect(jest.fn()).toBeCalledWith(expected) + +Expected mock function to have been called with: + \\"bar\\" +as argument 2, but it was called with + \\"bar3\\". + + \\"bar\\" +as argument 2, but it was called with + \\"bar2\\". + + \\"bar\\" +as argument 2, but it was called with + \\"bar1\\"." +`; + +exports[`toBeCalledWith works with trailing undefined arguments 1`] = ` +"expect(jest.fn()).toBeCalledWith(expected) + +Expected mock function to have been called with: + Did not expect argument 2 but it was called with undefined." +`; + +exports[`toHaveBeenCalled .not fails with any argument passed 1`] = ` +"expect(received)[.not].toHaveBeenCalled() + +Matcher does not accept any arguments. +Got: + number: 555" +`; + +exports[`toHaveBeenCalled .not passes when called 1`] = ` "expect(jest.fn()).toHaveBeenCalled() Expected mock function to have been called." `; -exports[`toHaveBeenCalled works with jest.fn 2`] = ` +exports[`toHaveBeenCalled fails with any argument passed 1`] = ` +"expect(received)[.not].toHaveBeenCalled() + +Matcher does not accept any arguments. +Got: + number: 555" +`; + +exports[`toHaveBeenCalled passes when called 1`] = ` "expect(jest.fn()).not.toHaveBeenCalled() Expected mock function not to be called but it was called with: []" `; -exports[`toHaveBeenCalled works with jest.fn 3`] = ` -"expect(received)[.not].toHaveBeenCalled() +exports[`toHaveBeenCalled works only on spies or jest.fn 1`] = ` +"expect(jest.fn())[.not].toHaveBeenCalled() -Matcher does not accept any arguments. -Got: - number: 555" +jest.fn() value must be a mock function or spy. +Received: + function: [Function fn]" `; -exports[`toHaveBeenCalledTimes accepts only numbers 1`] = ` +exports[`toHaveBeenCalledTimes .not only accepts a number argument 1`] = ` "expect(received)[.not].toHaveBeenCalledTimes(expected) Expected value must be a number. @@ -366,7 +575,7 @@ Got: object: {}" `; -exports[`toHaveBeenCalledTimes accepts only numbers 2`] = ` +exports[`toHaveBeenCalledTimes .not only accepts a number argument 2`] = ` "expect(received)[.not].toHaveBeenCalledTimes(expected) Expected value must be a number. @@ -374,7 +583,7 @@ Got: array: []" `; -exports[`toHaveBeenCalledTimes accepts only numbers 3`] = ` +exports[`toHaveBeenCalledTimes .not only accepts a number argument 3`] = ` "expect(received)[.not].toHaveBeenCalledTimes(expected) Expected value must be a number. @@ -382,7 +591,7 @@ Got: boolean: true" `; -exports[`toHaveBeenCalledTimes accepts only numbers 4`] = ` +exports[`toHaveBeenCalledTimes .not only accepts a number argument 4`] = ` "expect(received)[.not].toHaveBeenCalledTimes(expected) Expected value must be a number. @@ -390,7 +599,7 @@ Got: string: \\"a\\"" `; -exports[`toHaveBeenCalledTimes accepts only numbers 5`] = ` +exports[`toHaveBeenCalledTimes .not only accepts a number argument 5`] = ` "expect(received)[.not].toHaveBeenCalledTimes(expected) Expected value must be a number. @@ -398,7 +607,7 @@ Got: map: Map {}" `; -exports[`toHaveBeenCalledTimes accepts only numbers 6`] = ` +exports[`toHaveBeenCalledTimes .not only accepts a number argument 6`] = ` "expect(received)[.not].toHaveBeenCalledTimes(expected) Expected value must be a number. @@ -406,25 +615,73 @@ Got: function: [Function anonymous]" `; -exports[`toHaveBeenCalledTimes fails if function called less than expected times 1`] = ` +exports[`toHaveBeenCalledTimes .not passes if function called less than expected times 1`] = ` "expect(jest.fn()).toHaveBeenCalledTimes(2) Expected mock function to have been called two times, but it was called one time." `; -exports[`toHaveBeenCalledTimes fails if function called more than expected times 1`] = ` +exports[`toHaveBeenCalledTimes .not passes if function called more than expected times 1`] = ` "expect(jest.fn()).toHaveBeenCalledTimes(2) Expected mock function to have been called two times, but it was called three times." `; +exports[`toHaveBeenCalledTimes only accepts a number argument 1`] = ` +"expect(received)[.not].toHaveBeenCalledTimes(expected) + +Expected value must be a number. +Got: + object: {}" +`; + +exports[`toHaveBeenCalledTimes only accepts a number argument 2`] = ` +"expect(received)[.not].toHaveBeenCalledTimes(expected) + +Expected value must be a number. +Got: + array: []" +`; + +exports[`toHaveBeenCalledTimes only accepts a number argument 3`] = ` +"expect(received)[.not].toHaveBeenCalledTimes(expected) + +Expected value must be a number. +Got: + boolean: true" +`; + +exports[`toHaveBeenCalledTimes only accepts a number argument 4`] = ` +"expect(received)[.not].toHaveBeenCalledTimes(expected) + +Expected value must be a number. +Got: + string: \\"a\\"" +`; + +exports[`toHaveBeenCalledTimes only accepts a number argument 5`] = ` +"expect(received)[.not].toHaveBeenCalledTimes(expected) + +Expected value must be a number. +Got: + map: Map {}" +`; + +exports[`toHaveBeenCalledTimes only accepts a number argument 6`] = ` +"expect(received)[.not].toHaveBeenCalledTimes(expected) + +Expected value must be a number. +Got: + function: [Function anonymous]" +`; + exports[`toHaveBeenCalledTimes passes if function called equal to expected times 1`] = ` "expect(jest.fn()).not.toHaveBeenCalledTimes(2) Expected mock function not to be called two times, but it was called exactly two times." `; -exports[`toHaveBeenCalledTimes verifies that actual is a Spy 1`] = ` +exports[`toHaveBeenCalledTimes works only on spies or jest.fn 1`] = ` "expect(jest.fn())[.not].toHaveBeenCalledTimes() jest.fn() value must be a mock function or spy. @@ -466,7 +723,21 @@ exports[`toHaveBeenCalledWith works with Map 2`] = ` "expect(jest.fn()).toHaveBeenCalledWith(expected) Expected mock function to have been called with: - Map {\\"a\\" => \\"b\\", \\"b\\" => \\"a\\"} as argument 1, but it was called with Map {1 => 2, 2 => 1}." + Map {\\"a\\" => \\"b\\", \\"b\\" => \\"a\\"} +as argument 1, but it was called with + Map {1 => 2, 2 => 1}. + +Difference: + +- Expected ++ Received + + Map { +- \\"a\\" => \\"b\\", +- \\"b\\" => \\"a\\", ++ 1 => 2, ++ 2 => 1, + }" `; exports[`toHaveBeenCalledWith works with Set 1`] = ` @@ -480,14 +751,30 @@ exports[`toHaveBeenCalledWith works with Set 2`] = ` "expect(jest.fn()).toHaveBeenCalledWith(expected) Expected mock function to have been called with: - Set {3, 4} as argument 1, but it was called with Set {1, 2}." + Set {3, 4} +as argument 1, but it was called with + Set {1, 2}. + +Difference: + +- Expected ++ Received + + Set { +- 3, +- 4, ++ 1, ++ 2, + }" `; exports[`toHaveBeenCalledWith works with arguments that don't match 1`] = ` "expect(jest.fn()).toHaveBeenCalledWith(expected) Expected mock function to have been called with: - \\"bar\\" as argument 2, but it was called with \\"bar1\\"." + \\"bar\\" +as argument 2, but it was called with + \\"bar1\\"." `; exports[`toHaveBeenCalledWith works with arguments that match 1`] = ` @@ -504,69 +791,21 @@ Expected mock function not to have been called with: [\\"foo\\", \\"bar\\"]" `; -exports[`toHaveBeenCalledWith works with many arguments 2`] = ` -"expect(jest.fn()).not.toHaveBeenCalledWith(expected) - -Expected mock function not to have been called with: - [\\"foo\\", \\"bar\\"]" -`; - -exports[`toHaveBeenCalledWith works with many arguments 3`] = ` -"expect(jest.fn()).not.toHaveBeenCalledWith(expected) - -Expected mock function not to have been called with: - [\\"foo\\", \\"bar\\"]" -`; - -exports[`toHaveBeenCalledWith works with many arguments 4`] = ` -"expect(jest.fn()).not.toHaveBeenCalledWith(expected) - -Expected mock function not to have been called with: - [\\"foo\\", \\"bar\\"]" -`; - exports[`toHaveBeenCalledWith works with many arguments that don't match 1`] = ` "expect(jest.fn()).toHaveBeenCalledWith(expected) Expected mock function to have been called with: - \\"bar\\" as argument 2, but it was called with \\"bar3\\". + \\"bar\\" +as argument 2, but it was called with + \\"bar3\\". - \\"bar\\" as argument 2, but it was called with \\"bar2\\". + \\"bar\\" +as argument 2, but it was called with + \\"bar2\\". - \\"bar\\" as argument 2, but it was called with \\"bar1\\"." -`; - -exports[`toHaveBeenCalledWith works with many arguments that don't match 2`] = ` -"expect(jest.fn()).toHaveBeenCalledWith(expected) - -Expected mock function to have been called with: - \\"bar\\" as argument 2, but it was called with \\"bar3\\". - - \\"bar\\" as argument 2, but it was called with \\"bar2\\". - - \\"bar\\" as argument 2, but it was called with \\"bar1\\"." -`; - -exports[`toHaveBeenCalledWith works with many arguments that don't match 3`] = ` -"expect(jest.fn()).toHaveBeenCalledWith(expected) - -Expected mock function to have been called with: - \\"bar\\" as argument 2, but it was called with \\"bar3\\". - - \\"bar\\" as argument 2, but it was called with \\"bar2\\". - - \\"bar\\" as argument 2, but it was called with \\"bar1\\"." -`; - -exports[`toHaveBeenCalledWith works with many arguments that don't match 4`] = ` -"expect(jest.fn()).toHaveBeenCalledWith(expected) - -Expected mock function to have been called with: - \\"bar\\" as argument 2, but it was called with \\"bar3\\". - - \\"bar\\" as argument 2, but it was called with \\"bar2\\". - - \\"bar\\" as argument 2, but it was called with \\"bar1\\"." + \\"bar\\" +as argument 2, but it was called with + \\"bar1\\"." `; exports[`toHaveBeenCalledWith works with trailing undefined arguments 1`] = ` @@ -610,7 +849,21 @@ exports[`toHaveBeenLastCalledWith works with Map 2`] = ` "expect(jest.fn()).toHaveBeenLastCalledWith(expected) Expected mock function to have been last called with: - Map {\\"a\\" => \\"b\\", \\"b\\" => \\"a\\"} as argument 1, but it was called with Map {1 => 2, 2 => 1}." + Map {\\"a\\" => \\"b\\", \\"b\\" => \\"a\\"} +as argument 1, but it was called with + Map {1 => 2, 2 => 1}. + +Difference: + +- Expected ++ Received + + Map { +- \\"a\\" => \\"b\\", +- \\"b\\" => \\"a\\", ++ 1 => 2, ++ 2 => 1, + }" `; exports[`toHaveBeenLastCalledWith works with Set 1`] = ` @@ -624,14 +877,30 @@ exports[`toHaveBeenLastCalledWith works with Set 2`] = ` "expect(jest.fn()).toHaveBeenLastCalledWith(expected) Expected mock function to have been last called with: - Set {3, 4} as argument 1, but it was called with Set {1, 2}." + Set {3, 4} +as argument 1, but it was called with + Set {1, 2}. + +Difference: + +- Expected ++ Received + + Set { +- 3, +- 4, ++ 1, ++ 2, + }" `; exports[`toHaveBeenLastCalledWith works with arguments that don't match 1`] = ` "expect(jest.fn()).toHaveBeenLastCalledWith(expected) Expected mock function to have been last called with: - \\"bar\\" as argument 2, but it was called with \\"bar1\\"." + \\"bar\\" +as argument 2, but it was called with + \\"bar1\\"." `; exports[`toHaveBeenLastCalledWith works with arguments that match 1`] = ` @@ -648,58 +917,145 @@ Expected mock function to not have been last called with: [\\"foo\\", \\"bar\\"]" `; -exports[`toHaveBeenLastCalledWith works with many arguments 2`] = ` -"expect(jest.fn()).not.toHaveBeenLastCalledWith(expected) +exports[`toHaveBeenLastCalledWith works with many arguments that don't match 1`] = ` +"expect(jest.fn()).toHaveBeenLastCalledWith(expected) -Expected mock function to not have been last called with: - [\\"foo\\", \\"bar\\"]" +Expected mock function to have been last called with: + \\"bar\\" +as argument 2, but it was called with + \\"bar3\\"." `; -exports[`toHaveBeenLastCalledWith works with many arguments 3`] = ` -"expect(jest.fn()).not.toHaveBeenLastCalledWith(expected) +exports[`toHaveBeenLastCalledWith works with trailing undefined arguments 1`] = ` +"expect(jest.fn()).toHaveBeenLastCalledWith(expected) -Expected mock function to not have been last called with: - [\\"foo\\", \\"bar\\"]" +Expected mock function to have been last called with: + Did not expect argument 2 but it was called with undefined." `; -exports[`toHaveBeenLastCalledWith works with many arguments 4`] = ` -"expect(jest.fn()).not.toHaveBeenLastCalledWith(expected) +exports[`toHaveBeenNthCalledWith should reject non integer nth value 1`] = `"nth value 0.1 must be a positive integer greater than 0"`; -Expected mock function to not have been last called with: - [\\"foo\\", \\"bar\\"]" +exports[`toHaveBeenNthCalledWith should reject nth value smaller than 1 1`] = `"nth value 0 must be a positive integer greater than 0"`; + +exports[`toHaveBeenNthCalledWith should replace 1st, 2nd, 3rd with first, second, third 1`] = ` +"expect(jest.fn()).toHaveBeenNthCalledWith(expected) + +Expected mock function first call to have been called with: +" `; -exports[`toHaveBeenLastCalledWith works with many arguments that don't match 1`] = ` -"expect(jest.fn()).toHaveBeenLastCalledWith(expected) +exports[`toHaveBeenNthCalledWith should replace 1st, 2nd, 3rd with first, second, third 2`] = ` +"expect(jest.fn()).not.toHaveBeenNthCalledWith(expected) -Expected mock function to have been last called with: - \\"bar\\" as argument 2, but it was called with \\"bar3\\"." +Expected mock function first call to not have been called with: + [\\"foo1\\", \\"bar\\"]" `; -exports[`toHaveBeenLastCalledWith works with many arguments that don't match 2`] = ` -"expect(jest.fn()).toHaveBeenLastCalledWith(expected) +exports[`toHaveBeenNthCalledWith works only on spies or jest.fn 1`] = ` +"expect(jest.fn())[.not].toHaveBeenNthCalledWith() -Expected mock function to have been last called with: - \\"bar\\" as argument 2, but it was called with \\"bar3\\"." +jest.fn() value must be a mock function or spy. +Received: + function: [Function fn]" `; -exports[`toHaveBeenLastCalledWith works with many arguments that don't match 3`] = ` -"expect(jest.fn()).toHaveBeenLastCalledWith(expected) +exports[`toHaveBeenNthCalledWith works when not called 1`] = ` +"expect(jest.fn()).toHaveBeenNthCalledWith(expected) -Expected mock function to have been last called with: - \\"bar\\" as argument 2, but it was called with \\"bar3\\"." +Expected mock function first call to have been called with: + [\\"foo\\", \\"bar\\"] +But it was not called." `; -exports[`toHaveBeenLastCalledWith works with many arguments that don't match 4`] = ` -"expect(jest.fn()).toHaveBeenLastCalledWith(expected) +exports[`toHaveBeenNthCalledWith works with Immutable.js objects 1`] = ` +"expect(jest.fn()).not.toHaveBeenNthCalledWith(expected) -Expected mock function to have been last called with: - \\"bar\\" as argument 2, but it was called with \\"bar3\\"." +Expected mock function first call to not have been called with: + [Immutable.Map {\\"a\\": {\\"b\\": \\"c\\"}}, Immutable.Map {\\"a\\": {\\"b\\": \\"c\\"}}]" `; -exports[`toHaveBeenLastCalledWith works with trailing undefined arguments 1`] = ` -"expect(jest.fn()).toHaveBeenLastCalledWith(expected) +exports[`toHaveBeenNthCalledWith works with Map 1`] = ` +"expect(jest.fn()).not.toHaveBeenNthCalledWith(expected) -Expected mock function to have been last called with: +Expected mock function first call to not have been called with: + [Map {1 => 2, 2 => 1}]" +`; + +exports[`toHaveBeenNthCalledWith works with Map 2`] = ` +"expect(jest.fn()).toHaveBeenNthCalledWith(expected) + +Expected mock function first call to have been called with: + Map {\\"a\\" => \\"b\\", \\"b\\" => \\"a\\"} +as argument 1, but it was called with + Map {1 => 2, 2 => 1}. + +Difference: + +- Expected ++ Received + + Map { +- \\"a\\" => \\"b\\", +- \\"b\\" => \\"a\\", ++ 1 => 2, ++ 2 => 1, + }" +`; + +exports[`toHaveBeenNthCalledWith works with Set 1`] = ` +"expect(jest.fn()).not.toHaveBeenNthCalledWith(expected) + +Expected mock function first call to not have been called with: + [Set {1, 2}]" +`; + +exports[`toHaveBeenNthCalledWith works with Set 2`] = ` +"expect(jest.fn()).toHaveBeenNthCalledWith(expected) + +Expected mock function first call to have been called with: + Set {3, 4} +as argument 1, but it was called with + Set {1, 2}. + +Difference: + +- Expected ++ Received + + Set { +- 3, +- 4, ++ 1, ++ 2, + }" +`; + +exports[`toHaveBeenNthCalledWith works with arguments that don't match 1`] = ` +"expect(jest.fn()).toHaveBeenNthCalledWith(expected) + +Expected mock function first call to have been called with: + \\"bar\\" +as argument 2, but it was called with + \\"bar1\\"." +`; + +exports[`toHaveBeenNthCalledWith works with arguments that match 1`] = ` +"expect(jest.fn()).not.toHaveBeenNthCalledWith(expected) + +Expected mock function first call to not have been called with: + [\\"foo\\", \\"bar\\"]" +`; + +exports[`toHaveBeenNthCalledWith works with three calls 1`] = ` +"expect(jest.fn()).not.toHaveBeenNthCalledWith(expected) + +Expected mock function first call to not have been called with: + [\\"foo1\\", \\"bar\\"]" +`; + +exports[`toHaveBeenNthCalledWith works with trailing undefined arguments 1`] = ` +"expect(jest.fn()).toHaveBeenNthCalledWith(expected) + +Expected mock function first call to have been called with: Did not expect argument 2 but it was called with undefined." `; diff --git a/packages/expect/src/__tests__/spy_matchers.test.js b/packages/expect/src/__tests__/spy_matchers.test.js index 52cb3d1d29e9..91624ef28515 100644 --- a/packages/expect/src/__tests__/spy_matchers.test.js +++ b/packages/expect/src/__tests__/spy_matchers.test.js @@ -9,297 +9,336 @@ const Immutable = require('immutable'); const jestExpect = require('../'); -['toHaveBeenCalled', 'toBeCalled'].forEach(called => { - test(`${called} works with jest.fn`, () => { - const fn = jest.fn(); +['toBeCalled', 'toHaveBeenCalled'].forEach(called => { + describe(`${called}`, () => { + test(`works only on spies or jest.fn`, () => { + const fn = function fn() {}; - jestExpect(fn).not[called](); - expect(() => jestExpect(fn)[called]()).toThrowErrorMatchingSnapshot(); + expect(() => jestExpect(fn)[called]()).toThrowErrorMatchingSnapshot(); + }); - fn(); - jestExpect(fn)[called](); - expect(() => jestExpect(fn).not[called]()).toThrowErrorMatchingSnapshot(); + test(`passes when called`, () => { + const fn = jest.fn(); + fn(); + jestExpect(fn)[called](); + expect(() => jestExpect(fn).not[called]()).toThrowErrorMatchingSnapshot(); + }); - expect(() => jestExpect(fn)[called](555)).toThrowErrorMatchingSnapshot(); - }); -}); + test(`.not passes when called`, () => { + const fn = jest.fn(); + + jestExpect(fn).not[called](); + expect(() => jestExpect(fn)[called]()).toThrowErrorMatchingSnapshot(); + }); + + test(`fails with any argument passed`, () => { + const fn = jest.fn(); -describe('toHaveBeenCalledTimes', () => { - it('accepts only numbers', () => { - const fn = jest.fn(); - fn(); - jestExpect(fn).toHaveBeenCalledTimes(1); + fn(); + expect(() => jestExpect(fn)[called](555)).toThrowErrorMatchingSnapshot(); + }); + + test(`.not fails with any argument passed`, () => { + const fn = jest.fn(); - [{}, [], true, 'a', new Map(), () => {}].forEach(value => { expect(() => - jestExpect(fn).toHaveBeenCalledTimes(value), + jestExpect(fn).not[called](555), ).toThrowErrorMatchingSnapshot(); }); }); +}); - it('verifies that actual is a Spy', () => { - const fn = function fn() {}; +['toBeCalledTimes', 'toHaveBeenCalledTimes'].forEach(calledTimes => { + describe(`${calledTimes}`, () => { + test('works only on spies or jest.fn', () => { + const fn = function fn() {}; - expect(() => - jestExpect(fn).toHaveBeenCalledTimes(2), - ).toThrowErrorMatchingSnapshot(); - }); + expect(() => + jestExpect(fn)[calledTimes](2), + ).toThrowErrorMatchingSnapshot(); + }); - it('passes if function called equal to expected times', () => { - const fn = jest.fn(); - fn(); - fn(); + test('only accepts a number argument', () => { + const fn = jest.fn(); + fn(); + jestExpect(fn)[calledTimes](1); + + [{}, [], true, 'a', new Map(), () => {}].forEach(value => { + expect(() => + jestExpect(fn)[calledTimes](value), + ).toThrowErrorMatchingSnapshot(); + }); + }); - jestExpect(fn).toHaveBeenCalledTimes(2); + test('.not only accepts a number argument', () => { + const fn = jest.fn(); + jestExpect(fn).not[calledTimes](1); - expect(() => - jestExpect(fn).not.toHaveBeenCalledTimes(2), - ).toThrowErrorMatchingSnapshot(); - }); + [{}, [], true, 'a', new Map(), () => {}].forEach(value => { + expect(() => + jestExpect(fn).not[calledTimes](value), + ).toThrowErrorMatchingSnapshot(); + }); + }); - it('fails if function called more than expected times', () => { - const fn = jest.fn(); - fn(); - fn(); - fn(); + test('passes if function called equal to expected times', () => { + const fn = jest.fn(); + fn(); + fn(); - jestExpect(fn).toHaveBeenCalledTimes(3); - jestExpect(fn).not.toHaveBeenCalledTimes(2); + jestExpect(fn)[calledTimes](2); - expect(() => - jestExpect(fn).toHaveBeenCalledTimes(2), - ).toThrowErrorMatchingSnapshot(); - }); + expect(() => + jestExpect(fn).not[calledTimes](2), + ).toThrowErrorMatchingSnapshot(); + }); - it('fails if function called less than expected times', () => { - const fn = jest.fn(); - fn(); + test('.not passes if function called more than expected times', () => { + const fn = jest.fn(); + fn(); + fn(); + fn(); - jestExpect(fn).toHaveBeenCalledTimes(1); - jestExpect(fn).not.toHaveBeenCalledTimes(2); + jestExpect(fn)[calledTimes](3); + jestExpect(fn).not[calledTimes](2); - expect(() => - jestExpect(fn).toHaveBeenCalledTimes(2), - ).toThrowErrorMatchingSnapshot(); - }); -}); + expect(() => + jestExpect(fn)[calledTimes](2), + ).toThrowErrorMatchingSnapshot(); + }); -[ - 'lastCalledWith', - 'toBeCalled', - 'toBeCalledWith', - 'toHaveBeenCalled', - 'toHaveBeenCalledWith', - 'toHaveBeenLastCalledWith', -].forEach(calledWith => { - test(`${calledWith} works only on spies or jest.fn`, () => { - const fn = function fn() {}; + test('.not passes if function called less than expected times', () => { + const fn = jest.fn(); + fn(); + + jestExpect(fn)[calledTimes](1); + jestExpect(fn).not[calledTimes](2); - expect(() => jestExpect(fn)[calledWith]()).toThrowErrorMatchingSnapshot(); + expect(() => + jestExpect(fn)[calledTimes](2), + ).toThrowErrorMatchingSnapshot(); + }); }); }); [ 'lastCalledWith', + 'toHaveBeenLastCalledWith', 'nthCalledWith', + 'toHaveBeenNthCalledWith', + 'toBeCalledWith', 'toHaveBeenCalledWith', - 'toHaveBeenLastCalledWith', ].forEach(calledWith => { const caller = function(callee, ...args) { - if (calledWith == 'nthCalledWith') { + if ( + calledWith === 'nthCalledWith' || + calledWith === 'toHaveBeenNthCalledWith' + ) { callee(1, ...args); } else { callee(...args); } }; - test(`${calledWith} works when not called`, () => { - const fn = jest.fn(); - caller(jestExpect(fn).not[calledWith], 'foo', 'bar'); - - expect(() => - caller(jestExpect(fn)[calledWith], 'foo', 'bar'), - ).toThrowErrorMatchingSnapshot(); - }); - - test(`${calledWith} works with no arguments`, () => { - const fn = jest.fn(); - fn(); - caller(jestExpect(fn)[calledWith]); - }); - - test(`${calledWith} works with arguments that don't match`, () => { - const fn = jest.fn(); - fn('foo', 'bar1'); - - caller(jestExpect(fn).not[calledWith], 'foo', 'bar'); - - expect(() => - caller(jestExpect(fn)[calledWith], 'foo', 'bar'), - ).toThrowErrorMatchingSnapshot(); - }); - - test(`${calledWith} works with arguments that match`, () => { - const fn = jest.fn(); - fn('foo', 'bar'); - - caller(jestExpect(fn)[calledWith], 'foo', 'bar'); - - expect(() => - caller(jestExpect(fn).not[calledWith], 'foo', 'bar'), - ).toThrowErrorMatchingSnapshot(); - }); - - test(`${calledWith} works with trailing undefined arguments`, () => { - const fn = jest.fn(); - fn('foo', undefined); - - expect(() => - caller(jestExpect(fn)[calledWith], 'foo'), - ).toThrowErrorMatchingSnapshot(); - }); - - test(`${calledWith} works with Map`, () => { - const fn = jest.fn(); - - const m1 = new Map([[1, 2], [2, 1]]); - const m2 = new Map([[1, 2], [2, 1]]); - const m3 = new Map([['a', 'b'], ['b', 'a']]); - - fn(m1); + describe(`${calledWith}`, () => { + test(`works only on spies or jest.fn`, () => { + const fn = function fn() {}; - caller(jestExpect(fn)[calledWith], m2); - caller(jestExpect(fn).not[calledWith], m3); - - expect(() => - caller(jestExpect(fn).not[calledWith], m2), - ).toThrowErrorMatchingSnapshot(); - expect(() => - caller(jestExpect(fn)[calledWith], m3), - ).toThrowErrorMatchingSnapshot(); - }); + expect(() => jestExpect(fn)[calledWith]()).toThrowErrorMatchingSnapshot(); + }); - test(`${calledWith} works with Set`, () => { - const fn = jest.fn(); + test(`works when not called`, () => { + const fn = jest.fn(); + caller(jestExpect(fn).not[calledWith], 'foo', 'bar'); - const s1 = new Set([1, 2]); - const s2 = new Set([1, 2]); - const s3 = new Set([3, 4]); + expect(() => + caller(jestExpect(fn)[calledWith], 'foo', 'bar'), + ).toThrowErrorMatchingSnapshot(); + }); - fn(s1); + test(`works with no arguments`, () => { + const fn = jest.fn(); + fn(); + caller(jestExpect(fn)[calledWith]); + }); - caller(jestExpect(fn)[calledWith], s2); - caller(jestExpect(fn).not[calledWith], s3); + test(`works with arguments that don't match`, () => { + const fn = jest.fn(); + fn('foo', 'bar1'); - expect(() => - caller(jestExpect(fn).not[calledWith], s2), - ).toThrowErrorMatchingSnapshot(); - expect(() => - caller(jestExpect(fn)[calledWith], s3), - ).toThrowErrorMatchingSnapshot(); - }); + caller(jestExpect(fn).not[calledWith], 'foo', 'bar'); - test(`${calledWith} works with Immutable.js objects`, () => { - const fn = jest.fn(); - const directlyCreated = new Immutable.Map([['a', {b: 'c'}]]); - const indirectlyCreated = new Immutable.Map().set('a', {b: 'c'}); - fn(directlyCreated, indirectlyCreated); - - caller(jestExpect(fn)[calledWith], indirectlyCreated, directlyCreated); - - expect(() => - caller( - jestExpect(fn).not[calledWith], - indirectlyCreated, - directlyCreated, - ), - ).toThrowErrorMatchingSnapshot(); - }); + expect(() => + caller(jestExpect(fn)[calledWith], 'foo', 'bar'), + ).toThrowErrorMatchingSnapshot(); + }); - [ - 'lastCalledWith', - 'toHaveBeenCalledWith', - 'toHaveBeenLastCalledWith', - ].forEach(calledWith => { - test(`${calledWith} works with many arguments`, () => { + test(`works with arguments that match`, () => { const fn = jest.fn(); - fn('foo1', 'bar'); - fn('foo', 'bar1'); fn('foo', 'bar'); - jestExpect(fn)[calledWith]('foo', 'bar'); + caller(jestExpect(fn)[calledWith], 'foo', 'bar'); expect(() => - jestExpect(fn).not[calledWith]('foo', 'bar'), + caller(jestExpect(fn).not[calledWith], 'foo', 'bar'), ).toThrowErrorMatchingSnapshot(); }); - test(`${calledWith} works with many arguments that don't match`, () => { + test(`works with trailing undefined arguments`, () => { const fn = jest.fn(); - fn('foo', 'bar1'); - fn('foo', 'bar2'); - fn('foo', 'bar3'); - - jestExpect(fn).not[calledWith]('foo', 'bar'); + fn('foo', undefined); expect(() => - jestExpect(fn)[calledWith]('foo', 'bar'), + caller(jestExpect(fn)[calledWith], 'foo'), ).toThrowErrorMatchingSnapshot(); }); - }); - describe('nthCalledWith', () => { - test(`nthCalledWith`, () => { + test(`works with Map`, () => { const fn = jest.fn(); - fn('foo1', 'bar'); - fn('foo', 'bar1'); - fn('foo', 'bar'); - jestExpect(fn).nthCalledWith(1, 'foo1', 'bar'); - jestExpect(fn).nthCalledWith(2, 'foo', 'bar1'); - jestExpect(fn).nthCalledWith(3, 'foo', 'bar'); + const m1 = new Map([[1, 2], [2, 1]]); + const m2 = new Map([[1, 2], [2, 1]]); + const m3 = new Map([['a', 'b'], ['b', 'a']]); - expect(() => { - jestExpect(fn).not.nthCalledWith(1, 'foo1', 'bar'); - jestExpect(fn).not.nthCalledWith(2, 'foo', 'bar1'); - jestExpect(fn).not.nthCalledWith(3, 'foo', 'bar'); - }).toThrowErrorMatchingSnapshot(); - }); + fn(m1); - it('should replace 1st, 2nd, 3rd with first, second, third', async () => { - const fn = jest.fn(); - fn('foo1', 'bar'); - fn('foo', 'bar1'); - fn('foo', 'bar'); + caller(jestExpect(fn)[calledWith], m2); + caller(jestExpect(fn).not[calledWith], m3); - expect(() => { - jestExpect(fn).nthCalledWith(1, 'foo', 'bar'); - jestExpect(fn).nthCalledWith(2, 'foo', 'bar'); - jestExpect(fn).nthCalledWith(3, 'foo1', 'bar'); - }).toThrowErrorMatchingSnapshot(); - - expect(() => { - jestExpect(fn).not.nthCalledWith(1, 'foo1', 'bar'); - jestExpect(fn).not.nthCalledWith(2, 'foo', 'bar1'); - jestExpect(fn).not.nthCalledWith(3, 'foo', 'bar'); - }).toThrowErrorMatchingSnapshot(); + expect(() => + caller(jestExpect(fn).not[calledWith], m2), + ).toThrowErrorMatchingSnapshot(); + expect(() => + caller(jestExpect(fn)[calledWith], m3), + ).toThrowErrorMatchingSnapshot(); }); - it('should reject nth value smaller than 1', async () => { + test(`works with Set`, () => { const fn = jest.fn(); - fn('foo1', 'bar'); - expect(() => { - jestExpect(fn).nthCalledWith(0, 'foo1', 'bar'); - }).toThrowErrorMatchingSnapshot(); + const s1 = new Set([1, 2]); + const s2 = new Set([1, 2]); + const s3 = new Set([3, 4]); + + fn(s1); + + caller(jestExpect(fn)[calledWith], s2); + caller(jestExpect(fn).not[calledWith], s3); + + expect(() => + caller(jestExpect(fn).not[calledWith], s2), + ).toThrowErrorMatchingSnapshot(); + expect(() => + caller(jestExpect(fn)[calledWith], s3), + ).toThrowErrorMatchingSnapshot(); }); - it('should reject non integer nth value', async () => { + test(`works with Immutable.js objects`, () => { const fn = jest.fn(); - fn('foo1', 'bar'); + const directlyCreated = new Immutable.Map([['a', {b: 'c'}]]); + const indirectlyCreated = new Immutable.Map().set('a', {b: 'c'}); + fn(directlyCreated, indirectlyCreated); + + caller(jestExpect(fn)[calledWith], indirectlyCreated, directlyCreated); - expect(() => { - jestExpect(fn).nthCalledWith(0.1, 'foo1', 'bar'); - }).toThrowErrorMatchingSnapshot(); + expect(() => + caller( + jestExpect(fn).not[calledWith], + indirectlyCreated, + directlyCreated, + ), + ).toThrowErrorMatchingSnapshot(); }); + + const basicCalledWith = [ + 'lastCalledWith', + 'toHaveBeenLastCalledWith', + 'toBeCalledWith', + 'toHaveBeenCalledWith', + ]; + + if (basicCalledWith.indexOf(calledWith) >= 0) { + test(`works with many arguments`, () => { + const fn = jest.fn(); + fn('foo1', 'bar'); + fn('foo', 'bar1'); + fn('foo', 'bar'); + + jestExpect(fn)[calledWith]('foo', 'bar'); + + expect(() => + jestExpect(fn).not[calledWith]('foo', 'bar'), + ).toThrowErrorMatchingSnapshot(); + }); + + test(`works with many arguments that don't match`, () => { + const fn = jest.fn(); + fn('foo', 'bar1'); + fn('foo', 'bar2'); + fn('foo', 'bar3'); + + jestExpect(fn).not[calledWith]('foo', 'bar'); + + expect(() => + jestExpect(fn)[calledWith]('foo', 'bar'), + ).toThrowErrorMatchingSnapshot(); + }); + } + + const nthCalled = ['toHaveBeenNthCalledWith', 'nthCalledWith']; + if (nthCalled.indexOf(calledWith) >= 0) { + test(`works with three calls`, () => { + const fn = jest.fn(); + fn('foo1', 'bar'); + fn('foo', 'bar1'); + fn('foo', 'bar'); + + jestExpect(fn)[calledWith](1, 'foo1', 'bar'); + jestExpect(fn)[calledWith](2, 'foo', 'bar1'); + jestExpect(fn)[calledWith](3, 'foo', 'bar'); + + expect(() => { + jestExpect(fn).not[calledWith](1, 'foo1', 'bar'); + jestExpect(fn).not[calledWith](2, 'foo', 'bar1'); + jestExpect(fn).not[calledWith](3, 'foo', 'bar'); + }).toThrowErrorMatchingSnapshot(); + }); + + test('should replace 1st, 2nd, 3rd with first, second, third', async () => { + const fn = jest.fn(); + fn('foo1', 'bar'); + fn('foo', 'bar1'); + fn('foo', 'bar'); + + expect(() => { + jestExpect(fn)[calledWith](1, 'foo', 'bar'); + jestExpect(fn)[calledWith](2, 'foo', 'bar'); + jestExpect(fn)[calledWith](3, 'foo1', 'bar'); + }).toThrowErrorMatchingSnapshot(); + + expect(() => { + jestExpect(fn).not[calledWith](1, 'foo1', 'bar'); + jestExpect(fn).not[calledWith](2, 'foo', 'bar1'); + jestExpect(fn).not[calledWith](3, 'foo', 'bar'); + }).toThrowErrorMatchingSnapshot(); + }); + + test('should reject nth value smaller than 1', async () => { + const fn = jest.fn(); + fn('foo1', 'bar'); + + expect(() => { + jestExpect(fn)[calledWith](0, 'foo1', 'bar'); + }).toThrowErrorMatchingSnapshot(); + }); + + test('should reject non integer nth value', async () => { + const fn = jest.fn(); + fn('foo1', 'bar'); + + expect(() => { + jestExpect(fn)[calledWith](0.1, 'foo1', 'bar'); + }).toThrowErrorMatchingSnapshot(); + }); + } }); }); diff --git a/packages/expect/src/spy_matchers.js b/packages/expect/src/spy_matchers.js index 962febe48ac5..f1e4e7585dd4 100644 --- a/packages/expect/src/spy_matchers.js +++ b/packages/expect/src/spy_matchers.js @@ -24,6 +24,7 @@ import { } from 'jest-matcher-utils'; import {equals} from './jasmine_utils'; import {iterableEquality, partition} from './utils'; +import diff from 'jest-diff'; const createToBeCalledMatcher = matcherName => (received, expected) => { ensureNoExpected(expected, matcherName); @@ -53,6 +54,37 @@ const createToBeCalledMatcher = matcherName => (received, expected) => { return {message, pass}; }; +const createToBeCalledTimesMatcher = (matcherName: string) => ( + received: any, + expected: number, +) => { + ensureExpectedIsNumber(expected, matcherName); + ensureMock(received, matcherName); + + const receivedIsSpy = isSpy(received); + const type = receivedIsSpy ? 'spy' : 'mock function'; + const receivedName = receivedIsSpy ? 'spy' : received.getMockName(); + const count = receivedIsSpy + ? received.calls.count() + : received.mock.calls.length; + const pass = count === expected; + const message = pass + ? () => + matcherHint('.not' + matcherName, receivedName, String(expected)) + + `\n\n` + + `Expected ${type} not to be called ` + + `${EXPECTED_COLOR(pluralize('time', expected))}, but it was` + + ` called exactly ${RECEIVED_COLOR(pluralize('time', count))}.` + : () => + matcherHint(matcherName, receivedName, String(expected)) + + '\n\n' + + `Expected ${type} to have been called ` + + `${EXPECTED_COLOR(pluralize('time', expected))},` + + ` but it was called ${RECEIVED_COLOR(pluralize('time', count))}.`; + + return {message, pass}; +}; + const createToBeCalledWithMatcher = matcherName => ( received: any, ...expected: any @@ -115,83 +147,65 @@ const createLastCalledWithMatcher = matcherName => ( return {message, pass}; }; -const spyMatchers: MatchersObject = { - lastCalledWith: createLastCalledWithMatcher('.lastCalledWith'), - nthCalledWith(received: any, nth: number, ...expected: any) { - const matcherName = '.nthCalledWith'; - ensureMock(received, matcherName); +const createNthCalledWithMatcher = (matcherName: string) => ( + received: any, + nth: number, + ...expected: any +) => { + ensureMock(received, matcherName); - const receivedIsSpy = isSpy(received); - const type = receivedIsSpy ? 'spy' : 'mock function'; + const receivedIsSpy = isSpy(received); + const type = receivedIsSpy ? 'spy' : 'mock function'; - if (typeof nth !== 'number' || parseInt(nth, 10) !== nth || nth < 1) { - const message = () => - `nth value ${printReceived( + if (typeof nth !== 'number' || parseInt(nth, 10) !== nth || nth < 1) { + const message = () => + `nth value ${printReceived( + nth, + )} must be a positive integer greater than ${printExpected(0)}`; + const pass = false; + return {message, pass}; + } + + const receivedName = receivedIsSpy ? 'spy' : received.getMockName(); + const calls = receivedIsSpy + ? received.calls.all().map(x => x.args) + : received.mock.calls; + const pass = equals(calls[nth - 1], expected, [iterableEquality]); + + const message = pass + ? () => + matcherHint('.not' + matcherName, receivedName) + + '\n\n' + + `Expected ${type} ${nthToString( nth, - )} must be a positive integer greater than ${printExpected(0)}`; - const pass = false; - return {message, pass}; - } + )} call to not have been called with:\n` + + ` ${printExpected(expected)}` + : () => + matcherHint(matcherName, receivedName) + + '\n\n' + + `Expected ${type} ${nthToString( + nth, + )} call to have been called with:\n` + + formatMismatchedCalls(calls, expected, LAST_CALL_PRINT_LIMIT); - const receivedName = receivedIsSpy ? 'spy' : received.getMockName(); - const calls = receivedIsSpy - ? received.calls.all().map(x => x.args) - : received.mock.calls; - const pass = equals(calls[nth - 1], expected, [iterableEquality]); - - const message = pass - ? () => - matcherHint('.not' + matcherName, receivedName) + - '\n\n' + - `Expected ${type} ${nthToString( - nth, - )} call to not have been called with:\n` + - ` ${printExpected(expected)}` - : () => - matcherHint(matcherName, receivedName) + - '\n\n' + - `Expected ${type} ${nthToString( - nth, - )} call to have been called with:\n` + - formatMismatchedCalls(calls, expected, LAST_CALL_PRINT_LIMIT); + return {message, pass}; +}; - return {message, pass}; - }, +const spyMatchers: MatchersObject = { + lastCalledWith: createLastCalledWithMatcher('.lastCalledWith'), + nthCalledWith: createNthCalledWithMatcher('.nthCalledWith'), toBeCalled: createToBeCalledMatcher('.toBeCalled'), + toBeCalledTimes: createToBeCalledTimesMatcher('.toBeCalledTimes'), toBeCalledWith: createToBeCalledWithMatcher('.toBeCalledWith'), toHaveBeenCalled: createToBeCalledMatcher('.toHaveBeenCalled'), - toHaveBeenCalledTimes(received: any, expected: number) { - const matcherName = '.toHaveBeenCalledTimes'; - ensureExpectedIsNumber(expected, matcherName); - ensureMock(received, matcherName); - - const receivedIsSpy = isSpy(received); - const type = receivedIsSpy ? 'spy' : 'mock function'; - const receivedName = receivedIsSpy ? 'spy' : received.getMockName(); - const count = receivedIsSpy - ? received.calls.count() - : received.mock.calls.length; - const pass = count === expected; - const message = pass - ? () => - matcherHint('.not' + matcherName, receivedName, String(expected)) + - `\n\n` + - `Expected ${type} not to be called ` + - `${EXPECTED_COLOR(pluralize('time', expected))}, but it was` + - ` called exactly ${RECEIVED_COLOR(pluralize('time', count))}.` - : () => - matcherHint(matcherName, receivedName, String(expected)) + - '\n\n' + - `Expected ${type} to have been called ` + - `${EXPECTED_COLOR(pluralize('time', expected))},` + - ` but it was called ${RECEIVED_COLOR(pluralize('time', count))}.`; - - return {message, pass}; - }, + toHaveBeenCalledTimes: createToBeCalledTimesMatcher('.toHaveBeenCalledTimes'), toHaveBeenCalledWith: createToBeCalledWithMatcher('.toHaveBeenCalledWith'), toHaveBeenLastCalledWith: createLastCalledWithMatcher( '.toHaveBeenLastCalledWith', ), + toHaveBeenNthCalledWith: createNthCalledWithMatcher( + '.toHaveBeenNthCalledWith', + ), }; const isSpy = spy => spy.calls && typeof spy.calls.count === 'function'; @@ -268,9 +282,12 @@ const formatMismatchedArgs = (expected, received) => { const printedArgs = []; for (let i = 0; i < length; i++) { if (!equals(expected[i], received[i], [iterableEquality])) { + const diffString = diff(expected[i], received[i]); printedArgs.push( - ` ${printExpected(expected[i])} as argument ${i + 1}, ` + - `but it was called with ${printReceived(received[i])}.`, + ` ${printExpected(expected[i])}\n` + + `as argument ${i + 1}, but it was called with\n` + + ` ${printReceived(received[i])}.` + + (diffString ? `\n\nDifference:\n\n${diffString}` : ''), ); } else if (i >= expected.length) { printedArgs.push( diff --git a/packages/jest-cli/package.json b/packages/jest-cli/package.json index 07de853f620a..3e4bfd85189a 100644 --- a/packages/jest-cli/package.json +++ b/packages/jest-cli/package.json @@ -11,7 +11,7 @@ "graceful-fs": "^4.1.11", "import-local": "^1.0.0", "is-ci": "^1.0.10", - "istanbul-api": "^1.1.14", + "istanbul-api": "^1.3.1", "istanbul-lib-coverage": "^1.1.1", "istanbul-lib-instrument": "^1.8.0", "istanbul-lib-source-maps": "^1.2.1", diff --git a/packages/jest-cli/src/__tests__/__snapshots__/snapshot_interactive_mode.test.js.snap b/packages/jest-cli/src/__tests__/__snapshots__/snapshot_interactive_mode.test.js.snap index fd47bf1ef31f..e842ea64375f 100644 --- a/packages/jest-cli/src/__tests__/__snapshots__/snapshot_interactive_mode.test.js.snap +++ b/packages/jest-cli/src/__tests__/__snapshots__/snapshot_interactive_mode.test.js.snap @@ -1,36 +1,308 @@ // Jest Snapshot v1, https://goo.gl/fbAQLP -exports[`SnapshotInteractiveMode updateWithResults last test success, trigger end of interactive mode 1`] = `"TEST RESULTS CONTENTS"`; +exports[`SnapshotInteractiveMode skip 1 test, then quit 1`] = ` +"[MOCK - cursorUp] +[MOCK - eraseDown] + +Interactive Snapshot Progress + › 1 snapshot remaining + +Watch Usage + › Press u to update failing snapshots for this test. + › Press s to skip the current test. + › Press q to quit Interactive Snapshot Mode. + › Press Enter to trigger a test run. +" +`; + +exports[`SnapshotInteractiveMode skip 1 test, then quit 2`] = ` +"[MOCK - eraseDown] + +Interactive Snapshot Result + › 1 snapshot reviewed, 1 snapshot skipped + +Watch Usage + › Press r to restart Interactive Snapshot Mode. + › Press q to quit Interactive Snapshot Mode. +" +`; + +exports[`SnapshotInteractiveMode skip 1 test, then restart 1`] = ` +"[MOCK - cursorUp] +[MOCK - eraseDown] + +Interactive Snapshot Progress + › 1 snapshot remaining + +Watch Usage + › Press u to update failing snapshots for this test. + › Press s to skip the current test. + › Press q to quit Interactive Snapshot Mode. + › Press Enter to trigger a test run. +" +`; + +exports[`SnapshotInteractiveMode skip 1 test, then restart 2`] = ` +"[MOCK - eraseDown] + +Interactive Snapshot Result + › 1 snapshot reviewed, 1 snapshot skipped + +Watch Usage + › Press r to restart Interactive Snapshot Mode. + › Press q to quit Interactive Snapshot Mode. +" +`; + +exports[`SnapshotInteractiveMode skip 1 test, then restart 3`] = ` +"[MOCK - cursorUp] +[MOCK - eraseDown] + +Interactive Snapshot Progress + › 1 snapshot remaining + +Watch Usage + › Press u to update failing snapshots for this test. + › Press s to skip the current test. + › Press q to quit Interactive Snapshot Mode. + › Press Enter to trigger a test run. +" +`; + +exports[`SnapshotInteractiveMode skip 1 test, update 1 test, then finish and restart 1`] = ` +"[MOCK - cursorUp] +[MOCK - eraseDown] + +Interactive Snapshot Progress + › 2 snapshots remaining + +Watch Usage + › Press u to update failing snapshots for this test. + › Press s to skip the current test. + › Press q to quit Interactive Snapshot Mode. + › Press Enter to trigger a test run. +" +`; + +exports[`SnapshotInteractiveMode skip 1 test, update 1 test, then finish and restart 2`] = ` +"[MOCK - cursorUp] +[MOCK - eraseDown] + +Interactive Snapshot Progress + › 1 snapshot remaining, 1 snapshot skipped + +Watch Usage + › Press u to update failing snapshots for this test. + › Press s to skip the current test. + › Press q to quit Interactive Snapshot Mode. + › Press Enter to trigger a test run. +" +`; + +exports[`SnapshotInteractiveMode skip 1 test, update 1 test, then finish and restart 3`] = ` +"[MOCK - eraseDown] + +Interactive Snapshot Result + › 2 snapshots reviewed, 1 snapshot updated, 1 snapshot skipped + +Watch Usage + › Press r to restart Interactive Snapshot Mode. + › Press q to quit Interactive Snapshot Mode. +" +`; + +exports[`SnapshotInteractiveMode skip 1 test, update 1 test, then finish and restart 4`] = ` +"[MOCK - cursorUp] +[MOCK - eraseDown] + +Interactive Snapshot Progress + › 1 snapshot remaining + +Watch Usage + › Press u to update failing snapshots for this test. + › Press s to skip the current test. + › Press q to quit Interactive Snapshot Mode. + › Press Enter to trigger a test run. +" +`; + +exports[`SnapshotInteractiveMode skip 2 tests, then finish and restart 1`] = ` +"[MOCK - cursorUp] +[MOCK - eraseDown] + +Interactive Snapshot Progress + › 2 snapshots remaining + +Watch Usage + › Press u to update failing snapshots for this test. + › Press s to skip the current test. + › Press q to quit Interactive Snapshot Mode. + › Press Enter to trigger a test run. +" +`; + +exports[`SnapshotInteractiveMode skip 2 tests, then finish and restart 2`] = ` +"[MOCK - cursorUp] +[MOCK - eraseDown] + +Interactive Snapshot Progress + › 1 snapshot remaining, 1 snapshot skipped + +Watch Usage + › Press u to update failing snapshots for this test. + › Press s to skip the current test. + › Press q to quit Interactive Snapshot Mode. + › Press Enter to trigger a test run. +" +`; + +exports[`SnapshotInteractiveMode skip 2 tests, then finish and restart 3`] = ` +"[MOCK - eraseDown] + +Interactive Snapshot Result + › 2 snapshots reviewed, 2 snapshots skipped -exports[`SnapshotInteractiveMode updateWithResults overlay handle progress UI 1`] = ` -"TEST RESULTS CONTENTS -[MOCK - cursorUp] +Watch Usage + › Press r to restart Interactive Snapshot Mode. + › Press q to quit Interactive Snapshot Mode. +" +`; + +exports[`SnapshotInteractiveMode skip 2 tests, then finish and restart 4`] = ` +"[MOCK - cursorUp] [MOCK - eraseDown] Interactive Snapshot Progress - › 2 suites failed, 1 suite passed + › 2 snapshots remaining Watch Usage › Press u to update failing snapshots for this test. - › Press s to skip the current test suite. - › Press q to quit Interactive Snapshot Update Mode. + › Press s to skip the current test. + › Press q to quit Interactive Snapshot Mode. › Press Enter to trigger a test run. " `; -exports[`SnapshotInteractiveMode updateWithResults with a test failure simply update UI 1`] = ` -"TEST RESULTS CONTENTS -[MOCK - cursorUp] +exports[`SnapshotInteractiveMode update 1 test, skip 1 test, then finish and restart 1`] = ` +"[MOCK - cursorUp] [MOCK - eraseDown] Interactive Snapshot Progress - › 1 suite failed + › 2 snapshots remaining Watch Usage › Press u to update failing snapshots for this test. - › Press q to quit Interactive Snapshot Update Mode. + › Press s to skip the current test. + › Press q to quit Interactive Snapshot Mode. › Press Enter to trigger a test run. " `; -exports[`SnapshotInteractiveMode updateWithResults with a test success, call the next test 1`] = `"TEST RESULTS CONTENTS"`; +exports[`SnapshotInteractiveMode update 1 test, skip 1 test, then finish and restart 2`] = ` +"[MOCK - cursorUp] +[MOCK - eraseDown] + +Interactive Snapshot Progress + › 1 snapshot remaining, 1 snapshot updated + +Watch Usage + › Press u to update failing snapshots for this test. + › Press s to skip the current test. + › Press q to quit Interactive Snapshot Mode. + › Press Enter to trigger a test run. +" +`; + +exports[`SnapshotInteractiveMode update 1 test, skip 1 test, then finish and restart 3`] = ` +"[MOCK - eraseDown] + +Interactive Snapshot Result + › 2 snapshots reviewed, 1 snapshot updated, 1 snapshot skipped + +Watch Usage + › Press r to restart Interactive Snapshot Mode. + › Press q to quit Interactive Snapshot Mode. +" +`; + +exports[`SnapshotInteractiveMode update 1 test, skip 1 test, then finish and restart 4`] = ` +"[MOCK - cursorUp] +[MOCK - eraseDown] + +Interactive Snapshot Progress + › 1 snapshot remaining + +Watch Usage + › Press u to update failing snapshots for this test. + › Press s to skip the current test. + › Press q to quit Interactive Snapshot Mode. + › Press Enter to trigger a test run. +" +`; + +exports[`SnapshotInteractiveMode update 1 test, then finish and return 1`] = ` +"[MOCK - cursorUp] +[MOCK - eraseDown] + +Interactive Snapshot Progress + › 1 snapshot remaining + +Watch Usage + › Press u to update failing snapshots for this test. + › Press s to skip the current test. + › Press q to quit Interactive Snapshot Mode. + › Press Enter to trigger a test run. +" +`; + +exports[`SnapshotInteractiveMode update 1 test, then finish and return 2`] = ` +"[MOCK - eraseDown] + +Interactive Snapshot Result + › 1 snapshot reviewed, 1 snapshot updated + +Watch Usage + › Press Enter to return to watch mode. +" +`; + +exports[`SnapshotInteractiveMode update 2 tests, then finish and return 1`] = ` +"[MOCK - cursorUp] +[MOCK - eraseDown] + +Interactive Snapshot Progress + › 2 snapshots remaining + +Watch Usage + › Press u to update failing snapshots for this test. + › Press s to skip the current test. + › Press q to quit Interactive Snapshot Mode. + › Press Enter to trigger a test run. +" +`; + +exports[`SnapshotInteractiveMode update 2 tests, then finish and return 2`] = ` +"[MOCK - cursorUp] +[MOCK - eraseDown] + +Interactive Snapshot Progress + › 1 snapshot remaining, 1 snapshot updated + +Watch Usage + › Press u to update failing snapshots for this test. + › Press s to skip the current test. + › Press q to quit Interactive Snapshot Mode. + › Press Enter to trigger a test run. +" +`; + +exports[`SnapshotInteractiveMode update 2 tests, then finish and return 3`] = ` +"[MOCK - eraseDown] + +Interactive Snapshot Result + › 2 snapshots reviewed, 2 snapshots updated + +Watch Usage + › Press Enter to return to watch mode. +" +`; diff --git a/packages/jest-cli/src/__tests__/__snapshots__/watch.test.js.snap b/packages/jest-cli/src/__tests__/__snapshots__/watch.test.js.snap index 70dbb5623e7e..38f4a2d573ad 100644 --- a/packages/jest-cli/src/__tests__/__snapshots__/watch.test.js.snap +++ b/packages/jest-cli/src/__tests__/__snapshots__/watch.test.js.snap @@ -28,7 +28,6 @@ Watch Usage › Press a to run all tests. › Press f to run only failed tests. › Press t to filter by a test name regex pattern. - › Press i to update failing snapshots interactively. › Press q to quit watch mode. › Press p to custom \\"P\\" plugin. › Press Enter to trigger a test run. diff --git a/packages/jest-cli/src/__tests__/run_jest_with_coverage.test.js b/packages/jest-cli/src/__tests__/run_jest_with_coverage.test.js new file mode 100644 index 000000000000..9df75caec40d --- /dev/null +++ b/packages/jest-cli/src/__tests__/run_jest_with_coverage.test.js @@ -0,0 +1,112 @@ +import runJest from '../run_jest'; + +jest.mock('jest-util'); + +jest.mock( + '../test_scheduler', + () => + class { + constructor(globalConfig) { + this._globalConfig = globalConfig; + } + + scheduleTests() { + return {_globalConfig: this._globalConfig}; + } + }, +); + +jest.mock( + '../test_sequencer', + () => + class { + sort(allTests) { + return allTests; + } + cacheResults() {} + }, +); + +jest.mock( + '../search_source', + () => + class { + constructor(context) { + this._context = context; + } + + async getTestPaths(globalConfig, changedFilesPromise) { + const {files} = await changedFilesPromise; + const paths = files.filter(path => path.match(/__tests__/)); + + return { + collectCoverageFrom: files.filter(path => !path.match(/__tests__/)), + tests: paths.map(path => ({ + context: this._context, + duration: null, + path, + })), + }; + } + }, +); + +const config = {roots: [], testPathIgnorePatterns: [], testRegex: ''}; +let globalConfig; +const defaults = { + changedFilesPromise: Promise.resolve({ + files: ['foo.js', '__tests__/foo-test.js', 'dont/cover.js'], + }), + contexts: [{config}], + onComplete: runResults => (globalConfig = runResults._globalConfig), + outputStream: {}, + startRun: {}, + testWatcher: {isInterrupted: () => false}, +}; + +describe('collectCoverageFrom patterns', () => { + it('should apply collectCoverageFrom patterns coming from SearchSource', async () => { + expect.assertions(1); + + await runJest( + Object.assign({}, defaults, { + globalConfig: { + rootDir: '', + }, + }), + ); + expect(globalConfig.collectCoverageFrom).toEqual([ + 'foo.js', + 'dont/cover.js', + ]); + }); + + it('excludes coverage from files outside the global collectCoverageFrom config', async () => { + expect.assertions(1); + + await runJest( + Object.assign({}, defaults, { + globalConfig: { + collectCoverageFrom: ['**/dont/*.js'], + rootDir: '', + }, + }), + ); + expect(globalConfig.collectCoverageFrom).toEqual(['dont/cover.js']); + }); + + it('respects coveragePathIgnorePatterns', async () => { + expect.assertions(1); + + await runJest( + Object.assign({}, defaults, { + globalConfig: { + collectCoverageFrom: ['**/*.js'], + coveragePathIgnorePatterns: ['dont'], + rootDir: '', + }, + }), + ); + expect(globalConfig.collectCoverageFrom).toEqual(['foo.js']); + }); +}); diff --git a/packages/jest-cli/src/__tests__/snapshot_interactive_mode.test.js b/packages/jest-cli/src/__tests__/snapshot_interactive_mode.test.js index 638bb8c3e7a8..26fd83792a9f 100644 --- a/packages/jest-cli/src/__tests__/snapshot_interactive_mode.test.js +++ b/packages/jest-cli/src/__tests__/snapshot_interactive_mode.test.js @@ -17,6 +17,7 @@ jest.mock('../lib/terminal_utils', () => ({ })); jest.mock('ansi-escapes', () => ({ + clearScreen: '[MOCK - eraseDown]', cursorRestorePosition: '[MOCK - cursorRestorePosition]', cursorSavePosition: '[MOCK - cursorSavePosition]', cursorScrollDown: '[MOCK - cursorScrollDown]', @@ -34,10 +35,13 @@ jest.doMock('chalk', () => describe('SnapshotInteractiveMode', () => { let pipe; let instance; - + let mockCallback; beforeEach(() => { pipe = {write: jest.fn()}; instance = new SnapshotInteractiveMode(pipe); + mockCallback = jest.fn(() => { + instance.updateWithResults({snapshot: {failure: true}}); + }); }); test('is inactive at construction', () => { @@ -45,98 +49,293 @@ describe('SnapshotInteractiveMode', () => { }); test('call to run process the first file', () => { - const mockCallback = jest.fn(); - instance.run(['first.js', 'second.js'], mockCallback); + const assertions = [ + {path: 'first.js', title: 'test one'}, + {path: 'second.js', title: 'test two'}, + ]; + instance.run(assertions, mockCallback); expect(instance.isActive()).toBeTruthy(); - expect(mockCallback).toBeCalledWith('first.js', false); + expect(mockCallback).toBeCalledWith(assertions[0], false); }); test('call to abort', () => { - const mockCallback = jest.fn(); - instance.run(['first.js', 'second.js'], mockCallback); + const assertions = [ + {path: 'first.js', title: 'test one'}, + {path: 'second.js', title: 'test two'}, + ]; + instance.run(assertions, mockCallback); expect(instance.isActive()).toBeTruthy(); instance.abort(); expect(instance.isActive()).toBeFalsy(); - expect(mockCallback).toBeCalledWith('', false); + expect(instance.getSkippedNum()).toBe(0); + expect(mockCallback).toBeCalledWith(null, false); }); - describe('key press handler', () => { - test('call to skip trigger a processing of next file', () => { - const mockCallback = jest.fn(); - instance.run(['first.js', 'second.js'], mockCallback); - expect(mockCallback.mock.calls[0]).toEqual(['first.js', false]); - instance.put(KEYS.S); - expect(mockCallback.mock.calls[1]).toEqual(['second.js', false]); - instance.put(KEYS.S); - expect(mockCallback.mock.calls[2]).toEqual(['first.js', false]); - }); - - test('call to skip works with 1 file', () => { - const mockCallback = jest.fn(); - instance.run(['first.js'], mockCallback); - expect(mockCallback.mock.calls[0]).toEqual(['first.js', false]); - instance.put(KEYS.S); - expect(mockCallback.mock.calls[1]).toEqual(['first.js', false]); - }); - - test('press U trigger a snapshot update call', () => { - const mockCallback = jest.fn(); - instance.run(['first.js'], mockCallback); - expect(mockCallback.mock.calls[0]).toEqual(['first.js', false]); - instance.put(KEYS.U); - expect(mockCallback.mock.calls[1]).toEqual(['first.js', true]); - }); - - test('press Q or ESC triggers an abort', () => { - instance.abort = jest.fn(); - instance.put(KEYS.Q); - instance.put(KEYS.ESCAPE); - expect(instance.abort).toHaveBeenCalledTimes(2); - }); - - test('press ENTER trigger a run', () => { - const mockCallback = jest.fn(); - instance.run(['first.js'], mockCallback); - instance.put(KEYS.ENTER); - expect(mockCallback).toHaveBeenCalledTimes(2); - expect(mockCallback).toHaveBeenCalledWith('first.js', false); - }); + + test('call to reset', () => { + const assertions = [ + {path: 'first.js', title: 'test one'}, + {path: 'second.js', title: 'test two'}, + ]; + instance.run(assertions, mockCallback); + expect(instance.isActive()).toBeTruthy(); + instance.restart(); + expect(instance.isActive()).toBeTruthy(); + expect(instance.getSkippedNum()).toBe(0); + expect(mockCallback).toBeCalledWith(assertions[0], false); + }); + + test('press Q or ESC triggers an abort', () => { + instance.abort = jest.fn(); + instance.put(KEYS.Q); + instance.put(KEYS.ESCAPE); + expect(instance.abort).toHaveBeenCalledTimes(2); }); - describe('updateWithResults', () => { - test('with a test failure simply update UI', () => { - const mockCallback = jest.fn(); - instance.run(['first.js'], mockCallback); - pipe.write('TEST RESULTS CONTENTS'); + + test('press ENTER trigger a run', () => { + const assertions = [{path: 'first.js', title: 'test one'}]; + instance.run(assertions, mockCallback); + instance.put(KEYS.ENTER); + expect(mockCallback).toHaveBeenCalledTimes(2); + expect(mockCallback).toHaveBeenCalledWith(assertions[0], false); + }); + + test('skip 1 test, then restart', () => { + const assertions = [{path: 'first.js', title: 'test one'}]; + + instance.run(assertions, mockCallback); + expect(mockCallback).nthCalledWith(1, assertions[0], false); + expect(pipe.write.mock.calls.join('\n')).toMatchSnapshot(); + pipe.write.mockClear(); + + instance.put(KEYS.S); + expect(mockCallback).toHaveBeenCalledTimes(1); + expect(pipe.write.mock.calls.join('\n')).toMatchSnapshot(); + pipe.write.mockClear(); + + instance.put(KEYS.R); + expect(instance.getSkippedNum()).toBe(0); + expect(mockCallback).nthCalledWith(2, assertions[0], false); + expect(mockCallback).toHaveBeenCalledTimes(2); + expect(pipe.write.mock.calls.join('\n')).toMatchSnapshot(); + }); + + test('skip 1 test, then quit', () => { + const assertions = [{path: 'first.js', title: 'test one'}]; + + instance.run(assertions, mockCallback); + expect(mockCallback).nthCalledWith(1, assertions[0], false); + expect(pipe.write.mock.calls.join('\n')).toMatchSnapshot(); + pipe.write.mockClear(); + + instance.put(KEYS.S); + expect(mockCallback).toHaveBeenCalledTimes(1); + expect(pipe.write.mock.calls.join('\n')).toMatchSnapshot(); + pipe.write.mockClear(); + + instance.put(KEYS.Q); + expect(instance.getSkippedNum()).toBe(0); + expect(mockCallback).nthCalledWith(2, null, false); + expect(mockCallback).toHaveBeenCalledTimes(2); + }); + + test('update 1 test, then finish and return', () => { + const mockCallback = jest.fn(); + mockCallback.mockImplementationOnce(() => { + instance.updateWithResults({snapshot: {failure: true}}); + }); + mockCallback.mockImplementationOnce(() => { + instance.updateWithResults({snapshot: {failure: false}}); + }); + mockCallback.mockImplementationOnce(() => { instance.updateWithResults({snapshot: {failure: true}}); - expect(pipe.write.mock.calls.join('\n')).toMatchSnapshot(); - expect(mockCallback).toHaveBeenCalledTimes(1); }); - test('with a test success, call the next test', () => { - const mockCallback = jest.fn(); - instance.run(['first.js', 'second.js'], mockCallback); - pipe.write('TEST RESULTS CONTENTS'); + const assertions = [{path: 'first.js', title: 'test one'}]; + + instance.run(assertions, mockCallback); + expect(mockCallback).nthCalledWith(1, assertions[0], false); + expect(pipe.write.mock.calls.join('\n')).toMatchSnapshot(); + pipe.write.mockClear(); + + instance.put(KEYS.U); + expect(mockCallback).nthCalledWith(2, assertions[0], true); + expect(mockCallback).toHaveBeenCalledTimes(2); + expect(pipe.write.mock.calls.join('\n')).toMatchSnapshot(); + + instance.put(KEYS.ENTER); + expect(instance.isActive()).toBe(false); + expect(mockCallback).nthCalledWith(3, null, false); + }); + + test('skip 2 tests, then finish and restart', () => { + const assertions = [ + {path: 'first.js', title: 'test one'}, + {path: 'first.js', title: 'test two'}, + ]; + instance.run(assertions, mockCallback); + expect(mockCallback).nthCalledWith(1, assertions[0], false); + expect(pipe.write.mock.calls.join('\n')).toMatchSnapshot(); + pipe.write.mockClear(); + + instance.put(KEYS.S); + expect(mockCallback).nthCalledWith(2, assertions[1], false); + expect(mockCallback).toHaveBeenCalledTimes(2); + expect(pipe.write.mock.calls.join('\n')).toMatchSnapshot(); + pipe.write.mockClear(); + + instance.put(KEYS.S); + expect(mockCallback).toHaveBeenCalledTimes(2); + expect(pipe.write.mock.calls.join('\n')).toMatchSnapshot(); + pipe.write.mockClear(); + + instance.put(KEYS.R); + expect(instance.getSkippedNum()).toBe(0); + expect(mockCallback).nthCalledWith(3, assertions[0], false); + expect(mockCallback).toHaveBeenCalledTimes(3); + expect(pipe.write.mock.calls.join('\n')).toMatchSnapshot(); + }); + + test('update 2 tests, then finish and return', () => { + const mockCallback = jest.fn(); + mockCallback.mockImplementationOnce(() => { + instance.updateWithResults({snapshot: {failure: true}}); + }); + mockCallback.mockImplementationOnce(() => { + instance.updateWithResults({snapshot: {failure: false}}); + }); + mockCallback.mockImplementationOnce(() => { + instance.updateWithResults({snapshot: {failure: true}}); + }); + mockCallback.mockImplementationOnce(() => { instance.updateWithResults({snapshot: {failure: false}}); - expect(pipe.write.mock.calls.join('\n')).toMatchSnapshot(); - expect(mockCallback.mock.calls[1]).toEqual(['second.js', false]); }); + mockCallback.mockImplementationOnce(() => { + instance.updateWithResults({snapshot: {failure: true}}); + }); + + const assertions = [ + {path: 'first.js', title: 'test one'}, + {path: 'first.js', title: 'test two'}, + ]; + + instance.run(assertions, mockCallback); + expect(mockCallback).nthCalledWith(1, assertions[0], false); + expect(mockCallback).toHaveBeenCalledTimes(1); + expect(pipe.write.mock.calls.join('\n')).toMatchSnapshot(); + pipe.write.mockClear(); + + instance.put(KEYS.U); + expect(mockCallback).nthCalledWith(2, assertions[0], true); + expect(mockCallback).nthCalledWith(3, assertions[1], false); + expect(mockCallback).toHaveBeenCalledTimes(3); + expect(pipe.write.mock.calls.join('\n')).toMatchSnapshot(); + pipe.write.mockClear(); + + instance.put(KEYS.U); + expect(mockCallback).nthCalledWith(4, assertions[1], true); + expect(mockCallback).toHaveBeenCalledTimes(4); + expect(pipe.write.mock.calls.join('\n')).toMatchSnapshot(); + pipe.write.mockClear(); - test('overlay handle progress UI', () => { - const mockCallback = jest.fn(); - instance.run(['first.js', 'second.js', 'third.js'], mockCallback); - pipe.write('TEST RESULTS CONTENTS'); + instance.put(KEYS.ENTER); + expect(instance.isActive()).toBe(false); + expect(mockCallback).nthCalledWith(5, null, false); + expect(mockCallback).toHaveBeenCalledTimes(5); + }); + + test('update 1 test, skip 1 test, then finish and restart', () => { + const mockCallback = jest.fn(); + mockCallback.mockImplementationOnce(() => { + instance.updateWithResults({snapshot: {failure: true}}); + }); + mockCallback.mockImplementationOnce(() => { instance.updateWithResults({snapshot: {failure: false}}); + }); + mockCallback.mockImplementationOnce(() => { + instance.updateWithResults({snapshot: {failure: true}}); + }); + mockCallback.mockImplementationOnce(() => { + instance.updateWithResults({snapshot: {failure: true}}); + }); + mockCallback.mockImplementationOnce(() => { instance.updateWithResults({snapshot: {failure: true}}); - expect(pipe.write.mock.calls.join('\n')).toMatchSnapshot(); }); - test('last test success, trigger end of interactive mode', () => { - const mockCallback = jest.fn(); - instance.abort = jest.fn(); - instance.run(['first.js'], mockCallback); - pipe.write('TEST RESULTS CONTENTS'); + const assertions = [ + {path: 'first.js', title: 'test one'}, + {path: 'first.js', title: 'test two'}, + ]; + + instance.run(assertions, mockCallback); + expect(mockCallback).nthCalledWith(1, assertions[0], false); + expect(mockCallback).toHaveBeenCalledTimes(1); + expect(pipe.write.mock.calls.join('\n')).toMatchSnapshot(); + pipe.write.mockClear(); + + instance.put(KEYS.U); + expect(mockCallback).nthCalledWith(2, assertions[0], true); + expect(mockCallback).nthCalledWith(3, assertions[1], false); + expect(mockCallback).toHaveBeenCalledTimes(3); + expect(pipe.write.mock.calls.join('\n')).toMatchSnapshot(); + pipe.write.mockClear(); + + instance.put(KEYS.S); + expect(mockCallback).toHaveBeenCalledTimes(3); + expect(pipe.write.mock.calls.join('\n')).toMatchSnapshot(); + pipe.write.mockClear(); + + instance.put(KEYS.R); + expect(instance.getSkippedNum()).toBe(0); + expect(mockCallback).nthCalledWith(4, assertions[1], false); + expect(mockCallback).toHaveBeenCalledTimes(4); + expect(pipe.write.mock.calls.join('\n')).toMatchSnapshot(); + }); + + test('skip 1 test, update 1 test, then finish and restart', () => { + const mockCallback = jest.fn(); + mockCallback.mockImplementationOnce(() => { + instance.updateWithResults({snapshot: {failure: true}}); + }); + mockCallback.mockImplementationOnce(() => { + instance.updateWithResults({snapshot: {failure: true}}); + }); + mockCallback.mockImplementationOnce(() => { instance.updateWithResults({snapshot: {failure: false}}); - expect(pipe.write.mock.calls.join('\n')).toMatchSnapshot(); - expect(instance.abort).toHaveBeenCalled(); }); + mockCallback.mockImplementationOnce(() => { + instance.updateWithResults({snapshot: {failure: true}}); + }); + mockCallback.mockImplementationOnce(() => { + instance.updateWithResults({snapshot: {failure: true}}); + }); + + const assertions = [ + {path: 'first.js', title: 'test one'}, + {path: 'first.js', title: 'test two'}, + ]; + + instance.run(assertions, mockCallback); + expect(mockCallback).nthCalledWith(1, assertions[0], false); + expect(mockCallback).toHaveBeenCalledTimes(1); + expect(pipe.write.mock.calls.join('\n')).toMatchSnapshot(); + pipe.write.mockClear(); + + instance.put(KEYS.S); + expect(mockCallback).nthCalledWith(2, assertions[1], false); + expect(mockCallback).toHaveBeenCalledTimes(2); + expect(pipe.write.mock.calls.join('\n')).toMatchSnapshot(); + pipe.write.mockClear(); + + instance.put(KEYS.U); + expect(mockCallback).nthCalledWith(3, assertions[1], true); + expect(mockCallback).toHaveBeenCalledTimes(3); + expect(pipe.write.mock.calls.join('\n')).toMatchSnapshot(); + pipe.write.mockClear(); + + instance.put(KEYS.R); + expect(instance.getSkippedNum()).toBe(0); + expect(mockCallback).nthCalledWith(4, assertions[0], false); + expect(mockCallback).toHaveBeenCalledTimes(4); + expect(pipe.write.mock.calls.join('\n')).toMatchSnapshot(); }); }); diff --git a/packages/jest-cli/src/__tests__/watch.test.js b/packages/jest-cli/src/__tests__/watch.test.js index 87d7d504b90b..21f993934d01 100644 --- a/packages/jest-cli/src/__tests__/watch.test.js +++ b/packages/jest-cli/src/__tests__/watch.test.js @@ -245,8 +245,26 @@ describe('Watch mode flows', () => { jest.unmock('jest-util'); const util = require('jest-util'); util.isInteractive = true; - util.getFailedSnapshotTests = jest.fn(() => ['test.js']); - results = {snapshot: {failure: true}}; + results = { + numFailedTests: 1, + snapshot: { + failure: true, + }, + testPath: 'test.js', + testResults: [ + { + snapshot: { + unmatched: true, + }, + testResults: [ + { + status: 'failed', + title: 'test a', + }, + ], + }, + ], + }; const ci_watch = require('../watch').default; ci_watch( diff --git a/packages/jest-cli/src/constants.js b/packages/jest-cli/src/constants.js index b29941b351ef..0804d3922780 100644 --- a/packages/jest-cli/src/constants.js +++ b/packages/jest-cli/src/constants.js @@ -10,7 +10,7 @@ const isWindows = process.platform === 'win32'; export const CLEAR = isWindows ? '\x1B[2J\x1B[0f' : '\x1B[2J\x1B[3J\x1B[H'; - +export const ARROW = ' \u203A '; export const KEYS = { A: '61', ARROW_DOWN: '1b5b42', @@ -29,6 +29,7 @@ export const KEYS = { P: '70', Q: '71', QUESTION_MARK: '3f', + R: '72', S: '73', T: '74', U: '75', diff --git a/packages/jest-cli/src/plugins/update_snapshots_interactive.js b/packages/jest-cli/src/plugins/update_snapshots_interactive.js index 0b1590063921..59f8d2312987 100644 --- a/packages/jest-cli/src/plugins/update_snapshots_interactive.js +++ b/packages/jest-cli/src/plugins/update_snapshots_interactive.js @@ -8,13 +8,14 @@ */ import type {JestHookSubscriber} from '../jest_hooks'; import type {GlobalConfig} from 'types/Config'; +import type {AggregatedResult, AssertionLocation} from 'types/TestResult'; import BaseWatchPlugin from '../base_watch_plugin'; -import {getFailedSnapshotTests} from 'jest-util'; import SnapshotInteractiveMode from '../snapshot_interactive_mode'; class UpdateSnapshotInteractivePlugin extends BaseWatchPlugin { _snapshotInteractiveMode: SnapshotInteractiveMode; _failedSnapshotTestPaths: Array<*>; + _failedSnapshotTestAssertions: Array; isInternal: true; constructor(options: { @@ -22,14 +23,40 @@ class UpdateSnapshotInteractivePlugin extends BaseWatchPlugin { stdout: stream$Writable | tty$WriteStream, }) { super(options); - this._failedSnapshotTestPaths = []; + this._failedSnapshotTestAssertions = []; this._snapshotInteractiveMode = new SnapshotInteractiveMode(this._stdout); this.isInternal = true; } + getFailedSnapshotTestAssertions( + testResults: AggregatedResult, + ): Array { + const failedTestPaths = []; + if (testResults.numFailedTests === 0 || !testResults.testResults) { + return failedTestPaths; + } + + testResults.testResults.forEach(testResult => { + if (testResult.snapshot && testResult.snapshot.unmatched) { + testResult.testResults.forEach(result => { + if (result.status === 'failed') { + failedTestPaths.push({ + path: testResult.testFilePath, + title: result.title, + }); + } + }); + } + }); + + return failedTestPaths; + } + apply(hooks: JestHookSubscriber) { hooks.testRunComplete(results => { - this._failedSnapshotTestPaths = getFailedSnapshotTests(results); + this._failedSnapshotTestAssertions = this.getFailedSnapshotTestAssertions( + results, + ); if (this._snapshotInteractiveMode.isActive()) { this._snapshotInteractiveMode.updateWithResults(results); } @@ -43,15 +70,16 @@ class UpdateSnapshotInteractivePlugin extends BaseWatchPlugin { } run(globalConfig: GlobalConfig, updateConfigAndRun: Function): Promise { - if (this._failedSnapshotTestPaths.length) { + if (this._failedSnapshotTestAssertions.length) { return new Promise(res => { this._snapshotInteractiveMode.run( - this._failedSnapshotTestPaths, - (path: string, shouldUpdateSnapshot: boolean) => { + this._failedSnapshotTestAssertions, + (assertion: ?AssertionLocation, shouldUpdateSnapshot: boolean) => { updateConfigAndRun({ mode: 'watch', - testNamePattern: '', - testPathPattern: path, + testNamePattern: assertion ? `^${assertion.title}$` : '', + testPathPattern: assertion ? assertion.path : '', + updateSnapshot: shouldUpdateSnapshot ? 'all' : 'none', }); if (!this._snapshotInteractiveMode.isActive()) { @@ -67,8 +95,8 @@ class UpdateSnapshotInteractivePlugin extends BaseWatchPlugin { getUsageInfo(globalConfig: GlobalConfig) { if ( - this._failedSnapshotTestPaths && - this._failedSnapshotTestPaths.length > 0 + this._failedSnapshotTestAssertions && + this._failedSnapshotTestAssertions.length > 0 ) { return { key: 'i'.codePointAt(0), diff --git a/packages/jest-cli/src/run_jest.js b/packages/jest-cli/src/run_jest.js index 8a3df9a0900d..f4bd499ddbff 100644 --- a/packages/jest-cli/src/run_jest.js +++ b/packages/jest-cli/src/run_jest.js @@ -13,6 +13,7 @@ import type {GlobalConfig} from 'types/Config'; import type {AggregatedResult} from 'types/TestResult'; import type TestWatcher from './test_watcher'; +import micromatch from 'micromatch'; import chalk from 'chalk'; import path from 'path'; import {Console, formatTestResults} from 'jest-util'; @@ -131,6 +132,8 @@ export default (async function runJest({ } } + let collectCoverageFrom = []; + const testRunData = await Promise.all( contexts.map(async context => { const matches = await getTestPaths( @@ -141,10 +144,44 @@ export default (async function runJest({ jestHooks, ); allTests = allTests.concat(matches.tests); + + if (matches.collectCoverageFrom) { + collectCoverageFrom = collectCoverageFrom.concat( + matches.collectCoverageFrom.filter(filename => { + if ( + globalConfig.collectCoverageFrom && + !micromatch( + [path.relative(globalConfig.rootDir, filename)], + globalConfig.collectCoverageFrom, + ).length + ) { + return false; + } + + if ( + globalConfig.coveragePathIgnorePatterns && + globalConfig.coveragePathIgnorePatterns.some(pattern => + filename.match(pattern), + ) + ) { + return false; + } + + return true; + }), + ); + } + return {context, matches}; }), ); + if (collectCoverageFrom.length) { + globalConfig = Object.freeze( + Object.assign({}, globalConfig, {collectCoverageFrom}), + ); + } + allTests = sequencer.sort(allTests); if (globalConfig.listTests) { @@ -202,7 +239,16 @@ export default (async function runJest({ setConfig(contexts, {cwd: process.cwd()}); if (globalConfig.globalSetup) { // $FlowFixMe - await require(globalConfig.globalSetup)(); + const globalSetup = require(globalConfig.globalSetup); + if (typeof globalSetup !== 'function') { + throw new TypeError( + `globalSetup file must export a function at ${ + globalConfig.globalSetup + }`, + ); + } + + await globalSetup(); } const results = await new TestScheduler( globalConfig, @@ -216,7 +262,16 @@ export default (async function runJest({ if (globalConfig.globalTeardown) { // $FlowFixMe - await require(globalConfig.globalTeardown)(); + const globalTeardown = require(globalConfig.globalTeardown); + if (typeof globalTeardown !== 'function') { + throw new TypeError( + `globalTeardown file must export a function at ${ + globalConfig.globalTeardown + }`, + ); + } + + await globalTeardown(); } return processResults(results, { isJSON: globalConfig.json, diff --git a/packages/jest-cli/src/search_source.js b/packages/jest-cli/src/search_source.js index 1b5c7e06039b..e574c8e5fc48 100644 --- a/packages/jest-cli/src/search_source.js +++ b/packages/jest-cli/src/search_source.js @@ -17,10 +17,12 @@ import micromatch from 'micromatch'; import DependencyResolver from 'jest-resolve-dependencies'; import testPathPatternToRegExp from './test_path_pattern_to_regexp'; import {escapePathForRegex} from 'jest-regex-util'; +import {replaceRootDirInPath} from 'jest-config'; type SearchResult = {| noSCM?: boolean, stats?: {[key: string]: number}, + collectCoverageFrom?: Array, tests: Array, total?: number, |}; @@ -140,23 +142,38 @@ export default class SearchSource { return this._getAllTestPaths(testPathPattern); } - findRelatedTests(allPaths: Set): SearchResult { + findRelatedTests( + allPaths: Set, + collectCoverage: boolean, + ): SearchResult { const dependencyResolver = new DependencyResolver( this._context.resolver, this._context.hasteFS, ); - return { - tests: toTests( - this._context, - dependencyResolver.resolveInverse( - allPaths, - this.isTestFilePath.bind(this), - { - skipNodeResolution: this._context.config.skipNodeResolution, - }, - ), + + const tests = toTests( + this._context, + dependencyResolver.resolveInverse( + allPaths, + this.isTestFilePath.bind(this), + { + skipNodeResolution: this._context.config.skipNodeResolution, + }, ), - }; + ); + let collectCoverageFrom; + + // If we are collecting coverage, also return collectCoverageFrom patterns + if (collectCoverage) { + collectCoverageFrom = Array.from(allPaths).map(filename => { + filename = replaceRootDirInPath(this._context.config.rootDir, filename); + return path.isAbsolute(filename) + ? path.relative(this._context.config.rootDir, filename) + : filename; + }); + } + + return {collectCoverageFrom, tests}; } findTestsByPaths(paths: Array): SearchResult { @@ -170,24 +187,27 @@ export default class SearchSource { }; } - findRelatedTestsFromPattern(paths: Array): SearchResult { + findRelatedTestsFromPattern( + paths: Array, + collectCoverage: boolean, + ): SearchResult { if (Array.isArray(paths) && paths.length) { const resolvedPaths = paths.map(p => path.resolve(process.cwd(), p)); - return this.findRelatedTests(new Set(resolvedPaths)); + return this.findRelatedTests(new Set(resolvedPaths), collectCoverage); } return {tests: []}; } async findTestRelatedToChangedFiles( changedFilesPromise: ChangedFilesPromise, + collectCoverage: boolean, ) { const {repos, changedFiles} = await changedFilesPromise; - // no SCM (git/hg/...) is found in any of the roots. const noSCM = Object.keys(repos).every(scm => repos[scm].size === 0); return noSCM ? {noSCM: true, tests: []} - : this.findRelatedTests(changedFiles); + : this.findRelatedTests(changedFiles, collectCoverage); } async getTestPaths( @@ -200,11 +220,16 @@ export default class SearchSource { throw new Error('This promise must be present when running with -o.'); } - return this.findTestRelatedToChangedFiles(changedFilesPromise); + return this.findTestRelatedToChangedFiles( + changedFilesPromise, + globalConfig.collectCoverage, + ); } else if (globalConfig.runTestsByPath && paths && paths.length) { return Promise.resolve(this.findTestsByPaths(paths)); } else if (globalConfig.findRelatedTests && paths && paths.length) { - return Promise.resolve(this.findRelatedTestsFromPattern(paths)); + return Promise.resolve( + this.findRelatedTestsFromPattern(paths, globalConfig.collectCoverage), + ); } else if (globalConfig.testPathPattern != null) { return Promise.resolve( this.findMatchingTests(globalConfig.testPathPattern), diff --git a/packages/jest-cli/src/snapshot_interactive_mode.js b/packages/jest-cli/src/snapshot_interactive_mode.js index fdd6f62121fc..a78336aa6d37 100644 --- a/packages/jest-cli/src/snapshot_interactive_mode.js +++ b/packages/jest-cli/src/snapshot_interactive_mode.js @@ -8,60 +8,78 @@ * @flow */ -import type {AggregatedResult} from 'types/TestResult'; +import type {AggregatedResult, AssertionLocation} from 'types/TestResult'; const chalk = require('chalk'); const ansiEscapes = require('ansi-escapes'); const {pluralize} = require('./reporters/utils'); -const {KEYS} = require('./constants'); +const {KEYS, ARROW} = require('./constants'); export default class SnapshotInteractiveMode { _pipe: stream$Writable | tty$WriteStream; _isActive: boolean; - _updateTestRunnerConfig: (path: string, shouldUpdateSnapshot: boolean) => *; - _testFilePaths: Array; + _updateTestRunnerConfig: ( + assertion: ?AssertionLocation, + shouldUpdateSnapshot: boolean, + ) => *; + _testAssertions: Array; _countPaths: number; + _skippedNum: number; constructor(pipe: stream$Writable | tty$WriteStream) { this._pipe = pipe; this._isActive = false; + this._skippedNum = 0; } isActive() { return this._isActive; } - _drawUIOverlay() { + getSkippedNum() { + return this._skippedNum; + } + + _clearTestSummary() { this._pipe.write(ansiEscapes.cursorUp(6)); this._pipe.write(ansiEscapes.eraseDown); + } - const numFailed = this._testFilePaths.length; - const numPass = this._countPaths - this._testFilePaths.length; + _drawUIProgress() { + this._clearTestSummary(); + const numPass = this._countPaths - this._testAssertions.length; + const numRemaining = this._countPaths - numPass - this._skippedNum; - let stats = chalk.bold.red(pluralize('suite', numFailed) + ' failed'); + let stats = chalk.bold.dim( + pluralize('snapshot', numRemaining) + ' remaining', + ); if (numPass) { - stats += ', ' + chalk.bold.green(pluralize('suite', numPass) + ' passed'); + stats += + ', ' + chalk.bold.green(pluralize('snapshot', numPass) + ' updated'); + } + if (this._skippedNum) { + stats += + ', ' + + chalk.bold.yellow(pluralize('snapshot', this._skippedNum) + ' skipped'); } const messages = [ '\n' + chalk.bold('Interactive Snapshot Progress'), - ' \u203A ' + stats, + ARROW + stats, '\n' + chalk.bold('Watch Usage'), - chalk.dim(' \u203A Press ') + + chalk.dim(ARROW + 'Press ') + 'u' + chalk.dim(' to update failing snapshots for this test.'), - this._testFilePaths.length > 1 - ? chalk.dim(' \u203A Press ') + - 's' + - chalk.dim(' to skip the current test suite.') - : '', + chalk.dim(ARROW + 'Press ') + + 's' + + chalk.dim(' to skip the current test.'), - chalk.dim(' \u203A Press ') + + chalk.dim(ARROW + 'Press ') + 'q' + - chalk.dim(' to quit Interactive Snapshot Update Mode.'), + chalk.dim(' to quit Interactive Snapshot Mode.'), - chalk.dim(' \u203A Press ') + + chalk.dim(ARROW + 'Press ') + 'Enter' + chalk.dim(' to trigger a test run.'), ]; @@ -69,12 +87,89 @@ export default class SnapshotInteractiveMode { this._pipe.write(messages.filter(Boolean).join('\n') + '\n'); } + _drawUIDoneWithSkipped() { + this._pipe.write(ansiEscapes.clearScreen); + const numPass = this._countPaths - this._testAssertions.length; + + let stats = chalk.bold.dim( + pluralize('snapshot', this._countPaths) + ' reviewed', + ); + if (numPass) { + stats += + ', ' + chalk.bold.green(pluralize('snapshot', numPass) + ' updated'); + } + if (this._skippedNum) { + stats += + ', ' + + chalk.bold.yellow(pluralize('snapshot', this._skippedNum) + ' skipped'); + } + const messages = [ + '\n' + chalk.bold('Interactive Snapshot Result'), + ARROW + stats, + '\n' + chalk.bold('Watch Usage'), + + chalk.dim(ARROW + 'Press ') + + 'r' + + chalk.dim(' to restart Interactive Snapshot Mode.'), + + chalk.dim(ARROW + 'Press ') + + 'q' + + chalk.dim(' to quit Interactive Snapshot Mode.'), + ]; + + this._pipe.write(messages.filter(Boolean).join('\n') + '\n'); + } + + _drawUIDone() { + this._pipe.write(ansiEscapes.clearScreen); + const numPass = this._countPaths - this._testAssertions.length; + + let stats = chalk.bold.dim( + pluralize('snapshot', this._countPaths) + ' reviewed', + ); + if (numPass) { + stats += + ', ' + chalk.bold.green(pluralize('snapshot', numPass) + ' updated'); + } + const messages = [ + '\n' + chalk.bold('Interactive Snapshot Result'), + ARROW + stats, + '\n' + chalk.bold('Watch Usage'), + + chalk.dim(ARROW + 'Press ') + + 'Enter' + + chalk.dim(' to return to watch mode.'), + ]; + + this._pipe.write(messages.filter(Boolean).join('\n') + '\n'); + } + + _drawUIOverlay() { + if (this._testAssertions.length === 0) { + return this._drawUIDone(); + } + + if (this._testAssertions.length - this._skippedNum === 0) { + return this._drawUIDoneWithSkipped(); + } + + return this._drawUIProgress(); + } + put(key: string) { switch (key) { case KEYS.S: - const testFilePath = this._testFilePaths.shift(); - this._testFilePaths.push(testFilePath); - this._run(false); + if (this._skippedNum === this._testAssertions.length) break; + this._skippedNum += 1; + + // move skipped test to the end + this._testAssertions.push(this._testAssertions.shift()); + if (this._testAssertions.length - this._skippedNum > 0) { + this._run(false); + } else { + this._drawUIDoneWithSkipped(); + } + break; case KEYS.U: this._run(true); @@ -83,8 +178,15 @@ export default class SnapshotInteractiveMode { case KEYS.ESCAPE: this.abort(); break; + case KEYS.R: + this.restart(); + break; case KEYS.ENTER: - this._run(false); + if (this._testAssertions.length === 0) { + this.abort(); + } else { + this._run(false); + } break; default: break; @@ -93,7 +195,14 @@ export default class SnapshotInteractiveMode { abort() { this._isActive = false; - this._updateTestRunnerConfig('', false); + this._skippedNum = 0; + this._updateTestRunnerConfig(null, false); + } + + restart() { + this._skippedNum = 0; + this._countPaths = this._testAssertions.length; + this._run(false); } updateWithResults(results: AggregatedResult) { @@ -103,29 +212,34 @@ export default class SnapshotInteractiveMode { return; } - this._testFilePaths.shift(); - if (this._testFilePaths.length === 0) { - this.abort(); + this._testAssertions.shift(); + if (this._testAssertions.length - this._skippedNum === 0) { + this._drawUIOverlay(); return; } + + // Go to the next test this._run(false); } _run(shouldUpdateSnapshot: boolean) { - const testFilePath = this._testFilePaths[0]; - this._updateTestRunnerConfig(testFilePath, shouldUpdateSnapshot); + const testAssertion = this._testAssertions[0]; + this._updateTestRunnerConfig(testAssertion, shouldUpdateSnapshot); } run( - failedSnapshotTestPaths: Array, - onConfigChange: (path: string, shouldUpdateSnapshot: boolean) => *, + failedSnapshotTestAssertions: Array, + onConfigChange: ( + assertion: ?AssertionLocation, + shouldUpdateSnapshot: boolean, + ) => *, ) { - if (!failedSnapshotTestPaths.length) { + if (!failedSnapshotTestAssertions.length) { return; } - this._testFilePaths = [].concat(failedSnapshotTestPaths); - this._countPaths = this._testFilePaths.length; + this._testAssertions = [].concat(failedSnapshotTestAssertions); + this._countPaths = this._testAssertions.length; this._updateTestRunnerConfig = onConfigChange; this._isActive = true; this._run(false); diff --git a/packages/jest-config/src/__tests__/normalize.test.js b/packages/jest-config/src/__tests__/normalize.test.js index 0eeb2fed1791..94003c410899 100644 --- a/packages/jest-config/src/__tests__/normalize.test.js +++ b/packages/jest-config/src/__tests__/normalize.test.js @@ -211,6 +211,31 @@ describe('collectCoverageFrom', () => { }); }); +describe('findRelatedTests', () => { + it('it generates --coverageCoverageFrom patterns when needed', () => { + const sourceFile = 'file1.js'; + + const {options} = normalize( + { + collectCoverage: true, + rootDir: '/root/path/foo/', + }, + { + _: [ + `/root/path/${sourceFile}`, + sourceFile, + `/bar/${sourceFile}`, + ], + findRelatedTests: true, + }, + ); + + const expected = [`../${sourceFile}`, `${sourceFile}`, `bar/${sourceFile}`]; + + expect(options.collectCoverageFrom).toEqual(expected); + }); +}); + function testPathArray(key) { it('normalizes all paths relative to rootDir', () => { const {options} = normalize( diff --git a/packages/jest-config/src/index.js b/packages/jest-config/src/index.js index bd466e93a255..88afaedfb6c4 100644 --- a/packages/jest-config/src/index.js +++ b/packages/jest-config/src/index.js @@ -24,6 +24,7 @@ import readConfigFileAndSetRootDir from './read_config_file_and_set_root_dir'; export {getTestEnvironment, isJSONString} from './utils'; export {default as normalize} from './normalize'; export {default as deprecationEntries} from './deprecated'; +export {replaceRootDirInPath} from './utils'; export function readConfig( argv: Argv, @@ -68,7 +69,7 @@ export function readConfig( config.rootDir = config.rootDir || packageRootOrConfig; rawOptions = config; // A string passed to `--config`, which is either a direct path to the config - // or a path to directory containing `package.json` or `jest.conf.js` + // or a path to directory containing `package.json` or `jest.config.js` } else if (!skipArgvConfigOption && typeof argv.config == 'string') { configPath = resolveConfigPath(argv.config, process.cwd()); rawOptions = readConfigFileAndSetRootDir(configPath); diff --git a/packages/jest-config/src/normalize.js b/packages/jest-config/src/normalize.js index 7e0827c67fc2..b53185643f3f 100644 --- a/packages/jest-config/src/normalize.js +++ b/packages/jest-config/src/normalize.js @@ -23,7 +23,7 @@ import {replacePathSepForRegex} from 'jest-regex-util'; import { BULLET, DOCUMENTATION_NOTE, - _replaceRootDirInPath, + replaceRootDirInPath, _replaceRootDirTags, escapeGlobCharacters, getTestEnvironment, @@ -66,7 +66,7 @@ const setupPreset = ( optionsPreset: string, ): InitialOptions => { let preset; - const presetPath = _replaceRootDirInPath(options.rootDir, optionsPreset); + const presetPath = replaceRootDirInPath(options.rootDir, optionsPreset); const presetModule = Resolver.findNodeModule( presetPath.endsWith(JSON_EXTENSION) ? presetPath @@ -146,7 +146,7 @@ const normalizeCollectCoverageOnlyFrom = ( return collectCoverageOnlyFrom.reduce((map, filePath) => { filePath = path.resolve( options.rootDir, - _replaceRootDirInPath(options.rootDir, filePath), + replaceRootDirInPath(options.rootDir, filePath), ); map[filePath] = true; return map; @@ -271,7 +271,7 @@ const normalizeReporters = (options: InitialOptions, basedir) => { [reporterConfig, {}] : reporterConfig; - const reporterPath = _replaceRootDirInPath( + const reporterPath = replaceRootDirInPath( options.rootDir, normalizedReporterConfig[0], ); @@ -391,7 +391,7 @@ export default function normalize(options: InitialOptions, argv: Argv) { options[key].map(filePath => path.resolve( options.rootDir, - _replaceRootDirInPath(options.rootDir, filePath), + replaceRootDirInPath(options.rootDir, filePath), ), ); break; @@ -404,7 +404,7 @@ export default function normalize(options: InitialOptions, argv: Argv) { options[key] && path.resolve( options.rootDir, - _replaceRootDirInPath(options.rootDir, options[key]), + replaceRootDirInPath(options.rootDir, options[key]), ); break; case 'globalSetup': @@ -449,7 +449,7 @@ export default function normalize(options: InitialOptions, argv: Argv) { value.hasteImplModulePath = resolve( options.rootDir, 'haste.hasteImplModulePath', - _replaceRootDirInPath(options.rootDir, value.hasteImplModulePath), + replaceRootDirInPath(options.rootDir, value.hasteImplModulePath), ); } break; @@ -599,6 +599,21 @@ export default function normalize(options: InitialOptions, argv: Argv) { ); } + // If collectCoverage is enabled while using --findRelatedTests we need to + // avoid having false negatives in the generated coverage report. + // The following: `--findRelatedTests '/rootDir/file1.js' --coverage` + // Is transformed to: `--findRelatedTests '/rootDir/file1.js' --coverage --collectCoverageFrom 'file1.js'` + // where arguments to `--collectCoverageFrom` should be globs (or relative + // paths to the rootDir) + if (newOptions.collectCoverage && argv.findRelatedTests) { + newOptions.collectCoverageFrom = argv._.map(filename => { + filename = replaceRootDirInPath(options.rootDir, filename); + return path.isAbsolute(filename) + ? path.relative(options.rootDir, filename) + : filename; + }); + } + return { hasDeprecationWarnings, options: newOptions, diff --git a/packages/jest-config/src/utils.js b/packages/jest-config/src/utils.js index 8831b25c0233..c85998edbfe4 100644 --- a/packages/jest-config/src/utils.js +++ b/packages/jest-config/src/utils.js @@ -30,7 +30,7 @@ const createValidationError = (message: string) => { export const resolve = (rootDir: string, key: string, filePath: Path) => { const module = Resolver.findNodeModule( - _replaceRootDirInPath(rootDir, filePath), + replaceRootDirInPath(rootDir, filePath), { basedir: rootDir, }, @@ -52,7 +52,7 @@ export const escapeGlobCharacters = (path: Path): Glob => { return path.replace(/([()*{}\[\]!?\\])/g, '\\$1'); }; -export const _replaceRootDirInPath = ( +export const replaceRootDirInPath = ( rootDir: string, filePath: Path, ): string => { @@ -91,7 +91,7 @@ export const _replaceRootDirTags = (rootDir: string, config: any) => { } return _replaceRootDirInObject(rootDir, config); case 'string': - return _replaceRootDirInPath(rootDir, config); + return replaceRootDirInPath(rootDir, config); } return config; }; @@ -105,7 +105,7 @@ export const _replaceRootDirTags = (rootDir: string, config: any) => { * 1. looks for relative to Jest. */ export const getTestEnvironment = (config: Object) => { - const env = _replaceRootDirInPath(config.rootDir, config.testEnvironment); + const env = replaceRootDirInPath(config.rootDir, config.testEnvironment); let module = Resolver.findNodeModule(`jest-environment-${env}`, { basedir: config.rootDir, }); diff --git a/packages/jest-haste-map/src/__tests__/index.test.js b/packages/jest-haste-map/src/__tests__/index.test.js index 546bb8c06d8d..5920d0ae7905 100644 --- a/packages/jest-haste-map/src/__tests__/index.test.js +++ b/packages/jest-haste-map/src/__tests__/index.test.js @@ -8,6 +8,15 @@ 'use strict'; +const crypto = require('crypto'); + +function mockHashContents(contents) { + return crypto + .createHash('sha1') + .update(contents) + .digest('hex'); +} + jest.mock('child_process', () => ({ // If this does not throw, we'll use the (mocked) watchman crawler execSync() {}, @@ -28,14 +37,17 @@ jest.mock('jest-worker', () => { jest.mock('../crawlers/node'); jest.mock('../crawlers/watchman', () => jest.fn(options => { - const {data, ignore, roots} = options; + const {data, ignore, roots, computeSha1} = options; + const list = mockChangedFiles || mockFs; + data.clocks = mockClocks; - const list = mockChangedFiles || mockFs; for (const file in list) { if (new RegExp(roots.join('|')).test(file) && !ignore(file)) { if (list[file]) { - data.files[file] = ['', 32, 0, []]; + const hash = computeSha1 ? mockHashContents(list[file]) : null; + + data.files[file] = ['', 32, 0, [], hash]; } else { delete data.files[file]; } @@ -265,15 +277,27 @@ describe('HasteMap', () => { expect(data.clocks).toEqual(mockClocks); expect(data.files).toEqual({ - '/fruits/__mocks__/Pear.js': ['', 32, 1, ['Melon']], - '/fruits/banana.js': ['Banana', 32, 1, ['Strawberry']], + '/fruits/__mocks__/Pear.js': ['', 32, 1, ['Melon'], null], + '/fruits/banana.js': ['Banana', 32, 1, ['Strawberry'], null], // node modules - '/fruits/node_modules/fbjs/lib/flatMap.js': ['flatMap', 32, 1, []], - '/fruits/node_modules/react/react.js': ['React', 32, 1, ['Component']], - - '/fruits/pear.js': ['Pear', 32, 1, ['Banana', 'Strawberry']], - '/fruits/strawberry.js': ['Strawberry', 32, 1, []], - '/vegetables/melon.js': ['Melon', 32, 1, []], + '/fruits/node_modules/fbjs/lib/flatMap.js': [ + 'flatMap', + 32, + 1, + [], + null, + ], + '/fruits/node_modules/react/react.js': [ + 'React', + 32, + 1, + ['Component'], + null, + ], + + '/fruits/pear.js': ['Pear', 32, 1, ['Banana', 'Strawberry'], null], + '/fruits/strawberry.js': ['Strawberry', 32, 1, [], null], + '/vegetables/melon.js': ['Melon', 32, 1, [], null], }); expect(data.map).toEqual({ @@ -301,12 +325,85 @@ describe('HasteMap', () => { Pear: '/fruits/__mocks__/Pear.js', }); - // The cache file must exactly mirror the data structure returned - // from a build. + // The cache file must exactly mirror the data structure returned from a + // build. expect(hasteMap.read()).toEqual(data); }); }); + describe('builds a haste map on a fresh cache with SHA-1s', () => { + [false, true].forEach(useWatchman => { + it('uses watchman: ' + useWatchman, async () => { + const node = require('../crawlers/node'); + + node.mockImplementation(options => { + const {data} = options; + + // The node crawler returns "null" for the SHA-1. + data.files = object({ + '/fruits/__mocks__/Pear.js': ['', 32, 0, ['Melon'], null], + '/fruits/banana.js': ['Banana', 32, 0, ['Strawberry'], null], + '/fruits/pear.js': ['Pear', 32, 0, ['Banana', 'Strawberry'], null], + '/fruits/strawberry.js': ['Strawberry', 32, 0, [], null], + '/vegetables/melon.js': ['Melon', 32, 0, [], null], + }); + + return Promise.resolve(data); + }); + + const hasteMap = new HasteMap( + Object.assign({}, defaultConfig, { + computeSha1: true, + maxWorkers: 1, + useWatchman, + }), + ); + + const data = (await hasteMap.build()).__hasteMapForTest; + + expect(data.files).toEqual({ + '/fruits/__mocks__/Pear.js': [ + '', + 32, + 1, + ['Melon'], + 'a315b7804be2b124b77c1f107205397f45226964', + ], + '/fruits/banana.js': [ + 'Banana', + 32, + 1, + ['Strawberry'], + 'f24c6984cce6f032f6d55d771d04ab8dbbe63c8c', + ], + '/fruits/pear.js': [ + 'Pear', + 32, + 1, + ['Banana', 'Strawberry'], + '211a8ff1e67007b204727d26943c15cf9fd00031', + ], + '/fruits/strawberry.js': [ + 'Strawberry', + 32, + 1, + [], + 'd55d545ad7d997cb2aa10fb412e0cc287d4fbfb3', + ], + '/vegetables/melon.js': [ + 'Melon', + 32, + 1, + [], + '45c5d30e29313187829dfd5a16db81c3143fbcc7', + ], + }); + + expect(hasteMap.read()).toEqual(data); + }); + }); + }); + it('does not crawl native files even if requested to do so', async () => { mockFs['/video/i-require-a-video.js'] = [ '/**', @@ -351,6 +448,7 @@ describe('HasteMap', () => { 32, 0, [], + null, ]); expect(data.map.fbjs).not.toBeDefined(); @@ -452,9 +550,16 @@ describe('HasteMap', () => { 32, 1, ['Blackberry'], + null, + ], + '/fruits/strawberry.ios.js': [ + 'Strawberry', + 32, + 1, + ['Raspberry'], + null, ], - '/fruits/strawberry.ios.js': ['Strawberry', 32, 1, ['Raspberry']], - '/fruits/strawberry.js': ['Strawberry', 32, 1, ['Banana']], + '/fruits/strawberry.js': ['Strawberry', 32, 1, ['Banana'], null], }); expect(data.map).toEqual({ @@ -539,7 +644,7 @@ describe('HasteMap', () => { expect(data.clocks).toEqual(mockClocks); const files = object(initialData.files); - files['/fruits/banana.js'] = ['Kiwi', 32, 1, ['Raspberry']]; + files['/fruits/banana.js'] = ['Kiwi', 32, 1, ['Raspberry'], null]; expect(data.files).toEqual(files); @@ -800,11 +905,41 @@ describe('HasteMap', () => { expect(mockWorker.mock.calls.length).toBe(5); expect(mockWorker.mock.calls).toEqual([ - [{filePath: '/fruits/__mocks__/Pear.js'}], - [{filePath: '/fruits/banana.js'}], - [{filePath: '/fruits/pear.js'}], - [{filePath: '/fruits/strawberry.js'}], - [{filePath: '/vegetables/melon.js'}], + [ + { + computeSha1: false, + filePath: '/fruits/__mocks__/Pear.js', + hasteImplModulePath: undefined, + }, + ], + [ + { + computeSha1: false, + filePath: '/fruits/banana.js', + hasteImplModulePath: undefined, + }, + ], + [ + { + computeSha1: false, + filePath: '/fruits/pear.js', + hasteImplModulePath: undefined, + }, + ], + [ + { + computeSha1: false, + filePath: '/fruits/strawberry.js', + hasteImplModulePath: undefined, + }, + ], + [ + { + computeSha1: false, + filePath: '/vegetables/melon.js', + hasteImplModulePath: undefined, + }, + ], ]); expect(mockEnd).toBeCalled(); @@ -821,7 +956,7 @@ describe('HasteMap', () => { node.mockImplementation(options => { const {data} = options; data.files = object({ - '/fruits/banana.js': ['', 32, 0, []], + '/fruits/banana.js': ['', 32, 0, [], null], }); return Promise.resolve(data); }); @@ -833,7 +968,7 @@ describe('HasteMap', () => { expect(node).toBeCalled(); expect(data.files).toEqual({ - '/fruits/banana.js': ['Banana', 32, 1, ['Strawberry']], + '/fruits/banana.js': ['Banana', 32, 1, ['Strawberry'], null], }); expect(console.warn.mock.calls[0][0]).toMatchSnapshot(); @@ -850,7 +985,7 @@ describe('HasteMap', () => { node.mockImplementation(options => { const {data} = options; data.files = object({ - '/fruits/banana.js': ['', 32, 0, []], + '/fruits/banana.js': ['', 32, 0, [], null], }); return Promise.resolve(data); }); @@ -862,7 +997,7 @@ describe('HasteMap', () => { expect(node).toBeCalled(); expect(data.files).toEqual({ - '/fruits/banana.js': ['Banana', 32, 1, ['Strawberry']], + '/fruits/banana.js': ['Banana', 32, 1, ['Strawberry'], null], }); }); }); @@ -1022,14 +1157,17 @@ describe('HasteMap', () => { }, { mockFs: { - '/fruits/Orange.android.js': `/** - * @providesModule Orange - */ -`, - '/fruits/Orange.ios.js': `/** -* @providesModule Orange -*/ -`, + '/fruits/Orange.android.js': [ + '/**', + ' * @providesModule Orange', + ' */', + ].join('\n'), + + '/fruits/Orange.ios.js': [ + '/**', + ' * @providesModule Orange', + ' */', + ].join('\n'), }, }, ); diff --git a/packages/jest-haste-map/src/constants.js b/packages/jest-haste-map/src/constants.js index 3acca06d4ddd..38be492df15b 100644 --- a/packages/jest-haste-map/src/constants.js +++ b/packages/jest-haste-map/src/constants.js @@ -22,6 +22,7 @@ export default { MTIME: 1, VISITED: 2, DEPENDENCIES: 3, + SHA1: 4, /* module map attributes */ PATH: 0, diff --git a/packages/jest-haste-map/src/crawlers/__tests__/node.test.js b/packages/jest-haste-map/src/crawlers/__tests__/node.test.js index e61ad415bf51..c7af076c4ba3 100644 --- a/packages/jest-haste-map/src/crawlers/__tests__/node.test.js +++ b/packages/jest-haste-map/src/crawlers/__tests__/node.test.js @@ -125,9 +125,9 @@ describe('node crawler', () => { expect(data.files).not.toBe(null); expect(data.files).toEqual({ - '/fruits/strawberry.js': ['', 32, 0, []], - '/fruits/tomato.js': ['', 33, 0, []], - '/vegetables/melon.json': ['', 34, 0, []], + '/fruits/strawberry.js': ['', 32, 0, [], null], + '/fruits/tomato.js': ['', 33, 0, [], null], + '/vegetables/melon.json': ['', 34, 0, [], null], }); }); @@ -142,8 +142,8 @@ describe('node crawler', () => { const files = Object.create(null); // In this test sample, strawberry is changed and tomato is unchanged - const tomato = ['', 33, 1, []]; - files['/fruits/strawberry.js'] = ['', 30, 1, []]; + const tomato = ['', 33, 1, [], null]; + files['/fruits/strawberry.js'] = ['', 30, 1, [], null]; files['/fruits/tomato.js'] = tomato; return nodeCrawl({ @@ -153,7 +153,7 @@ describe('node crawler', () => { roots: ['/fruits'], }).then(data => { expect(data.files).toEqual({ - '/fruits/strawberry.js': ['', 32, 0, []], + '/fruits/strawberry.js': ['', 32, 0, [], null], '/fruits/tomato.js': tomato, }); @@ -175,8 +175,8 @@ describe('node crawler', () => { roots: ['/fruits'], }).then(data => { expect(data.files).toEqual({ - '/fruits/directory/strawberry.js': ['', 33, 0, []], - '/fruits/tomato.js': ['', 32, 0, []], + '/fruits/directory/strawberry.js': ['', 33, 0, [], null], + '/fruits/tomato.js': ['', 32, 0, [], null], }); }); }); @@ -195,8 +195,8 @@ describe('node crawler', () => { roots: ['/fruits'], }).then(data => { expect(data.files).toEqual({ - '/fruits/directory/strawberry.js': ['', 33, 0, []], - '/fruits/tomato.js': ['', 32, 0, []], + '/fruits/directory/strawberry.js': ['', 33, 0, [], null], + '/fruits/tomato.js': ['', 32, 0, [], null], }); }); }); diff --git a/packages/jest-haste-map/src/crawlers/__tests__/watchman.test.js b/packages/jest-haste-map/src/crawlers/__tests__/watchman.test.js index 9b52c70e21d9..57d5eb138254 100644 --- a/packages/jest-haste-map/src/crawlers/__tests__/watchman.test.js +++ b/packages/jest-haste-map/src/crawlers/__tests__/watchman.test.js @@ -15,7 +15,8 @@ jest.mock('fb-watchman', () => { const Client = jest.fn(); Client.prototype.command = jest.fn((args, callback) => setImmediate(() => { - const response = mockResponse[args[0]][normalizePathSep(args[1])]; + const path = args[1] ? normalizePathSep(args[1]) : undefined; + const response = mockResponse[args[0]][path]; callback(null, response.next ? response.next().value : response); }), ); @@ -59,6 +60,11 @@ describe('watchman watch', () => { watchman = require('fb-watchman'); mockResponse = { + 'list-capabilities': { + [undefined]: { + capabilities: ['field-content.sha1hex'], + }, + }, query: { [ROOT_MOCK]: { clock: 'c:fake-clock:1', @@ -92,9 +98,9 @@ describe('watchman watch', () => { }; mockFiles = Object.assign(Object.create(null), { - [MELON]: ['', 33, 0, []], - [STRAWBERRY]: ['', 30, 0, []], - [TOMATO]: ['', 31, 0, []], + [MELON]: ['', 33, 0, [], null], + [STRAWBERRY]: ['', 30, 0, [], null], + [TOMATO]: ['', 31, 0, [], null], }); }); @@ -149,6 +155,11 @@ describe('watchman watch', () => { test('updates the file object when the clock is given', () => { mockResponse = { + 'list-capabilities': { + [undefined]: { + capabilities: ['field-content.sha1hex'], + }, + }, query: { [ROOT_MOCK]: { clock: 'c:fake-clock:2', @@ -192,15 +203,20 @@ describe('watchman watch', () => { }); expect(data.files).toEqual({ - [KIWI]: ['', 42, 0, []], - [MELON]: ['', 33, 0, []], - [STRAWBERRY]: ['', 30, 0, []], + [KIWI]: ['', 42, 0, [], null], + [MELON]: ['', 33, 0, [], null], + [STRAWBERRY]: ['', 30, 0, [], null], }); }); }); test('resets the file object when watchman is restarted', () => { mockResponse = { + 'list-capabilities': { + [undefined]: { + capabilities: ['field-content.sha1hex'], + }, + }, query: { [ROOT_MOCK]: { clock: 'c:fake-clock:3', @@ -228,7 +244,7 @@ describe('watchman watch', () => { 'watch-project': WATCH_PROJECT_MOCK, }; - const mockMetadata = ['Banana', 41, 1, ['Raspberry']]; + const mockMetadata = ['Banana', 41, 1, ['Raspberry'], null]; mockFiles[BANANA] = mockMetadata; const clocks = Object.assign(Object.create(null), { @@ -254,7 +270,7 @@ describe('watchman watch', () => { // /fruits/strawberry.js was removed from the file list. expect(data.files).toEqual({ [BANANA]: mockMetadata, - [KIWI]: ['', 42, 0, []], + [KIWI]: ['', 42, 0, [], null], [TOMATO]: mockFiles[TOMATO], }); @@ -268,6 +284,11 @@ describe('watchman watch', () => { test('properly resets the file map when only one watcher is reset', () => { mockResponse = { + 'list-capabilities': { + [undefined]: { + capabilities: ['field-content.sha1hex'], + }, + }, query: { [FRUITS]: { clock: 'c:fake-clock:3', @@ -324,14 +345,19 @@ describe('watchman watch', () => { }); expect(data.files).toEqual({ - [KIWI]: ['', 42, 0, []], - [MELON]: ['', 33, 0, []], + [KIWI]: ['', 42, 0, [], null], + [MELON]: ['', 33, 0, [], null], }); }); }); test('does not add directory filters to query when watching a ROOT', () => { mockResponse = { + 'list-capabilities': { + [undefined]: { + capabilities: ['field-content.sha1hex'], + }, + }, query: { [ROOT_MOCK]: { clock: 'c:fake-clock:1', @@ -398,4 +424,82 @@ describe('watchman watch', () => { expect(client.end).toBeCalled(); }); }); + + test('SHA-1 requested and available', async () => { + mockResponse = { + 'list-capabilities': { + [undefined]: { + capabilities: ['field-content.sha1hex'], + }, + }, + query: { + [ROOT_MOCK]: { + clock: 'c:fake-clock:1', + files: [], + is_fresh_instance: false, + version: '4.5.0', + }, + }, + 'watch-project': { + [ROOT_MOCK]: { + watch: forcePOSIXPaths(ROOT_MOCK), + }, + }, + }; + + await watchmanCrawl({ + computeSha1: true, + data: { + clocks: Object.create(null), + files: Object.create(null), + }, + extensions: ['js', 'json'], + roots: [ROOT_MOCK], + }); + + const client = watchman.Client.mock.instances[0]; + const calls = client.command.mock.calls; + + expect(calls[0][0]).toEqual(['list-capabilities']); + expect(calls[2][0][2].fields).toContain('content.sha1hex'); + }); + + test('SHA-1 requested and NOT available', async () => { + mockResponse = { + 'list-capabilities': { + [undefined]: { + capabilities: [], + }, + }, + query: { + [ROOT_MOCK]: { + clock: 'c:fake-clock:1', + files: [], + is_fresh_instance: false, + version: '4.5.0', + }, + }, + 'watch-project': { + [ROOT_MOCK]: { + watch: forcePOSIXPaths(ROOT_MOCK), + }, + }, + }; + + await watchmanCrawl({ + computeSha1: true, + data: { + clocks: Object.create(null), + files: Object.create(null), + }, + extensions: ['js', 'json'], + roots: [ROOT_MOCK], + }); + + const client = watchman.Client.mock.instances[0]; + const calls = client.command.mock.calls; + + expect(calls[0][0]).toEqual(['list-capabilities']); + expect(calls[2][0][2].fields).not.toContain('content.sha1hex'); + }); }); diff --git a/packages/jest-haste-map/src/crawlers/node.js b/packages/jest-haste-map/src/crawlers/node.js index 1b7d20e5bd9c..17ce3452e757 100644 --- a/packages/jest-haste-map/src/crawlers/node.js +++ b/packages/jest-haste-map/src/crawlers/node.js @@ -136,8 +136,8 @@ module.exports = function nodeCrawl( if (existingFile && existingFile[H.MTIME] === mtime) { files[name] = existingFile; } else { - // See ../constants.js - files[name] = ['', mtime, 0, []]; + // See ../constants.js; SHA-1 will always be null and fulfilled later. + files[name] = ['', mtime, 0, [], null]; } }); data.files = files; diff --git a/packages/jest-haste-map/src/crawlers/watchman.js b/packages/jest-haste-map/src/crawlers/watchman.js index ed14bf213774..7a706689e089 100644 --- a/packages/jest-haste-map/src/crawlers/watchman.js +++ b/packages/jest-haste-map/src/crawlers/watchman.js @@ -28,6 +28,7 @@ function WatchmanError(error: Error): Error { module.exports = async function watchmanCrawl( options: CrawlerOptions, ): Promise { + const fields = ['name', 'exists', 'mtime_ms']; const {data, extensions, ignore, roots} = options; const defaultWatchExpression = [ 'allof', @@ -35,8 +36,8 @@ module.exports = async function watchmanCrawl( ['anyof'].concat(extensions.map(extension => ['suffix', extension])), ]; const clocks = data.clocks; - const client = new watchman.Client(); + let clientError; client.on('error', error => (clientError = WatchmanError(error))); @@ -49,13 +50,22 @@ module.exports = async function watchmanCrawl( ), ); + if (options.computeSha1) { + const {capabilities} = await cmd('list-capabilities'); + + if (capabilities.indexOf('field-content.sha1hex') !== -1) { + fields.push('content.sha1hex'); + } + } + async function getWatchmanRoots(roots) { const watchmanRoots = new Map(); await Promise.all( roots.map(async root => { const response = await cmd('watch-project', root); const existing = watchmanRoots.get(response.watch); - // A root can only be filtered if it was never seen with a relative_path before + // A root can only be filtered if it was never seen with a + // relative_path before. const canBeFiltered = !existing || existing.length > 0; if (canBeFiltered) { @@ -65,8 +75,9 @@ module.exports = async function watchmanCrawl( (existing || []).concat(response.relative_path), ); } else { - // Make the filter directories an empty array to signal that this root - // was already seen and needs to be watched for all files/directories + // Make the filter directories an empty array to signal that this + // root was already seen and needs to be watched for all files or + // directories. watchmanRoots.set(response.watch, []); } } @@ -88,7 +99,6 @@ module.exports = async function watchmanCrawl( ...directoryFilters.map(dir => ['dirname', dir]), ]); } - const fields = ['name', 'exists', 'mtime_ms']; const query = clocks[root] ? // Use the `since` generator if we have a clock available @@ -97,9 +107,11 @@ module.exports = async function watchmanCrawl( {expression, fields, suffix: extensions}; const response = await cmd('query', root, query); + if ('warning' in response) { console.warn('watchman warning: ', response.warning); } + isFresh = isFresh || response.is_fresh_instance; files.set(root, response); }, @@ -117,10 +129,13 @@ module.exports = async function watchmanCrawl( try { const watchmanRoots = await getWatchmanRoots(roots); const watchmanFileResults = await queryWatchmanForDirs(watchmanRoots); - // Reset the file map if watchman was restarted and sends us a list of files. + + // Reset the file map if watchman was restarted and sends us a list of + // files. if (watchmanFileResults.isFresh) { files = Object.create(null); } + watchmanFiles = watchmanFileResults.files; } finally { client.end(); @@ -148,7 +163,7 @@ module.exports = async function watchmanCrawl( files[name] = existingFileData; } else { // See ../constants.js - files[name] = ['', mtime, 0, []]; + files[name] = ['', mtime, 0, [], fileData['content.sha1hex'] || null]; } } } diff --git a/packages/jest-haste-map/src/haste_fs.js b/packages/jest-haste-map/src/haste_fs.js index ee7801514ac5..7f09f9f40098 100644 --- a/packages/jest-haste-map/src/haste_fs.js +++ b/packages/jest-haste-map/src/haste_fs.js @@ -29,6 +29,10 @@ export default class HasteFS { return (this._files[file] && this._files[file][H.DEPENDENCIES]) || null; } + getSha1(file: Path): ?string { + return (this._files[file] && this._files[file][H.SHA1]) || null; + } + exists(file: Path): boolean { return !!this._files[file]; } diff --git a/packages/jest-haste-map/src/index.js b/packages/jest-haste-map/src/index.js index 86c79cc6bd01..3edd60d64c7c 100644 --- a/packages/jest-haste-map/src/index.js +++ b/packages/jest-haste-map/src/index.js @@ -46,6 +46,7 @@ import typeof HType from './constants'; type Options = { cacheDirectory?: string, + computeSha1?: boolean, console?: Console, extensions: Array, forceNodeFilesystemAPI?: boolean, @@ -66,6 +67,7 @@ type Options = { type InternalOptions = { cacheDirectory: string, + computeSha1: boolean, extensions: Array, forceNodeFilesystemAPI: boolean, hasteImplModulePath?: string, @@ -157,6 +159,7 @@ const getWhiteList = (list: ?Array): ?RegExp => { * mtime: number, // check for outdated files. * visited: boolean, // whether the file has been parsed or not. * dependencies: Array, // all relative dependencies of this file. + * sha1: ?string, // SHA-1 of the file, if requested via options. * }; * * // Modules can be targeted to a specific platform based on the file name. @@ -178,6 +181,7 @@ const getWhiteList = (list: ?Array): ?RegExp => { * * The HasteMap is created as follows: * 1. read data from the cache or create an empty structure. + * * 2. crawl the file system. * * empty cache: crawl the entire file system. * * cache available: @@ -185,12 +189,14 @@ const getWhiteList = (list: ?Array): ?RegExp => { * * if watchman is unavailable: crawl the entire file system. * * build metadata objects for every file. This builds the `files` part of * the `HasteMap`. + * * 3. parse and extract metadata from changed files. * * this is done in parallel over worker processes to improve performance. * * the worst case is to parse all files. * * the best case is no file system access and retrieving all data from * the cache. - * * the average case is a small number of changed files. + * * the average case is a small number of changed files. + * * 4. serialize the new `HasteMap` in a cache file. * Worker processes can directly access the cache through `HasteMap.read()`. * @@ -209,6 +215,7 @@ class HasteMap extends EventEmitter { super(); this._options = { cacheDirectory: options.cacheDirectory || os.tmpdir(), + computeSha1: options.computeSha1 || false, extensions: options.extensions, forceNodeFilesystemAPI: !!options.forceNodeFilesystemAPI, hasteImplModulePath: options.hasteImplModulePath, @@ -240,6 +247,7 @@ class HasteMap extends EventEmitter { this._options.roots.join(':'), this._options.extensions.join(':'), this._options.platforms.join(':'), + this._options.computeSha1.toString(), options.mocksPattern || '', options.ignorePattern.toString(), ); @@ -429,27 +437,35 @@ class HasteMap extends EventEmitter { const fileMetadata = hasteMap.files[filePath]; const moduleMetadata = hasteMap.map[fileMetadata[H.ID]]; + const computeSha1 = this._options.computeSha1 && !fileMetadata[H.SHA1]; + if (fileMetadata[H.VISITED]) { if (!fileMetadata[H.ID]) { return null; } + if (moduleMetadata != null) { const platform = getPlatformExtension(filePath, this._options.platforms) || H.GENERIC_PLATFORM; + const module = moduleMetadata[platform]; + if (module == null) { return null; } + const modulesByPlatform = map[fileMetadata[H.ID]] || (map[fileMetadata[H.ID]] = {}); modulesByPlatform[platform] = module; + return null; } } return this._getWorker(workerOptions) .worker({ + computeSha1, filePath, hasteImplModulePath: this._options.hasteImplModulePath, }) @@ -457,13 +473,20 @@ class HasteMap extends EventEmitter { metadata => { // `1` for truthy values instead of `true` to save cache space. fileMetadata[H.VISITED] = 1; + const metadataId = metadata.id; const metadataModule = metadata.module; + if (metadataId && metadataModule) { fileMetadata[H.ID] = metadataId; setModule(metadataId, metadataModule); } + fileMetadata[H.DEPENDENCIES] = metadata.dependencies || []; + + if (computeSha1) { + fileMetadata[H.SHA1] = metadata.sha1; + } }, error => { if (typeof error !== 'object' || !error.message || !error.stack) { @@ -498,6 +521,7 @@ class HasteMap extends EventEmitter { } for (const filePath in hasteMap.files) { + // SHA-1, if requested, should already be present thanks to the crawler. const promise = this._processFile(hasteMap, map, mocks, filePath); if (promise) { promises.push(promise); @@ -572,6 +596,7 @@ class HasteMap extends EventEmitter { error, ); return nodeCrawl({ + computeSha1: options.computeSha1, data: hasteMap, extensions: options.extensions, forceNodeFilesystemAPI: options.forceNodeFilesystemAPI, @@ -591,6 +616,7 @@ class HasteMap extends EventEmitter { try { return crawl({ + computeSha1: options.computeSha1, data: hasteMap, extensions: options.extensions, forceNodeFilesystemAPI: options.forceNodeFilesystemAPI, @@ -746,16 +772,14 @@ class HasteMap extends EventEmitter { // If the file was added or changed, // parse it and update the haste map. if (type === 'add' || type === 'change') { - const fileMetadata = ['', stat.mtime.getTime(), 0, []]; + const fileMetadata = ['', stat.mtime.getTime(), 0, [], null]; hasteMap.files[filePath] = fileMetadata; const promise = this._processFile( hasteMap, hasteMap.map, hasteMap.mocks, filePath, - { - forceInBand: true, - }, + {forceInBand: true}, ); // Cleanup this._cleanup(); diff --git a/packages/jest-haste-map/src/types.js b/packages/jest-haste-map/src/types.js index f379805d1ee3..aaedde6a83e7 100644 --- a/packages/jest-haste-map/src/types.js +++ b/packages/jest-haste-map/src/types.js @@ -12,17 +12,20 @@ import type {InternalHasteMap, ModuleMetaData} from 'types/HasteMap'; export type IgnoreMatcher = (item: string) => boolean; export type WorkerMessage = { + computeSha1: boolean, filePath: string, hasteImplModulePath?: string, }; -export type WorkerMetadata = { +export type WorkerMetadata = {| + dependencies: ?Array, id: ?string, module: ?ModuleMetaData, - dependencies: ?Array, -}; + sha1: ?string, +|}; export type CrawlerOptions = {| + computeSha1: boolean, data: InternalHasteMap, extensions: Array, forceNodeFilesystemAPI: boolean, diff --git a/packages/jest-haste-map/src/worker.js b/packages/jest-haste-map/src/worker.js index c35365a15836..969e384dbbc2 100644 --- a/packages/jest-haste-map/src/worker.js +++ b/packages/jest-haste-map/src/worker.js @@ -9,6 +9,7 @@ import type {HasteImpl, WorkerMessage, WorkerMetadata} from './types'; +import crypto from 'crypto'; import path from 'path'; import * as docblock from 'jest-docblock'; import fs from 'graceful-fs'; @@ -35,23 +36,25 @@ export async function worker(data: WorkerMessage): Promise { } const filePath = data.filePath; - let module; - let id: ?string; + let content; let dependencies; + let id; + let module; + let sha1; + // Process a package.json that is returned as a PACKAGE type with its name. if (filePath.endsWith(PACKAGE_JSON)) { - const fileData = JSON.parse(fs.readFileSync(filePath, 'utf8')); + content = fs.readFileSync(filePath, 'utf8'); + const fileData = JSON.parse(content); if (fileData.name) { id = fileData.name; module = [filePath, H.PACKAGE]; } - return {dependencies, id, module}; - } - - if (!blacklist.has(filePath.substr(filePath.lastIndexOf('.')))) { - const content = fs.readFileSync(filePath, 'utf8'); + // Process a randome file that is returned as a MODULE. + } else if (!blacklist.has(filePath.substr(filePath.lastIndexOf('.')))) { + content = fs.readFileSync(filePath, 'utf8'); if (hasteImpl) { id = hasteImpl.getHasteName(filePath); @@ -67,5 +70,17 @@ export async function worker(data: WorkerMessage): Promise { } } - return {dependencies, id, module}; + // If a SHA-1 is requested on update, compute it. + if (data.computeSha1) { + if (content == null) { + content = fs.readFileSync(filePath); + } + + sha1 = crypto + .createHash('sha1') + .update(content) + .digest('hex'); + } + + return {dependencies, id, module, sha1}; } diff --git a/packages/jest-matcher-utils/src/index.js b/packages/jest-matcher-utils/src/index.js index f5df6c90901c..557dd9cba5ca 100644 --- a/packages/jest-matcher-utils/src/index.js +++ b/packages/jest-matcher-utils/src/index.js @@ -49,7 +49,7 @@ const NUMBERS = [ ]; export const SUGGEST_TO_EQUAL = chalk.dim( - 'Looks like you wanted to test for object/array equality with strict `toBe` matcher. You probably need to use `toEqual` instead.', + 'Looks like you wanted to test for object/array equality with the stricter `toBe` matcher. You probably need to use `toEqual` instead.', ); export const stringify = (object: any, maxDepth?: number = 10): string => { diff --git a/packages/jest-mock/src/__tests__/jest_mock.test.js b/packages/jest-mock/src/__tests__/jest_mock.test.js index f573e5c31f0f..7c3f983aa027 100644 --- a/packages/jest-mock/src/__tests__/jest_mock.test.js +++ b/packages/jest-mock/src/__tests__/jest_mock.test.js @@ -476,6 +476,38 @@ describe('moduleMocker', () => { }); }); + it(`tracks thrown errors without interfering with other tracking`, () => { + const error = new Error('ODD!'); + const fn = moduleMocker.fn((x, y) => { + // multiply params + const result = x * y; + + if (result % 2 === 1) { + // throw error if result is odd + throw error; + } else { + return result; + } + }); + + expect(fn(2, 4)).toBe(8); + + // Mock still throws the error even though it was internally + // caught and recorded + expect(() => { + fn(3, 5); + }).toThrow('ODD!'); + + expect(fn(6, 3)).toBe(18); + + // All call args tracked + expect(fn.mock.calls).toEqual([[2, 4], [3, 5], [6, 3]]); + // tracked return value is undefined when an error is thrown + expect(fn.mock.returnValues).toEqual([8, undefined, 18]); + // tracked thrown error is undefined when an error is NOT thrown + expect(fn.mock.thrownErrors).toEqual([undefined, error, undefined]); + }); + describe('timestamps', () => { const RealDate = Date; @@ -868,5 +900,112 @@ describe('moduleMocker', () => { expect(spy1.mock.calls.length).toBe(1); expect(spy2.mock.calls.length).toBe(1); }); + + it('should work with getters on the prototype chain', () => { + let isOriginalCalled = false; + let originalCallThis; + let originalCallArguments; + const prototype = { + get method() { + return function() { + isOriginalCalled = true; + originalCallThis = this; + originalCallArguments = arguments; + }; + }, + }; + const obj = Object.create(prototype, {}); + + const spy = moduleMocker.spyOn(obj, 'method', 'get'); + + const thisArg = {this: true}; + const firstArg = {first: true}; + const secondArg = {second: true}; + obj.method.call(thisArg, firstArg, secondArg); + expect(isOriginalCalled).toBe(true); + expect(originalCallThis).toBe(thisArg); + expect(originalCallArguments.length).toBe(2); + expect(originalCallArguments[0]).toBe(firstArg); + expect(originalCallArguments[1]).toBe(secondArg); + expect(spy).toHaveBeenCalled(); + + isOriginalCalled = false; + originalCallThis = null; + originalCallArguments = null; + spy.mockReset(); + spy.mockRestore(); + obj.method.call(thisArg, firstArg, secondArg); + expect(isOriginalCalled).toBe(true); + expect(originalCallThis).toBe(thisArg); + expect(originalCallArguments.length).toBe(2); + expect(originalCallArguments[0]).toBe(firstArg); + expect(originalCallArguments[1]).toBe(secondArg); + expect(spy).not.toHaveBeenCalled(); + }); + + test('should work with setters on the prototype chain', () => { + const prototype = { + _property: false, + set property(value) { + this._property = value; + }, + get property() { + return this._property; + }, + }; + const obj = Object.create(prototype, {}); + + const spy = moduleMocker.spyOn(obj, 'property', 'set'); + obj.property = true; + expect(spy).toHaveBeenCalled(); + expect(obj.property).toBe(true); + obj.property = false; + spy.mockReset(); + spy.mockRestore(); + obj.property = true; + expect(spy).not.toHaveBeenCalled(); + expect(obj.property).toBe(true); + }); + + it('supports restoring all spies on the prototype chain', () => { + let methodOneCalls = 0; + let methodTwoCalls = 0; + const prototype = { + get methodOne() { + return function() { + methodOneCalls++; + }; + }, + get methodTwo() { + return function() { + methodTwoCalls++; + }; + }, + }; + const obj = Object.create(prototype, {}); + + const spy1 = moduleMocker.spyOn(obj, 'methodOne', 'get'); + const spy2 = moduleMocker.spyOn(obj, 'methodTwo', 'get'); + + // First, we call with the spies: both spies and both original functions + // should be called. + obj.methodOne(); + obj.methodTwo(); + expect(methodOneCalls).toBe(1); + expect(methodTwoCalls).toBe(1); + expect(spy1.mock.calls.length).toBe(1); + expect(spy2.mock.calls.length).toBe(1); + + moduleMocker.restoreAllMocks(); + + // Then, after resetting all mocks, we call methods again. Only the real + // methods should bump their count, not the spies. + obj.methodOne(); + obj.methodTwo(); + expect(methodOneCalls).toBe(2); + expect(methodTwoCalls).toBe(2); + expect(spy1.mock.calls.length).toBe(1); + expect(spy2.mock.calls.length).toBe(1); + }); }); }); diff --git a/packages/jest-mock/src/index.js b/packages/jest-mock/src/index.js index 10113434233c..ff02d3a5ff38 100644 --- a/packages/jest-mock/src/index.js +++ b/packages/jest-mock/src/index.js @@ -25,6 +25,7 @@ type MockFunctionState = { instances: Array, calls: Array>, returnValues: Array, + thrownErrors: Array, timestamps: Array, }; @@ -282,6 +283,7 @@ class ModuleMockerClass { calls: [], instances: [], returnValues: [], + thrownErrors: [], timestamps: [], }; } @@ -319,67 +321,85 @@ class ModuleMockerClass { mockState.calls.push(Array.prototype.slice.call(arguments)); mockState.timestamps.push(Date.now()); - // The bulk of the implementation is wrapped in an immediately executed - // arrow function so the return value of the mock function can - // be easily captured and recorded, despite the many separate return - // points within the logic. - const finalReturnValue = (() => { - if (this instanceof f) { - // This is probably being called as a constructor - prototypeSlots.forEach(slot => { - // Copy prototype methods to the instance to make - // it easier to interact with mock instance call and - // return values - if (prototype[slot].type === 'function') { - const protoImpl = this[slot]; - this[slot] = mocker.generateFromMetadata(prototype[slot]); - this[slot]._protoImpl = protoImpl; - } - }); - - // Run the mock constructor implementation - const mockImpl = mockConfig.specificMockImpls.length - ? mockConfig.specificMockImpls.shift() - : mockConfig.mockImpl; - return mockImpl && mockImpl.apply(this, arguments); - } - - const returnValue = mockConfig.defaultReturnValue; - // If return value is last set, either specific or default, i.e. - // mockReturnValueOnce()/mockReturnValue() is called and no - // mockImplementationOnce()/mockImplementation() is called after that. - // use the set return value. - if (mockConfig.specificReturnValues.length) { - return mockConfig.specificReturnValues.shift(); - } + // Will be set to the return value of the mock if an error is not thrown + let finalReturnValue; + // Will be set to the error that is thrown by the mock (if it throws) + let thrownError; + + try { + // The bulk of the implementation is wrapped in an immediately + // executed arrow function so the return value of the mock function + // can be easily captured and recorded, despite the many separate + // return points within the logic. + finalReturnValue = (() => { + if (this instanceof f) { + // This is probably being called as a constructor + prototypeSlots.forEach(slot => { + // Copy prototype methods to the instance to make + // it easier to interact with mock instance call and + // return values + if (prototype[slot].type === 'function') { + const protoImpl = this[slot]; + this[slot] = mocker.generateFromMetadata(prototype[slot]); + this[slot]._protoImpl = protoImpl; + } + }); + + // Run the mock constructor implementation + const mockImpl = mockConfig.specificMockImpls.length + ? mockConfig.specificMockImpls.shift() + : mockConfig.mockImpl; + return mockImpl && mockImpl.apply(this, arguments); + } - if (mockConfig.isReturnValueLastSet) { - return mockConfig.defaultReturnValue; - } + const returnValue = mockConfig.defaultReturnValue; + // If return value is last set, either specific or default, i.e. + // mockReturnValueOnce()/mockReturnValue() is called and no + // mockImplementationOnce()/mockImplementation() is called after + // that. + // use the set return value. + if (mockConfig.specificReturnValues.length) { + return mockConfig.specificReturnValues.shift(); + } - // If mockImplementationOnce()/mockImplementation() is last set, - // or specific return values are used up, use the mock implementation. - let specificMockImpl; - if (returnValue === undefined) { - specificMockImpl = mockConfig.specificMockImpls.shift(); - if (specificMockImpl === undefined) { - specificMockImpl = mockConfig.mockImpl; + if (mockConfig.isReturnValueLastSet) { + return mockConfig.defaultReturnValue; } - if (specificMockImpl) { - return specificMockImpl.apply(this, arguments); + + // If mockImplementationOnce()/mockImplementation() is last set, + // or specific return values are used up, use the mock + // implementation. + let specificMockImpl; + if (returnValue === undefined) { + specificMockImpl = mockConfig.specificMockImpls.shift(); + if (specificMockImpl === undefined) { + specificMockImpl = mockConfig.mockImpl; + } + if (specificMockImpl) { + return specificMockImpl.apply(this, arguments); + } } - } - // Otherwise use prototype implementation - if (returnValue === undefined && f._protoImpl) { - return f._protoImpl.apply(this, arguments); - } + // Otherwise use prototype implementation + if (returnValue === undefined && f._protoImpl) { + return f._protoImpl.apply(this, arguments); + } - return returnValue; - })(); + return returnValue; + })(); + } catch (error) { + // Store the thrown error so we can record it, then re-throw it. + thrownError = error; + throw error; + } finally { + // Record the return value of the mock function. + // If the mock threw an error, then the value will be undefined. + mockState.returnValues.push(finalReturnValue); + // Record the error thrown by the mock function. + // If no error was thrown, then the value will be udnefiend. + mockState.thrownErrors.push(thrownError); + } - // Record the return value of the mock function before returning it. - mockState.returnValues.push(finalReturnValue); return finalReturnValue; }, metadata.length || 0); @@ -737,7 +757,13 @@ class ModuleMockerClass { throw new Error('No property name supplied'); } - const descriptor = Object.getOwnPropertyDescriptor(obj, propertyName); + let descriptor = Object.getOwnPropertyDescriptor(obj, propertyName); + let proto = Object.getPrototypeOf(obj); + + while (!descriptor && proto !== null) { + descriptor = Object.getOwnPropertyDescriptor(proto, propertyName); + proto = Object.getPrototypeOf(proto); + } if (!descriptor) { throw new Error(propertyName + ' property does not exist'); diff --git a/packages/jest-runner/src/__tests__/test_runner.test.js b/packages/jest-runner/src/__tests__/test_runner.test.js index f05ab6c6dc4d..ced1c934a8cc 100644 --- a/packages/jest-runner/src/__tests__/test_runner.test.js +++ b/packages/jest-runner/src/__tests__/test_runner.test.js @@ -86,3 +86,22 @@ test('does not inject the rawModuleMap in serial mode', () => { ]); }); }); + +test('assign process.env.JEST_WORKER_ID = 1 when in runInBand mode', () => { + const globalConfig = {maxWorkers: 1, watch: false}; + const config = {rootDir: '/path/'}; + const context = {config}; + + return new TestRunner(globalConfig) + .runTests( + [{context, path: './file.test.js'}], + new TestWatcher({isWatchMode: globalConfig.watch}), + () => {}, + () => {}, + () => {}, + {serial: true}, + ) + .then(() => { + expect(process.env.JEST_WORKER_ID).toBe('1'); + }); +}); diff --git a/packages/jest-runner/src/index.js b/packages/jest-runner/src/index.js index f4a2ce92c1ab..2f4dd7243697 100644 --- a/packages/jest-runner/src/index.js +++ b/packages/jest-runner/src/index.js @@ -61,6 +61,7 @@ class TestRunner { onResult: OnTestSuccess, onFailure: OnTestFailure, ) { + process.env.JEST_WORKER_ID = '1'; const mutex = throat(1); return tests.reduce( (promise, test) => diff --git a/packages/jest-worker/src/__performance_tests__/test.js b/packages/jest-worker/src/__performance_tests__/test.js index aeff514657af..5db9938889eb 100644 --- a/packages/jest-worker/src/__performance_tests__/test.js +++ b/packages/jest-worker/src/__performance_tests__/test.js @@ -2,10 +2,17 @@ // eslint-disable-next-line import/no-extraneous-dependencies const workerFarm = require('worker-farm'); -import JestWorker from '../../build'; +const assert = require('assert'); +const JestWorker = require('../../build').default; + +// Typical tests: node --expose-gc test.js empty 100000 +// node --expose-gc test.js loadTest 10000 +assert(process.argv[2], 'Pass a child method name'); +assert(process.argv[3], 'Pass the number of iteratitons'); const sleep = ms => new Promise(resolve => setTimeout(resolve, ms)); -const calls = 10000; +const method = process.argv[2]; +const calls = +process.argv[3]; const threads = 6; function testWorkerFarm() { @@ -35,7 +42,7 @@ function testWorkerFarm() { maxConcurrentWorkers: threads, }, require.resolve('./workers/worker_farm'), - ['loadTest'], + [method], ); // Let all workers come up. @@ -45,7 +52,7 @@ function testWorkerFarm() { for (let i = 0; i < calls; i++) { const promisified = new Promise((resolve, reject) => { - api.loadTest((err, result) => { + api[method]((err, result) => { if (err) { reject(err); } else { @@ -80,7 +87,7 @@ function testJestWorker() { } const farm = new JestWorker(require.resolve('./workers/jest_worker'), { - exposedMethods: ['loadTest'], + exposedMethods: [method], forkOptions: {execArgv: []}, workers: threads, }); @@ -94,7 +101,7 @@ function testJestWorker() { const startProcess = Date.now(); for (let i = 0; i < calls; i++) { - const promisified = farm.loadTest(); + const promisified = farm[method](); promisified.then(countToFinish); } diff --git a/packages/jest-worker/src/__performance_tests__/workers/jest_worker.js b/packages/jest-worker/src/__performance_tests__/workers/jest_worker.js index e48d8527c4f8..5468ec07aa65 100644 --- a/packages/jest-worker/src/__performance_tests__/workers/jest_worker.js +++ b/packages/jest-worker/src/__performance_tests__/workers/jest_worker.js @@ -5,3 +5,7 @@ const pi = require('./pi'); module.exports.loadTest = function() { return pi(); }; + +module.exports.empty = function() { + // Do nothing. +}; diff --git a/packages/jest-worker/src/__performance_tests__/workers/worker_farm.js b/packages/jest-worker/src/__performance_tests__/workers/worker_farm.js index 4213db2463b4..360042c808b0 100644 --- a/packages/jest-worker/src/__performance_tests__/workers/worker_farm.js +++ b/packages/jest-worker/src/__performance_tests__/workers/worker_farm.js @@ -5,3 +5,8 @@ const pi = require('./pi'); module.exports.loadTest = function(callback) { callback(null, pi()); }; + +module.exports.empty = function(callback) { + // Do nothing. + callback(); +}; diff --git a/packages/jest-worker/src/types.js b/packages/jest-worker/src/types.js index c40ed0e50e33..cd61fa2d3dc2 100644 --- a/packages/jest-worker/src/types.js +++ b/packages/jest-worker/src/types.js @@ -99,4 +99,5 @@ export type QueueCallback = (?Error, ?any) => void; export type QueueChildMessage = {| request: ChildMessage, callback: QueueCallback, + next: ?QueueChildMessage, |}; diff --git a/packages/jest-worker/src/worker.js b/packages/jest-worker/src/worker.js index e087ea05adec..80562376828b 100644 --- a/packages/jest-worker/src/worker.js +++ b/packages/jest-worker/src/worker.js @@ -48,13 +48,14 @@ import type { export default class { _busy: boolean; _child: ChildProcess; + _last: ?QueueChildMessage; _options: WorkerOptions; - _queue: Array; + _queue: ?QueueChildMessage; _retries: number; constructor(options: WorkerOptions) { this._options = options; - this._queue = []; + this._queue = null; this._initialize(); } @@ -68,7 +69,15 @@ export default class { } send(request: ChildMessage, callback: QueueCallback) { - this._queue.push({callback, request}); + const item = {callback, next: null, request}; + + if (this._last) { + this._last.next = item; + } else { + this._queue = item; + } + + this._last = item; this._process(); } @@ -82,7 +91,7 @@ export default class { env: Object.assign({}, process.env, { JEST_WORKER_ID: this._options.workerId, }), - // suppress --debug / --inspect flags while preserving others (like --harmony) + // Suppress --debug / --inspect flags while preserving others (like --harmony). execArgv: process.execArgv.filter(v => !/^--(debug|inspect)/.test(v)), silent: true, }, @@ -121,35 +130,39 @@ export default class { return; } - const queue = this._queue; - let skip = 0; + let item = this._queue; // Calls in the queue might have already been processed by another worker, // so we have to skip them. - while (queue.length > skip && queue[skip].request[1]) { - skip++; + while (item && item.request[1]) { + item = item.next; } - // Remove all pieces at once. - queue.splice(0, skip); - - if (queue.length) { - const call = queue[0]; + this._queue = item; + if (item) { // Flag the call as processed, so that other workers know that they don't // have to process it as well. - call.request[1] = true; + item.request[1] = true; this._retries = 0; this._busy = true; // $FlowFixMe: wrong "ChildProcess.send" signature. - this._child.send(call.request); + this._child.send(item.request); + } else { + this._last = item; } } _receive(response: any /* Should be ParentMessage */) { - const callback = this._queue[0].callback; + const item = this._queue; + + if (!item) { + throw new TypeError('Unexpected response with an empty queue'); + } + + const callback = item.callback; this._busy = false; this._process(); diff --git a/packages/pretty-format/src/__tests__/react.test.js b/packages/pretty-format/src/__tests__/react.test.js index efa597981b8f..f136884305d9 100644 --- a/packages/pretty-format/src/__tests__/react.test.js +++ b/packages/pretty-format/src/__tests__/react.test.js @@ -13,6 +13,7 @@ const React = require('react'); const renderer = require('react-test-renderer'); const elementSymbol = Symbol.for('react.element'); +const fragmentSymbol = Symbol.for('react.fragment'); const testSymbol = Symbol.for('react.test.json'); const prettyFormat = require('..'); @@ -300,6 +301,32 @@ test('supports undefined element type', () => { ); }); +test('supports a fragment with no children', () => { + expect( + formatElement({$$typeof: elementSymbol, props: {}, type: fragmentSymbol}), + ).toEqual(''); +}); + +test('supports a fragment with string child', () => { + expect( + formatElement({ + $$typeof: elementSymbol, + props: {children: 'test'}, + type: fragmentSymbol, + }), + ).toEqual('\n test\n'); +}); + +test('supports a fragment with element child', () => { + expect( + formatElement({ + $$typeof: elementSymbol, + props: {children: React.createElement('div', null, 'test')}, + type: fragmentSymbol, + }), + ).toEqual('\n
\n test\n
\n'); +}); + test('supports a single element with React elements with a child', () => { assertPrintedJSX( React.createElement('Mouse', { diff --git a/packages/pretty-format/src/plugins/react_element.js b/packages/pretty-format/src/plugins/react_element.js index f90ff1ee279e..bd261491c6b6 100644 --- a/packages/pretty-format/src/plugins/react_element.js +++ b/packages/pretty-format/src/plugins/react_element.js @@ -17,6 +17,7 @@ import { } from './lib/markup'; const elementSymbol = Symbol.for('react.element'); +const fragmentSymbol = Symbol.for('react.fragment'); // Given element.props.children, or subtree during recursive traversal, // return flattened array of children. @@ -38,6 +39,9 @@ const getType = element => { if (typeof element.type === 'function') { return element.type.displayName || element.type.name || 'Unknown'; } + if (element.type === fragmentSymbol) { + return 'React.Fragment'; + } return 'UNDEFINED'; }; diff --git a/scripts/build.js b/scripts/build.js index fbc9d05cb783..d687b794def5 100644 --- a/scripts/build.js +++ b/scripts/build.js @@ -28,6 +28,7 @@ const mkdirp = require('mkdirp'); const babel = require('babel-core'); const chalk = require('chalk'); const micromatch = require('micromatch'); +const prettier = require('prettier'); const stringLength = require('string-length'); const getPackages = require('./getPackages'); const browserBuild = require('./browserBuild'); @@ -46,6 +47,8 @@ const transformOptions = JSON.parse( fs.readFileSync(path.resolve(__dirname, '..', '.babelrc'), 'utf8') ); transformOptions.babelrc = false; +const prettierConfig = prettier.resolveConfig.sync(__filename); +prettierConfig.trailingComma = 'none'; const adjustToTerminalWidth = str => { const columns = process.stdout.columns || 80; @@ -161,7 +164,8 @@ function buildFile(file, silent) { } const transformed = babel.transformFileSync(file, options).code; - fs.writeFileSync(destPath, transformed); + const prettyCode = prettier.format(transformed, prettierConfig); + fs.writeFileSync(destPath, prettyCode); silent || process.stdout.write( chalk.green(' \u2022 ') + diff --git a/types/HasteMap.js b/types/HasteMap.js index 24f496a4c889..bc985254807b 100644 --- a/types/HasteMap.js +++ b/types/HasteMap.js @@ -53,6 +53,7 @@ export type FileMetaData = [ /* mtime */ number, /* visited */ 0 | 1, /* dependencies */ Array, + /* sha1 */ ?string, ]; type ModuleMapItem = {[platform: string]: ModuleMetaData}; diff --git a/types/TestResult.js b/types/TestResult.js index 4442398290cd..7a293f5862f2 100644 --- a/types/TestResult.js +++ b/types/TestResult.js @@ -78,6 +78,11 @@ export type FailedAssertion = {| stack?: string, |}; +export type AssertionLocation = {| + path: string, + title: string, +|}; + export type Status = 'passed' | 'failed' | 'skipped' | 'pending'; export type Bytes = number; diff --git a/website/pages/en/versions.js b/website/pages/en/versions.js index 691b2681b7a9..726d4be16cff 100644 --- a/website/pages/en/versions.js +++ b/website/pages/en/versions.js @@ -79,7 +79,7 @@ class Versions extends React.Component { version => version !== latestVersion && ( - {version} + {version === '22.0' ? '<=22' : version} + +--- + +## 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. Note: depending on your terminal, you may need to quote +this argument: `jest "my.*(complex)?pattern"`. + +### `--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` + +When used together with `--onlyChanged` or `--watch`, it runs tests related to +the current changes and the changes made in the last commit. + +### `--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` + +##### available in Jest **22.0.0+** + +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=` + +Relative to the root directory, glob pattern 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. + +### `--debug` + +Print debugging info about your Jest config. + +### `--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`. + +### `--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. + +### `--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._ + +### `--help` + +Show the help information, similar to this page. + +### `--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` + +When used together with `--onlyChanged`, it will run all tests affected by file +changes in the last commit made. + +### `--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. + +### `--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 and test suites 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`. + +### `--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. + +### `--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-22.0/Configuration.md b/website/versioned_docs/version-22.0/Configuration.md new file mode 100644 index 000000000000..35f40dc0768b --- /dev/null +++ b/website/versioned_docs/version-22.0/Configuration.md @@ -0,0 +1,1087 @@ +--- +id: version-22.0-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. + + + +--- + +## Reference + +### `automock` [boolean] + +Default: `false` + +This option is disabled by default. If you are introducing Jest to a large +organization with an existing codebase but few tests, enabling this option can +be helpful to introduce unit tests gradually. Modules can be explicitly +auto-mocked using `jest.mock(moduleName)`. + +_Note: Core modules, like `fs`, are not mocked by default. They can be mocked +explicitly, like `jest.mock('fs')`._ + +_Note: Automocking has a performance cost most noticeable in large projects. See +[here](troubleshooting.html#tests-are-slow-when-leveraging-automocking) for +details and a workaround._ + +### `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. + +### `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. + +### `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. + +### `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/gotwarlost/istanbul/tree/master/lib/report) +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`). + +### `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. + +### `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. + +### `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. + +### `mapCoverage` [boolean] + +##### available in Jest **20.0.0+** + +Default: `false` + +If you have [transformers](#transform-object-string-string) configured that emit +source maps, Jest will use them to try and map code coverage against the +original source code when writing [reports](#coveragereporters-array-string) and +checking [thresholds](#coveragethreshold-object). This is done on a best-effort +basis as some compile-to-JavaScript languages may provide more accurate source +maps than others. This can also be resource-intensive. If Jest is taking a long +time to calculate coverage at the end of a test run, try setting this option to +`false`. + +Both inline source maps and source maps returned directly from a transformer are +supported. Source map URLs are not supported because Jest may not be able to +locate them. To return source maps from a transformer, the `process` function +can return an object like the following. The `map` property may either be the +source map object, or the source map object as a JSON string. + +```js +return { + code: 'the code', + map: 'the source map', +}; +``` + +### `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). + +### `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"]` + +### `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. + +### `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` module on its top level. + +### `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"] + } + ] +} +``` + +### `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. + +### `reporters` [array] + +Default: `undefined` + +##### available in Jest **20.0.0+** + +Use this configuration option to add custom reporters to Jest. A custom reporter +is a class that implements `onRunStart`, `onTestStart`, `onTestResult`, +`onRunComplete` methods that will be called when any of those events occurs. + +If custom reporters are specified, the default Jest reporters will be +overridden. To keep default reporters, `default` can be passed as a module name. + +This will override default reporters: + +```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` + +If enabled, the module registry for every test file will be reset before running +each individual test. This is useful to isolate modules for every test so that +local module state doesn't conflict between tests. This can be done +programmatically using [`jest.resetModules()`](#jest-resetmodules). + +### `resolver` [string] + +Default: `undefined` + +##### available in Jest **20.0.0+** + +This option allows the use of a custom resolver. This resolver must be a node +module that exports a function expecting a string as the first argument for the +path to resolve and an object with the following structure as the second +argument: + +``` +{ + "basedir": string, + "browser": bool, + "extensions": [string], + "moduleDirectory": [string], + "paths": [string], + "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. + +### `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] + +##### available in Jest **21.0.0+** + +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 +``` + +### `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. + +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: + +``` +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. + +If some tests require another environment, you can add a `@jest-environment` +docblock. + +##### available in Jest **20.0.0+** + +```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. + +##### available in Jest **22.0.0+** + +_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] + +##### available in Jest **22.0.0+** + +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] + +##### available in Jest **19.0.0+** + +(default: `[ '**/__tests__/**/*.js?(x)', '**/?(*.)(spec|test).js?(x)' ]`) + +The glob patterns Jest uses to detect test files. By default it looks for `.js` +and `.jsx` files inside of `__tests__` folders, as well as any files with a +suffix of `.test` or `.spec` (e.g. `Component.test.js` or `Component.spec.js`). +It will also find files called `test.js` or `spec.js`. + +See the [micromatch](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: + +``` +├── __tests__ +│ └── component.spec.js # test +│ └── anything # test +├── package.json # not test +├── foo.test.js # test +├── bar.spec.jsx # test +└── component.js # not test +``` + +### `testResultsProcessor` [string] + +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: + +``` +{ + "success": bool, + "startTime": epoch, + "numTotalTestSuites": number, + "numPassedTestSuites": number, + "numFailedTestSuites": number, + "numRuntimeErrorTestSuites": number, + "numTotalTests": number, + "numPassedTests": number, + "numFailedTests": number, + "numPendingTests": number, + "testResults": [{ + "numFailingTests": number, + "numPassingTests": number, + "numPendingTests": number, + "testResults": [{ + "title": string (message in it block), + "status": "failed" | "pending" | "passed", + "ancestorTitles": [string (message in describe blocks)], + "failureMessages": [string], + "numPassingAsserts": number, + "location": { + "column": number, + "line": number + } + }, + ... + ], + "perfStats": { + "start": epoch, + "end": epoch + }, + "testFilePath": absolute path to test file, + "coverage": {} + }, + ... + ] +} +``` + +### `testRunner` [string] + +Default: `jasmine2` + +This option allows use of a custom test runner. The default is jasmine2. A +custom test runner can be provided by specifying a path to a test runner +implementation. + +The test runner module must export a function with the following signature: + +``` +function testRunner( + config: Config, + environment: Environment, + runtime: Runtime, + testPath: string, +): Promise +``` + +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](http://facebook.github.io/jest/docs/en/tutorial-react-native.html#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: `[]` + +##### available in Jest **21.0.0+** + +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-22.0/ExpectAPI.md b/website/versioned_docs/version-22.0/ExpectAPI.md new file mode 100644 index 000000000000..42b93e7e6bf0 --- /dev/null +++ b/website/versioned_docs/version-22.0/ExpectAPI.md @@ -0,0 +1,1060 @@ +--- +id: version-22.0-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); +}); +``` + +Matchers should return 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: + +``` + 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.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)` + +##### available in Jest **19.0.0+** + +`expect.stringContaining(string)` matches any received string that contains the +exact expected string. + +### `expect.stringMatching(regexp)` + +`expect.stringMatching(regexp)` matches any 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` + +##### available in Jest **20.0.0+** + +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` + +##### available in Jest **20.0.0+** + +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)` + +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'); +}); +``` + +### `.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', + }, +}; + +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).not.toHaveProperty(['kitchen', 'open']); +}); +``` + +### `.toMatchSnapshot(optionalString)` + +This ensures that a value matches the most recent snapshot. Check out +[the Snapshot Testing guide](SnapshotTesting.md) for more information. + +You can also specify an optional 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._ + +### `.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 for the error message, a +class for the error, or a regex that should match the error. 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 the exact error message + expect(drinkOctopus).toThrowError('yuck, octopus flavor'); + + // Test that the error message says "yuck" somewhere + expect(drinkOctopus).toThrowError(/yuck/); + + // 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: + +``` +exports[`drinking flavors throws on octopus 1`] = `"yuck, octopus flavor"`; +``` + +Check out +[React Tree Snapshot Testing](http://facebook.github.io/jest/blog/2016/07/27/jest-14.html) +for more information on snapshot testing. diff --git a/website/versioned_docs/version-22.0/GettingStarted.md b/website/versioned_docs/version-22.0/GettingStarted.md new file mode 100644 index 000000000000..231f29a52fa0 --- /dev/null +++ b/website/versioned_docs/version-22.0/GettingStarted.md @@ -0,0 +1,156 @@ +--- +id: version-22.0-getting-started +title: Getting Started +original_id: getting-started +--- + +Install Jest using [`npm`](https://www.npmjs.com/): + +``` +npm install --save-dev jest +``` + +Or via [`yarn`](https://yarnpkg.com/en/package/jest): + +``` +yarn add --dev jest +``` + +Let's get started by writing a test for a hypothetical function that adds two +numbers. First, create a `sum.js` file: + +```javascript +function sum(a, b) { + return a + b; +} +module.exports = sum; +``` + +Then, create a file named `sum.test.js`. This will contain our actual test: + +```javascript +const sum = require('./sum'); + +test('adds 1 + 2 to equal 3', () => { + expect(sum(1, 2)).toBe(3); +}); +``` + +Add the following section to your `package.json`: + +```json +{ + "scripts": { + "test": "jest" + } +} +``` + +Finally, run `npm test` and Jest will print this message: + +``` +PASS ./sum.test.js +✓ adds 1 + 2 to equal 3 (5ms) +``` + +**You just successfully wrote your first test using Jest!** + +This test used `expect` and `toBe` to test that two values were exactly +identical. To learn about the other things that Jest can test, see +[Using Matchers](UsingMatchers.md). + +## Running from command line + +You can run Jest directly from the CLI (if it's globally available in your +`PATH`, e.g. by `npm install -g jest`) with variety of useful options. + +Here's how to run Jest on files matching `my-test`, using `config.json` as a +configuration file and display a native OS notification after the run: + +```bash +jest my-test --notify --config=config.json +``` + +If you'd like to learn more about running `jest` through the command line, take +a look at the [Jest CLI Options](CLI.md) page. + +## Additional Configuration + +### Using Babel + +To use [Babel](http://babeljs.io/), install the `babel-jest` and +`regenerator-runtime` packages: + +``` +npm install --save-dev babel-jest babel-core regenerator-runtime +``` + +> Note: If you are using a babel version 7 then you need to install `babel-jest` +> with the following command: +> +> ``` +> npm install --save-dev babel-jest 'babel-core@^7.0.0-0' @babel/core regenerator-runtime +> ``` + +_Note: Explicitly installing `regenerator-runtime` is not needed if you use +`npm` 3 or 4 or Yarn_ + +Don't forget to add a [`.babelrc`](https://babeljs.io/docs/usage/babelrc/) file +in your project's root folder. For example, if you are using ES6 and +[React.js](https://facebook.github.io/react/) with the +[`babel-preset-es2015`](https://babeljs.io/docs/plugins/preset-es2015/) and +[`babel-preset-react`](https://babeljs.io/docs/plugins/preset-react/) presets: + +```json +{ + "presets": ["es2015", "react"] +} +``` + +You are now set up to use all ES6 features and React specific syntax. + +> Note: If you are using a more complicated Babel configuration, using Babel's +> `env` option, keep in mind that Jest will automatically define `NODE_ENV` as +> `test`. It will not use `development` section like Babel does by default when +> no `NODE_ENV` is set. + +> Note: If you've turned off transpilation of ES2015 modules with the option +> `{ "modules": false }`, you have to make sure to turn this on in your test +> environment. + +```json +{ + "presets": [["es2015", {"modules": false}], "react"], + "env": { + "test": { + "presets": [["es2015"], "react"] + } + } +} +``` + +> Note: `babel-jest` is automatically installed when installing Jest and will +> automatically transform files if a babel configuration exists in your project. +> To avoid this behavior, you can explicitly reset the `transform` configuration +> option: + +```json +// package.json +{ + "jest": { + "transform": {} + } +} +``` + +### Using webpack + +Jest can be used in projects that use [webpack](https://webpack.github.io/) to +manage assets, styles, and compilation. webpack does offer some unique +challenges over other tools. Refer to the [webpack guide](Webpack.md) to get +started. + +### Using TypeScript + +To use TypeScript in your tests you can use +[ts-jest](https://github.com/kulshekhar/ts-jest). diff --git a/website/versioned_docs/version-22.0/GlobalAPI.md b/website/versioned_docs/version-22.0/GlobalAPI.md new file mode 100644 index 000000000000..a863b53d8534 --- /dev/null +++ b/website/versioned_docs/version-22.0/GlobalAPI.md @@ -0,0 +1,413 @@ +--- +id: version-22.0-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.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.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. + +### `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.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.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. diff --git a/website/versioned_docs/version-22.0/JestObjectAPI.md b/website/versioned_docs/version-22.0/JestObjectAPI.md new file mode 100644 index 000000000000..2d9a4050239d --- /dev/null +++ b/website/versioned_docs/version-22.0/JestObjectAPI.md @@ -0,0 +1,483 @@ +--- +id: version-22.0-jest-object +title: The Jest Object +original_id: jest-object +--- + +The `jest` object is automatically in scope within every test file. The methods +in the `jest` object help create mocks and let you control Jest's overall +behavior. + +## Methods + +* [`jest.clearAllTimers()`](#jestclearalltimers) +* [`jest.disableAutomock()`](#jestdisableautomock) +* [`jest.enableAutomock()`](#jestenableautomock) +* [`jest.fn(implementation)`](#jestfnimplementation) +* [`jest.isMockFunction(fn)`](#jestismockfunctionfn) +* [`jest.genMockFromModule(moduleName)`](#jestgenmockfrommodulemodulename) +* [`jest.mock(moduleName, factory, options)`](#jestmockmodulename-factory-options) +* [`jest.unmock(moduleName)`](#jestunmockmodulename) +* [`jest.doMock(moduleName, factory, options)`](#jestdomockmodulename-factory-options) +* [`jest.dontMock(moduleName)`](#jestdontmockmodulename) +* [`jest.clearAllMocks()`](#jestclearallmocks) +* [`jest.resetAllMocks()`](#jestresetallmocks) +* [`jest.restoreAllMocks()`](#jestrestoreallmocks) +* [`jest.resetModules()`](#jestresetmodules) +* [`jest.runAllTicks()`](#jestrunallticks) +* [`jest.runAllTimers()`](#jestrunalltimers) +* [`jest.advanceTimersByTime(msToRun)`](#jestadvancetimersbytimemstorun) +* [`jest.runOnlyPendingTimers()`](#jestrunonlypendingtimers) +* [`jest.setMock(moduleName, moduleExports)`](#jestsetmockmodulename-moduleexports) +* [`jest.setTimeout(timeout)`](#jestsettimeouttimeout) +* [`jest.useFakeTimers()`](#jestusefaketimers) +* [`jest.useRealTimers()`](#jestuserealtimers) +* [`jest.spyOn(object, methodName)`](#jestspyonobject-methodname) + +--- + +## Reference + +### `jest.clearAllTimers()` + +Removes any pending timers from the timer system. + +This means, if any timers have been scheduled (but have not yet executed), they +will be cleared and will never have the opportunity to execute in the future. + +### `jest.disableAutomock()` + +Disables automatic mocking in the module loader. + +After this method is called, all `require()`s will return the real versions of +each module (rather than a mocked version). + +This is usually useful when you have a scenario where the number of dependencies +you want to mock is far less than the number of dependencies that you don't. For +example, if you're writing a test for a module that uses a large number of +dependencies that can be reasonably classified as "implementation details" of +the module, then you likely do not want to mock them. + +Examples of dependencies that might be considered "implementation details" are +things ranging from language built-ins (e.g. Array.prototype methods) to highly +common utility methods (e.g. underscore/lo-dash, array utilities etc) and entire +libraries like React.js. + +Returns the `jest` object for chaining. + +_Note: this method was previously called `autoMockOff`. When using `babel-jest`, +calls to `disableAutomock` will automatically be hoisted to the top of the code +block. Use `autoMockOff` if you want to explicitly avoid this behavior._ + +### `jest.enableAutomock()` + +Enables automatic mocking in the module loader. + +Returns the `jest` object for chaining. + +_Note: this method was previously called `autoMockOn`. When using `babel-jest`, +calls to `enableAutomock` will automatically be hoisted to the top of the code +block. Use `autoMockOn` if you want to explicitly avoid this behavior._ + +### `jest.fn(implementation)` + +Returns a new, unused [mock function](MockFunctionAPI.md). Optionally takes a +mock implementation. + +```js +const mockFn = jest.fn(); +mockFn(); +expect(mockFn).toHaveBeenCalled(); + +// With a mock implementation: +const returnsTrue = jest.fn(() => true); +console.log(returnsTrue()); // true; +``` + +### `jest.isMockFunction(fn)` + +Determines if the given function is a mocked function. + +### `jest.genMockFromModule(moduleName)` + +Given the name of a module, use the automatic mocking system to generate a +mocked version of the module for you. + +This is useful when you want to create a [manual mock](ManualMocks.md) that +extends the automatic mock's behavior. + +### `jest.mock(moduleName, factory, options)` + +Mocks a module with an auto-mocked version when it is being required. `factory` +and `options` are optional. For example: + +```js +// banana.js +module.exports = () => 'banana'; + +// __tests__/test.js +jest.mock('../banana'); + +const banana = require('../banana'); // banana will be explicitly mocked. + +banana(); // will return 'undefined' because the function is auto-mocked. +``` + +The second argument can be used to specify an explicit module factory that is +being run instead of using Jest's automocking feature: + +```js +jest.mock('../moduleName', () => { + return jest.fn(() => 42); +}); + +// This runs the function specified as second argument to `jest.mock`. +const moduleName = require('../moduleName'); +moduleName(); // Will return '42'; +``` + +The third argument can be used to create virtual mocks – mocks of modules that +don't exist anywhere in the system: + +```js +jest.mock( + '../moduleName', + () => { + /* + * Custom implementation of a module that doesn't exist in JS, + * like a generated module or a native module in react-native. + */ + }, + {virtual: true}, +); +``` + +_Warning: Importing a module in a setup file (as specified by +`setupTestFrameworkScriptFile`) will prevent mocking for the module in question, +as well as all the modules that it imports._ + +Modules that are mocked with `jest.mock` are mocked only for the file that calls +`jest.mock`. Another file that imports the module will get the original +implementation even if run after the test file that mocks the module. + +Returns the `jest` object for chaining. + +### `jest.unmock(moduleName)` + +Indicates that the module system should never return a mocked version of the +specified module from `require()` (e.g. that it should always return the real +module). + +The most common use of this API is for specifying the module a given test +intends to be testing (and thus doesn't want automatically mocked). + +Returns the `jest` object for chaining. + +### `jest.doMock(moduleName, factory, options)` + +When using `babel-jest`, calls to `mock` will automatically be hoisted to the +top of the code block. Use this method if you want to explicitly avoid this +behavior. + +One example when this is useful is when you want to mock a module differently +within the same file: + +```js +beforeEach(() => { + jest.resetModules(); +}); + +test('moduleName 1', () => { + jest.doMock('../moduleName', () => { + return jest.fn(() => 1); + }); + const moduleName = require('../moduleName'); + expect(moduleName()).toEqual(1); +}); + +test('moduleName 2', () => { + jest.doMock('../moduleName', () => { + return jest.fn(() => 2); + }); + const moduleName = require('../moduleName'); + expect(moduleName()).toEqual(2); +}); +``` + +Returns the `jest` object for chaining. + +### `jest.dontMock(moduleName)` + +When using `babel-jest`, calls to `unmock` will automatically be hoisted to the +top of the code block. Use this method if you want to explicitly avoid this +behavior. + +Returns the `jest` object for chaining. + +### `jest.clearAllMocks()` + +Clears the `mock.calls` and `mock.instances` properties of all mocks. Equivalent +to calling `.mockClear()` on every mocked function. + +Returns the `jest` object for chaining. + +### `jest.resetAllMocks()` + +Resets the state of all mocks. Equivalent to calling `.mockReset()` on every +mocked function. + +Returns the `jest` object for chaining. + +### `jest.restoreAllMocks()` + +##### available in Jest **21.1.0+** + +Restores all mocks back to their original value. Equivalent to calling +`.mockRestore` on every mocked function. Beware that `jest.restoreAllMocks()` +only works when mock was created with `jest.spyOn`; other mocks will require you +to manually restore them. + +### `jest.resetModules()` + +Resets the module registry - the cache of all required modules. This is useful +to isolate modules where local state might conflict between tests. + +Example: + +```js +const sum1 = require('../sum'); +jest.resetModules(); +const sum2 = require('../sum'); +sum1 === sum2; +// > false (Both sum modules are separate "instances" of the sum module.) +``` + +Example in a test: + +```js +beforeEach(() => { + jest.resetModules(); +}); + +test('works', () => { + const sum = require('../sum'); +}); + +test('works too', () => { + const sum = require('../sum'); + // sum is a different copy of the sum module from the previous test. +}); +``` + +Returns the `jest` object for chaining. + +### `jest.runAllTicks()` + +Exhausts the **micro**-task queue (usually interfaced in node via +`process.nextTick`). + +When this API is called, all pending micro-tasks that have been queued via +`process.nextTick` will be executed. Additionally, if those micro-tasks +themselves schedule new micro-tasks, those will be continually exhausted until +there are no more micro-tasks remaining in the queue. + +### `jest.runAllTimers()` + +Exhausts the **macro**-task queue (i.e., all tasks queued by `setTimeout()`, +`setInterval()`, and `setImmediate()`). + +When this API is called, all pending "macro-tasks" that have been queued via +`setTimeout()` or `setInterval()` will be executed. Additionally if those +macro-tasks themselves schedule new macro-tasks, those will be continually +exhausted until there are no more macro-tasks remaining in the queue. + +This is often useful for synchronously executing setTimeouts during a test in +order to synchronously assert about some behavior that would only happen after +the `setTimeout()` or `setInterval()` callbacks executed. See the +[Timer mocks](TimerMocks.md) doc for more information. + +### `jest.runAllImmediates()` + +Exhausts all tasks queued by `setImmediate()`. + +### `jest.advanceTimersByTime(msToRun)` + +##### renamed in Jest **22.0.0+** + +Also under the alias: `.runTimersToTime()` + +Executes only the macro task queue (i.e. all tasks queued by `setTimeout()` or +`setInterval()` and `setImmediate()`). + +When this API is called, all timers are advanced by `msToRun` milliseconds. All +pending "macro-tasks" that have been queued via `setTimeout()` or +`setInterval()`, and would be executed within this timeframe will be executed. +Additionally if those macro-tasks schedule new macro-tasks that would be +executed within the same time frame, those will be executed until there are no +more macro-tasks remaining in the queue, that should be run within `msToRun` +milliseconds. + +### `jest.runOnlyPendingTimers()` + +Executes only the macro-tasks that are currently pending (i.e., only the tasks +that have been queued by `setTimeout()` or `setInterval()` up to this point). If +any of the currently pending macro-tasks schedule new macro-tasks, those new +tasks will not be executed by this call. + +This is useful for scenarios such as one where the module being tested schedules +a `setTimeout()` whose callback schedules another `setTimeout()` recursively +(meaning the scheduling never stops). In these scenarios, it's useful to be able +to run forward in time by a single step at a time. + +### `jest.setMock(moduleName, moduleExports)` + +Explicitly supplies the mock object that the module system should return for the +specified module. + +On occasion there are times where the automatically generated mock the module +system would normally provide you isn't adequate enough for your testing needs. +Normally under those circumstances you should write a +[manual mock](ManualMocks.md) that is more adequate for the module in question. +However, on extremely rare occasions, even a manual mock isn't suitable for your +purposes and you need to build the mock yourself inside your test. + +In these rare scenarios you can use this API to manually fill the slot in the +module system's mock-module registry. + +Returns the `jest` object for chaining. + +_Note It is recommended to use +[`jest.mock()`](#jestmockmodulename-factory-options) instead. The `jest.mock` +API's second argument is a module factory instead of the expected exported +module object._ + +### `jest.setTimeout(timeout)` + +Set the default timeout interval for tests and before/after hooks in +milliseconds. + +_Note: The default timeout interval is 5 seconds if this method is not called._ + +Example: + +```js +jest.setTimeout(1000); // 1 second +``` + +### `jest.useFakeTimers()` + +Instructs Jest to use fake versions of the standard timer functions +(`setTimeout`, `setInterval`, `clearTimeout`, `clearInterval`, `nextTick`, +`setImmediate` and `clearImmediate`). + +Returns the `jest` object for chaining. + +### `jest.useRealTimers()` + +Instructs Jest to use the real versions of the standard timer functions. + +Returns the `jest` object for chaining. + +### `jest.spyOn(object, methodName)` + +##### available in Jest **19.0.0+** + +Creates a mock function similar to `jest.fn` but also tracks calls to +`object[methodName]`. Returns a Jest mock function. + +_Note: By default, `jest.spyOn` also calls the **spied** method. This is +different behavior from most other test libraries. If you want to overwrite the +original function, you can use +`jest.spyOn(object, methodName).mockImplementation(() => customImplementation)` +or `object[methodName] = jest.fn(() => customImplementation);`_ + +Example: + +```js +const video = { + play() { + return true; + }, +}; + +module.exports = video; +``` + +Example test: + +```js +const video = require('./video'); + +test('plays video', () => { + const spy = jest.spyOn(video, 'play'); + const isPlaying = video.play(); + + expect(spy).toHaveBeenCalled(); + expect(isPlaying).toBe(true); + + spy.mockReset(); + spy.mockRestore(); +}); +``` + +### `jest.spyOn(object, methodName, accessType?)` + +##### available in Jest **22.1.0+** + +Since Jest 22.1.0+, the `jest.spyOn` method takes an optional third argument of +`accessType` that can be either `'get'` or `'set'`, which proves to be useful +when you want to spy on a getter or a setter, respectively. + +Example: + +```js +const video = { + // it's a getter! + get play() { + return true; + }, +}; + +module.exports = video; + +const audio = { + _volume: false, + // it's a setter! + set volume(value) { + this._volume = value; + }, + get volume() { + return this._volume; + }, +}; + +module.exports = video; +``` + +Example test: + +```js +const video = require('./video'); + +test('plays video', () => { + const spy = jest.spyOn(video, 'play', 'get'); // we pass 'get' + const isPlaying = video.play; + + expect(spy).toHaveBeenCalled(); + expect(isPlaying).toBe(true); + + spy.mockReset(); + spy.mockRestore(); +}); + +test('plays audio', () => { + const spy = jest.spyOn(video, 'play', 'set'); // we pass 'set' + video.volume = 100; + + expect(spy).toHaveBeenCalled(); + expect(video.volume).toBe(100); + + spy.mockReset(); + spy.mockRestore(); +}); +``` diff --git a/website/versioned_docs/version-22.0/JestPlatform.md b/website/versioned_docs/version-22.0/JestPlatform.md new file mode 100644 index 000000000000..438f732f1c2d --- /dev/null +++ b/website/versioned_docs/version-22.0/JestPlatform.md @@ -0,0 +1,197 @@ +--- +id: version-22.0-jest-platform +title: Jest Platform +original_id: jest-platform +--- + +You can cherry pick specific features of Jest and use them as standalone +packages. Here's a list of the available packages: + +## jest-changed-files + +Tool for identifying modified files in a git/hg repository. Exports two +functions: + +* `getChangedFilesForRoots` returns a promise that resolves to an object with + the changed files and repos. +* `findRepos` returns a promise that resolves to a set of repositories contained + in the specified path. + +### Example + +```javascript +const {getChangedFilesForRoots} = require('jest-changed-files'); + +// print the set of modified files since last commit in the current repo +getChangedFilesForRoots(['./'], { + lastCommit: true, +}).then(result => console.log(result.changedFiles)); +``` + +You can read more about `jest-changed-files` in the +[readme file](https://github.com/facebook/jest/blob/master/packages/jest-changed-files/README.md). + +## jest-diff + +Tool for visualizing changes in data. Exports a function that compares two +values of any type and returns a "pretty-printed" string illustrating the +difference between the two arguments. + +### Example + +```javascript +const diff = require('jest-diff'); + +const a = {a: {b: {c: 5}}}; +const b = {a: {b: {c: 6}}}; + +const result = diff(a, b); + +// print diff +console.log(result); +``` + +## jest-docblock + +Tool for extracting and parsing the comments at the top of a JavaScript file. +Exports various function to manipulate the data inside the comment block. + +### Example + +```javascript +const {parseWithComments} = require('jest-docblock'); + +const code = ` +/** + * This is a sample + * + * @flow + */ + + console.log('Hello World!'); +`; + +const parsed = parseWithComments(code); + +// prints an object with two attributes: comments and pragmas. +console.log(parsed); +``` + +You can read more about `jest-docblock` in the +[readme file](https://github.com/facebook/jest/blob/master/packages/jest-docblock/README.md). + +## jest-get-type + +Module that identifies the primitive type of any JavaScript value. Exports a +function that returns a string with the type of the value passed as argument. + +### Example + +```javascript +const getType = require('jest-get-type'); + +const array = [1, 2, 3]; +const nullValue = null; +const undefinedValue = undefined; + +// prints 'array' +console.log(getType(array)); +// prints 'null' +console.log(getType(nullValue)); +// prints 'undefined' +console.log(getType(undefinedValue)); +``` + +## jest-validate + +Tool for validating configurations submitted by users. Exports a function that +takes two arguments: the user's configuration and an object containing an +example configuration and other options. The return value is an object with two +attributes: + +* `hasDeprecationWarnings`, a boolean indicating whether the submitted + configuration has deprecation warnings, +* `isValid`, a boolean indicating whether the configuration is correct or not. + +### Example + +```javascript +const {validate} = require('jest-validate'); + +const configByUser = { + transform: '/node_modules/my-custom-transform', +}; + +const result = validate(configByUser, { + comment: ' Documentation: http://custom-docs.com', + exampleConfig: {transform: '/node_modules/babel-jest'}, +}); + +console.log(result); +``` + +You can read more about `jest-validate` in the +[readme file](https://github.com/facebook/jest/blob/master/packages/jest-validate/README.md). + +## jest-worker + +Module used for parallelization of tasks. Exports a class `Worker` that takes +the path of Node.js module and lets you call the module's exported methods as if +they where class methods, returning a promise that resolves when the specified +method finishes its execution in a forked process. + +### Example + +```javascript +// heavy-task.js + +module.exports = { + myHeavyTask: args => { + // long running CPU intensive task. + }, +}; +``` + +```javascript +// main.js + +async function main() { + const worker = new Worker(require.resolve('./heavy-task.js')); + + // run 2 tasks in parellel with different arguments + const results = await Promise.all([ + worker.myHeavyTask({foo: 'bar'}), + worker.myHeavyTask({bar: 'foo'}), + ]); + + console.log(results); +} + +main(); +``` + +You can read more about `jest-worker` in the +[readme file](https://github.com/facebook/jest/blob/master/packages/jest-worker/README.md). + +## pretty-format + +Exports a function that converts any JavaScript value into a human-readable +string. Supports all built-in JavaScript types out of the box and allows +extension for application-specific types via user-defined plugins. + +### Example + +```javascript +const prettyFormat = require('pretty-format'); + +const val = {object: {}}; +val.circularReference = val; +val[Symbol('foo')] = 'foo'; +val.map = new Map([['prop', 'value']]); +val.array = [-0, Infinity, NaN]; + +console.log(prettyFormat(val)); +``` + +You can read more about `pretty-format` in the +[readme file](https://github.com/facebook/jest/blob/master/packages/pretty-format/README.md). diff --git a/website/versioned_docs/version-22.0/ManualMocks.md b/website/versioned_docs/version-22.0/ManualMocks.md new file mode 100644 index 000000000000..4c8f02937a8c --- /dev/null +++ b/website/versioned_docs/version-22.0/ManualMocks.md @@ -0,0 +1,157 @@ +--- +id: version-22.0-manual-mocks +title: Manual Mocks +original_id: manual-mocks +--- + +Manual mocks are used to stub out functionality with mock data. For example, +instead of accessing a remote resource like a website or a database, you might +want to create a manual mock that allows you to use fake data. This ensures your +tests will be fast and not flaky. + +Manual mocks are defined by writing a module in a `__mocks__/` subdirectory +immediately adjacent to the module. For example, to mock a module called `user` +in the `models` directory, create a file called `user.js` and put it in the +`models/__mocks__` directory. Note that the `__mocks__` folder is +case-sensitive, so naming the directory `__MOCKS__` will break on some systems. +If the module you are mocking is a node module (eg: `fs`), the mock should be +placed in the `__mocks__` directory adjacent to `node_modules` (unless you +configured [`roots`](Configuration.md#roots-array-string) to point to a folder +other than the project root). Eg: + +```bash +. +├── config +├── __mocks__ +│   └── fs.js +├── models +│   ├── __mocks__ +│   │   └── user.js +│   └── user.js +├── node_modules +└── views +``` + +When a manual mock exists for a given module, Jest's module system will use that +module when explicitly calling `jest.mock('moduleName')`. However, manual mocks +will take precedence over node modules even if `jest.mock('moduleName')` is not +called. To opt out of this behavior you will need to explicitly call +`jest.unmock('moduleName')` in tests that should use the actual module +implementation. + +Here's a contrived example where we have a module that provides a summary of all +the files in a given directory. + +```javascript +// FileSummarizer.js +'use strict'; + +const fs = require('fs'); + +function summarizeFilesInDirectorySync(directory) { + return fs.readdirSync(directory).map(fileName => ({ + directory, + fileName, + })); +} + +exports.summarizeFilesInDirectorySync = summarizeFilesInDirectorySync; +``` + +Since we'd like our tests to avoid actually hitting the disk (that's pretty slow +and fragile), we create a manual mock for the `fs` module by extending an +automatic mock. Our manual mock will implement custom versions of the `fs` APIs +that we can build on for our tests: + +```javascript +// __mocks__/fs.js +'use strict'; + +const path = require('path'); + +const fs = jest.genMockFromModule('fs'); + +// This is a custom function that our tests can use during setup to specify +// what the files on the "mock" filesystem should look like when any of the +// `fs` APIs are used. +let mockFiles = Object.create(null); +function __setMockFiles(newMockFiles) { + mockFiles = Object.create(null); + for (const file in newMockFiles) { + const dir = path.dirname(file); + + if (!mockFiles[dir]) { + mockFiles[dir] = []; + } + mockFiles[dir].push(path.basename(file)); + } +} + +// A custom version of `readdirSync` that reads from the special mocked out +// file list set via __setMockFiles +function readdirSync(directoryPath) { + return mockFiles[directoryPath] || []; +} + +fs.__setMockFiles = __setMockFiles; +fs.readdirSync = readdirSync; + +module.exports = fs; +``` + +Now we write our test: + +```javascript +// __tests__/FileSummarizer-test.js +'use strict'; + +jest.mock('fs'); + +describe('listFilesInDirectorySync', () => { + const MOCK_FILE_INFO = { + '/path/to/file1.js': 'console.log("file1 contents");', + '/path/to/file2.txt': 'file2 contents', + }; + + beforeEach(() => { + // Set up some mocked out file info before each test + require('fs').__setMockFiles(MOCK_FILE_INFO); + }); + + test('includes all files in the directory in the summary', () => { + const FileSummarizer = require('../FileSummarizer'); + const fileSummary = FileSummarizer.summarizeFilesInDirectorySync( + '/path/to', + ); + + expect(fileSummary.length).toBe(2); + }); +}); +``` + +The example mock shown here uses +[`jest.genMockFromModule`](JestObjectAPI.md#jestgenmockfrommodulemodulename) to +generate an automatic mock, and overrides its default behavior. This is the +recommended approach, but is completely optional. If you do not want to use the +automatic mock at all, you can simply export your own functions from the mock +file. One downside to fully manual mocks is that they're manual – meaning you +have to manually update them any time the module they are mocking changes. +Because of this, it's best to use or extend the automatic mock when it works for +your needs. + +To ensure that a manual mock and its real implementation stay in sync, it might +be useful to require the real module using `require.requireActual(moduleName)` +in your manual mock and amending it with mock functions before exporting it. + +The code for this example is available at +[examples/manual_mocks](https://github.com/facebook/jest/tree/master/examples/manual_mocks). + +### Using with ES module imports + +If you're using +[ES module imports](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import) +then you'll normally be inclined to put your `import` statements at the top of +the test file. But often you need to instruct Jest to use a mock before modules +use it. For this reason, Jest will automatically hoist `jest.mock` calls to the +top of the module (before any imports). To learn more about this and see it in +action, see [this repo](https://github.com/kentcdodds/how-jest-mocking-works). diff --git a/website/versioned_docs/version-22.0/MigrationGuide.md b/website/versioned_docs/version-22.0/MigrationGuide.md new file mode 100644 index 000000000000..336c472e830b --- /dev/null +++ b/website/versioned_docs/version-22.0/MigrationGuide.md @@ -0,0 +1,48 @@ +--- +id: version-22.0-migration-guide +title: Migrating to Jest +original_id: migration-guide +--- + +If you'd like to try out Jest with an existing codebase, there are a number of +ways to convert to Jest: + +* If you are using Jasmine, or a Jasmine like API (for example + [Mocha](https://mochajs.org)), Jest should be mostly compatible and easy to + migrate to. +* If you are using AVA, Expect.js (by Automattic), Jasmine, Mocha, proxyquire, + Should.js or Tape you can automatically migrate with Jest Codemods (see + below). +* If you like [chai](http://chaijs.com/), you can upgrade to Jest and continue + using chai. However, we recommend trying out Jest's assertions and their + failure messages. Jest Codemods can migrate from chai (see below). + +### jest-codemods + +If you are using [AVA](https://github.com/avajs/ava), +[Chai](https://github.com/chaijs/chai), +[Expect.js (by Automattic)](https://github.com/Automattic/expect.js), +[Jasmine](https://github.com/jasmine/jasmine), +[Mocha](https://github.com/mochajs/mocha), +[proxyquire](https://github.com/thlorenz/proxyquire), +[Should.js](https://github.com/tj/should.js/) or +[Tape](https://github.com/substack/tape) you can use the third-party +[jest-codemods](https://github.com/skovhus/jest-codemods) to do most of the +dirty migration work. It runs a code transformation on your codebase using +[jscodeshift](https://github.com/facebook/jscodeshift). + +Install Jest Codemods with `npm` by running: + +``` +npm install -g jest-codemods +``` + +To transform your existing tests, navigate to the project containing the tests +and run: + +``` +jest-codemods +``` + +More information can be found at +[https://github.com/skovhus/jest-codemods](https://github.com/skovhus/jest-codemods). diff --git a/website/versioned_docs/version-22.0/MockFunctionAPI.md b/website/versioned_docs/version-22.0/MockFunctionAPI.md new file mode 100644 index 000000000000..2ec7bb0d3856 --- /dev/null +++ b/website/versioned_docs/version-22.0/MockFunctionAPI.md @@ -0,0 +1,241 @@ +--- +id: version-22.0-mock-function-api +title: Mock Functions +original_id: mock-function-api +--- + +Mock functions are also known as "spies", because they let you spy on the +behavior of a function that is called indirectly by some other code, rather than +just testing the output. You can create a mock function with `jest.fn()`. If no +implementation is given, the mock function will return `undefined` when invoked. + +## Methods + + + +--- + +## Reference + +### `mockFn.getMockName()` + +##### available in Jest **22.0.0+** + +Returns the mock name string set by calling `mockFn.mockName(value)`. + +### `mockFn.mock.calls` + +An array that represents all calls that have been made into this mock function. +Each call is represented by an array of arguments that were passed during the +call. + +For example: A mock function `f` that has been called twice, with the arguments +`f('arg1', 'arg2')`, and then with the arguments `f('arg3', 'arg4')` would have +a `mock.calls` array that looks like this: + +```js +[['arg1', 'arg2'], ['arg3', 'arg4']]; +``` + +### `mockFn.mock.instances` + +An array that contains all the object instances that have been instantiated from +this mock function using `new`. + +For example: A mock function that has been instantiated twice would have the +following `mock.instances` array: + +```js +const mockFn = jest.fn(); + +const a = new mockFn(); +const b = new mockFn(); + +mockFn.mock.instances[0] === a; // true +mockFn.mock.instances[1] === b; // true +``` + +### `mockFn.mockClear()` + +Resets all information stored in the [`mockFn.mock.calls`](#mockfn-mock-calls) +and [`mockFn.mock.instances`](#mockfn-mock-instances) arrays. + +Often this is useful when you want to clean up a mock's usage data between two +assertions. + +Beware that `mockClear` will replace `mockFn.mock`, not just +[`mockFn.mock.calls`](#mockfn-mock-calls) and +[`mockFn.mock.instances`](#mockfn-mock-instances). You should therefore avoid +assigning `mockFn.mock` to other variables, temporary or not, to make sure you +don't access stale data. + +The [`clearMocks`](configuration.html#clearmocks-boolean) configuration option +is available to clear mocks automatically between tests. + +### `mockFn.mockReset()` + +Resets all information stored in the mock, including any initial implementation +and mock name given. + +This is useful when you want to completely restore a mock back to its initial +state. + +Beware that `mockReset` will replace `mockFn.mock`, not just +[`mockFn.mock.calls`](#mockfn-mock-calls) and +[`mockFn.mock.instances`](#mockfn-mock-instances). You should therefore avoid +assigning `mockFn.mock` to other variables, temporary or not, to make sure you +don't access stale data. + +### `mockFn.mockRestore()` + +Removes the mock and restores the initial implementation. + +This is useful when you want to mock functions in certain test cases and restore +the original implementation in others. + +Beware that `mockFn.mockRestore` only works when mock was created with +`jest.spyOn`. Thus you have to take care of restoration yourself when manually +assigning `jest.fn()`. + +### `mockFn.mockImplementation(fn)` + +Accepts a function that should be used as the implementation of the mock. The +mock itself will still record all calls that go into and instances that come +from itself – the only difference is that the implementation will also be +executed when the mock is called. + +_Note: `jest.fn(implementation)` is a shorthand for +`jest.fn().mockImplementation(implementation)`._ + +For example: + +```js +const mockFn = jest.fn().mockImplementation(scalar => 42 + scalar); +// or: jest.fn(scalar => 42 + scalar); + +const a = mockFn(0); +const b = mockFn(1); + +a === 42; // true +b === 43; // true + +mockFn.mock.calls[0][0] === 0; // true +mockFn.mock.calls[1][0] === 1; // true +``` + +`mockImplementation` can also be used to mock class constructors: + +``` +// SomeClass.js +module.exports = class SomeClass { + m(a, b) {} +} + +// OtherModule.test.js +jest.mock('./SomeClass'); // this happens automatically with automocking +const SomeClass = require('./SomeClass') +const mMock = jest.fn() +SomeClass.mockImplementation(() => { + return { + m: mMock + } +}) + +const some = new SomeClass() +some.m('a', 'b') +console.log('Calls to m: ', mMock.mock.calls) +``` + +### `mockFn.mockImplementationOnce(fn)` + +Accepts a function that will be used as an implementation of the mock for one +call to the mocked function. Can be chained so that multiple function calls +produce different results. + +``` +var myMockFn = jest.fn() + .mockImplementationOnce(cb => cb(null, true)) + .mockImplementationOnce(cb => cb(null, false)); + +myMockFn((err, val) => console.log(val)); +> true + +myMockFn((err, val) => console.log(val)); +> false +``` + +When the mocked function runs out of implementations defined with +mockImplementationOnce, it will execute the default implementation set with +`jest.fn(() => defaultValue)` or `.mockImplementation(() => defaultValue)` if +they were called: + +``` +var myMockFn = jest.fn(() => 'default') + .mockImplementationOnce(() => 'first call') + .mockImplementationOnce(() => 'second call'); + +console.log(myMockFn(), myMockFn(), myMockFn(), myMockFn()); +> 'first call', 'second call', 'default', 'default' +``` + +### `mockFn.mockName(value)` + +##### available in Jest **22.0.0+** + +Accepts a string to use in test result output in place of "jest.fn()" to +indicate which mock function is being referenced. + +For example: + +```js +const mockFn = jest.fn().mockName('mockedFunction'); +// mockFn(); +expect(mockFn).toHaveBeenCalled(); +``` + +Will result in this error: + +``` + expect(mockedFunction).toHaveBeenCalled() + + Expected mock function to have been called. +``` + +### `mockFn.mockReturnThis()` + +Just a simple sugar function for: + +```js +jest.fn(function() { + return this; +}); +``` + +### `mockFn.mockReturnValue(value)` + +Accepts a value that will be returned whenever the mock function is called. + +```js +const mock = jest.fn(); +mock.mockReturnValue(42); +mock(); // 42 +mock.mockReturnValue(43); +mock(); // 43 +``` + +### `mockFn.mockReturnValueOnce(value)` + +Accepts a value that will be returned for one call to the mock function. Can be +chained so that successive calls to the mock function return different values. +When there are no more `mockReturnValueOnce` values to use, calls will return a +value specified by `mockReturnValue`. + +``` +const myMockFn = jest.fn() + .mockReturnValue('default') + .mockReturnValueOnce('first call') + .mockReturnValueOnce('second call'); + +console.log(myMockFn(), myMockFn(), myMockFn(), myMockFn()); +> 'first call', 'second call', 'default', 'default' +``` diff --git a/website/versioned_docs/version-22.0/MockFunctions.md b/website/versioned_docs/version-22.0/MockFunctions.md new file mode 100644 index 000000000000..28e1e31cde34 --- /dev/null +++ b/website/versioned_docs/version-22.0/MockFunctions.md @@ -0,0 +1,279 @@ +--- +id: version-22.0-mock-functions +title: Mock Functions +original_id: mock-functions +--- + +Mock functions make it easy to test the links between code by erasing the actual +implementation of a function, capturing calls to the function (and the +parameters passed in those calls), capturing instances of constructor functions +when instantiated with `new`, and allowing test-time configuration of return +values. + +There are two ways to mock functions: Either by creating a mock function to use +in test code, or writing a [`manual mock`](ManualMocks.md) to override a module +dependency. + +## Using a mock function + +Let's imagine we're testing an implementation of a function `forEach`, which +invokes a callback for each item in a supplied array. + +```javascript +function forEach(items, callback) { + for (let index = 0; index < items.length; index++) { + callback(items[index]); + } +} +``` + +To test this function, we can use a mock function, and inspect the mock's state +to ensure the callback is invoked as expected. + +```javascript +const mockCallback = jest.fn(); +forEach([0, 1], mockCallback); + +// The mock function is called twice +expect(mockCallback.mock.calls.length).toBe(2); + +// The first argument of the first call to the function was 0 +expect(mockCallback.mock.calls[0][0]).toBe(0); + +// The first argument of the second call to the function was 1 +expect(mockCallback.mock.calls[1][0]).toBe(1); +``` + +## `.mock` property + +All mock functions have this special `.mock` property, which is where data about +how the function has been called is kept. The `.mock` property also tracks the +value of `this` for each call, so it is possible to inspect this as well: + +```javascript +const myMock = jest.fn(); + +const a = new myMock(); +const b = {}; +const bound = myMock.bind(b); +bound(); + +console.log(myMock.mock.instances); +// > [ , ] +``` + +These mock members are very useful in tests to assert how these functions get +called, or instantiated: + +```javascript +// The function was called exactly once +expect(someMockFunction.mock.calls.length).toBe(1); + +// The first arg of the first call to the function was 'first arg' +expect(someMockFunction.mock.calls[0][0]).toBe('first arg'); + +// The second arg of the first call to the function was 'second arg' +expect(someMockFunction.mock.calls[0][1]).toBe('second arg'); + +// This function was instantiated exactly twice +expect(someMockFunction.mock.instances.length).toBe(2); + +// The object returned by the first instantiation of this function +// had a `name` property whose value was set to 'test' +expect(someMockFunction.mock.instances[0].name).toEqual('test'); +``` + +## Mock Return Values + +Mock functions can also be used to inject test values into your code during a +test: + +```javascript +const myMock = jest.fn(); +console.log(myMock()); +// > undefined + +myMock + .mockReturnValueOnce(10) + .mockReturnValueOnce('x') + .mockReturnValue(true); + +console.log(myMock(), myMock(), myMock(), myMock()); +// > 10, 'x', true, true +``` + +Mock functions are also very effective in code that uses a functional +continuation-passing style. Code written in this style helps avoid the need for +complicated stubs that recreate behavior of the real component they're standing +in for, in favor of injecting values directly into the test right before they're +used. + +```javascript +const filterTestFn = jest.fn(); + +// Make the mock return `true` for the first call, +// and `false` for the second call +filterTestFn.mockReturnValueOnce(true).mockReturnValueOnce(false); + +const result = [11, 12].filter(filterTestFn); + +console.log(result); +// > [11] +console.log(filterTestFn.mock.calls); +// > [ [11], [12] ] +``` + +Most real-world examples actually involve getting ahold of a mock function on a +dependent component and configuring that, but the technique is the same. In +these cases, try to avoid the temptation to implement logic inside of any +function that's not directly being tested. + +## Mock Implementations + +Still, there are cases where it's useful to go beyond the ability to specify +return values and full-on replace the implementation of a mock function. This +can be done with `jest.fn` or the `mockImplementationOnce` method on mock +functions. + +```javascript +const myMockFn = jest.fn(cb => cb(null, true)); + +myMockFn((err, val) => console.log(val)); +// > true + +myMockFn((err, val) => console.log(val)); +// > true +``` + +The `mockImplementation` method is useful when you need to define the default +implementation of a mock function that is created from another module: + +```js +// foo.js +module.exports = function() { + // some implementation; +}; + +// test.js +jest.mock('../foo'); // this happens automatically with automocking +const foo = require('../foo'); + +// foo is a mock function +foo.mockImplementation(() => 42); +foo(); +// > 42 +``` + +When you need to recreate a complex behavior of a mock function such that +multiple function calls produce different results, use the +`mockImplementationOnce` method: + +```javascript +const myMockFn = jest + .fn() + .mockImplementationOnce(cb => cb(null, true)) + .mockImplementationOnce(cb => cb(null, false)); + +myMockFn((err, val) => console.log(val)); +// > true + +myMockFn((err, val) => console.log(val)); +// > false +``` + +When the mocked function runs out of implementations defined with +`mockImplementationOnce`, it will execute the default implementation set with +`jest.fn` (if it is defined): + +```javascript +const myMockFn = jest + .fn(() => 'default') + .mockImplementationOnce(() => 'first call') + .mockImplementationOnce(() => 'second call'); + +console.log(myMockFn(), myMockFn(), myMockFn(), myMockFn()); +// > 'first call', 'second call', 'default', 'default' +``` + +For cases where we have methods that are typically chained (and thus always need +to return `this`), we have a sugary API to simplify this in the form of a +`.mockReturnThis()` function that also sits on all mocks: + +```javascript +const myObj = { + myMethod: jest.fn().mockReturnThis(), +}; + +// is the same as + +const otherObj = { + myMethod: jest.fn(function() { + return this; + }), +}; +``` + +## Mock Names + +##### available in Jest **22.0.0+** + +You can optionally provide a name for your mock functions, which will be +displayed instead of "jest.fn()" in test error output. Use this if you want to +be able to quickly identify the mock function reporting an error in your test +output. + +```javascript +const myMockFn = jest + .fn() + .mockReturnValue('default') + .mockImplementation(scalar => 42 + scalar) + .mockName('add42'); +``` + +## Custom Matchers + +Finally, in order to make it simpler to assert how mock functions have been +called, we've added some custom matcher functions for you: + +```javascript +// The mock function was called at least once +expect(mockFunc).toBeCalled(); + +// The mock function was called at least once with the specified args +expect(mockFunc).toBeCalledWith(arg1, arg2); + +// The last call to the mock function was called with the specified args +expect(mockFunc).lastCalledWith(arg1, arg2); + +// All calls and the name of the mock is written as a snapshot +expect(mockFunc).toMatchSnapshot(); +``` + +These matchers are really just sugar for common forms of inspecting the `.mock` +property. You can always do this manually yourself if that's more to your taste +or if you need to do something more specific: + +```javascript +// The mock function was called at least once +expect(mockFunc.mock.calls.length).toBeGreaterThan(0); + +// The mock function was called at least once with the specified args +expect(mockFunc.mock.calls).toContain([arg1, arg2]); + +// The last call to the mock function was called with the specified args +expect(mockFunc.mock.calls[mockFunc.mock.calls.length - 1]).toEqual([ + arg1, + arg2, +]); + +// The first arg of the last call to the mock function was `42` +// (note that there is no sugar helper for this specific of an assertion) +expect(mockFunc.mock.calls[mockFunc.mock.calls.length - 1][0]).toBe(42); + +// A snapshot will check that a mock was invoked the same number of times, +// in the same order, with the same arguments. It will also assert on the name. +expect(mockFunc.mock.calls).toEqual([[arg1, arg2]]); +expect(mockFunc.mock.getMockName()).toBe('a mock name'); +``` + +For a complete list of matchers, check out the [reference docs](ExpectAPI.md). diff --git a/website/versioned_docs/version-22.0/MoreResources.md b/website/versioned_docs/version-22.0/MoreResources.md new file mode 100644 index 000000000000..df85907a9e5e --- /dev/null +++ b/website/versioned_docs/version-22.0/MoreResources.md @@ -0,0 +1,41 @@ +--- +id: version-22.0-more-resources +title: More Resources +original_id: more-resources +--- + +By now you should have a good idea of how Jest can make it easy to test your +applications. If you're interested in learning more, here's some related stuff +you might want to check out. + +### Browse the docs + +* Learn about [Snapshot Testing](SnapshotTesting.md), + [Mock Functions](MockFunctions.md), and more in our in-depth guides. +* Migrate your existing tests to Jest by following our + [migration guide](MigrationGuide.md). +* Learn how to [configure Jest](Configuration.md). +* Look at the full [API Reference](GlobalAPI.md). +* [Troubleshoot](Troubleshooting.md) problems with Jest. + +### Learn by example + +You will find a number of example test cases in the +[`examples`](https://github.com/facebook/jest/tree/master/examples) folder on +GitHub. You can also learn from the excellent tests used by the +[React](https://github.com/facebook/react/tree/master/src/renderers/__tests__), +[Relay](https://github.com/facebook/relay/tree/master/packages/react-relay/modern/__tests__), +and +[React Native](https://github.com/facebook/react-native/tree/master/Libraries/Animated/src/__tests__) +projects. + +### Join the community + +Ask questions and find answers from other Jest users like you. +[Reactiflux](http://www.reactiflux.com/) is a Discord chat where a lot of Jest +discussion happens. Check out the +[#jest](https://discordapp.com/channels/102860784329052160/103622435865104384) +channel. + +Follow the [Jest Twitter account](https://twitter.com/fbjest) and +[blog](/jest/blog/) to find out what's happening in the world of Jest. diff --git a/website/versioned_docs/version-22.0/Puppeteer.md b/website/versioned_docs/version-22.0/Puppeteer.md new file mode 100644 index 000000000000..89802f51bfb7 --- /dev/null +++ b/website/versioned_docs/version-22.0/Puppeteer.md @@ -0,0 +1,103 @@ +--- +id: version-22.0-puppeteer +title: Using with puppeteer +original_id: puppeteer +--- + +With the [Global Setup/Teardown](Configuration.md#globalsetup-string) and +[Async Test Environment](Configuration.md#testenvironment-string) APIs, Jest can +work smoothly with [puppeteer](https://github.com/GoogleChrome/puppeteer). + +## A jest-puppeteer example + +The basic idea is to: + +1. launch & file the websocket endpoint of puppeteer with Global Setup +2. connect to puppeteer from each Test Environment +3. close puppeteer with Global Teardown + +Here's an example of the GlobalSetup script + +```js +// setup.js +module.exports = async function() { + const browser = await puppeteer.launch(); + // store the browser instance so we can teardown it later + global.__BROWSER__ = browser; + + // file the wsEndpoint for TestEnvironments + mkdirp.sync(DIR); + fs.writeFileSync(path.join(DIR, 'wsEndpoint'), browser.wsEndpoint()); +}; +``` + +Then we need a custom Test Environment for puppeteer + +```js +// puppeteer_environment.js +class PuppeteerEnvironment extends NodeEnvironment { + constructor(config) { + super(config); + } + + async setup() { + await super.setup(); + // get the wsEndpoint + const wsEndpoint = fs.readFileSync(path.join(DIR, 'wsEndpoint'), 'utf8'); + if (!wsEndpoint) { + throw new Error('wsEndpoint not found'); + } + + // connect to puppeteer + this.global.__BROWSER__ = await puppeteer.connect({ + browserWSEndpoint: wsEndpoint, + }); + } + + async teardown() { + await super.teardown(); + } + + runScript(script) { + return super.runScript(script); + } +} +``` + +Finally we can close the puppeteer instance and clean-up the file + +```js +// teardown.js +module.exports = async function() { + // close the browser instance + await global.__BROWSER__.close(); + + // clean-up the wsEndpoint file + rimraf.sync(DIR); +}; +``` + +With all the things set up, we can now write our tests like this: + +```js +// test.js +describe( + '/ (Home Page)', + () => { + let page; + beforeAll(async () => { + page = await global.__BROWSER__.newPage(); + await page.goto('https://google.com'); + }, timeout); + + it('should load without error', async () => { + const text = await page.evaluate(() => document.body.textContent); + expect(text).toContain('google'); + }); + }, + timeout, +); +``` + +Here's the code of +[full working example](https://github.com/xfumihiro/jest-puppeteer-example). diff --git a/website/versioned_docs/version-22.0/SetupAndTeardown.md b/website/versioned_docs/version-22.0/SetupAndTeardown.md new file mode 100644 index 000000000000..8bb3b1c17d74 --- /dev/null +++ b/website/versioned_docs/version-22.0/SetupAndTeardown.md @@ -0,0 +1,222 @@ +--- +id: version-22.0-setup-teardown +title: Setup and Teardown +original_id: setup-teardown +--- + +Often while writing tests you have some setup work that needs to happen before +tests run, and you have some finishing work that needs to happen after tests +run. Jest provides helper functions to handle this. + +### Repeating Setup For Many Tests + +If you have some work you need to do repeatedly for many tests, you can use +`beforeEach` and `afterEach`. + +For example, let's say that several tests interact with a database of cities. +You have a method `initializeCityDatabase()` that must be called before each of +these tests, and a method `clearCityDatabase()` that must be called after each +of these tests. You can do this with: + +```js +beforeEach(() => { + initializeCityDatabase(); +}); + +afterEach(() => { + clearCityDatabase(); +}); + +test('city database has Vienna', () => { + expect(isCity('Vienna')).toBeTruthy(); +}); + +test('city database has San Juan', () => { + expect(isCity('San Juan')).toBeTruthy(); +}); +``` + +`beforeEach` and `afterEach` can handle asynchronous code in the same ways that +[tests can handle asynchronous code](TestingAsyncCode.md) - they can either take +a `done` parameter or return a promise. For example, if +`initializeCityDatabase()` returned a promise that resolved when the database +was initialized, we would want to return that promise: + +```js +beforeEach(() => { + return initializeCityDatabase(); +}); +``` + +### One-Time Setup + +In some cases, you only need to do setup once, at the beginning of a file. This +can be especially bothersome when the setup is asynchronous, so you can't just +do it inline. Jest provides `beforeAll` and `afterAll` to handle this situation. + +For example, if both `initializeCityDatabase` and `clearCityDatabase` returned +promises, and the city database could be reused between tests, we could change +our test code to: + +```js +beforeAll(() => { + return initializeCityDatabase(); +}); + +afterAll(() => { + return clearCityDatabase(); +}); + +test('city database has Vienna', () => { + expect(isCity('Vienna')).toBeTruthy(); +}); + +test('city database has San Juan', () => { + expect(isCity('San Juan')).toBeTruthy(); +}); +``` + +### Scoping + +By default, the `before` and `after` blocks apply to every test in a file. You +can also group tests together using a `describe` block. When they are inside a +`describe` block, the `before` and `after` blocks only apply to the tests within +that `describe` block. + +For example, let's say we had not just a city database, but also a food +database. We could do different setup for different tests: + +```js +// Applies to all tests in this file +beforeEach(() => { + return initializeCityDatabase(); +}); + +test('city database has Vienna', () => { + expect(isCity('Vienna')).toBeTruthy(); +}); + +test('city database has San Juan', () => { + expect(isCity('San Juan')).toBeTruthy(); +}); + +describe('matching cities to foods', () => { + // Applies only to tests in this describe block + beforeEach(() => { + return initializeFoodDatabase(); + }); + + test('Vienna <3 sausage', () => { + expect(isValidCityFoodPair('Vienna', 'Wiener Schnitzel')).toBe(true); + }); + + test('San Juan <3 plantains', () => { + expect(isValidCityFoodPair('San Juan', 'Mofongo')).toBe(true); + }); +}); +``` + +Note that the top-level `beforeEach` is executed before the `beforeEach` inside +the `describe` block. It may help to illustrate the order of execution of all +hooks. + +```js +beforeAll(() => console.log('1 - beforeAll')); +afterAll(() => console.log('1 - afterAll')); +beforeEach(() => console.log('1 - beforeEach')); +afterEach(() => console.log('1 - afterEach')); +test('', () => console.log('1 - test')); +describe('Scoped / Nested block', () => { + beforeAll(() => console.log('2 - beforeAll')); + afterAll(() => console.log('2 - afterAll')); + beforeEach(() => console.log('2 - beforeEach')); + afterEach(() => console.log('2 - afterEach')); + test('', () => console.log('2 - test')); +}); + +// 1 - beforeAll +// 1 - beforeEach +// 1 - test +// 1 - afterEach +// 2 - beforeAll +// 1 - beforeEach +// 2 - beforeEach +// 2 - test +// 2 - afterEach +// 1 - afterEach +// 2 - afterAll +// 1 - afterAll +``` + +### Order of execution of describe and test blocks + +Jest executes all describe handlers in a test file _before_ it executes any of +the actual tests. This is another reason to do setup and teardown in `before*` +and `after*` handlers rather in the describe blocks. Once the describe blocks +are complete, by default Jest runs all the tests serially in the order they were +encountered in the collection phase, waiting for each to finish and be tidied up +before moving on. + +Consider the following illustrative test file and output: + +```js +describe('outer', () => { + console.log('describe outer-a'); + + describe('describe inner 1', () => { + console.log('describe inner 1'); + test('test 1', () => { + console.log('test for describe inner 1'); + expect(true).toEqual(true); + }); + }); + + console.log('describe outer-b'); + + test('test 1', () => { + console.log('test for describe outer'); + expect(true).toEqual(true); + }); + + describe('describe inner 2', () => { + console.log('describe inner 2'); + test('test for describe inner 2', () => { + console.log('test for describe inner 2'); + expect(false).toEqual(false); + }); + }); + + console.log('describe outer-c'); +}); + +// describe outer-a +// describe inner 1 +// describe outer-b +// describe inner 2 +// describe outer-c +// test for describe inner 1 +// test for describe outer +// test for describe inner 2 +``` + +### General Advice + +If a test is failing, one of the first things to check should be whether the +test is failing when it's the only test that runs. In Jest it's simple to run +only one test - just temporarily change that `test` command to a `test.only`: + +```js +test.only('this will be the only test that runs', () => { + expect(true).toBe(false); +}); + +test('this test will not run', () => { + expect('A').toBe('A'); +}); +``` + +If you have a test that often fails when it's run as part of a larger suite, but +doesn't fail when you run it alone, it's a good bet that something from a +different test is interfering with this one. You can often fix this by clearing +some shared state with `beforeEach`. If you're not sure whether some shared +state is being modified, you can also try a `beforeEach` that just logs data. diff --git a/website/versioned_docs/version-22.0/SnapshotTesting.md b/website/versioned_docs/version-22.0/SnapshotTesting.md new file mode 100644 index 000000000000..9bacb3cbc825 --- /dev/null +++ b/website/versioned_docs/version-22.0/SnapshotTesting.md @@ -0,0 +1,222 @@ +--- +id: version-22.0-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://facebook.github.io/jest/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: + +![](/jest/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: + +``` +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. + +### Tests Should Be Deterministic + +Your tests should be deterministic. That is, 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: + +``` +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. + +### Snapshots are not written automatically on Continuous Integration systems (CI) + +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. + +## Frequently Asked Questions + +### 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](TutorialReacte.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/integration_tests/__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](http://facebook.github.io/jest/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-22.0/TestingAsyncCode.md b/website/versioned_docs/version-22.0/TestingAsyncCode.md new file mode 100644 index 000000000000..3c8288ba8e2a --- /dev/null +++ b/website/versioned_docs/version-22.0/TestingAsyncCode.md @@ -0,0 +1,160 @@ +--- +id: version-22.0-asynchronous +title: Testing Asynchronous Code +original_id: asynchronous +--- + +It's common in JavaScript for code to run asynchronously. When you have code +that runs asynchronously, Jest needs to know when the code it is testing has +completed, before it can move on to another test. Jest has several ways to +handle this. + +### Callbacks + +The most common asynchronous pattern is callbacks. + +For example, let's say that you have a `fetchData(callback)` function that +fetches some data and calls `callback(data)` when it is complete. You want to +test that this returned data is just the string `'peanut butter'`. + +By default, Jest tests complete once they reach the end of their execution. That +means this test will _not_ work as intended: + +```js +// Don't do this! +test('the data is peanut butter', () => { + function callback(data) { + expect(data).toBe('peanut butter'); + } + + fetchData(callback); +}); +``` + +The problem is that the test will complete as soon as `fetchData` completes, +before ever calling the callback. + +There is an alternate form of `test` that fixes this. Instead of putting the +test in a function with an empty argument, use a single argument called `done`. +Jest will wait until the `done` callback is called before finishing the test. + +```js +test('the data is peanut butter', done => { + function callback(data) { + expect(data).toBe('peanut butter'); + done(); + } + + fetchData(callback); +}); +``` + +If `done()` is never called, the test will fail, which is what you want to +happen. + +### Promises + +If your code uses promises, there is a simpler way to handle asynchronous tests. +Just return a promise from your test, and Jest will wait for that promise to +resolve. If the promise is rejected, the test will automatically fail. + +For example, let's say that `fetchData`, instead of using a callback, returns a +promise that is supposed to resolve to the string `'peanut butter'`. We could +test it with: + +```js +test('the data is peanut butter', () => { + expect.assertions(1); + return fetchData().then(data => { + expect(data).toBe('peanut butter'); + }); +}); +``` + +Be sure to return the promise - if you omit this `return` statement, your test +will complete before `fetchData` completes. + +If you expect a promise to be rejected use 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 +test('the fetch fails with an error', () => { + expect.assertions(1); + return fetchData().catch(e => expect(e).toMatch('error')); +}); +``` + +### `.resolves` / `.rejects` + +##### available in Jest **20.0.0+** + +You can also use the `.resolves` matcher in your expect statement, and Jest will +wait for that promise to resolve. If the promise is rejected, the test will +automatically fail. + +```js +test('the data is peanut butter', () => { + expect.assertions(1); + return expect(fetchData()).resolves.toBe('peanut butter'); +}); +``` + +Be sure to return the assertion—if you omit this `return` statement, your test +will complete before `fetchData` completes. + +If you expect a promise to be rejected use the `.rejects` matcher. It works +analogically to the `.resolves` matcher. If the promise is fulfilled, the test +will automatically fail. + +```js +test('the fetch fails with an error', () => { + expect.assertions(1); + return expect(fetchData()).rejects.toMatch('error'); +}); +``` + +### Async/Await + +Alternatively, you can use `async` and `await` in your tests. To write an async +test, just use the `async` keyword in front of the function passed to `test`. +For example, the same `fetchData` scenario can be tested with: + +```js +test('the data is peanut butter', async () => { + expect.assertions(1); + const data = await fetchData(); + expect(data).toBe('peanut butter'); +}); + +test('the fetch fails with an error', async () => { + expect.assertions(1); + try { + await fetchData(); + } catch (e) { + expect(e).toMatch('error'); + } +}); +``` + +Of course, you can combine `async` and `await` with `.resolves` or `.rejects` +(available in Jest **20.0.0+**). + +```js +test('the data is peanut butter', async () => { + expect.assertions(1); + await expect(fetchData()).resolves.toBe('peanut butter'); +}); + +test('the fetch fails with an error', async () => { + expect.assertions(1); + await expect(fetchData()).rejects.toMatch('error'); +}); +``` + +In these cases, `async` and `await` are effectively just syntactic sugar for the +same logic as the promises example uses. + +None of these forms is particularly superior to the others, and you can mix and +match them across a codebase or even in a single file. It just depends on which +style makes your tests simpler. diff --git a/website/versioned_docs/version-22.0/TestingFrameworks.md b/website/versioned_docs/version-22.0/TestingFrameworks.md new file mode 100644 index 000000000000..9766001d3fb9 --- /dev/null +++ b/website/versioned_docs/version-22.0/TestingFrameworks.md @@ -0,0 +1,39 @@ +--- +id: version-22.0-testing-frameworks +title: Testing Web Frameworks +original_id: testing-frameworks +--- + +Although Jest may be considered a React-specific test runner, in fact it is a +universal testing platform, with the ability to adapt to any JavaScript library +or framework. In this section we'd like to link to community posts and articles +about integrating Jest into other popular JS libraries. + +## Vue.js + +* [Testing Vue.js components with Jest](https://alexjoverm.github.io/series/Unit-Testing-Vue-js-Components-with-the-Official-Vue-Testing-Tools-and-Jest/) + by Alex Jover Morales ([@alexjoverm](https://twitter.com/alexjoverm)) +* [Jest for all: Episode 1 — Vue.js](https://medium.com/@kentaromiura_the_js_guy/jest-for-all-episode-1-vue-js-d616bccbe186#.d573vrce2) + by Cristian Carlesso ([@kentaromiura](https://twitter.com/kentaromiura)) + +## AngularJS + +* [Testing an AngularJS app with Jest](https://medium.com/aya-experience/testing-an-angularjs-app-with-jest-3029a613251) + by Matthieu Lux ([@Swiip](https://twitter.com/Swiip)) +* [Running AngularJS Tests with Jest](https://engineering.talentpair.com/running-angularjs-tests-with-jest-49d0cc9c6d26) + by Ben Brandt ([@benjaminbrandt](https://twitter.com/benjaminbrandt)) + +## Angular + +* [Testing Angular faster with Jest](https://www.xfive.co/blog/testing-angular-faster-jest/) + by Michał Pierzchała ([@thymikee](https://twitter.com/thymikee)) + +## MobX + +* [How to Test React and MobX with Jest](https://semaphoreci.com/community/tutorials/how-to-test-react-and-mobx-with-jest) + by Will Stern ([@willsterndev](https://twitter.com/willsterndev)) + +## Redux + +* [Writing Tests](http://redux.js.org/docs/recipes/WritingTests.html) by Redux + docs diff --git a/website/versioned_docs/version-22.0/TimerMocks.md b/website/versioned_docs/version-22.0/TimerMocks.md new file mode 100644 index 000000000000..297772e740a5 --- /dev/null +++ b/website/versioned_docs/version-22.0/TimerMocks.md @@ -0,0 +1,182 @@ +--- +id: version-22.0-timer-mocks +title: Timer Mocks +original_id: timer-mocks +--- + +The native timer functions (i.e., `setTimeout`, `setInterval`, `clearTimeout`, +`clearInterval`) are less than ideal for a testing environment since they depend +on real time to elapse. Jest can swap out timers with functions that allow you +to control the passage of time. +[Great Scott!](https://www.youtube.com/watch?v=5gVv10J4nio) + +```javascript +// timerGame.js +'use strict'; + +function timerGame(callback) { + console.log('Ready....go!'); + setTimeout(() => { + console.log('Times up -- stop!'); + callback && callback(); + }, 1000); +} + +module.exports = timerGame; +``` + +```javascript +// __tests__/timerGame-test.js +'use strict'; + +jest.useFakeTimers(); + +test('waits 1 second before ending the game', () => { + const timerGame = require('../timerGame'); + timerGame(); + + expect(setTimeout).toHaveBeenCalledTimes(1); + expect(setTimeout).toHaveBeenLastCalledWith(expect.any(Function), 1000); +}); +``` + +Here we enable fake timers by calling `jest.useFakeTimers();`. This mocks out +setTimeout and other timer functions with mock functions. + +## Run All Timers + +Another test we might want to write for this module is one that asserts that the +callback is called after 1 second. To do this, we're going to use Jest's timer +control APIs to fast-forward time right in the middle of the test: + +```javascript +test('calls the callback after 1 second', () => { + const timerGame = require('../timerGame'); + const callback = jest.fn(); + + timerGame(callback); + + // At this point in time, the callback should not have been called yet + expect(callback).not.toBeCalled(); + + // Fast-forward until all timers have been executed + jest.runAllTimers(); + + // Now our callback should have been called! + expect(callback).toBeCalled(); + expect(callback).toHaveBeenCalledTimes(1); +}); +``` + +## Run Pending Timers + +There are also scenarios where you might have a recursive timer -- that is a +timer that sets a new timer in its own callback. For these, running all the +timers would be an endless loop… so something like `jest.runAllTimers()` is not +desirable. For these cases you might use `jest.runOnlyPendingTimers()`: + +```javascript +// infiniteTimerGame.js +'use strict'; + +function infiniteTimerGame(callback) { + console.log('Ready....go!'); + + setTimeout(() => { + console.log('Times up! 10 seconds before the next game starts...'); + callback && callback(); + + // Schedule the next game in 10 seconds + setTimeout(() => { + infiniteTimerGame(callback); + }, 10000); + }, 1000); +} + +module.exports = infiniteTimerGame; +``` + +```javascript +// __tests__/infiniteTimerGame-test.js +'use strict'; + +jest.useFakeTimers(); + +describe('infiniteTimerGame', () => { + test('schedules a 10-second timer after 1 second', () => { + const infiniteTimerGame = require('../infiniteTimerGame'); + const callback = jest.fn(); + + infiniteTimerGame(callback); + + // At this point in time, there should have been a single call to + // setTimeout to schedule the end of the game in 1 second. + expect(setTimeout).toHaveBeenCalledTimes(1); + expect(setTimeout).toHaveBeenLastCalledWith(expect.any(Function), 1000); + + // Fast forward and exhaust only currently pending timers + // (but not any new timers that get created during that process) + jest.runOnlyPendingTimers(); + + // At this point, our 1-second timer should have fired it's callback + expect(callback).toBeCalled(); + + // And it should have created a new timer to start the game over in + // 10 seconds + expect(setTimeout).toHaveBeenCalledTimes(2); + expect(setTimeout).toHaveBeenLastCalledWith(expect.any(Function), 10000); + }); +}); +``` + +## Advance Timers by Time + +##### renamed from `runTimersToTime` to `advanceTimersByTime` in Jest **22.0.0** + +Another possibility is use `jest.advanceTimersByTime(msToRun)`. When this API is +called, all timers are advanced by `msToRun` milliseconds. All pending +"macro-tasks" that have been queued via setTimeout() or setInterval(), and would +be executed during this timeframe, will be executed. Additionally if those +macro-tasks schedule new macro-tasks that would be executed within the same time +frame, those will be executed until there are no more macro-tasks remaining in +the queue that should be run within msToRun milliseconds. + +```javascript +// timerGame.js +'use strict'; + +function timerGame(callback) { + console.log('Ready....go!'); + setTimeout(() => { + console.log('Times up -- stop!'); + callback && callback(); + }, 1000); +} + +module.exports = timerGame; +``` + +```javascript +it('calls the callback after 1 second via advanceTimersByTime', () => { + const timerGame = require('../timerGame'); + const callback = jest.fn(); + + timerGame(callback); + + // At this point in time, the callback should not have been called yet + expect(callback).not.toBeCalled(); + + // Fast-forward until all timers have been executed + jest.advanceTimersByTime(1000); + + // Now our callback should have been called! + expect(callback).toBeCalled(); + expect(callback).toHaveBeenCalledTimes(1); +}); +``` + +Lastly, it may occasionally be useful in some tests to be able to clear all of +the pending timers. For this, we have `jest.clearAllTimers()`. + +The code for this example is available at +[examples/timer](https://github.com/facebook/jest/tree/master/examples/timer). diff --git a/website/versioned_docs/version-22.0/Troubleshooting.md b/website/versioned_docs/version-22.0/Troubleshooting.md new file mode 100644 index 000000000000..ac74b963ffcc --- /dev/null +++ b/website/versioned_docs/version-22.0/Troubleshooting.md @@ -0,0 +1,317 @@ +--- +id: version-22.0-troubleshooting +title: Troubleshooting +original_id: troubleshooting +--- + +Uh oh, something went wrong? Use this guide to resolve issues with Jest. + +### Tests are Failing and You Don't Know Why + +Try using the debugging support built into Node. + +Place a `debugger;` statement in any of your tests, and then, in your project's +directory, run: + +``` +node --inspect-brk node_modules/.bin/jest --runInBand [any other arguments here] +or on Windows +node --inspect-brk ./node_modules/jest/bin/jest.js --runInBand [any other arguments here] +``` + +This will run Jest in a Node process that an external debugger can connect to. +Note that the process will pause until the debugger has connected to it. + +To debug in Google Chrome (or any Chromium-based browser), simply open your +browser and go to `chrome://inspect` and click on "Open Dedicated DevTools for +Node", which will give you a list of available node instances you can connect +to. Simply click on the address displayed in the terminal (usually something +like `localhost:9229`) after running the above command, and you will be able to +debug Jest using Chrome's DevTools. + +The Chrome Developer Tools will be displayed, and a breakpoint will be set at +the first line of the Jest CLI script (this is done simply to give you time to +open the developer tools and to prevent Jest from executing before you have time +to do so). Click the button that looks like a "play" button in the upper right +hand side of the screen to continue execution. When Jest executes the test that +contains the `debugger` statement, execution will pause and you can examine the +current scope and call stack. + +> Note: the `--runInBand` cli option makes sure Jest runs test in the same +> process rather than spawning processes for individual tests. Normally Jest +> parallelizes test runs across processes but it is hard to debug many processes +> at the same time. + +### Debugging in VS Code + +There are multiple ways to debug Jest tests with +[Visual Studio Code's](https://code.visualstudio.com) built in +[debugger](https://code.visualstudio.com/docs/nodejs/nodejs-debugging). + +To attach the built-in debugger, run your tests as aforementioned: + +``` +node --inspect-brk node_modules/.bin/jest --runInBand [any other arguments here] +or on Windows +node --inspect-brk ./node_modules/jest/bin/jest.js --runInBand [any other arguments here] +``` + +Then attach VS Code's debugger using the following `launch.json` config: + +```json +{ + "version": "0.2.0", + "configurations": [ + { + "type": "node", + "request": "attach", + "name": "Attach", + "port": 9229 + } + ] +} +``` + +To automatically launch and attach to a process running your tests, use the +following configuration: + +```json +{ + "version": "0.2.0", + "configurations": [ + { + "name": "Debug Jest Tests", + "type": "node", + "request": "launch", + "runtimeArgs": [ + "--inspect-brk", + "${workspaceRoot}/node_modules/.bin/jest", + "--runInBand" + ], + "console": "integratedTerminal", + "internalConsoleOptions": "neverOpen" + } + ] +} +``` + +or the following for Windows: + +```json +{ + "version": "0.2.0", + "configurations": [ + { + "name": "Debug Jest Tests", + "type": "node", + "request": "launch", + "runtimeArgs": [ + "--inspect-brk", + "${workspaceRoot}/node_modules/jest/bin/jest.js", + "--runInBand" + ], + "console": "integratedTerminal", + "internalConsoleOptions": "neverOpen" + } + ] +} +``` + +If you are using Facebook's +[`create-react-app`](https://github.com/facebookincubator/create-react-app), you +can debug your Jest tests with the following configuration: + +```json +{ + "version": "0.2.0", + "configurations": [ + { + "name": "Debug CRA Tests", + "type": "node", + "request": "launch", + "runtimeExecutable": "${workspaceRoot}/node_modules/.bin/react-scripts", + "args": ["test", "--runInBand", "--no-cache", "--env=jsdom"], + "cwd": "${workspaceRoot}", + "protocol": "inspector", + "console": "integratedTerminal", + "internalConsoleOptions": "neverOpen" + } + ] +} +``` + +More information on Node debugging can be found +[here](https://nodejs.org/api/debugger.html). + +### Debugging in WebStorm + +The easiest way to debug Jest tests in +[WebStorm](https://www.jetbrains.com/webstorm/) is using +`Jest run/debug configuration`. It will launch tests and automatically attach +debugger. + +In the WebStorm menu `Run` select `Edit Configurations...`. Then click `+` and +select `Jest`. Optionally specify the Jest configuration file, additional +options, and environment variables. Save the configuration, put the breakpoints +in the code, then click the green debug icon to start debugging. + +If you are using Facebook's +[`create-react-app`](https://github.com/facebookincubator/create-react-app), in +the Jest run/debug configuration specify the path to the `react-scripts` package +in the Jest package field and add `--env=jsdom` to the Jest options field. + +### Caching Issues + +The transform script was changed or babel was updated and the changes aren't +being recognized by Jest? + +Retry with [`--no-cache`](CLI.md#cache). Jest caches transformed module files to +speed up test execution. If you are using your own custom transformer, consider +adding a `getCacheKey` function to it: +[getCacheKey in Relay](https://github.com/facebook/relay/blob/58cf36c73769690f0bbf90562707eadb062b029d/scripts/jest/preprocessor.js#L56-L61). + +### Unresolved Promises + +If a promise doesn't resolve at all, this error might be thrown: + +``` +- Error: Timeout - Async callback was not invoked within timeout specified by jasmine.DEFAULT_TIMEOUT_INTERVAL.` +``` + +Most commonly this is being caused by conflicting Promise implementations. +Consider replacing the global promise implementation with your own, for example +`global.Promise = require.requireActual('promise');` and/or consolidate the used +Promise libraries to a single one. + +If your test is long running, you may want to consider to increase the timeout +by calling `jest.setTimeout` + +``` +jest.setTimeout(10000); // 10 second timeout +``` + +### Watchman Issues + +Try running Jest with [`--no-watchman`](CLI.md#watchman) or set the `watchman` +configuration option to `false`. + +Also see +[watchman troubleshooting](https://facebook.github.io/watchman/docs/troubleshooting.html). + +### Tests are Extremely Slow on Docker and/or Continuous Integration (CI) server. + +While Jest is most of the time extremely fast on modern multi-core computers +with fast SSDs, it may be slow on certain setups as our users +[have](https://github.com/facebook/jest/issues/1395) +[discovered](https://github.com/facebook/jest/issues/1524#issuecomment-260246008). + +Based on the +[findings](https://github.com/facebook/jest/issues/1524#issuecomment-262366820), +one way to mitigate this issue and improve the speed by up to 50% is to run +tests sequentially. + +In order to do this you can run tests in the same thread using +[`--runInBand`](CLI.md#runinband): + +```bash +# Using Jest CLI +jest --runInBand + +# Using npm test (e.g. with create-react-app) +npm test -- --runInBand +``` + +Another alternative to expediting test execution time on Continuous Integration +Servers such as Travis-CI is to set the max worker pool to ~_4_. Specifically on +Travis-CI, this can reduce test execution time in half. Note: The Travis CI +_free_ plan available for open source projects only includes 2 CPU cores. + +```bash +# Using Jest CLI +jest --maxWorkers=4 + +# Using npm test (e.g. with create-react-app) +npm test -- --maxWorkers=4 +``` + +### Tests are slow when leveraging automocking + +Whether via [`automock: true`](configuration.html#automock-boolean) in config or +lots of +[`jest.mock('my-module')`](jest-object.html#jestmockmodulename-factory-options) +calls in tests, automocking has a performance cost that can add up in large +projects. The more dependencies a module has, the more work Jest has to do to +mock it. Something that can offset this performance cost significantly is adding +a code transformer that moves `import` or `require` calls from the top of a +module, where they are always executed, down into the body of the module, where +they are usually not executed. This can lower the number of modules Jest has to +load when running your tests by a considerable amount. + +To transform `import` statements, there is +[babel-plugin-transform-inline-imports-commonjs](https://github.com/zertosh/babel-plugin-transform-inline-imports-commonjs), +and to transform `require` statements, there is +[Facebook's `inline-requires` babel plugin](https://github.com/facebook/fbjs/blob/master/packages/babel-preset-fbjs/plugins/inline-requires.js), +which is part of the `babel-preset-fbjs` package. + +### I'm using npm3 and my node_modules aren't properly loading. + +Upgrade `jest-cli` to `0.9.0` or above. + +### I'm using babel and my unmocked imports aren't working? + +Upgrade `jest-cli` to `0.9.0` or above. + +Explanation: + +```js +jest.dontMock('foo'); + +import foo from './foo'; +``` + +In ES6, import statements get hoisted before all other + +```js +const foo = require('foo'); +jest.dontMock('foo'); // Oops! +``` + +In Jest 0.9.0, a new API `jest.unmock` was introduced. Together with a plugin +for babel, this will now work properly when using `babel-jest`: + +```js +jest.unmock('./foo'); // Use unmock! + +import foo from './foo'; + +// foo is not mocked! +``` + +See the [Getting Started]GettingStarted.md#using-babel) guide on how to enable +babel support. + +### I upgraded to Jest 0.9.0 and my tests are now failing? + +Jest is now using Jasmine 2 by default. It should be easy to upgrade using the +Jasmine [upgrade guide](http://jasmine.github.io/2.0/introduction.html). + +If you would like to continue using Jasmine 1, set the `testRunner` config +option to `jasmine1` or pass `--testRunner=jasmine1` as a command line option. + +### Compatibility issues + +Jest takes advantage of new features added to Node 4. We recommend that you +upgrade to the latest stable release of Node. The minimum supported version is +`v4.0.0`. Versions `0.x.x` are not supported. + +### `coveragePathIgnorePatterns` seems to not have any effect. + +Make sure you are not using the `babel-plugin-istanbul` plugin. Jest wraps +Istanbul, and therefore also tells Istanbul what files to instrument with +coverage collection. When using `babel-plugin-istanbul`, every file that is +processed by Babel will have coverage collection code, hence it is not being +ignored by `coveragePathIgnorePatterns`. + +### Still unresolved? + +See [Help](/jest/help.html). diff --git a/website/versioned_docs/version-22.0/TutorialAsync.md b/website/versioned_docs/version-22.0/TutorialAsync.md new file mode 100644 index 000000000000..19355a5cb90c --- /dev/null +++ b/website/versioned_docs/version-22.0/TutorialAsync.md @@ -0,0 +1,190 @@ +--- +id: version-22.0-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` + +##### available in Jest **20.0.0+** + +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', async () => { + 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` + +##### available in Jest **20.0.0+** + +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-22.0/TutorialReact.md b/website/versioned_docs/version-22.0/TutorialReact.md new file mode 100644 index 000000000000..e27edbf2d010 --- /dev/null +++ b/website/versioned_docs/version-22.0/TutorialReact.md @@ -0,0 +1,302 @@ +--- +id: version-22.0-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 don't need to do any extra steps for setup, and can head straight to the +next section. + +### 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 +npm install --save-dev jest babel-jest babel-preset-es2015 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-es2015": "", + "babel-preset-react": "", + "jest": "", + "react-test-renderer": "" + }, + "scripts": { + "test": "jest" + } +``` + +```json +// .babelrc +{ + "presets": ["es2015", "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 `npm 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). + +### 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 `npm install --save-dev enzyme` to use Enzyme. If you are using +a React below version 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], + retainLines: true, + }).code; + } + 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-22.0/TutorialReactNative.md b/website/versioned_docs/version-22.0/TutorialReactNative.md new file mode 100644 index 000000000000..256ccb74dd49 --- /dev/null +++ b/website/versioned_docs/version-22.0/TutorialReactNative.md @@ -0,0 +1,285 @@ +--- +id: version-22.0-tutorial-react-native +title: Testing React Native Apps +original_id: tutorial-react-native +--- + +At Facebook, we use Jest to test +[React Native](http://facebook.github.io/react-native/) applications. + +Get a deeper insight into testing a working React Native app example by reading +the following series: +[Part 1: Jest – Snapshot come into play](https://blog.callstack.io/unit-testing-react-native-with-the-new-jest-i-snapshots-come-into-play-68ba19b1b9fe#.12zbnbgwc) +and +[Part 2: Jest – Redux Snapshots for your Actions and Reducers](https://blog.callstack.io/unit-testing-react-native-with-the-new-jest-ii-redux-snapshots-for-your-actions-and-reducers-8559f6f8050b). + +## Setup + +Starting from react-native version 0.38, a Jest setup is included by default +when running `react-native init`. The following configuration should be +automatically added to your package.json file: + +```json +// package.json + "scripts": { + "test": "jest" + }, + "jest": { + "preset": "react-native" + } +``` + +_Note: If you are upgrading your react-native application and previously used +the `jest-react-native` preset, remove the dependency from your `package.json` +file and change the preset to `react-native` instead._ + +Simply run `npm test` to run tests with Jest. + +## Snapshot Test + +Let's create a [snapshot test](SnapshotTesting.md) for a small intro component +with a few views and text components and some styles: + +```javascript +// Intro.js +import React, {Component} from 'react'; +import {StyleSheet, Text, View} from 'react-native'; + +const styles = StyleSheet.create({ + container: { + alignItems: 'center', + backgroundColor: '#F5FCFF', + flex: 1, + justifyContent: 'center', + }, + instructions: { + color: '#333333', + marginBottom: 5, + textAlign: 'center', + }, + welcome: { + fontSize: 20, + margin: 10, + textAlign: 'center', + }, +}); + +export default class Intro extends Component { + render() { + return ( + + Welcome to React Native! + + This is a React Native snapshot test. + + + ); + } +} +``` + +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 +// __tests__/Intro-test.js +import 'react-native'; +import React from 'react'; +import Intro from '../Intro'; + +// Note: test renderer must be required after react-native. +import renderer from 'react-test-renderer'; + +test('renders correctly', () => { + const tree = renderer.create().toJSON(); + expect(tree).toMatchSnapshot(); +}); +``` + +When you run `npm test` or `jest`, this will produce an output file like this: + +```javascript +// __tests__/__snapshots__/Intro-test.js.snap +exports[`Intro renders correctly 1`] = ` + + + Welcome to React Native! + + + This is a React Native snapshot test. + + +`; +``` + +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/react-native](https://github.com/facebook/jest/tree/master/examples/react-native). + +## Preset configuration + +The preset sets up the environment and is very opinionated and based on what we +found to be useful at Facebook. All of the configuration options can be +overwritten just as they can be customized when no preset is used. + +### Environment + +`react-native` ships with a Jest preset, so the `jest.preset` field of your +`package.json` should point to `react-native`. The preset is a node environment +that mimics the environment of a React Native app. Because it doesn't load any +DOM or browser APIs, it greatly improves Jest's startup time. + +### transformIgnorePatterns customization + +The +[`transformIgnorePatterns`](configuration.html#transformignorepatterns-array-string) +option can be used to whitelist or blacklist files from being transformed with +babel. Many react-native npm modules unfortunately don't pre-compile their +source code before publishing. + +By default the jest-react-native preset only processes the project's own source +files and react-native. If you have npm dependencies that have to be transformed +you can customize this configuration option by whitelisting modules other than +react-native: + +```json +"transformIgnorePatterns": [ + "node_modules/(?!(react-native|my-project|react-native-button)/)" +] +``` + +### setupFiles + +If you'd like to provide additional configuration for every test file, the +[`setupFiles` configuration option](configuration.html#setupfiles-array) can be +used to specify setup scripts. + +### moduleNameMapper + +The +[`moduleNameMapper`](configuration.html#modulenamemapper-object-string-string) +can be used to map a module path to a different module. By default the preset +maps all images to an image stub module but if a module cannot be found this +configuration option can help: + +```json +"moduleNameMapper": { + "my-module.js": "/path/to/my-module.js" +} +``` + +## Tips + +### Mock native modules using jest.mock + +The Jest preset built into `react-native` comes with a few default mocks that +are applied on a react-native repository. However some react-native components +or third party components rely on native code to be rendered. In such cases, +Jest's manual mocking system can help to mock out the underlying implementation. + +For example, if your code depends on a third party native video component called +`react-native-video` you might want to stub it out with a manual mock like this: + +```js +jest.mock('react-native-video', () => 'Video'); +``` + +This will render the component as `