docs: Replace shallow equality with referential identity in ExpectAPI.md

CHANGELOG.md

@@ -12,10 +12,8 @@
 ### Chore & Maintenance
 
 - `[docs]` Fix babel-core installation instructions ([#6745](https://github.com/facebook/jest/pull/6745))
-
-### Chore & Maintenance
-
 - `[docs]` Explain how to rewrite assertions to avoid large irrelevant diff ([#6971](https://github.com/facebook/jest/pull/6971))
+- `[docs]` Replace shallow equality with referential identity in `ExpectAPI.md` ([#6991](https://github.com/facebook/jest/pull/6991))
 
 ## 23.6.0
 

docs/ExpectAPI.md

@@ -512,7 +512,7 @@ test('rejects to octopus', async () => {
 
 ### `.toBe(value)`
 
-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.
+Use `.toBe` to compare primitive values or to check referential identity of object instances. 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:
 
@@ -535,7 +535,7 @@ 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.
 
-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:
+Although the `.toBe` matcher **checks** referential identity, 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)`

website/versioned_docs/version-22.0/ExpectAPI.md

@@ -372,7 +372,7 @@ test('rejects to octopus', async () => {
 
 ### `.toBe(value)`
 
-Use `.toBe` to compare primitive values or to check identity of object instances (also known as "shallow" equality).
+Use `.toBe` to compare primitive values or to check referential identity of object instances.
 
 For example, this code will validate some properties of the `can` object:
 
@@ -395,7 +395,7 @@ 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.
 
-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:
+Although the `.toBe` matcher **checks** referential identity, 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)`

website/versioned_docs/version-22.1/ExpectAPI.md

@@ -366,7 +366,7 @@ test('rejects to octopus', async () => {
 
 ### `.toBe(value)`
 
-Use `.toBe` to compare primitive values or to check identity of object instances (also known as "shallow" equality).
+Use `.toBe` to compare primitive values or to check referential identity of object instances.
 
 For example, this code will validate some properties of the `can` object:
 
@@ -389,7 +389,7 @@ 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.
 
-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:
+Although the `.toBe` matcher **checks** referential identity, 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)`

website/versioned_docs/version-22.2/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 referential identity of object instances.
 
 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** referential identity, 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()`
 

website/versioned_docs/version-22.3/ExpectAPI.md

@@ -366,7 +366,7 @@ test('rejects to octopus', async () => {
 
 ### `.toBe(value)`
 
-Use `.toBe` to compare primitive values or to check identity of object instances (also known as "shallow" equality).
+Use `.toBe` to compare primitive values or to check referential identity of object instances.
 
 For example, this code will validate some properties of the `can` object:
 
@@ -389,7 +389,7 @@ 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.
 
-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:
+Although the `.toBe` matcher **checks** referential identity, 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)`

website/versioned_docs/version-23.0/ExpectAPI.md

@@ -465,7 +465,7 @@ test('rejects to octopus', async () => {
 
 ### `.toBe(value)`
 
-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.
+Use `.toBe` to compare primitive values or to check referential identity of object instances. 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,9 @@ 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. 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:
+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** referential identity, 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)`
@@ -886,7 +888,9 @@ 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:
+> 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)`

website/versioned_docs/version-23.1/ExpectAPI.md

@@ -465,7 +465,7 @@ test('rejects to octopus', async () => {
 
 ### `.toBe(value)`
 
-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.
+Use `.toBe` to compare primitive values or to check referential identity of object instances. 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:
 
@@ -488,7 +488,7 @@ 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.
 
-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:
+Although the `.toBe` matcher **checks** referential identity, 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)`

website/versioned_docs/version-23.2/ExpectAPI.md

@@ -465,7 +465,7 @@ test('rejects to octopus', async () => {
 
 ### `.toBe(value)`
 
-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.
+Use `.toBe` to compare primitive values or to check referential identity of object instances. 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:
 
@@ -488,7 +488,7 @@ 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.
 
-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:
+Although the `.toBe` matcher **checks** referential identity, 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)`

website/versioned_docs/version-23.3/ExpectAPI.md

@@ -465,7 +465,7 @@ test('rejects to octopus', async () => {
 
 ### `.toBe(value)`
 
-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.
+Use `.toBe` to compare primitive values or to check referential identity of object instances. 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:
 
@@ -488,7 +488,7 @@ 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.
 
-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:
+Although the `.toBe` matcher **checks** referential identity, 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)`

website/versioned_docs/version-23.4/ExpectAPI.md

@@ -465,7 +465,7 @@ test('rejects to octopus', async () => {
 
 ### `.toBe(value)`
 
-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.
+Use `.toBe` to compare primitive values or to check referential identity of object instances. 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:
 
@@ -488,7 +488,7 @@ 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.
 
-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:
+Although the `.toBe` matcher **checks** referential identity, 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)`