Add toMatchNamedSnapshot

Author: bakamitai456

CHANGELOG.md

@@ -25,6 +25,11 @@
 
 ### Performance
 
+## 29.6.0
+
+### Features
+
+- `[jest-snapshot]` Add `toMatchNamedSnapshot` to bring snapshot support to concurrent mode
 ## 29.5.0
 
 ### Features

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(propertyMatchers?, snapshotName?)`
+
+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 functions as the test name. By providing a snapshot name (as opposed to letting Jest infer the name from context) snapshot names 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.

docs/SnapshotTesting.md

@@ -264,6 +264,8 @@ Now, every time the snapshot test case runs, `Date.now()` will return `148236336
 
 Always strive to use descriptive test and/or snapshot names for snapshots. The best names describe the expected snapshot content. This makes it easier for reviewers to verify the snapshots during review, and for anyone to know whether or not an outdated snapshot is the correct behavior before updating.
 
+The default matcher, `toMatchSnapshot`, 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 `toMatchNamedSnapshot` as an alternative matcher.
+
 For example, compare:
 
 ```js

packages/jest-snapshot/src/index.ts

@@ -30,7 +30,12 @@ import {
   printReceived,
   printSnapshotAndReceived,
 } from './printSnapshot';
-import type {Context, FileSystem, MatchSnapshotConfig} from './types';
+import type {
+  Context,
+  FileSystem,
+  MatchSnapshotConfig,
+  SnapshotNameConfig,
+} from './types';
 import {deepMerge, escapeBacktickString, serialize} from './utils';
 
 export {addSerializer, getSerializers} from './plugins';
@@ -67,6 +72,19 @@ const printSnapshotName = (
   } ${count}\``;
 };
 
+const getSnapshotName = (config: SnapshotNameConfig): string => {
+  const {snapshotName, currentTestName, hint} = config;
+
+  if (snapshotName) {
+    return snapshotName;
+  }
+  if (currentTestName && hint) {
+    return `${currentTestName}: ${hint}`;
+  }
+  // future BREAKING change: || hint
+  return currentTestName || '';
+};
+
 function stripAddedIndentation(inlineSnapshot: string) {
   // Find indentation if exists.
   const match = inlineSnapshot.match(INDENTATION_REGEX);
@@ -209,6 +227,67 @@ export const toMatchSnapshot: MatcherFunctionWithContext<
   });
 };
 
+export const toMatchNamedSnapshot: MatcherFunctionWithContext<
+  Context,
+  [propertiesOrSnapshot?: object | string, snapshotName?: string]
+> = function (received, propertiesOrSnapshotName, snapshotName) {
+  const matcherName = 'toMatchNamedSnapshot';
+  let properties;
+
+  const length = arguments.length;
+  if (length === 2 && typeof propertiesOrSnapshotName === 'string') {
+    snapshotName = propertiesOrSnapshotName;
+  } else if (length >= 2) {
+    if (
+      Array.isArray(propertiesOrSnapshotName) ||
+      typeof propertiesOrSnapshotName !== 'object' ||
+      propertiesOrSnapshotName === null
+    ) {
+      const options: MatcherHintOptions = {
+        isNot: this.isNot,
+        promise: this.promise,
+      };
+      let printedWithType = printWithType(
+        'Expected properties',
+        propertiesOrSnapshotName,
+        printExpected,
+      );
+
+      if (length === 3) {
+        options.secondArgument = 'snapshotName';
+        options.secondArgumentColor = BOLD_WEIGHT;
+
+        if (propertiesOrSnapshotName == null) {
+          printedWithType +=
+            "\n\nTo provide a snapshot name without properties: toMatchNamedSnapshot('snapshotName')";
+        }
+      }
+
+      throw new Error(
+        matcherErrorMessage(
+          matcherHint(matcherName, undefined, PROPERTIES_ARG, options),
+          `Expected ${EXPECTED_COLOR('properties')} must be an object`,
+          printedWithType,
+        ),
+      );
+    }
+
+    // Future breaking change: Snapshot hint must be a string
+    // if (arguments.length === 3 && typeof hint !== 'string') {}
+
+    properties = propertiesOrSnapshotName;
+  }
+
+  return _toMatchSnapshot({
+    context: this,
+    isInline: false,
+    matcherName,
+    properties,
+    received,
+    snapshotName,
+  });
+};
+
 export const toMatchInlineSnapshot: MatcherFunctionWithContext<
   Context,
   [propertiesOrSnapshot?: object | string, inlineSnapshot?: string]
@@ -273,8 +352,15 @@ export const toMatchInlineSnapshot: MatcherFunctionWithContext<
 };
 
 const _toMatchSnapshot = (config: MatchSnapshotConfig) => {
-  const {context, hint, inlineSnapshot, isInline, matcherName, properties} =
-    config;
+  const {
+    context,
+    hint,
+    inlineSnapshot,
+    isInline,
+    matcherName,
+    snapshotName,
+    properties,
+  } = config;
   let {received} = config;
 
   context.dontThrow && context.dontThrow();
@@ -301,10 +387,7 @@ const _toMatchSnapshot = (config: MatchSnapshotConfig) => {
     );
   }
 
-  const fullTestName =
-    currentTestName && hint
-      ? `${currentTestName}: ${hint}`
-      : currentTestName || ''; // future BREAKING change: || hint
+  const fullTestName = getSnapshotName({currentTestName, hint, snapshotName});
 
   if (typeof properties === 'object') {
     if (typeof received !== 'object' || received === null) {

packages/jest-snapshot/src/types.ts

@@ -27,10 +27,17 @@ export type MatchSnapshotConfig = {
   inlineSnapshot?: string;
   isInline: boolean;
   matcherName: string;
+  snapshotName?: string;
   properties?: object;
   received: any;
 };
 
+export type SnapshotNameConfig = {
+  hint?: string;
+  snapshotName?: string;
+  currentTestName?: string;
+};
+
 export type SnapshotData = Record<string, string>;
 
 export interface SnapshotMatchers<R extends void | Promise<void>, T> {
@@ -47,6 +54,19 @@ export interface SnapshotMatchers<R extends void | Promise<void>, T> {
     propertyMatchers: Partial<U>,
     hint?: string,
   ): R;
+  /**
+   * This ensures that a value matches the most recent snapshot.
+   * Check out [the Snapshot Testing guide](https://jestjs.io/docs/snapshot-testing) for more information.
+   */
+  toMatchNamedSnapshot<U extends Record<keyof T, unknown>>(
+    propertyMatchers: Partial<U>,
+    snapshot?: string,
+  ): R;
+  /**
+   * This ensures that a value matches the most recent snapshot.
+   * Check out [the Snapshot Testing guide](https://jestjs.io/docs/snapshot-testing) for more information.
+   */
+  toMatchNamedSnapshot(snapshotName?: string): R;
   /**
    * This ensures that a value matches the most recent snapshot with property matchers.
    * Instead of writing the snapshot value to a .snap file, it will be written into the source code automatically.