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

Jump to bottom

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 all 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.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.md
View file
Open in desktop
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)
- `[*]` Move @types/node to the root package.json [#8129](https://github.com/facebook/jest/pull/8129)

### Performance
Expand Down
42 changes: 26 additions & 16 deletions docs/ExpectAPI.md
View file
Open in desktop
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,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.

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

Expand All @@ -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
Expand Down Expand Up @@ -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) {
Expand Down Expand Up @@ -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.
42 changes: 26 additions & 16 deletions website/versioned_docs/version-24.0/ExpectAPI.md
View file
Open in desktop
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,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.

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

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