Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore: Improve description of optional arguments in ExpectAPI.md #8126

Merged
merged 5 commits into from
Mar 17, 2019
Merged

chore: Improve description of optional arguments in ExpectAPI.md #8126

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
1246431
chore: Improve description of optional arguments in ExpectAPI.md
pedrottimark Mar 14, 2019
7ea0b88
Add missing argument toThrowErrorMatchingInlineSnapshot
pedrottimark Mar 14, 2019
2fdb39f
Update CHANGELOG.md
pedrottimark Mar 14, 2019
d5ed9af
Rewrite snapshotName paragraph and add inlineSnapshot paragraph
pedrottimark Mar 15, 2019
c188014
Resolve merge conflict in CHANGELOG.md
pedrottimark Mar 15, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
34 changes: 20 additions & 14 deletions docs/ExpectAPI.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand All @@ -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()`

Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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)`
Expand Down Expand Up @@ -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:

Expand All @@ -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
Expand Down Expand Up @@ -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.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I find this description convoluted around "snapshot key" and "nam arguments of containing blocks". Can we make it simpler?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, thank you. What do you think of this rewrite?

You can provide an optional snapshotName string argument for the snapshot key. It follows the concatenated name arguments of containing blocks and precedes the final number (that Jest appends in case an it or test block contains multiple snapshot assertions).

I deleted the comment that I wrote in the main thread by mistake.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

s/multiple snapshot assertions/more than one snapshot assertion/

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How about:

You can provide an optional snapshotName string argument that will be appended to the corresponding test title in .snap file, followed by a number that Jest appends to differentiate between snapshots created during single it or test block.

(the number is always appended)

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh btw, can you mention that snapshots are sorted in alphabetical order for stability? I don't see this mentioned anywhere in the docs


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) {
Expand Down Expand Up @@ -1242,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.

Expand Down
34 changes: 20 additions & 14 deletions website/versioned_docs/version-24.0/ExpectAPI.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand All @@ -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()`

Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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)`
Expand Down Expand Up @@ -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:

Expand All @@ -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
Expand Down Expand Up @@ -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) {
Expand Down Expand Up @@ -1243,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.

Expand Down