jest-snapshot: Improve report when matcher fails, part 14

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ### Features
 
+- `[jest-snapshot]` Improve report when matcher fails, part 14 ([#8132](https://github.com/facebook/jest/pull/8132))
+
 ### Fixes
 
 - `[jest-each]` Fix test function type ([#8145](https://github.com/facebook/jest/pull/8145))

docs/ExpectAPI.md

@@ -1113,13 +1113,13 @@ test('this house has my desired features', () => {
 });
 ```
 
-### `.toMatchSnapshot(propertyMatchers?, snapshotName?)`
+### `.toMatchSnapshot(propertyMatchers?, snapshotHint?)`
 
 This ensures that a value matches the most recent snapshot. Check out [the Snapshot Testing guide](SnapshotTesting.md) for more information.
 
 You can provide an optional `propertyMatchers` object argument, which has asymmetric matchers as values of a subset of expected properties, **if** the received value will be an **object** instance. It is like `toMatchObject` with flexible criteria for a subset of properties, followed by a snapshot test as exact criteria for the rest of the properties.
 
-You can provide an optional `snapshotName` string argument that is appended to the test name. Jest always appends a number at the end of a snapshot key to differentiate snapshots from a single `it` or `test` block. Jest sorts snapshots by key in the corresponding `.snap` file.
+You can provide an optional `snapshotHint` string argument that is appended to the test name. Although Jest always appends a number at the end of a snapshot name, short descriptive hints might be more useful than numbers to differentiate **multiple** snapshots in a **single** `it` or `test` block. Jest sorts snapshots by name in the corresponding `.snap` file.
 
 _Note: While snapshot testing is most commonly used with React components, any serializable value can be used as a snapshot._
 
@@ -1213,11 +1213,11 @@ test('throws on octopus', () => {
 
 > Note: You must wrap the code in a function, otherwise the error will not be caught and the assertion will fail.
 
-### `.toThrowErrorMatchingSnapshot(snapshotName?)`
+### `.toThrowErrorMatchingSnapshot(snapshotHint?)`
 
 Use `.toThrowErrorMatchingSnapshot` to test that a function throws an error matching the most recent snapshot when it is called.
 
-You can provide an optional `snapshotName` string argument that is appended to the test name. Jest always appends a number at the end of a snapshot key to differentiate snapshots from a single `it` or `test` block. Jest sorts snapshots by key in the corresponding `.snap` file.
+You can provide an optional `snapshotHint` string argument that is appended to the test name. Although Jest always appends a number at the end of a snapshot name, short descriptive hints might be more useful than numbers to differentiate **multiple** snapshots in a **single** `it` or `test` block. Jest sorts snapshots by name in the corresponding `.snap` file.
 
 For example, let's say you have a `drinkFlavor` function that throws whenever the flavor is `'octopus'`, and is coded like this:
 

e2e/__tests__/__snapshots__/failures.test.ts.snap

@@ -387,9 +387,9 @@ FAIL __tests__/snapshotNamed.test.js
 
   ● failing named snapshot
 
-    expect(value).toMatchSnapshot()
+    expect(received).toMatchSnapshot(hint)
 
-    Received value does not match stored snapshot "failing named snapshot: snapname 1".
+    Snapshot name: \`failing named snapshot: snapname 1\`
 
     - Snapshot
     + Received
@@ -819,9 +819,9 @@ FAIL __tests__/snapshot.test.js
 
   ● failing snapshot
 
-    expect(value).toMatchSnapshot()
+    expect(received).toMatchSnapshot()
 
-    Received value does not match stored snapshot "failing snapshot 1".
+    Snapshot name: \`failing snapshot 1\`
 
     - Snapshot
     + Received

e2e/__tests__/__snapshots__/watchModeUpdateSnapshot.test.ts.snap

@@ -4,8 +4,8 @@ exports[`can press "u" to update snapshots: test results 1`] = `
 FAIL __tests__/bar.spec.js
   ✕ bar
   ● bar
-    expect(value).toMatchSnapshot()
-    Received value does not match stored snapshot "bar 1".
+    expect(received).toMatchSnapshot()
+    Snapshot name: \`bar 1\`
     - Snapshot
     + Received
     - "foo"

e2e/__tests__/toMatchInlineSnapshot.test.ts

@@ -52,7 +52,7 @@ test('basic support', () => {
     });
     const {stderr, status} = runJest(DIR, ['-w=1', '--ci=false', filename]);
     const fileAfter = readFile(filename);
-    expect(stderr).toMatch('Received value does not match stored snapshot');
+    expect(stderr).toMatch('Snapshot name: `inline snapshots 1`');
     expect(status).toBe(1);
     expect(wrap(fileAfter)).toMatchSnapshot('snapshot mismatch');
   }
@@ -101,9 +101,7 @@ test('handles property matchers', () => {
     });
     const {stderr, status} = runJest(DIR, ['-w=1', '--ci=false', filename]);
     const fileAfter = readFile(filename);
-    expect(stderr).toMatch(
-      'Received value does not match snapshot properties for "handles property matchers 1".',
-    );
+    expect(stderr).toMatch('Snapshot name: `handles property matchers 1`');
     expect(stderr).toMatch('Snapshots:   1 failed, 1 total');
     expect(status).toBe(1);
     expect(wrap(fileAfter)).toMatchSnapshot('snapshot failed');

e2e/__tests__/toMatchSnapshot.test.ts

@@ -42,7 +42,7 @@ test('basic support', () => {
       [filename]: template(['{apple: "updated value"}']),
     });
     const {stderr, status} = runJest(DIR, ['-w=1', '--ci=false', filename]);
-    expect(stderr).toMatch('Received value does not match stored snapshot');
+    expect(stderr).toMatch('Snapshot name: `snapshots 1`');
     expect(status).toBe(1);
   }
 
@@ -107,7 +107,7 @@ test('first snapshot fails, second passes', () => {
   {
     writeFiles(TESTS_DIR, {[filename]: template([`'kiwi'`, `'banana'`])});
     const {stderr, status} = runJest(DIR, ['-w=1', '--ci=false', filename]);
-    expect(stderr).toMatch('Received value does not match stored snapshot');
+    expect(stderr).toMatch('Snapshot name: `snapshots 1`');
     expect(stderr).toMatch('- "apple"\n    + "kiwi"');
     expect(stderr).not.toMatch('1 obsolete snapshot found');
     expect(status).toBe(1);
@@ -178,9 +178,7 @@ test('handles property matchers', () => {
   {
     writeFiles(TESTS_DIR, {[filename]: template(['"string"'])});
     const {stderr, status} = runJest(DIR, ['-w=1', '--ci=false', filename]);
-    expect(stderr).toMatch(
-      'Received value does not match snapshot properties for "handles property matchers 1".',
-    );
+    expect(stderr).toMatch('Snapshot name: `handles property matchers 1`');
     expect(stderr).toMatch('Snapshots:   1 failed, 1 total');
     expect(status).toBe(1);
   }
@@ -253,9 +251,9 @@ test('handles property matchers with custom name', () => {
     writeFiles(TESTS_DIR, {[filename]: template(['"string"'])});
     const {stderr, status} = runJest(DIR, ['-w=1', '--ci=false', filename]);
     expect(stderr).toMatch(
-      'Received value does not match snapshot properties for "handles property matchers with name: custom-name 1".',
+      'Snapshot name: `handles property matchers with name: custom-name 1`',
     );
-    expect(stderr).toMatch('Expected snapshot to match properties:');
+    expect(stderr).toMatch('Expected properties:');
     expect(stderr).toMatch('Snapshots:   1 failed, 1 total');
     expect(status).toBe(1);
   }
@@ -285,9 +283,9 @@ test('handles property matchers with deep properties', () => {
     writeFiles(TESTS_DIR, {[filename]: template(['"string"', '"Jest"'])});
     const {stderr, status} = runJest(DIR, ['-w=1', '--ci=false', filename]);
     expect(stderr).toMatch(
-      'Received value does not match snapshot properties for "handles property matchers with deep properties 1".',
+      'Snapshot name: `handles property matchers with deep properties 1`',
     );
-    expect(stderr).toMatch('Expected snapshot to match properties:');
+    expect(stderr).toMatch('Expected properties:');
     expect(stderr).toMatch('Snapshots:   1 failed, 1 total');
     expect(status).toBe(1);
   }
@@ -296,7 +294,7 @@ test('handles property matchers with deep properties', () => {
     writeFiles(TESTS_DIR, {[filename]: template(['new Date()', '"CHANGED"'])});
     const {stderr, status} = runJest(DIR, ['-w=1', '--ci=false', filename]);
     expect(stderr).toMatch(
-      'Received value does not match stored snapshot "handles property matchers with deep properties 1"',
+      'Snapshot name: `handles property matchers with deep properties 1`',
     );
     expect(stderr).toMatch('Snapshots:   1 failed, 1 total');
     expect(status).toBe(1);

e2e/__tests__/toThrowErrorMatchingInlineSnapshot.test.ts

@@ -81,9 +81,7 @@ test('cannot be used with .not', () => {
   {
     writeFiles(TESTS_DIR, {[filename]: template()});
     const {stderr, status} = runJest(DIR, ['-w=1', '--ci=false', filename]);
-    expect(stderr).toMatch(
-      'Jest: `.not` cannot be used with `.toThrowErrorMatchingInlineSnapshot()`.',
-    );
+    expect(stderr).toMatch('.not cannot be used with snapshot matchers');
     expect(status).toBe(1);
   }
 });

e2e/__tests__/toThrowErrorMatchingSnapshot.test.ts

@@ -43,7 +43,7 @@ test(`throws the error if tested function didn't throw error`, () => {
   {
     writeFiles(TESTS_DIR, {[filename]: template()});
     const {stderr, status} = runJest(DIR, ['-w=1', '--ci=false', filename]);
-    expect(stderr).toMatch(`Expected the function to throw an error.`);
+    expect(stderr).toMatch('Received function did not throw');
     expect(status).toBe(1);
   }
 });
@@ -74,9 +74,7 @@ test('cannot be used with .not', () => {
   {
     writeFiles(TESTS_DIR, {[filename]: template()});
     const {stderr, status} = runJest(DIR, ['-w=1', '--ci=false', filename]);
-    expect(stderr).toMatch(
-      'Jest: `.not` cannot be used with `.toThrowErrorMatchingSnapshot()`.',
-    );
+    expect(stderr).toMatch('.not cannot be used with snapshot matchers');
     expect(status).toBe(1);
   }
 });

e2e/snapshot/__tests__/snapshot.test.js

@@ -31,7 +31,7 @@ describe('snapshot', () => {
 
   it('cannot be used with .not', () => {
     expect(() => expect('').not.toMatchSnapshot()).toThrow(
-      'Jest: `.not` cannot be used with `.toMatchSnapshot()`.'
+      '.not cannot be used with snapshot matchers'
     );
   });
 

packages/jest-matcher-utils/src/index.ts

@@ -40,6 +40,7 @@ export {DiffOptions};
 export const EXPECTED_COLOR = chalk.green;
 export const RECEIVED_COLOR = chalk.red;
 export const INVERTED_COLOR = chalk.inverse;
+export const BOLD_WEIGHT = chalk.bold;
 const DIM_COLOR = chalk.dim;
 
 const NUMBERS = [