feat: add match named snapshot (jestjs#14045)

Co-authored-by: Tom Mrazauskas <[email protected]>

CHANGELOG.md

@@ -3,8 +3,9 @@
 ### Features
 
 - `[jest-cli]` Include type definitions to generated config files ([#14078](https://github.com/facebook/jest/pull/14078))
-- `[jest-snapshot]` Support arrays as property matchers ([#14025](https://github.com/facebook/jest/pull/14025))
 - `[jest-core, jest-circus, jest-reporter, jest-runner]` Added support for reporting about start individual test cases using jest-circus ([#14174](https://github.com/jestjs/jest/pull/14174))
+- `[jest-snapshot]` Support arrays as property matchers ([#14025](https://github.com/facebook/jest/pull/14025))
+- `[jest-snapshot]` Add `toMatchNamedSnapshot` to bring snapshot support to concurrent mode ([#14045](https://github.com/facebook/jest/pull/14045))
 
 ### Fixes
 

docs/ExpectAPI.md

@@ -744,6 +744,16 @@ You can provide an optional `propertyMatchers` object argument, which has asymme
 
 You can provide an optional `hint` 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.
 
+### `.toMatchNamedSnapshot(snapshotName, propertyMatchers?)`
+
+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.
+
+By setting the `snapshotName` explicitly (as opposed to letting Jest infer the name from context) it can be guaranteed to be consistent across test runs, whatever the context at the time of evaluation. Jest always appends a number at the end of a snapshot name.
+
+Jest sorts snapshots by name in the corresponding `.snap` file.
+
 ### `.toMatchInlineSnapshot(propertyMatchers?, inlineSnapshot)`
 
 Ensures that a value matches the most recent snapshot.
@@ -876,6 +886,12 @@ exports[`drinking flavors throws on octopus 1`] = `"yuck, octopus flavor"`;
 
 Check out [React Tree Snapshot Testing](/blog/2016/07/27/jest-14) for more information on snapshot testing.
 
+### `.toThrowErrorMatchingNamedSnapshot(snapshotName)`
+
+Use `.toThrowErrorMatchingNamedSnapshot` to test that a function throws an error matching the most recent snapshot when it is called.
+
+By setting the `snapshotName` explicitly (as opposed to letting Jest infer the name from context) it can be guaranteed to be consistent across test runs, whatever the context at the time of evaluation. Jest always appends a number at the end of a snapshot name.
+
 ### `.toThrowErrorMatchingInlineSnapshot(inlineSnapshot)`
 
 Use `.toThrowErrorMatchingInlineSnapshot` to test that a function throws an error matching the most recent snapshot when it is called.

docs/SnapshotTesting.md

@@ -52,6 +52,12 @@ More information on how snapshot testing works and why we built it can be found
 
 :::
 
+:::tip
+
+The `toMatchSnapshot` matcher infers the name based on the test function context when the snapshot is evaluated. This can cause snapshots in tests that are run concurrently to have different names on each test run. If you want to guarantee consistent names, you can use the `toMatchNamedSnapshot` matcher.
+
+:::
+
 ### Updating Snapshots
 
 It's straightforward to spot when a snapshot test fails after a bug has been introduced. When that happens, go ahead and fix the issue and make sure your snapshot tests are passing again. Now, let's talk about the case when a snapshot test is failing due to an intentional implementation change.

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

@@ -0,0 +1,8 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`support-reject 1`] = `
+"// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[\`support-reject 1\`] = \`"octopus"\`;
+"
+`;