diff --git a/CHANGELOG.md b/CHANGELOG.md index b2cbf673415b..63a678598e5f 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/docs/ExpectAPI.md b/docs/ExpectAPI.md index 77236126a489..e03744d04946 100644 --- a/docs/ExpectAPI.md +++ b/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. diff --git a/website/versioned_docs/version-22.0/ExpectAPI.md b/website/versioned_docs/version-22.0/ExpectAPI.md index 5f2d187dcea1..97f6a961f780 100644 --- a/website/versioned_docs/version-22.0/ExpectAPI.md +++ b/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. diff --git a/website/versioned_docs/version-22.1/ExpectAPI.md b/website/versioned_docs/version-22.1/ExpectAPI.md index 62c0ab000ae4..c7f12b1b9005 100644 --- a/website/versioned_docs/version-22.1/ExpectAPI.md +++ b/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. diff --git a/website/versioned_docs/version-22.2/ExpectAPI.md b/website/versioned_docs/version-22.2/ExpectAPI.md index d0a7e6433a5f..816fb2e5d3d1 100644 --- a/website/versioned_docs/version-22.2/ExpectAPI.md +++ b/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. diff --git a/website/versioned_docs/version-22.3/ExpectAPI.md b/website/versioned_docs/version-22.3/ExpectAPI.md index 09c2adc45094..1021fa34fe54 100644 --- a/website/versioned_docs/version-22.3/ExpectAPI.md +++ b/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. diff --git a/website/versioned_docs/version-23.0/ExpectAPI.md b/website/versioned_docs/version-23.0/ExpectAPI.md index b3fb4d1cea43..202433cd422f 100644 --- a/website/versioned_docs/version-23.0/ExpectAPI.md +++ b/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)` diff --git a/website/versioned_docs/version-23.1/ExpectAPI.md b/website/versioned_docs/version-23.1/ExpectAPI.md index 64a3d5c1f3b7..5e3dc76f90ab 100644 --- a/website/versioned_docs/version-23.1/ExpectAPI.md +++ b/website/versioned_docs/version-23.1/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,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()` @@ -859,7 +864,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 = { @@ -883,6 +890,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. diff --git a/website/versioned_docs/version-23.2/ExpectAPI.md b/website/versioned_docs/version-23.2/ExpectAPI.md index 937026f7c2d8..00afc1d654d0 100644 --- a/website/versioned_docs/version-23.2/ExpectAPI.md +++ b/website/versioned_docs/version-23.2/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,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()` @@ -859,7 +864,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 = { @@ -883,6 +890,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. diff --git a/website/versioned_docs/version-23.3/ExpectAPI.md b/website/versioned_docs/version-23.3/ExpectAPI.md index 7b9ead1d9302..c85f553d688d 100644 --- a/website/versioned_docs/version-23.3/ExpectAPI.md +++ b/website/versioned_docs/version-23.3/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,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()` @@ -859,7 +864,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 = { @@ -883,6 +890,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. diff --git a/website/versioned_docs/version-23.4/ExpectAPI.md b/website/versioned_docs/version-23.4/ExpectAPI.md index 7b2dc31bbd3c..9b15addb1397 100644 --- a/website/versioned_docs/version-23.4/ExpectAPI.md +++ b/website/versioned_docs/version-23.4/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,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()` @@ -859,7 +864,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 = { @@ -883,6 +890,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. diff --git a/website/versioned_docs/version-23.5/ExpectAPI.md b/website/versioned_docs/version-23.5/ExpectAPI.md index b7cc577442c7..d08018837125 100644 --- a/website/versioned_docs/version-23.5/ExpectAPI.md +++ b/website/versioned_docs/version-23.5/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,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()` @@ -859,7 +864,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 = { @@ -883,6 +890,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. diff --git a/website/versioned_docs/version-23.6/ExpectAPI.md b/website/versioned_docs/version-23.6/ExpectAPI.md index a2dee9768e79..9bf18fa0d60d 100644 --- a/website/versioned_docs/version-23.6/ExpectAPI.md +++ b/website/versioned_docs/version-23.6/ExpectAPI.md @@ -513,7 +513,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: @@ -534,7 +534,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()` @@ -907,7 +912,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 = { @@ -931,6 +938,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.