docs: Explain how to rewrite assertions to avoid large irrelevant diff

CHANGELOG.md

@@ -4,6 +4,10 @@
 
 - `[jest-haste-map]` [**BREAKING**] Replaced internal data structures to improve performance ([#6960](https://github.com/facebook/jest/pull/6960))
 
+### Chore & Maintenance
+
+- `[docs]` Explain how to rewrite assertions to avoid large irrelevant diff ([#6971](https://github.com/facebook/jest/pull/6971))
+
 ## 23.6.0
 
 ### Features

docs/ExpectAPI.md

@@ -512,7 +512,7 @@ test('rejects to octopus', async () => {
 
 ### `.toBe(value)`
 
-`toBe` just checks that a value is what you expect. It uses `Object.is` to check exact equality.
+Use `.toBe` to compare primitive values or to check identity of object instances (also known as "shallow" equality). It calls `Object.is` to compare values, which is even better for testing than `===` strict equality operator.
 
 For example, this code will validate some properties of the `can` object:
 
@@ -533,7 +533,12 @@ describe('the can', () => {
 });
 ```
 
-Don't use `toBe` with floating-point numbers. For example, due to rounding, in JavaScript `0.2 + 0.1` is not strictly equal to `0.3`. If you have floating point numbers, try `.toBeCloseTo` instead.
+Don't use `.toBe` with floating-point numbers. For example, due to rounding, in JavaScript `0.2 + 0.1` is not strictly equal to `0.3`. If you have floating point numbers, try `.toBeCloseTo` instead.
+
+Although the `.toBe` matcher **checks** shallow equality, it **reports** a deep comparison of values if the assertion fails. If differences between properties do not help you to understand why a test fails, especially if the report is large, then you might move the comparison into the `expect` function. For example, to assert whether or not elements are the same instance:
+
+- rewrite `expect(received).toBe(expected)` as `expect(Object.is(received, expected)).toBe(true)`
+- rewrite `expect(received).not.toBe(expected)` as `expect(Object.is(received, expected)).toBe(false)`
 
 ### `.toHaveBeenCalled()`
 
@@ -906,7 +911,9 @@ describe('my beverage', () => {
 
 ### `.toEqual(value)`
 
-Use `.toEqual` when you want to check that two objects have the same value. This matcher recursively checks the equality of all fields, rather than checking for object identity—this is also known as "deep equal". For example, `toEqual` and `toBe` behave differently in this test suite, so all the tests pass:
+Use `.toEqual` to compare recursively all properties of object instances (also known as "deep" equality). It calls `Object.is` to compare primitive values, which is even better for testing than `===` strict equality operator.
+
+For example, `.toEqual` and `.toBe` behave differently in this test suite, so all the tests pass:
 
 ```js
 const can1 = {
@@ -930,6 +937,11 @@ describe('the La Croix cans on my desk', () => {
 
 > Note: `.toEqual` won't perform a _deep equality_ check for two errors. Only the `message` property of an Error is considered for equality. It is recommended to use the `.toThrow` matcher for testing against errors.
 
+If differences between properties do not help you to understand why a test fails, especially if the report is large, then you might move the comparison into the `expect` function. For example, use `equals` method of `Buffer` class to assert whether or not buffers contain the same content:
+
+- rewrite `expect(received).toEqual(expected)` as `expect(received.equals(expected)).toBe(true)`
+- rewrite `expect(received).not.toEqual(expected)` as `expect(received.equals(expected)).toBe(false)`
+
 ### `.toHaveLength(number)`
 
 Use `.toHaveLength` to check that an object has a `.length` property and it is set to a certain numeric value.

website/versioned_docs/version-22.0/ExpectAPI.md

@@ -372,7 +372,7 @@ test('rejects to octopus', async () => {
 
 ### `.toBe(value)`
 
-`toBe` just checks that a value is what you expect. It uses `Object.is` to check exact equality.
+Use `.toBe` to compare primitive values or to check identity of object instances (also known as "shallow" equality).
 
 For example, this code will validate some properties of the `can` object:
 
@@ -393,7 +393,12 @@ describe('the can', () => {
 });
 ```
 
-Don't use `toBe` with floating-point numbers. For example, due to rounding, in JavaScript `0.2 + 0.1` is not strictly equal to `0.3`. If you have floating point numbers, try `.toBeCloseTo` instead.
+Don't use `.toBe` with floating-point numbers. For example, due to rounding, in JavaScript `0.2 + 0.1` is not strictly equal to `0.3`. If you have floating point numbers, try `.toBeCloseTo` instead.
+
+Although the `.toBe` matcher **checks** shallow equality, it **reports** a deep comparison of values if the assertion fails. If differences between properties do not help you to understand why a test fails, especially if the report is large, then you might move the comparison into the `expect` function. For example, to assert whether or not elements are the same instance:
+
+- rewrite `expect(received).toBe(expected)` as `expect(Object.is(received, expected)).toBe(true)`
+- rewrite `expect(received).not.toBe(expected)` as `expect(Object.is(received, expected)).toBe(false)`
 
 ### `.toHaveBeenCalled()`
 
@@ -648,7 +653,9 @@ describe('my beverage', () => {
 
 ### `.toEqual(value)`
 
-Use `.toEqual` when you want to check that two objects have the same value. This matcher recursively checks the equality of all fields, rather than checking for object identity—this is also known as "deep equal". For example, `toEqual` and `toBe` behave differently in this test suite, so all the tests pass:
+Use `.toEqual` to compare recursively all properties of object instances (also known as "deep" equality).
+
+For example, `.toEqual` and `.toBe` behave differently in this test suite, so all the tests pass:
 
 ```js
 const can1 = {
@@ -672,6 +679,11 @@ describe('the La Croix cans on my desk', () => {
 
 > Note: `.toEqual` won't perform a _deep equality_ check for two errors. Only the `message` property of an Error is considered for equality. It is recommended to use the `.toThrow` matcher for testing against errors.
 
+If differences between properties do not help you to understand why a test fails, especially if the report is large, then you might move the comparison into the `expect` function. For example, use `equals` method of `Buffer` class to assert whether or not buffers contain the same content:
+
+- rewrite `expect(received).toEqual(expected)` as `expect(received.equals(expected)).toBe(true)`
+- rewrite `expect(received).not.toEqual(expected)` as `expect(received.equals(expected)).toBe(false)`
+
 ### `.toHaveLength(number)`
 
 Use `.toHaveLength` to check that an object has a `.length` property and it is set to a certain numeric value.

website/versioned_docs/version-22.1/ExpectAPI.md

@@ -366,7 +366,7 @@ test('rejects to octopus', async () => {
 
 ### `.toBe(value)`
 
-`toBe` just checks that a value is what you expect. It uses `Object.is` to check exact equality.
+Use `.toBe` to compare primitive values or to check identity of object instances (also known as "shallow" equality).
 
 For example, this code will validate some properties of the `can` object:
 
@@ -387,7 +387,12 @@ describe('the can', () => {
 });
 ```
 
-Don't use `toBe` with floating-point numbers. For example, due to rounding, in JavaScript `0.2 + 0.1` is not strictly equal to `0.3`. If you have floating point numbers, try `.toBeCloseTo` instead.
+Don't use `.toBe` with floating-point numbers. For example, due to rounding, in JavaScript `0.2 + 0.1` is not strictly equal to `0.3`. If you have floating point numbers, try `.toBeCloseTo` instead.
+
+Although the `.toBe` matcher **checks** shallow equality, it **reports** a deep comparison of values if the assertion fails. If differences between properties do not help you to understand why a test fails, especially if the report is large, then you might move the comparison into the `expect` function. For example, to assert whether or not elements are the same instance:
+
+- rewrite `expect(received).toBe(expected)` as `expect(Object.is(received, expected)).toBe(true)`
+- rewrite `expect(received).not.toBe(expected)` as `expect(Object.is(received, expected)).toBe(false)`
 
 ### `.toHaveBeenCalled()`
 
@@ -642,7 +647,9 @@ describe('my beverage', () => {
 
 ### `.toEqual(value)`
 
-Use `.toEqual` when you want to check that two objects have the same value. This matcher recursively checks the equality of all fields, rather than checking for object identity—this is also known as "deep equal". For example, `toEqual` and `toBe` behave differently in this test suite, so all the tests pass:
+Use `.toEqual` to compare recursively all properties of object instances (also known as "deep" equality).
+
+For example, `.toEqual` and `.toBe` behave differently in this test suite, so all the tests pass:
 
 ```js
 const can1 = {
@@ -666,6 +673,11 @@ describe('the La Croix cans on my desk', () => {
 
 > Note: `.toEqual` won't perform a _deep equality_ check for two errors. Only the `message` property of an Error is considered for equality. It is recommended to use the `.toThrow` matcher for testing against errors.
 
+If differences between properties do not help you to understand why a test fails, especially if the report is large, then you might move the comparison into the `expect` function. For example, use `equals` method of `Buffer` class to assert whether or not buffers contain the same content:
+
+- rewrite `expect(received).toEqual(expected)` as `expect(received.equals(expected)).toBe(true)`
+- rewrite `expect(received).not.toEqual(expected)` as `expect(received.equals(expected)).toBe(false)`
+
 ### `.toHaveLength(number)`
 
 Use `.toHaveLength` to check that an object has a `.length` property and it is set to a certain numeric value.

website/versioned_docs/version-22.2/ExpectAPI.md

@@ -642,7 +642,9 @@ describe('my beverage', () => {
 
 ### `.toEqual(value)`
 
-Use `.toEqual` when you want to check that two objects have the same value. This matcher recursively checks the equality of all fields, rather than checking for object identity—this is also known as "deep equal". For example, `toEqual` and `toBe` behave differently in this test suite, so all the tests pass:
+Use `.toEqual` to compare recursively all properties of object instances (also known as "deep" equality).
+
+For example, `.toEqual` and `.toBe` behave differently in this test suite, so all the tests pass:
 
 ```js
 const can1 = {
@@ -666,6 +668,11 @@ describe('the La Croix cans on my desk', () => {
 
 > Note: `.toEqual` won't perform a _deep equality_ check for two errors. Only the `message` property of an Error is considered for equality. It is recommended to use the `.toThrow` matcher for testing against errors.
 
+If differences between properties do not help you to understand why a test fails, especially if the report is large, then you might move the comparison into the `expect` function. For example, use `equals` method of `Buffer` class to assert whether or not buffers contain the same content:
+
+- rewrite `expect(received).toEqual(expected)` as `expect(received.equals(expected)).toBe(true)`
+- rewrite `expect(received).not.toEqual(expected)` as `expect(received.equals(expected)).toBe(false)`
+
 ### `.toHaveLength(number)`
 
 Use `.toHaveLength` to check that an object has a `.length` property and it is set to a certain numeric value.

website/versioned_docs/version-22.3/ExpectAPI.md

@@ -366,7 +366,7 @@ test('rejects to octopus', async () => {
 
 ### `.toBe(value)`
 
-`toBe` just checks that a value is what you expect. It uses `Object.is` to check exact equality.
+Use `.toBe` to compare primitive values or to check identity of object instances (also known as "shallow" equality).
 
 For example, this code will validate some properties of the `can` object:
 
@@ -387,7 +387,12 @@ describe('the can', () => {
 });
 ```
 
-Don't use `toBe` with floating-point numbers. For example, due to rounding, in JavaScript `0.2 + 0.1` is not strictly equal to `0.3`. If you have floating point numbers, try `.toBeCloseTo` instead.
+Don't use `.toBe` with floating-point numbers. For example, due to rounding, in JavaScript `0.2 + 0.1` is not strictly equal to `0.3`. If you have floating point numbers, try `.toBeCloseTo` instead.
+
+Although the `.toBe` matcher **checks** shallow equality, it **reports** a deep comparison of values if the assertion fails. If differences between properties do not help you to understand why a test fails, especially if the report is large, then you might move the comparison into the `expect` function. For example, to assert whether or not elements are the same instance:
+
+- rewrite `expect(received).toBe(expected)` as `expect(Object.is(received, expected)).toBe(true)`
+- rewrite `expect(received).not.toBe(expected)` as `expect(Object.is(received, expected)).toBe(false)`
 
 ### `.toHaveBeenCalled()`
 
@@ -642,7 +647,9 @@ describe('my beverage', () => {
 
 ### `.toEqual(value)`
 
-Use `.toEqual` when you want to check that two objects have the same value. This matcher recursively checks the equality of all fields, rather than checking for object identity—this is also known as "deep equal". For example, `toEqual` and `toBe` behave differently in this test suite, so all the tests pass:
+Use `.toEqual` to compare recursively all properties of object instances (also known as "deep" equality).
+
+For example, `.toEqual` and `.toBe` behave differently in this test suite, so all the tests pass:
 
 ```js
 const can1 = {
@@ -666,6 +673,11 @@ describe('the La Croix cans on my desk', () => {
 
 > Note: `.toEqual` won't perform a _deep equality_ check for two errors. Only the `message` property of an Error is considered for equality. It is recommended to use the `.toThrow` matcher for testing against errors.
 
+If differences between properties do not help you to understand why a test fails, especially if the report is large, then you might move the comparison into the `expect` function. For example, use `equals` method of `Buffer` class to assert whether or not buffers contain the same content:
+
+- rewrite `expect(received).toEqual(expected)` as `expect(received.equals(expected)).toBe(true)`
+- rewrite `expect(received).not.toEqual(expected)` as `expect(received.equals(expected)).toBe(false)`
+
 ### `.toHaveLength(number)`
 
 Use `.toHaveLength` to check that an object has a `.length` property and it is set to a certain numeric value.

website/versioned_docs/version-23.0/ExpectAPI.md

@@ -465,7 +465,7 @@ test('rejects to octopus', async () => {
 
 ### `.toBe(value)`
 
-`toBe` just checks that a value is what you expect. It uses `Object.is` to check exact equality.
+Use `.toBe` to compare primitive values or to check identity of object instances (also known as "shallow" equality). It calls `Object.is` to compare values, which is even better for testing than `===` strict equality operator.
 
 For example, this code will validate some properties of the `can` object:
 
@@ -486,7 +486,10 @@ describe('the can', () => {
 });
 ```
 
-Don't use `toBe` with floating-point numbers. For example, due to rounding, in JavaScript `0.2 + 0.1` is not strictly equal to `0.3`. If you have floating point numbers, try `.toBeCloseTo` instead.
+Don't use `.toBe` with floating-point numbers. For example, due to rounding, in JavaScript `0.2 + 0.1` is not strictly equal to `0.3`. If you have floating point numbers, try `.toBeCloseTo` instead. Although the `.toBe` matcher **checks** shallow equality, it **reports** a deep comparison of values if the assertion fails. If differences between properties do not help you to understand why a test fails, especially if the report is large, then you might move the comparison into the `expect` function. For example, to assert whether or not elements are the same instance:
+
+- rewrite `expect(received).toBe(expected)` as `expect(Object.is(received, expected)).toBe(true)`
+- rewrite `expect(received).not.toBe(expected)` as `expect(Object.is(received, expected)).toBe(false)`
 
 ### `.toHaveBeenCalled()`
 
@@ -859,7 +862,9 @@ describe('my beverage', () => {
 
 ### `.toEqual(value)`
 
-Use `.toEqual` when you want to check that two objects have the same value. This matcher recursively checks the equality of all fields, rather than checking for object identity—this is also known as "deep equal". For example, `toEqual` and `toBe` behave differently in this test suite, so all the tests pass:
+Use `.toEqual` to compare recursively all properties of object instances (also known as "deep" equality). It calls `Object.is` to compare primitive values, which is even better for testing than `===` strict equality operator.
+
+For example, `.toEqual` and `.toBe` behave differently in this test suite, so all the tests pass:
 
 ```js
 const can1 = {
@@ -881,7 +886,10 @@ describe('the La Croix cans on my desk', () => {
 });
 ```
 
-> Note: `.toEqual` won't perform a _deep equality_ check for two errors. Only the `message` property of an Error is considered for equality. It is recommended to use the `.toThrow` matcher for testing against errors.
+> Note: `.toEqual` won't perform a _deep equality_ check for two errors. Only the `message` property of an Error is considered for equality. It is recommended to use the `.toThrow` matcher for testing against errors. If differences between properties do not help you to understand why a test fails, especially if the report is large, then you might move the comparison into the `expect` function. For example, use `equals` method of `Buffer` class to assert whether or not buffers contain the same content:
+
+- rewrite `expect(received).toEqual(expected)` as `expect(received.equals(expected)).toBe(true)`
+- rewrite `expect(received).not.toEqual(expected)` as `expect(received.equals(expected)).toBe(false)`
 
 ### `.toHaveLength(number)`