Skip to content

Commit 03fdbed

Browse files
hi-ogawahi-ogawa
committed
docs: re-order
1 parent 03f1316 commit 03fdbed

1 file changed

Lines changed: 69 additions & 73 deletions

File tree

‎docs/guide/snapshot.md‎

Lines changed: 69 additions & 73 deletions
Original file line numberDiff line numberDiff line change
@@ -232,9 +232,76 @@ Pretty foo: Object {
232232

233233
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).
234234

235-
## Custom Snapshot Matchers with Domain Adapters <Badge type="warning">experimental</Badge> {#custom-snapshot-domain}
235+
## Custom Snapshot Matchers <Badge type="warning">experimental</Badge> <Version>4.1.3</Version> {#custom-snapshot-matchers}
236+
237+
You can build custom snapshot matchers using composable functions exported from `vitest`. These let you transform values before snapshotting while preserving full snapshot lifecycle support (creation, update, inline rewriting).
236238

237-
<!-- TODO: move after custom snapshot matchers section -->
239+
```ts
240+
import { expect, test, toMatchFileSnapshot, toMatchInlineSnapshot, toMatchSnapshot } from 'vitest'
241+
242+
expect.extend({
243+
toMatchTrimmedSnapshot(received: string, length: number) {
244+
return toMatchSnapshot.call(this, received.slice(0, length))
245+
},
246+
toMatchTrimmedInlineSnapshot(received: string, inlineSnapshot?: string) {
247+
return toMatchInlineSnapshot.call(this, received.slice(0, 10), inlineSnapshot)
248+
},
249+
async toMatchTrimmedFileSnapshot(received: string, file: string) {
250+
return toMatchFileSnapshot.call(this, received.slice(0, 10), file)
251+
},
252+
})
253+
254+
test('file snapshot', () => {
255+
expect('extra long string oh my gerd').toMatchTrimmedSnapshot(10)
256+
})
257+
258+
test('inline snapshot', () => {
259+
expect('extra long string oh my gerd').toMatchTrimmedInlineSnapshot()
260+
})
261+
262+
test('raw file snapshot', async () => {
263+
await expect('extra long string oh my gerd').toMatchTrimmedFileSnapshot('./raw-file.txt')
264+
})
265+
```
266+
267+
The composables return `{ pass, message }` so you can further customize the error:
268+
269+
```ts
270+
expect.extend({
271+
toMatchTrimmedSnapshot(received: string, length: number) {
272+
const result = toMatchSnapshot.call(this, received.slice(0, length))
273+
return { ...result, message: () => `Trimmed snapshot failed: ${result.message()}` }
274+
},
275+
})
276+
```
277+
278+
::: warning
279+
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.
280+
:::
281+
282+
::: tip
283+
File snapshot matchers must be `async` — `toMatchFileSnapshot` returns a `Promise`. Remember to `await` the result in the matcher and in your test.
284+
:::
285+
286+
For TypeScript, extend the `Assertion` interface:
287+
288+
```ts
289+
import 'vitest'
290+
291+
declare module 'vitest' {
292+
interface Assertion<T = any> {
293+
toMatchTrimmedSnapshot: (length: number) => T
294+
toMatchTrimmedInlineSnapshot: (inlineSnapshot?: string) => T
295+
toMatchTrimmedFileSnapshot: (file: string) => Promise<T>
296+
}
297+
}
298+
```
299+
300+
::: tip
301+
See [Extending Matchers](/guide/extending-matchers) for more on `expect.extend` and custom matcher conventions.
302+
:::
303+
304+
## Custom Snapshot Domain <Badge type="warning">experimental</Badge> {#custom-snapshot-domain}
238305

239306
Custom serializers control how values are _rendered_ into snapshot strings, but comparison is still string equality. A **domain snapshot adapter** goes further: it owns the entire comparison pipeline for a custom matcher, including how to capture a value, render it, parse a stored snapshot, and match them semantically.
240307

@@ -420,77 +487,6 @@ test('user data inline', () => {
420487
})
421488
```
422489

423-
## Custom Snapshot Matchers <Badge type="warning">experimental</Badge> <Version>4.1.3</Version> {#custom-snapshot-matchers}
424-
425-
You can build custom snapshot matchers using composable functions exported from `vitest`. These let you transform values before snapshotting while preserving full snapshot lifecycle support (creation, update, inline rewriting).
426-
427-
```ts
428-
import { expect, test, toMatchFileSnapshot, toMatchInlineSnapshot, toMatchSnapshot } from 'vitest'
429-
430-
expect.extend({
431-
toMatchTrimmedSnapshot(received: string, length: number) {
432-
return toMatchSnapshot.call(this, received.slice(0, length))
433-
},
434-
toMatchTrimmedInlineSnapshot(received: string, inlineSnapshot?: string) {
435-
return toMatchInlineSnapshot.call(this, received.slice(0, 10), inlineSnapshot)
436-
},
437-
async toMatchTrimmedFileSnapshot(received: string, file: string) {
438-
return toMatchFileSnapshot.call(this, received.slice(0, 10), file)
439-
},
440-
})
441-
442-
test('file snapshot', () => {
443-
expect('extra long string oh my gerd').toMatchTrimmedSnapshot(10)
444-
})
445-
446-
test('inline snapshot', () => {
447-
expect('extra long string oh my gerd').toMatchTrimmedInlineSnapshot()
448-
})
449-
450-
test('raw file snapshot', async () => {
451-
await expect('extra long string oh my gerd').toMatchTrimmedFileSnapshot('./raw-file.txt')
452-
})
453-
```
454-
455-
The composables return `{ pass, message }` so you can further customize the error:
456-
457-
```ts
458-
expect.extend({
459-
toMatchTrimmedSnapshot(received: string, length: number) {
460-
const result = toMatchSnapshot.call(this, received.slice(0, length))
461-
return { ...result, message: () => `Trimmed snapshot failed: ${result.message()}` }
462-
},
463-
})
464-
```
465-
466-
::: warning
467-
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.
468-
:::
469-
470-
::: tip
471-
File snapshot matchers must be `async` — `toMatchFileSnapshot` returns a `Promise`. Remember to `await` the result in the matcher and in your test.
472-
:::
473-
474-
The same pattern works with [`DomainSnapshotAdapter`](#custom-snapshot-domain) when you need semantic matching instead of plain string snapshots.
475-
476-
For TypeScript, extend the `Assertion` interface:
477-
478-
```ts
479-
import 'vitest'
480-
481-
declare module 'vitest' {
482-
interface Assertion<T = any> {
483-
toMatchTrimmedSnapshot: (length: number) => T
484-
toMatchTrimmedInlineSnapshot: (inlineSnapshot?: string) => T
485-
toMatchTrimmedFileSnapshot: (file: string) => Promise<T>
486-
}
487-
}
488-
```
489-
490-
::: tip
491-
See [Extending Matchers](/guide/extending-matchers) for more on `expect.extend` and custom matcher conventions.
492-
:::
493-
494490
## Difference from Jest
495491

496492
Vitest provides an almost compatible Snapshot feature with [Jest's](https://jestjs.io/docs/snapshot-testing) with a few exceptions:

0 commit comments

Comments
 (0)