From 12464311a9ff8a68b4acd9494ca71b7314080143 Mon Sep 17 00:00:00 2001 From: Mark Pedrotti Date: Thu, 14 Mar 2019 16:18:07 -0400 Subject: [PATCH 1/4] chore: Improve description of optional arguments in ExpectAPI.md --- docs/ExpectAPI.md | 32 +++++++++++-------- .../versioned_docs/version-24.0/ExpectAPI.md | 32 +++++++++++-------- 2 files changed, 38 insertions(+), 26 deletions(-) diff --git a/docs/ExpectAPI.md b/docs/ExpectAPI.md index aae714b09239..2865698e0fb4 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,20 +1113,22 @@ 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 for the snapshot key, in addition to the concatenated name arguments of containing blocks. Jest also appends `1`, `2`, `3`, and so on to snapshot keys, in case an `it` or `test` block contains multiple snapshot assertions. _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. +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. + Check out the section on [Inline Snapshots](SnapshotTesting.md#inline-snapshots) for more info. ### `.toStrictEqual(value)` @@ -1154,9 +1156,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 +1170,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 +1211,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. + +You can provide an optional `snapshotName` string argument for the snapshot key, in addition to the concatenated name arguments of containing blocks. Jest also appends `1`, `2`, `3`, and so on to snapshot keys, in case an `it` or `test` block contains multiple snapshot assertions. -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: +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) { diff --git a/website/versioned_docs/version-24.0/ExpectAPI.md b/website/versioned_docs/version-24.0/ExpectAPI.md index 6ad2f0fef75d..f054a642a85b 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,20 +1114,22 @@ 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 for the snapshot key, in addition to the concatenated name arguments of containing blocks. Jest also appends `1`, `2`, `3`, and so on to snapshot keys, in case an `it` or `test` block contains multiple snapshot assertions. _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. +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. + Check out the section on [Inline Snapshots](SnapshotTesting.md#inline-snapshots) for more info. ### `.toStrictEqual(value)` @@ -1155,9 +1157,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 +1171,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 +1212,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. + +You can provide an optional `snapshotName` string argument for the snapshot key, in addition to the concatenated name arguments of containing blocks. Jest also appends `1`, `2`, `3`, and so on to snapshot keys, in case an `it` or `test` block contains multiple snapshot assertions. -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: +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) { From 7ea0b888ed5426b692354d4634dbbf774826987b Mon Sep 17 00:00:00 2001 From: Mark Pedrotti Date: Thu, 14 Mar 2019 16:33:01 -0400 Subject: [PATCH 2/4] Add missing argument toThrowErrorMatchingInlineSnapshot --- docs/ExpectAPI.md | 2 +- website/versioned_docs/version-24.0/ExpectAPI.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/ExpectAPI.md b/docs/ExpectAPI.md index 2865698e0fb4..96133dd6ad4c 100644 --- a/docs/ExpectAPI.md +++ b/docs/ExpectAPI.md @@ -1248,7 +1248,7 @@ 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)` 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. diff --git a/website/versioned_docs/version-24.0/ExpectAPI.md b/website/versioned_docs/version-24.0/ExpectAPI.md index f054a642a85b..7307c4745dc4 100644 --- a/website/versioned_docs/version-24.0/ExpectAPI.md +++ b/website/versioned_docs/version-24.0/ExpectAPI.md @@ -1249,7 +1249,7 @@ 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)` 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. From 2fdb39f9ff9c2bd1c215a09b5cd0cb8c7d4ad271 Mon Sep 17 00:00:00 2001 From: Mark Pedrotti Date: Thu, 14 Mar 2019 16:34:41 -0400 Subject: [PATCH 3/4] Update CHANGELOG.md --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 2efb5c4e8048..7808de03f4d8 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) ### Performance From d5ed9af4cc097d345652c596cbd7238651cdf573 Mon Sep 17 00:00:00 2001 From: Mark Pedrotti Date: Fri, 15 Mar 2019 11:53:21 -0400 Subject: [PATCH 4/4] Rewrite snapshotName paragraph and add inlineSnapshot paragraph --- docs/ExpectAPI.md | 12 ++++++++---- website/versioned_docs/version-24.0/ExpectAPI.md | 12 ++++++++---- 2 files changed, 16 insertions(+), 8 deletions(-) diff --git a/docs/ExpectAPI.md b/docs/ExpectAPI.md index 96133dd6ad4c..d6c923774093 100644 --- a/docs/ExpectAPI.md +++ b/docs/ExpectAPI.md @@ -1119,16 +1119,18 @@ This ensures that a value matches the most recent snapshot. Check out [the Snaps 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. -You can provide an optional `snapshotName` string argument for the snapshot key, in addition to the concatenated name arguments of containing blocks. Jest also appends `1`, `2`, `3`, and so on to snapshot keys, in case an `it` or `test` block contains multiple snapshot assertions. +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)` -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. ### `.toStrictEqual(value)` @@ -1215,7 +1217,7 @@ test('throws on octopus', () => { Use `.toThrowErrorMatchingSnapshot` to test that a function throws an error matching the most recent snapshot when it is called. -You can provide an optional `snapshotName` string argument for the snapshot key, in addition to the concatenated name arguments of containing blocks. Jest also appends `1`, `2`, `3`, and so on to snapshot keys, in case an `it` or `test` block contains multiple snapshot assertions. +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: @@ -1250,6 +1252,8 @@ Check out [React Tree Snapshot Testing](https://jestjs.io/blog/2016/07/27/jest-1 ### `.toThrowErrorMatchingInlineSnapshot(inlineSnapshot)` -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. +Use `.toThrowErrorMatchingInlineSnapshot` to test that a function throws an error matching the most recent snapshot when it is called. + +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 7307c4745dc4..44d213022d83 100644 --- a/website/versioned_docs/version-24.0/ExpectAPI.md +++ b/website/versioned_docs/version-24.0/ExpectAPI.md @@ -1120,16 +1120,18 @@ This ensures that a value matches the most recent snapshot. Check out [the Snaps 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. -You can provide an optional `snapshotName` string argument for the snapshot key, in addition to the concatenated name arguments of containing blocks. Jest also appends `1`, `2`, `3`, and so on to snapshot keys, in case an `it` or `test` block contains multiple snapshot assertions. +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)` -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. ### `.toStrictEqual(value)` @@ -1216,7 +1218,7 @@ test('throws on octopus', () => { Use `.toThrowErrorMatchingSnapshot` to test that a function throws an error matching the most recent snapshot when it is called. -You can provide an optional `snapshotName` string argument for the snapshot key, in addition to the concatenated name arguments of containing blocks. Jest also appends `1`, `2`, `3`, and so on to snapshot keys, in case an `it` or `test` block contains multiple snapshot assertions. +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: @@ -1251,6 +1253,8 @@ Check out [React Tree Snapshot Testing](https://jestjs.io/blog/2016/07/27/jest-1 ### `.toThrowErrorMatchingInlineSnapshot(inlineSnapshot)` -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. +Use `.toThrowErrorMatchingInlineSnapshot` to test that a function throws an error matching the most recent snapshot when it is called. + +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.