Add this.extend to the Custom Matchers API reference (#7130)

* Add this.expand to custom matchers API docs

* Update CHANGELOG.md

* Update language

CHANGELOG.md

@@ -34,6 +34,7 @@
 
 ### Chore & Maintenance
 
+- `[docs]` Add `this.extend` to the Custom Matchers API reference ([#7130](https://github.com/facebook/jest/pull/7130))
 - `[docs]` Fix default value for `coverageReporters` value in configuration docs ([#7126](https://github.com/facebook/jest/pull/7126))
 - `[docs]` Add link for jest-extended in expect docs ([#7078](https://github.com/facebook/jest/pull/7078))
 - `[jest-util]` Add ErrorWithStack class ([#7067](https://github.com/facebook/jest/pull/7067))

docs/ExpectAPI.md

@@ -113,7 +113,7 @@ expect.extend({
 });
 ```
 
-These helper functions can be found on `this` inside a custom matcher:
+These helper functions and properties can be found on `this` inside a custom matcher:
 
 #### `this.isNot`
 
@@ -123,6 +123,10 @@ A boolean to let you know this matcher was called with the negated `.not` modifi
 
 This is a deep-equality function that will return `true` if two objects have the same values (recursively).
 
+#### `this.expand`
+
+A boolean to let you know this matcher was called with an `expand` option. When Jest is called with the `--expand` flag, `this.expand` can be used to determine if Jest is expected to show full diffs and errors.
+
 #### `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).

website/versioned_docs/version-22.0/ExpectAPI.md

@@ -63,7 +63,7 @@ test('even and odd numbers', () => {
 
 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:
+These helper functions and properties can be found on `this` inside a custom matcher:
 
 #### `this.isNot`
 
@@ -73,6 +73,10 @@ A boolean to let you know this matcher was called with the negated `.not` modifi
 
 This is a deep-equality function that will return `true` if two objects have the same values (recursively).
 
+#### `this.expand`
+
+A boolean to let you know this matcher was called with an `expand` option. When Jest is called with the `--expand` flag, `this.expand` can be used to determine if Jest is expected to show full diffs and errors.
+
 #### `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).

website/versioned_docs/version-22.1/ExpectAPI.md

@@ -63,7 +63,7 @@ test('even and odd numbers', () => {
 
 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:
+These helper functions and properties can be found on `this` inside a custom matcher:
 
 #### `this.isNot`
 
@@ -73,6 +73,10 @@ A boolean to let you know this matcher was called with the negated `.not` modifi
 
 This is a deep-equality function that will return `true` if two objects have the same values (recursively).
 
+#### `this.expand`
+
+A boolean to let you know this matcher was called with an `expand` option. When Jest is called with the `--expand` flag, `this.expand` can be used to determine if Jest is expected to show full diffs and errors.
+
 #### `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).

website/versioned_docs/version-22.2/ExpectAPI.md

@@ -63,7 +63,7 @@ test('even and odd numbers', () => {
 
 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:
+These helper functions and properties can be found on `this` inside a custom matcher:
 
 #### `this.isNot`
 
@@ -73,6 +73,10 @@ A boolean to let you know this matcher was called with the negated `.not` modifi
 
 This is a deep-equality function that will return `true` if two objects have the same values (recursively).
 
+#### `this.expand`
+
+A boolean to let you know this matcher was called with an `expand` option. When Jest is called with the `--expand` flag, `this.expand` can be used to determine if Jest is expected to show full diffs and errors.
+
 #### `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).

website/versioned_docs/version-22.3/ExpectAPI.md

@@ -63,7 +63,7 @@ test('even and odd numbers', () => {
 
 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:
+These helper functions and properties can be found on `this` inside a custom matcher:
 
 #### `this.isNot`
 
@@ -73,6 +73,10 @@ A boolean to let you know this matcher was called with the negated `.not` modifi
 
 This is a deep-equality function that will return `true` if two objects have the same values (recursively).
 
+#### `this.expand`
+
+A boolean to let you know this matcher was called with an `expand` option. When Jest is called with the `--expand` flag, `this.expand` can be used to determine if Jest is expected to show full diffs and errors.
+
 #### `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).

website/versioned_docs/version-23.0/ExpectAPI.md

@@ -96,7 +96,7 @@ test('is divisible by external value', async () => {
 
 Matchers should return an object (or a Promise of 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:
+These helper functions and properties can be found on `this` inside a custom matcher:
 
 #### `this.isNot`
 
@@ -106,6 +106,10 @@ A boolean to let you know this matcher was called with the negated `.not` modifi
 
 This is a deep-equality function that will return `true` if two objects have the same values (recursively).
 
+#### `this.expand`
+
+A boolean to let you know this matcher was called with an `expand` option. When Jest is called with the `--expand` flag, `this.expand` can be used to determine if Jest is expected to show full diffs and errors.
+
 #### `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).

website/versioned_docs/version-23.1/ExpectAPI.md

@@ -96,7 +96,7 @@ test('is divisible by external value', async () => {
 
 Matchers should return an object (or a Promise of 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:
+These helper functions and properties can be found on `this` inside a custom matcher:
 
 #### `this.isNot`
 
@@ -106,6 +106,10 @@ A boolean to let you know this matcher was called with the negated `.not` modifi
 
 This is a deep-equality function that will return `true` if two objects have the same values (recursively).
 
+#### `this.expand`
+
+A boolean to let you know this matcher was called with an `expand` option. When Jest is called with the `--expand` flag, `this.expand` can be used to determine if Jest is expected to show full diffs and errors.
+
 #### `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).

website/versioned_docs/version-23.2/ExpectAPI.md

@@ -96,7 +96,7 @@ test('is divisible by external value', async () => {
 
 Matchers should return an object (or a Promise of 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:
+These helper functions and properties can be found on `this` inside a custom matcher:
 
 #### `this.isNot`
 
@@ -106,6 +106,10 @@ A boolean to let you know this matcher was called with the negated `.not` modifi
 
 This is a deep-equality function that will return `true` if two objects have the same values (recursively).
 
+#### `this.expand`
+
+A boolean to let you know this matcher was called with an `expand` option. When Jest is called with the `--expand` flag, `this.expand` can be used to determine if Jest is expected to show full diffs and errors.
+
 #### `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).

website/versioned_docs/version-23.3/ExpectAPI.md

@@ -96,7 +96,7 @@ test('is divisible by external value', async () => {
 
 Matchers should return an object (or a Promise of 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:
+These helper functions and properties can be found on `this` inside a custom matcher:
 
 #### `this.isNot`
 
@@ -106,6 +106,10 @@ A boolean to let you know this matcher was called with the negated `.not` modifi
 
 This is a deep-equality function that will return `true` if two objects have the same values (recursively).
 
+#### `this.expand`
+
+A boolean to let you know this matcher was called with an `expand` option. When Jest is called with the `--expand` flag, `this.expand` can be used to determine if Jest is expected to show full diffs and errors.
+
 #### `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).

website/versioned_docs/version-23.4/ExpectAPI.md

@@ -96,7 +96,7 @@ test('is divisible by external value', async () => {
 
 Matchers should return an object (or a Promise of 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:
+These helper functions and properties can be found on `this` inside a custom matcher:
 
 #### `this.isNot`
 
@@ -106,6 +106,10 @@ A boolean to let you know this matcher was called with the negated `.not` modifi
 
 This is a deep-equality function that will return `true` if two objects have the same values (recursively).
 
+#### `this.expand`
+
+A boolean to let you know this matcher was called with an `expand` option. When Jest is called with the `--expand` flag, `this.expand` can be used to determine if Jest is expected to show full diffs and errors.
+
 #### `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).

website/versioned_docs/version-23.5/ExpectAPI.md

@@ -96,7 +96,7 @@ test('is divisible by external value', async () => {
 
 Matchers should return an object (or a Promise of 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:
+These helper functions and properties can be found on `this` inside a custom matcher:
 
 #### `this.isNot`
 
@@ -106,6 +106,10 @@ A boolean to let you know this matcher was called with the negated `.not` modifi
 
 This is a deep-equality function that will return `true` if two objects have the same values (recursively).
 
+#### `this.expand`
+
+A boolean to let you know this matcher was called with an `expand` option. When Jest is called with the `--expand` flag, `this.expand` can be used to determine if Jest is expected to show full diffs and errors.
+
 #### `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).

website/versioned_docs/version-23.6/ExpectAPI.md

@@ -114,7 +114,7 @@ expect.extend({
 });
 ```
 
-These helper functions can be found on `this` inside a custom matcher:
+These helper functions and properties can be found on `this` inside a custom matcher:
 
 #### `this.isNot`
 
@@ -124,6 +124,10 @@ A boolean to let you know this matcher was called with the negated `.not` modifi
 
 This is a deep-equality function that will return `true` if two objects have the same values (recursively).
 
+#### `this.expand`
+
+A boolean to let you know this matcher was called with an `expand` option. When Jest is called with the `--expand` flag, `this.expand` can be used to determine if Jest is expected to show full diffs and errors.
+
 #### `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).