feat(snapshot): support custom snapshot matcher

docs/guide/extending-matchers.md

@@ -107,6 +107,10 @@ function customMatcher(this: MatcherState, received: unknown, arg1: unknown, arg
 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).
+:::
+
 Matcher function has access to `this` context with the following properties:
 
 ## `isNot`

docs/guide/migration.md

@@ -650,6 +650,36 @@ export default defineConfig({
 
 Otherwise your snapshots will have a lot of escaped `"` characters.
 
+### Custom Snapshot Matchers
+
+Jest imports snapshot composables from `jest-snapshot`. In Vitest, import from `vitest/runtime` instead:
+
+```ts
+const { toMatchSnapshot } = require('jest-snapshot') // [!code --]
+import { toMatchSnapshot } from 'vitest/runtime' // [!code ++]
+
+expect.extend({
+  toMatchTrimmedSnapshot(received: string, length: number) {
+    return toMatchSnapshot.call(this, received.slice(0, length))
+  },
+})
+```
+
+For inline snapshots, the same applies:
+
+```ts
+const { toMatchInlineSnapshot } = require('jest-snapshot') // [!code --]
+import { toMatchInlineSnapshot } from 'vitest/runtime' // [!code ++]
+
+expect.extend({
+  toMatchTrimmedInlineSnapshot(received: string, inlineSnapshot?: string) {
+    return toMatchInlineSnapshot.call(this, received.slice(0, 10), inlineSnapshot)
+  },
+})
+```
+
+See [Custom Snapshot Matchers](/guide/snapshot#custom-snapshot-matchers) for the full guide.
+
 ## Migrating from Mocha + Chai + Sinon {#mocha-chai-sinon}
 
 Vitest provides excellent support for migrating from Mocha+Chai+Sinon test suites. While Vitest uses a Jest-compatible API by default, it also provides Chai-style assertions for spy/mock testing, making migration easier.

docs/guide/snapshot.md

@@ -200,6 +200,76 @@ Pretty foo: Object {
 
 We are using Jest's `pretty-format` for serializing snapshots. You can read more about it here: [pretty-format](https://github.com/facebook/jest/blob/main/packages/pretty-format/README.md#serialize).
 
+## 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).
+
+```ts
+import { expect, test } from 'vitest'
+import { toMatchFileSnapshot, toMatchInlineSnapshot, toMatchSnapshot } from 'vitest/runtime'
+
+expect.extend({
+  toMatchTrimmedSnapshot(received: string, length: number) {
+    return toMatchSnapshot.call(this, received.slice(0, length))
+  },
+  toMatchTrimmedInlineSnapshot(received: string, inlineSnapshot?: string) {
+    return toMatchInlineSnapshot.call(this, received.slice(0, 10), inlineSnapshot)
+  },
+  async toMatchTrimmedFileSnapshot(received: string, file: string) {
+    return toMatchFileSnapshot.call(this, received.slice(0, 10), file)
+  },
+})
+
+test('file snapshot', () => {
+  expect('extra long string oh my gerd').toMatchTrimmedSnapshot(10)
+})
+
+test('inline snapshot', () => {
+  expect('extra long string oh my gerd').toMatchTrimmedInlineSnapshot()
+})
+
+test('raw file snapshot', async () => {
+  await expect('extra long string oh my gerd').toMatchTrimmedFileSnapshot('./raw-file.txt')
+})
+```
+
+The composables return `{ pass, message }` so you can further customize the error:
+
+```ts
+expect.extend({
+  toMatchTrimmedSnapshot(received: string, length: number) {
+    const result = toMatchSnapshot.call(this, received.slice(0, length))
+    return { ...result, message: () => `Trimmed snapshot failed: ${result.message()}` }
+  },
+})
+```
+
+::: warning
+For inline snapshot matchers, the snapshot argument must be the last parameter (or second-to-last when using property matchers). Vitest rewrites the last string argument in the source code, so custom arguments before the snapshot work, but custom arguments after it are not supported.
+:::
+
+::: tip
+File snapshot matchers must be `async` — `toMatchFileSnapshot` returns a `Promise`. Remember to `await` the result in the matcher and in your test.
+:::
+
+For TypeScript, extend the `Assertion` interface:
+
+```ts
+import 'vitest'
+
+declare module 'vitest' {
+  interface Assertion<T = any> {
+    toMatchTrimmedSnapshot: (length: number) => T
+    toMatchTrimmedInlineSnapshot: (inlineSnapshot?: string) => T
+    toMatchTrimmedFileSnapshot: (file: string) => Promise<T>
+  }
+}
+```
+
+::: tip
+See [Extending Matchers](/guide/extending-matchers) for more on `expect.extend` and custom matcher conventions.
+:::
+
 ## Difference from Jest
 
 Vitest provides an almost compatible Snapshot feature with [Jest's](https://jestjs.io/docs/snapshot-testing) with a few exceptions:

packages/expect/src/jest-extend.ts

@@ -54,6 +54,7 @@ function getMatcherState(
     suppressedErrors: [],
     soft: util.flag(assertion, 'soft') as boolean | undefined,
     poll: util.flag(assertion, 'poll') as boolean | undefined,
+    __vitest_assertion__: assertion as any,
   }
 
   return {
@@ -89,7 +90,7 @@ function JestExtendPlugin(
   return (_, utils) => {
     Object.entries(matchers).forEach(
       ([expectAssertionName, expectAssertion]) => {
-        function expectWrapper(
+        function __VITEST_EXTEND_ASSERTION__(
           this: Chai.AssertionStatic & Chai.Assertion,
           ...args: any[]
         ) {
@@ -133,7 +134,7 @@ function JestExtendPlugin(
           }
         }
 
-        const softWrapper = wrapAssertion(utils, expectAssertionName, expectWrapper)
+        const softWrapper = wrapAssertion(utils, expectAssertionName, __VITEST_EXTEND_ASSERTION__)
         utils.addMethod(
           (globalThis as any)[JEST_MATCHERS_OBJECT].matchers,
           expectAssertionName,

packages/expect/src/types.ts

@@ -82,6 +82,13 @@ export interface MatcherState {
   }
   soft?: boolean
   poll?: boolean
+  /**
+   * this allows `expect.extend`-based custom matcher
+   * to implement builtin vitest/chai assertion equivalent feature.
+   * this used for custom snapshot matcher API.
+   */
+  /** @internal */
+  __vitest_assertion__: Assertion
 }
 
 export interface SyncExpectationResult {

packages/expect/src/utils.ts

@@ -5,7 +5,7 @@ import { noop } from '@vitest/utils/helpers'
 
 export function createAssertionMessage(
   util: Chai.ChaiUtils,
-  assertion: Assertion,
+  assertion: Chai.Assertion,
   hasArgs: boolean,
 ) {
   const soft = util.flag(assertion, 'soft') ? '.soft' : ''
@@ -92,6 +92,7 @@ function handleTestError(test: Test, err: unknown) {
   test.result.errors.push(processError(err))
 }
 
+/** wrap assertion function to support `expect.soft` and provide assertion name as `_name` */
 export function wrapAssertion(
   utils: Chai.ChaiUtils,
   name: string,

packages/snapshot/src/client.ts

@@ -48,6 +48,7 @@ interface AssertOptions {
   error?: Error
   errorMessage?: string
   rawSnapshot?: RawSnapshotInfo
+  assertionName?: string
 }
 
 /** Same shape as expect.extend custom matcher result (SyncExpectationResult from @vitest/expect) */
@@ -119,6 +120,7 @@ export class SnapshotClient {
       error,
       errorMessage,
       rawSnapshot,
+      assertionName,
     } = options
     let { received } = options
 
@@ -173,6 +175,7 @@ export class SnapshotClient {
       error,
       inlineSnapshot,
       rawSnapshot,
+      assertionName,
     })
 
     return {

packages/snapshot/src/port/inlineSnapshot.ts

@@ -6,13 +6,18 @@ import {
   offsetToLineNumber,
   positionToOffset,
 } from '@vitest/utils/offset'
+import { memo } from './utils'
 
 export interface InlineSnapshot {
   snapshot: string
   testId: string
   file: string
   line: number
   column: number
+  // it maybe possible to accurately extract this from `ParsedStack.method`,
+  // but for now, we ask higher level assertion to pass it explicitly
+  // since this is useful for certain error messages before we extract stack.
+  assertionName?: string
 }
 
 export async function saveInlineSnapshots(
@@ -33,7 +38,7 @@ export async function saveInlineSnapshots(
 
       for (const snap of snaps) {
         const index = positionToOffset(code, snap.line, snap.column)
-        replaceInlineSnap(code, s, index, snap.snapshot)
+        replaceInlineSnap(code, s, index, snap.snapshot, snap.assertionName)
       }
 
       const transformed = s.toString()
@@ -44,17 +49,31 @@ export async function saveInlineSnapshots(
   )
 }
 
-const startObjectRegex
+const defaultStartObjectRegex
   = /(?:toMatchInlineSnapshot|toThrowErrorMatchingInlineSnapshot)\s*\(\s*(?:\/\*[\s\S]*\*\/\s*|\/\/.*(?:[\n\r\u2028\u2029]\s*|[\t\v\f \xA0\u1680\u2000-\u200A\u202F\u205F\u3000\uFEFF]))*\{/
 
+function escapeRegExp(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+const buildStartObjectRegex = memo((assertionName: string) => {
+  const replaced = defaultStartObjectRegex.source.replace(
+    'toMatchInlineSnapshot|toThrowErrorMatchingInlineSnapshot',
+    escapeRegExp(assertionName),
+  )
+  return new RegExp(replaced)
+})
+
 function replaceObjectSnap(
   code: string,
   s: MagicString,
   index: number,
   newSnap: string,
+  assertionName?: string,
 ) {
   let _code = code.slice(index)
-  const startMatch = startObjectRegex.exec(_code)
+  const regex = assertionName ? buildStartObjectRegex(assertionName) : defaultStartObjectRegex
+  const startMatch = regex.exec(_code)
   if (!startMatch) {
     return false
   }
@@ -121,23 +140,17 @@ function prepareSnapString(snap: string, source: string, index: number) {
     .replace(/\$\{/g, '\\${')}\n${indent}${quote}`
 }
 
-const toMatchInlineName = 'toMatchInlineSnapshot'
-const toThrowErrorMatchingInlineName = 'toThrowErrorMatchingInlineSnapshot'
+const defaultMethodNames = ['toMatchInlineSnapshot', 'toThrowErrorMatchingInlineSnapshot']
 
 // on webkit, the line number is at the end of the method, not at the start
-function getCodeStartingAtIndex(code: string, index: number) {
-  const indexInline = index - toMatchInlineName.length
-  if (code.slice(indexInline, index) === toMatchInlineName) {
-    return {
-      code: code.slice(indexInline),
-      index: indexInline,
-    }
-  }
-  const indexThrowInline = index - toThrowErrorMatchingInlineName.length
-  if (code.slice(index - indexThrowInline, index) === toThrowErrorMatchingInlineName) {
-    return {
-      code: code.slice(index - indexThrowInline),
-      index: index - indexThrowInline,
+function getCodeStartingAtIndex(code: string, index: number, methodNames: string[]) {
+  for (const name of methodNames) {
+    const adjusted = index - name.length
+    if (adjusted >= 0 && code.slice(adjusted, index) === name) {
+      return {
+        code: code.slice(adjusted),
+        index: adjusted,
+      }
     }
   }
   return {
@@ -146,24 +159,35 @@ function getCodeStartingAtIndex(code: string, index: number) {
   }
 }
 
-const startRegex
+const defaultStartRegex
   = /(?:toMatchInlineSnapshot|toThrowErrorMatchingInlineSnapshot)\s*\(\s*(?:\/\*[\s\S]*\*\/\s*|\/\/.*(?:[\n\r\u2028\u2029]\s*|[\t\v\f \xA0\u1680\u2000-\u200A\u202F\u205F\u3000\uFEFF]))*[\w$]*(['"`)])/
+
+const buildStartRegex = memo((assertionName: string) => {
+  const replaced = defaultStartRegex.source.replace(
+    'toMatchInlineSnapshot|toThrowErrorMatchingInlineSnapshot',
+    escapeRegExp(assertionName),
+  )
+  return new RegExp(replaced)
+})
+
 export function replaceInlineSnap(
   code: string,
   s: MagicString,
   currentIndex: number,
   newSnap: string,
+  assertionName?: string,
 ): boolean {
-  const { code: codeStartingAtIndex, index } = getCodeStartingAtIndex(code, currentIndex)
+  const methodNames = assertionName ? [assertionName] : defaultMethodNames
+  const { code: codeStartingAtIndex, index } = getCodeStartingAtIndex(code, currentIndex, methodNames)
 
+  const startRegex = assertionName ? buildStartRegex(assertionName) : defaultStartRegex
   const startMatch = startRegex.exec(codeStartingAtIndex)
 
-  const firstKeywordMatch = /toMatchInlineSnapshot|toThrowErrorMatchingInlineSnapshot/.exec(
-    codeStartingAtIndex,
-  )
+  const keywordRegex = assertionName ? new RegExp(escapeRegExp(assertionName)) : /toMatchInlineSnapshot|toThrowErrorMatchingInlineSnapshot/
+  const firstKeywordMatch = keywordRegex.exec(codeStartingAtIndex)
 
   if (!startMatch || startMatch.index !== firstKeywordMatch?.index) {
-    return replaceObjectSnap(code, s, index, newSnap)
+    return replaceObjectSnap(code, s, index, newSnap, assertionName)
   }
 
   const quote = startMatch[1]