fix(snapshot): export custom snapshot matcher helper from vitest (#10042)

Co-authored-by: Codex <noreply@openai.com>

Author: hi-ogawa

docs/guide/extending-matchers.md

@@ -108,7 +108,7 @@ expect.extend({ customMatcher })
 ```
 
 ::: tip
-To build custom **snapshot matchers** (wrappers around `toMatchSnapshot` / `toMatchInlineSnapshot` / `toMatchFileSnapshot`), use the composable functions from `vitest/runtime`. See [Custom Snapshot Matchers](/guide/snapshot#custom-snapshot-matchers).
+To build custom **snapshot matchers** (wrappers around `toMatchSnapshot()` / `toMatchInlineSnapshot()` / `toMatchFileSnapshot()`), use `Snapshots` exported from `vitest`. See [Custom Snapshot Matchers](/guide/snapshot#custom-snapshot-matchers).
 :::
 
 Matcher function has access to `this` context with the following properties:

docs/guide/migration.md

@@ -652,11 +652,12 @@ Otherwise your snapshots will have a lot of escaped `"` characters.
 
 ### Custom Snapshot Matchers <Badge type="warning">experimental</Badge> <Version>4.1.3</Version>
 
-Jest imports snapshot composables from `jest-snapshot`. In Vitest, import from `vitest/runtime` instead:
+Jest imports snapshot composables from `jest-snapshot`. In Vitest, use `Snapshots` from `vitest` instead:
 
 ```ts
 const { toMatchSnapshot } = require('jest-snapshot') // [!code --]
-import { toMatchSnapshot } from 'vitest/runtime' // [!code ++]
+import { Snapshots } from 'vitest' // [!code ++]
+const { toMatchSnapshot } = Snapshots // [!code ++]
 
 expect.extend({
   toMatchTrimmedSnapshot(received: string, length: number) {
@@ -669,7 +670,8 @@ For inline snapshots, the same applies:
 
 ```ts
 const { toMatchInlineSnapshot } = require('jest-snapshot') // [!code --]
-import { toMatchInlineSnapshot } from 'vitest/runtime' // [!code ++]
+import { Snapshots } from 'vitest' // [!code ++]
+const { toMatchInlineSnapshot } = Snapshots // [!code ++]
 
 expect.extend({
   toMatchTrimmedInlineSnapshot(received: string, inlineSnapshot?: string) {

docs/guide/snapshot.md

@@ -202,11 +202,12 @@ Pretty foo: Object {
 
 ## Custom Snapshot Matchers <Badge type="warning">experimental</Badge> <Version>4.1.3</Version> {#custom-snapshot-matchers}
 
-You can build custom snapshot matchers using the composable functions exported from `vitest/runtime`. These let you transform values before snapshotting while preserving full snapshot lifecycle support (creation, update, inline rewriting).
+You can build custom snapshot matchers using the composable functions exposed on `Snapshots` from `vitest`. These let you transform values before snapshotting while preserving full snapshot lifecycle support (creation, update, inline rewriting).
 
 ```ts
-import { expect, test } from 'vitest'
-import { toMatchFileSnapshot, toMatchInlineSnapshot, toMatchSnapshot } from 'vitest/runtime'
+import { expect, test, Snapshots } from 'vitest'
+
+const { toMatchFileSnapshot, toMatchInlineSnapshot, toMatchSnapshot } = Snapshots
 
 expect.extend({
   toMatchTrimmedSnapshot(received: string, length: number) {
@@ -236,6 +237,10 @@ test('raw file snapshot', async () => {
 The composables return `{ pass, message }` so you can further customize the error:
 
 ```ts
+import { Snapshots } from 'vitest'
+
+const { toMatchSnapshot } = Snapshots
+
 expect.extend({
   toMatchTrimmedSnapshot(received: string, length: number) {
     const result = toMatchSnapshot.call(this, received.slice(0, length))

packages/vitest/src/integrations/snapshot/chai.ts

@@ -1,4 +1,4 @@
-import type { ChaiPlugin, MatcherState, SyncExpectationResult } from '@vitest/expect'
+import type { AsyncExpectationResult, ChaiPlugin, MatcherState, SyncExpectationResult } from '@vitest/expect'
 import type { Test } from '@vitest/runner'
 import { chai, createAssertionMessage, equals, iterableEquality, recordAsyncExpect, subsetEquality, wrapAssertion } from '@vitest/expect'
 import { getNames } from '@vitest/runner/utils'
@@ -268,100 +268,109 @@ function assertMatchResult(result: SyncExpectationResult): void {
 }
 
 /**
- * Composable for building custom snapshot matchers via `expect.extend`.
- * Call with `this` bound to the matcher state. Returns `{ pass, message }`
- * compatible with the custom matcher return contract.
- *
- * @example
- * ```ts
- * import { toMatchSnapshot } from 'vitest/runtime'
- *
- * expect.extend({
- *   toMatchTrimmedSnapshot(received: string) {
- *     return toMatchSnapshot.call(this, received.slice(0, 10))
- *   },
- * })
- * ```
+ * Composable snapshot matcher helpers for building custom snapshot matchers
+ * with `expect.extend`.
  *
  * @experimental
  * @see https://vitest.dev/guide/snapshot.html#custom-snapshot-matchers
  */
-export function toMatchSnapshot(
-  this: MatcherState,
-  received: unknown,
-  propertiesOrHint?: object | string,
-  hint?: string,
-): SyncExpectationResult {
-  return toMatchSnapshotImpl({
-    assertion: this.__vitest_assertion__,
-    received,
-    ...normalizeArguments(propertiesOrHint, hint),
-  })
-}
+export const Snapshots = {
+  /**
+   * Composable for building custom snapshot matchers via `expect.extend`.
+   * Call with `this` bound to the matcher state. Returns `{ pass, message }`
+   * compatible with the custom matcher return contract.
+   *
+   * @example
+   * ```ts
+   * import { Snapshots } from 'vitest/runtime'
+   *
+   * expect.extend({
+   *   toMatchTrimmedSnapshot(received: string) {
+   *     return Snapshots.toMatchSnapshot.call(this, received.slice(0, 10))
+   *   },
+   * })
+   * ```
+   *
+   * @experimental
+   * @see https://vitest.dev/guide/snapshot.html#custom-snapshot-matchers
+   */
+  toMatchSnapshot(
+    this: MatcherState,
+    received: unknown,
+    propertiesOrHint?: object | string,
+    hint?: string,
+  ): SyncExpectationResult {
+    return toMatchSnapshotImpl({
+      assertion: this.__vitest_assertion__,
+      received,
+      ...normalizeArguments(propertiesOrHint, hint),
+    })
+  },
 
-/**
- * Composable for building custom inline snapshot matchers via `expect.extend`.
- * Call with `this` bound to the matcher state. Returns `{ pass, message }`
- * compatible with the custom matcher return contract.
- *
- * @example
- * ```ts
- * import { toMatchInlineSnapshot } from 'vitest/runtime'
- *
- * expect.extend({
- *   toMatchTrimmedInlineSnapshot(received: string, inlineSnapshot?: string) {
- *     return toMatchInlineSnapshot.call(this, received.slice(0, 10), inlineSnapshot)
- *   },
- * })
- * ```
- *
- * @experimental
- * @see https://vitest.dev/guide/snapshot.html#custom-snapshot-matchers
- */
-export function toMatchInlineSnapshot(
-  this: MatcherState,
-  received: unknown,
-  propertiesOrInlineSnapshot?: object | string,
-  inlineSnapshotOrHint?: string,
-  hint?: string,
-): SyncExpectationResult {
-  return toMatchSnapshotImpl({
-    assertion: this.__vitest_assertion__,
-    received,
-    isInline: true,
-    ...normalizeInlineArguments(propertiesOrInlineSnapshot, inlineSnapshotOrHint, hint),
-  })
-}
+  /**
+   * Composable for building custom inline snapshot matchers via `expect.extend`.
+   * Call with `this` bound to the matcher state. Returns `{ pass, message }`
+   * compatible with the custom matcher return contract.
+   *
+   * @example
+   * ```ts
+   * import { Snapshots } from 'vitest/runtime'
+   *
+   * expect.extend({
+   *   toMatchTrimmedInlineSnapshot(received: string, inlineSnapshot?: string) {
+   *     return Snapshots.toMatchInlineSnapshot.call(this, received.slice(0, 10), inlineSnapshot)
+   *   },
+   * })
+   * ```
+   *
+   * @experimental
+   * @see https://vitest.dev/guide/snapshot.html#custom-snapshot-matchers
+   */
+  toMatchInlineSnapshot(
+    this: MatcherState,
+    received: unknown,
+    propertiesOrInlineSnapshot?: object | string,
+    inlineSnapshotOrHint?: string,
+    hint?: string,
+  ): SyncExpectationResult {
+    return toMatchSnapshotImpl({
+      assertion: this.__vitest_assertion__,
+      received,
+      isInline: true,
+      ...normalizeInlineArguments(propertiesOrInlineSnapshot, inlineSnapshotOrHint, hint),
+    })
+  },
 
-/**
- * Composable for building custom file snapshot matchers via `expect.extend`.
- * Call with `this` bound to the matcher state. Returns a `Promise<{ pass, message }>`
- * compatible with the custom matcher return contract.
- *
- * @example
- * ```ts
- * import { toMatchFileSnapshot } from 'vitest/runtime'
- *
- * expect.extend({
- *   async toMatchTrimmedFileSnapshot(received: string, file: string) {
- *     return toMatchFileSnapshot.call(this, received.slice(0, 10), file)
- *   },
- * })
- * ```
- *
- * @experimental
- * @see https://vitest.dev/guide/snapshot.html#custom-snapshot-matchers
- */
-export function toMatchFileSnapshot(
-  this: MatcherState,
-  received: unknown,
-  filepath: string,
-  hint?: string,
-): Promise<SyncExpectationResult> {
-  return toMatchFileSnapshotImpl({
-    assertion: this.__vitest_assertion__,
-    received,
-    filepath,
-    hint,
-  })
+  /**
+   * Composable for building custom file snapshot matchers via `expect.extend`.
+   * Call with `this` bound to the matcher state. Returns a `Promise<{ pass, message }>`
+   * compatible with the custom matcher return contract.
+   *
+   * @example
+   * ```ts
+   * import { Snapshots } from 'vitest/runtime'
+   *
+   * expect.extend({
+   *   async toMatchTrimmedFileSnapshot(received: string, file: string) {
+   *     return Snapshots.toMatchFileSnapshot.call(this, received.slice(0, 10), file)
+   *   },
+   * })
+   * ```
+   *
+   * @experimental
+   * @see https://vitest.dev/guide/snapshot.html#custom-snapshot-matchers
+   */
+  toMatchFileSnapshot(
+    this: MatcherState,
+    received: unknown,
+    filepath: string,
+    hint?: string,
+  ): AsyncExpectationResult {
+    return toMatchFileSnapshotImpl({
+      assertion: this.__vitest_assertion__,
+      received,
+      filepath,
+      hint,
+    })
+  },
 }

packages/vitest/src/public/index.ts

@@ -30,6 +30,7 @@ export type {
 } from '../api/types'
 export { assert, chai, createExpect, expect, should } from '../integrations/chai'
 export { inject } from '../integrations/inject'
+export { Snapshots } from '../integrations/snapshot/chai'
 
 export { vi, vitest } from '../integrations/vi'
 export type { VitestUtils } from '../integrations/vi'

packages/vitest/src/public/runtime.ts

@@ -11,7 +11,6 @@ import { getWorkerState } from '../runtime/utils'
 
 export { environments as builtinEnvironments } from '../integrations/env/index'
 export { populateGlobal } from '../integrations/env/utils'
-export { toMatchFileSnapshot, toMatchInlineSnapshot, toMatchSnapshot } from '../integrations/snapshot/chai'
 export { VitestNodeSnapshotEnvironment as VitestSnapshotEnvironment } from '../integrations/snapshot/environments/node'
 export type {
   Environment,

pnpm-lock.yaml

@@ -19,6 +19,7 @@ it('exports snapshot', async ({ skip, task }) => {
       ".": {
         "BenchmarkRunner": "function",
         "EvaluatedModules": "function",
+        "Snapshots": "object",
         "TestRunner": "function",
         "afterAll": "function",
         "afterEach": "function",
@@ -165,9 +166,6 @@ it('exports snapshot', async ({ skip, task }) => {
         "__INTERNAL": "object",
         "builtinEnvironments": "object",
         "populateGlobal": "function",
-        "toMatchFileSnapshot": "function",
-        "toMatchInlineSnapshot": "function",
-        "toMatchSnapshot": "function",
       },
       "./snapshot": {
         "VitestSnapshotEnvironment": "function",

test/core/test/exports.test.ts

@@ -9,6 +9,7 @@
     "vitest": "workspace:*"
   },
   "devDependencies": {
+    "@vitest/browser-playwright": "workspace:*",
     "jest-image-snapshot": "^6.5.1"
   }
 }