Description

• Closes Support building custom snapshot matchers with expect.extend #9948
• Research note https://gist.github.com/hi-ogawa/617dbc67f7afb19cb903093d0e693dbe

This PR adds composable toMatchSnapshot, toMatchInlineSnapshot, and toMatchFileSnapshot helper exported from vitest/runtime, enabling users to build custom snapshot matchers with expect.extend similar to jest-snapshot allows.

This closes the gap between expect.extend and vitest's snapshot infrastructure — custom matchers now get full snapshot lifecycle support (creation, mismatch detection, inline rewriting, update) without workarounds.

Additionally, builtin snapshot matchers are refactored to go through toMatchSnapshotImpl as single snapshot integration point internally within packages/vitest/src/integrations/snapshot/chai.ts.

Example

import { toMatchFileSnapshot, toMatchInlineSnapshot, toMatchSnapshot } from 'vitest/runtime'

expect.extend({
  toMatchTrimmedSnapshot(received: string) {
    return toMatchSnapshot.call(this, received.slice(0, 10))
  },
  toMatchTrimmedInlineSnapshot(received: string, inlineSnapshot?: string) {
    return toMatchInlineSnapshot.call(this, received.slice(0, 10), inlineSnapshot)
  },
  async toMatchTrimmedFileSnapshot(received: string, filepath: string) {
    return toMatchFileSnapshot.call(this, received.slice(0, 10), filepath)
  },
})

test('file snapshot', () => {
  expect('extra long string oh my gerd').toMatchTrimmedSnapshot()
})

test('inline snapshot', () => {
  expect('extra long string oh my gerd').toMatchTrimmedInlineSnapshot(`"extra long"`)
})

test('raw file snapshot', async () => {
  await expect('extra long string oh my gerd').toMatchFileTrimmedSnapshot('./raw.txt')
})

Please don't delete this checklist! Before submitting the PR, please make sure you do the following:

• It's really useful if your PR references an issue where it is discussed ahead of time. If the feature is substantial or introduces breaking changes without a discussion, PR might be closed.
• Ideally, include a test that fails without this PR but passes with it.
• Please, don't make changes to pnpm-lock.yaml unless you introduce a new test example.
• Please check Allow edits by maintainers to make review process faster. Note that this option is not available for repositories that are owned by Github organizations.

Tests

• Run the tests with pnpm test:ci.

Documentation

• If you introduce new functionality, document it. You can run documentation with pnpm run docs command.

Changesets

• Changes in changelog are generated from PR name. Please, make sure that it explains your changes in an understandable manner. Please, prefix changeset messages with feat:, fix:, perf:, docs:, or chore:.