From ea18c26f4926721905ae9d8f9161461fa06ef007 Mon Sep 17 00:00:00 2001 From: Mark Pedrotti Date: Wed, 12 Sep 2018 13:51:14 -0400 Subject: [PATCH 1/8] docs: Explain how to rewrite assertions to avoid large irrelevant diff --- docs/ExpectAPI.md | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) diff --git a/docs/ExpectAPI.md b/docs/ExpectAPI.md index 77236126a489..2d4ebe6fcfb9 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. From 9c892ccb544982118cf8b36b197fc12089b13aaa Mon Sep 17 00:00:00 2001 From: Mark Pedrotti Date: Wed, 12 Sep 2018 14:04:56 -0400 Subject: [PATCH 2/8] Update CHANGELOG.md --- CHANGELOG.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5534cf4d0105..6f8998ec0cfc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,9 @@ ## master +### 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 From bcb4ec853c417ef75d0ef312e360e053942cb052 Mon Sep 17 00:00:00 2001 From: Mark Pedrotti Date: Wed, 12 Sep 2018 14:55:21 -0400 Subject: [PATCH 3/8] Fix pretty lint error --- docs/ExpectAPI.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/ExpectAPI.md b/docs/ExpectAPI.md index 2d4ebe6fcfb9..e03744d04946 100644 --- a/docs/ExpectAPI.md +++ b/docs/ExpectAPI.md @@ -537,8 +537,8 @@ Don't use `.toBe` with floating-point numbers. For example, due to rounding, in 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)` +- 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()` @@ -939,8 +939,8 @@ describe('the La Croix cans on my desk', () => { 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)` +- 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)` From 09e17a2a03b72cc47dc295cc537638709d168f0f Mon Sep 17 00:00:00 2001 From: Mark Pedrotti Date: Thu, 13 Sep 2018 12:47:22 -0400 Subject: [PATCH 4/8] Fix pretty lint error in CONTRIBUTING.md --- CONTRIBUTING.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 48dbaf2fce23..027d42cf7069 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -37,6 +37,7 @@ _Before_ submitting a pull request, please make sure the following is done… 1. Make sure you have `python` installed (v2.7 is recommended, v3.x.x is not supported). Python is required by [node-gyp](https://github.com/nodejs/node-gyp) that is used when running `yarn install`. To check your version of Python and ensure it's installed you can type: + ``` python --version ``` From 88b1e589e418f883a5e51c191ab65fa72ff3d81c Mon Sep 17 00:00:00 2001 From: Simen Bekkhus Date: Sat, 15 Sep 2018 13:44:07 +0200 Subject: [PATCH 5/8] Revert "Fix pretty lint error in CONTRIBUTING.md" This reverts commit 09e17a2a03b72cc47dc295cc537638709d168f0f. --- CONTRIBUTING.md | 1 - 1 file changed, 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 027d42cf7069..48dbaf2fce23 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -37,7 +37,6 @@ _Before_ submitting a pull request, please make sure the following is done… 1. Make sure you have `python` installed (v2.7 is recommended, v3.x.x is not supported). Python is required by [node-gyp](https://github.com/nodejs/node-gyp) that is used when running `yarn install`. To check your version of Python and ensure it's installed you can type: - ``` python --version ``` From 8b19210160364e5ed6be0245e2e5ba4fc80c11f7 Mon Sep 17 00:00:00 2001 From: Mark Pedrotti Date: Mon, 17 Sep 2018 12:00:40 -0400 Subject: [PATCH 6/8] Copy explanation to version-23.6 doc --- .../versioned_docs/version-23.6/ExpectAPI.md | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) 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. From fd1e505d1d3e276706c7910d088cc4d77d113f65 Mon Sep 17 00:00:00 2001 From: Mark Pedrotti Date: Mon, 17 Sep 2018 13:07:52 -0400 Subject: [PATCH 7/8] Copy explanation to earlier versioned docs --- .../versioned_docs/version-22.0/ExpectAPI.md | 18 +++++++++++++++--- .../versioned_docs/version-22.1/ExpectAPI.md | 18 +++++++++++++++--- .../versioned_docs/version-22.2/ExpectAPI.md | 9 ++++++++- .../versioned_docs/version-22.3/ExpectAPI.md | 18 +++++++++++++++--- .../versioned_docs/version-23.0/ExpectAPI.md | 16 +++++++++++++--- .../versioned_docs/version-23.1/ExpectAPI.md | 18 +++++++++++++++--- .../versioned_docs/version-23.2/ExpectAPI.md | 18 +++++++++++++++--- .../versioned_docs/version-23.3/ExpectAPI.md | 18 +++++++++++++++--- .../versioned_docs/version-23.4/ExpectAPI.md | 18 +++++++++++++++--- .../versioned_docs/version-23.5/ExpectAPI.md | 17 ++++++++++++++--- 10 files changed, 140 insertions(+), 28 deletions(-) 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..a4ba01ca97b0 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,11 @@ 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 +863,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 = { @@ -882,6 +888,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. +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..c10b01d2463f 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,8 +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()` Also under the alias: `.toBeCalled()` @@ -859,7 +863,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 +889,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. From 3449f0c5216a841e552763451b9339d0584fa17e Mon Sep 17 00:00:00 2001 From: Simen Bekkhus Date: Mon, 17 Sep 2018 19:16:59 +0200 Subject: [PATCH 8/8] fix lint --- website/versioned_docs/version-23.0/ExpectAPI.md | 6 ++---- website/versioned_docs/version-23.5/ExpectAPI.md | 1 + 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/website/versioned_docs/version-23.0/ExpectAPI.md b/website/versioned_docs/version-23.0/ExpectAPI.md index a4ba01ca97b0..202433cd422f 100644 --- a/website/versioned_docs/version-23.0/ExpectAPI.md +++ b/website/versioned_docs/version-23.0/ExpectAPI.md @@ -486,8 +486,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: +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)` @@ -887,8 +886,7 @@ 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)` diff --git a/website/versioned_docs/version-23.5/ExpectAPI.md b/website/versioned_docs/version-23.5/ExpectAPI.md index c10b01d2463f..d08018837125 100644 --- a/website/versioned_docs/version-23.5/ExpectAPI.md +++ b/website/versioned_docs/version-23.5/ExpectAPI.md @@ -492,6 +492,7 @@ Although the `.toBe` matcher **checks** shallow equality, it **reports** a deep - 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()` Also under the alias: `.toBeCalled()`