diff --git a/CHANGELOG.md b/CHANGELOG.md index 786c91a3a910..8d1c2d804a70 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,7 @@ - `[*]` Remove flow from code base ([#8061](https://github.com/facebook/jest/pull/8061)) - `[*]` Use property initializer syntax in Jest codebase [#8117](https://github.com/facebook/jest/pull/8117) +- `[docs]` Improve description of optional arguments in ExpectAPI.md [#8126](https://github.com/facebook/jest/pull/8126) - `[*]` Move @types/node to the root package.json [#8129](https://github.com/facebook/jest/pull/8129) ### Performance diff --git a/docs/ExpectAPI.md b/docs/ExpectAPI.md index aae714b09239..d6c923774093 100644 --- a/docs/ExpectAPI.md +++ b/docs/ExpectAPI.md @@ -745,7 +745,7 @@ test('drink returns expected nth calls', () => { Note: the nth argument must be positive integer starting from 1. -### `.toBeCloseTo(number, numDigits)` +### `.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: @@ -765,7 +765,7 @@ test('adding works sanely with simple decimals', () => { }); ``` -The default for `numDigits` is 2, which has proved to be a good default in most cases. +The optional `numDigits` argument has default value `2` which means the criterion is `Math.abs(expected - received) < 0.005` (that is, `10 ** -2 / 2`). ### `.toBeDefined()` @@ -1059,11 +1059,11 @@ describe('toMatchObject applied to arrays', () => { }); ``` -### `.toHaveProperty(keyPath, value)` +### `.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. +You can provide an optional `value` argument to compare the received property value (recursively for all properties of object instances, also known as deep equality, like the `toEqual` matcher). 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. @@ -1113,19 +1113,23 @@ test('this house has my desired features', () => { }); ``` -### `.toMatchSnapshot(propertyMatchers, snapshotName)` +### `.toMatchSnapshot(propertyMatchers?, snapshotName?)` This ensures that a value matches the most recent snapshot. Check out [the Snapshot Testing guide](SnapshotTesting.md) for more information. -The optional `propertyMatchers` argument allows you to specify asymmetric matchers which are verified instead of the exact values. Any value will be matched exactly if not provided as a matcher. +You can provide an optional `propertyMatchers` object argument, which has asymmetric matchers as values of a subset of expected properties, **if** the received value will be an **object** instance. It is like `toMatchObject` with flexible criteria for a subset of properties, followed by a snapshot test as exact criteria for the rest of the properties. -The last argument allows you option to specify a snapshot name. Otherwise, the name is inferred from the test. +You can provide an optional `snapshotName` string argument that is appended to the test name. Jest always appends a number at the end of a snapshot key to differentiate snapshots from a single `it` or `test` block. Jest sorts snapshots by key in the corresponding `.snap` file. _Note: While snapshot testing is most commonly used with React components, any serializable value can be used as a snapshot._ -### `.toMatchInlineSnapshot(propertyMatchers, inlineSnapshot)` +### `.toMatchInlineSnapshot(propertyMatchers?, inlineSnapshot)` -Ensures that a value matches the most recent snapshot. Unlike [`.toMatchSnapshot()`](#tomatchsnapshotpropertymatchers-snapshotname), the snapshots will be written to the current source file, inline. +Ensures that a value matches the most recent snapshot. + +You can provide an optional `propertyMatchers` object argument, which has asymmetric matchers as values of a subset of expected properties, **if** the received value will be an **object** instance. It is like `toMatchObject` with flexible criteria for a subset of properties, followed by a snapshot test as exact criteria for the rest of the properties. + +Jest adds the `inlineSnapshot` string argument to the matcher in the test file (instead of an external `.snap` file) the first time that the test runs. Check out the section on [Inline Snapshots](SnapshotTesting.md#inline-snapshots) for more info. @@ -1154,9 +1158,9 @@ describe('the La Croix cans on my desk', () => { }); ``` -### `.toThrow(error)` +### `.toThrow(error?)` -Also under the alias: `.toThrowError(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: @@ -1168,7 +1172,7 @@ test('throws on octopus', () => { }); ``` -To test that a specific error is thrown, you can provide an argument: +You can provide an optional argument to test that a specific error is thrown: - regular expression: error message **matches** the pattern - string: error message **includes** the substring @@ -1209,9 +1213,13 @@ test('throws on octopus', () => { > Note: You must wrap the code in a function, otherwise the error will not be caught and the assertion will fail. -### `.toThrowErrorMatchingSnapshot()` +### `.toThrowErrorMatchingSnapshot(snapshotName?)` + +Use `.toThrowErrorMatchingSnapshot` to test that a function throws an error matching the most recent snapshot when it is called. -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: +You can provide an optional `snapshotName` string argument that is appended to the test name. Jest always appends a number at the end of a snapshot key to differentiate snapshots from a single `it` or `test` block. Jest sorts snapshots by key in the corresponding `.snap` file. + +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) { @@ -1242,8 +1250,10 @@ exports[`drinking flavors throws on octopus 1`] = `"yuck, octopus flavor"`; Check out [React Tree Snapshot Testing](https://jestjs.io/blog/2016/07/27/jest-14.html) for more information on snapshot testing. -### `.toThrowErrorMatchingInlineSnapshot()` +### `.toThrowErrorMatchingInlineSnapshot(inlineSnapshot)` + +Use `.toThrowErrorMatchingInlineSnapshot` to test that a function throws an error matching the most recent snapshot when it is called. -This matcher is much like [`.toThrowErrorMatchingSnapshot`](#tothrowerrormatchingsnapshot), except instead of writing the snapshot value to a `.snap` file, it will be written into the source code automatically. +Jest adds the `inlineSnapshot` string argument to the matcher in the test file (instead of an external `.snap` file) the first time that the test runs. Check out the section on [Inline Snapshots](SnapshotTesting.md#inline-snapshots) for more info. diff --git a/website/versioned_docs/version-24.0/ExpectAPI.md b/website/versioned_docs/version-24.0/ExpectAPI.md index 6ad2f0fef75d..44d213022d83 100644 --- a/website/versioned_docs/version-24.0/ExpectAPI.md +++ b/website/versioned_docs/version-24.0/ExpectAPI.md @@ -746,7 +746,7 @@ test('drink returns expected nth calls', () => { Note: the nth argument must be positive integer starting from 1. -### `.toBeCloseTo(number, numDigits)` +### `.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: @@ -766,7 +766,7 @@ test('adding works sanely with simple decimals', () => { }); ``` -The default for `numDigits` is 2, which has proved to be a good default in most cases. +The optional `numDigits` argument has default value `2` which means the criterion is `Math.abs(expected - received) < 0.005` (that is, `10 ** -2 / 2`). ### `.toBeDefined()` @@ -1060,11 +1060,11 @@ describe('toMatchObject applied to arrays', () => { }); ``` -### `.toHaveProperty(keyPath, value)` +### `.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. +You can provide an optional `value` argument to compare the received property value (recursively for all properties of object instances, also known as deep equality, like the `toEqual` matcher). 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. @@ -1114,19 +1114,23 @@ test('this house has my desired features', () => { }); ``` -### `.toMatchSnapshot(propertyMatchers, snapshotName)` +### `.toMatchSnapshot(propertyMatchers?, snapshotName?)` This ensures that a value matches the most recent snapshot. Check out [the Snapshot Testing guide](SnapshotTesting.md) for more information. -The optional `propertyMatchers` argument allows you to specify asymmetric matchers which are verified instead of the exact values. Any value will be matched exactly if not provided as a matcher. +You can provide an optional `propertyMatchers` object argument, which has asymmetric matchers as values of a subset of expected properties, **if** the received value will be an **object** instance. It is like `toMatchObject` with flexible criteria for a subset of properties, followed by a snapshot test as exact criteria for the rest of the properties. -The last argument allows you option to specify a snapshot name. Otherwise, the name is inferred from the test. +You can provide an optional `snapshotName` string argument that is appended to the test name. Jest always appends a number at the end of a snapshot key to differentiate snapshots from a single `it` or `test` block. Jest sorts snapshots by key in the corresponding `.snap` file. _Note: While snapshot testing is most commonly used with React components, any serializable value can be used as a snapshot._ -### `.toMatchInlineSnapshot(propertyMatchers, inlineSnapshot)` +### `.toMatchInlineSnapshot(propertyMatchers?, inlineSnapshot)` -Ensures that a value matches the most recent snapshot. Unlike [`.toMatchSnapshot()`](#tomatchsnapshotpropertymatchers-snapshotname), the snapshots will be written to the current source file, inline. +Ensures that a value matches the most recent snapshot. + +You can provide an optional `propertyMatchers` object argument, which has asymmetric matchers as values of a subset of expected properties, **if** the received value will be an **object** instance. It is like `toMatchObject` with flexible criteria for a subset of properties, followed by a snapshot test as exact criteria for the rest of the properties. + +Jest adds the `inlineSnapshot` string argument to the matcher in the test file (instead of an external `.snap` file) the first time that the test runs. Check out the section on [Inline Snapshots](SnapshotTesting.md#inline-snapshots) for more info. @@ -1155,9 +1159,9 @@ describe('the La Croix cans on my desk', () => { }); ``` -### `.toThrow(error)` +### `.toThrow(error?)` -Also under the alias: `.toThrowError(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: @@ -1169,7 +1173,7 @@ test('throws on octopus', () => { }); ``` -To test that a specific error is thrown, you can provide an argument: +You can provide an optional argument to test that a specific error is thrown: - regular expression: error message **matches** the pattern - string: error message **includes** the substring @@ -1210,9 +1214,13 @@ test('throws on octopus', () => { > Note: You must wrap the code in a function, otherwise the error will not be caught and the assertion will fail. -### `.toThrowErrorMatchingSnapshot()` +### `.toThrowErrorMatchingSnapshot(snapshotName?)` + +Use `.toThrowErrorMatchingSnapshot` to test that a function throws an error matching the most recent snapshot when it is called. -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: +You can provide an optional `snapshotName` string argument that is appended to the test name. Jest always appends a number at the end of a snapshot key to differentiate snapshots from a single `it` or `test` block. Jest sorts snapshots by key in the corresponding `.snap` file. + +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) { @@ -1243,8 +1251,10 @@ exports[`drinking flavors throws on octopus 1`] = `"yuck, octopus flavor"`; Check out [React Tree Snapshot Testing](https://jestjs.io/blog/2016/07/27/jest-14.html) for more information on snapshot testing. -### `.toThrowErrorMatchingInlineSnapshot()` +### `.toThrowErrorMatchingInlineSnapshot(inlineSnapshot)` + +Use `.toThrowErrorMatchingInlineSnapshot` to test that a function throws an error matching the most recent snapshot when it is called. -This matcher is much like [`.toThrowErrorMatchingSnapshot`](#tothrowerrormatchingsnapshot), except instead of writing the snapshot value to a `.snap` file, it will be written into the source code automatically. +Jest adds the `inlineSnapshot` string argument to the matcher in the test file (instead of an external `.snap` file) the first time that the test runs. Check out the section on [Inline Snapshots](SnapshotTesting.md#inline-snapshots) for more info.