toMatchSnapshot

toMatchSnapshot is a Jest matcher used in snapshot testing to compare a value with a previously stored snapshot. It enables the automatic capture of complex data structures, serialized objects, or UI output. On the first run, a snapshot is created and saved to a __snapshots__ file alongside the test. On subsequent runs, the current value is compared to the stored snapshot; if it differs, the test fails and shows a diff.

The matcher can be used with or without additional naming. expect(value).toMatchSnapshot() creates a default snapshot for the test. Passing a string argument (expect(value).toMatchSnapshot('name')) assigns a named snapshot within the test, useful when multiple snapshots are produced. There is also toMatchInlineSnapshot(), which stores the snapshot inline in the test file as an inline string.

Serialization and extensions: Jest supports snapshot serializers to customize how values are rendered, and you can pair toMatchSnapshot with inline snapshots or with named snapshots. Snapshot files are typically version controlled, making them part of the test suite.

Updating snapshots: If changes are intentional, snapshots can be updated by running the test command with -u or --updateSnapshot. This overwrites existing snapshots with the new values. Best practices include keeping snapshots focused, avoiding large, brittle outputs, and using inline snapshots for small units or for values tightly coupled to the test code.

See also: snapshot testing, Jest, Vitest.