Registry / testing / snapshot-diff

snapshot-diff

JSON →
library0.10.0jsnpmunverified

snapshot-diff is a utility library for Jest that facilitates the creation of diff snapshots between two values, particularly useful for comparing states of React components. The current stable version is 0.10.0. The library's release cadence is tightly coupled with Jest's major releases, leading to frequent breaking changes primarily due to updates in its Jest peer dependencies. It offers both a direct `snapshotDiff` function and a custom Jest matcher, `toMatchDiffSnapshot`, to integrate seamlessly into Jest tests. A key differentiator is its ability to provide readable, Git-style diff output for complex data structures by leveraging Jest's serialization mechanisms and supporting custom serializers.

npm install snapshot-diff
INSTALL
IMPORT
SIG · SNAPSHOT-DIFF
S
snapshot-diff
testingjavascriptv0.10.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

snapshotDiff
import snapshotDiff from 'snapshot-diff';
import { snapshotDiff } from 'snapshot-diff';
The primary `snapshotDiff` function is a default export for direct usage. Avoid named import syntax for the main function.
toMatchDiffSnapshot
import { toMatchDiffSnapshot } from 'snapshot-diff';
import toMatchDiffSnapshot from 'snapshot-diff';
This custom Jest matcher is a named export. Ensure it's imported with destructuring.
extend-expect (side-effect)
import 'snapshot-diff/extend-expect';
require('snapshot-diff/extend-expect');
Imports and registers the custom matcher directly as a side effect. Recommended for `setupFilesAfterEnv` in Jest config. While `require` works in CJS, prefer `import` for modern projects.
getSnapshotDiffSerializer
import { getSnapshotDiffSerializer } from 'snapshot-diff';
const { getSnapshotDiffSerializer } = require('snapshot-diff');
Named export for the serializer designed to prevent Jest from adding extraneous quotes around diff strings. Prefer ESM import syntax.
defaultSerializers
import { defaultSerializers } from 'snapshot-diff';
const { defaultSerializers } = require('snapshot-diff');
Named export providing the default array of serializers. Useful when configuring custom serializers to retain built-in functionality (e.g., React component serialization).

This quickstart demonstrates using `toMatchDiffSnapshot` for comparing React component states, strings, and plain objects, along with configuring the recommended snapshot serializer.

import React from 'react'; import { toMatchDiffSnapshot, getSnapshotDiffSerializer } from 'snapshot-diff'; // Extend Jest's expect with the custom matcher expect.extend({ toMatchDiffSnapshot }); // Add the custom serializer to prevent extra quotes in snapshots expect.addSnapshotSerializer(getSnapshotDiffSerializer()); // Define a simple React component for demonstration interface ComponentProps { value: string; } const MyComponent: React.FC<ComponentProps> = ({ value }) => { return ( <div> <p>Current value: {value}</p> <button onClick={() => console.log('clicked')}>Click Me</button> </div> ); }; describe('snapshot-diff usage', () => { test('should diff changes in React component props', () => { const initialElement = <MyComponent value="initial" />; const updatedElement = <MyComponent value="changed" />; // Compare the two React elements directly with the custom matcher expect(initialElement).toMatchDiffSnapshot(updatedElement); }); test('should diff differences between two strings', () => { const stringA = 'The quick brown fox jumps over the lazy dog.'; const stringB = 'The quick red fox jumps over the sleeping cat.'; // Compare two strings directly expect(stringA).toMatchDiffSnapshot(stringB); }); test('should diff two plain objects', () => { const objA = { id: 1, name: 'Alice', age: 30 }; const objB = { id: 1, name: 'Alicia', age: 31, city: 'NY' }; // Compare two plain objects expect(objA).toMatchDiffSnapshot(objB); }); });
Debug
Known issues
breakingsnapshot-diff frequently introduces breaking changes tied to Jest major version upgrades. Always check the release notes when updating `jest` or `snapshot-diff` as peer dependency ranges often tighten.
fix
Ensure your `jest` version meets the peer dependency requirements of `snapshot-diff`. Update `jest` if necessary, or downgrade `snapshot-diff` to a compatible version. Refer to the `peerDependencies` in `package.json`.
affects: >=0.5.0
breakingTypeScript users experienced breaking changes in type definitions due to updates to `@types/jest` and internal type refactorings.
fix
Update your `@types/jest` package to match your Jest version and the `snapshot-diff` requirements. Review any TypeScript errors related to `jest.Matchers` or `SnapshotSerializer` interfaces in your project.
affects: >=0.6.0
gotchaJest's default snapshot serialization can add extra quotes around string diffs, making output noisy and less readable. `snapshot-diff` provides a specific serializer to address this.
fix
Add `expect.addSnapshotSerializer(getSnapshotDiffSerializer());` in your Jest setup file (e.g., `setupFilesAfterEnv`) to ensure diffs are clean and human-readable.
affects: all
gotchaWhen setting custom serializers with `setSerializers`, the default React serializer is replaced. If you intend to diff React components, you must explicitly include `defaultSerializers`.
fix
When calling `snapshotDiff.setSerializers(mySerializers)`, ensure `...defaultSerializers` (imported from `snapshot-diff`) is spread into your custom array if you still need default React component serialization.
affects: all
Errors
Common errors & fixes
TypeError: expect.extend is not a function
The Jest `expect` object was not correctly extended with the `toMatchDiffSnapshot` custom matcher.
fix
Ensure you either `import { toMatchDiffSnapshot } from 'snapshot-diff'; expect.extend({ toMatchDiffSnapshot });` or `import 'snapshot-diff/extend-expect';` in your Jest setup file or relevant test files.
Invariant Violation: `ReactTestRenderer` is a dependency of `react-test-renderer`
This error typically occurs when React Test Renderer dependencies are misconfigured or multiple versions exist, often in conjunction with snapshot testing utilities.
fix
Ensure `react-test-renderer` is correctly installed as a development dependency. If using Yarn or PNPM, check for hoisted dependencies or use `resolutions` to enforce a single version. Clearing `node_modules` and `package-lock.json`/`yarn.lock` and reinstalling often resolves this.
TS2307: Cannot find module 'snapshot-diff' or its corresponding type declarations.
TypeScript compiler cannot locate the package's type definitions.
fix
Ensure `snapshot-diff` is installed and that `@types/jest` (if Jest is a peer dependency) is also installed. Verify your `tsconfig.json` includes `node_modules/@types` in `typeRoots` and `types` arrays are correctly configured, or that it is implicitly picked up.
Error: Jest: a snapshot serializer must be an object with a `print` method.
A custom serializer provided to `expect.addSnapshotSerializer` or `snapshotDiff.setSerializers` does not conform to Jest's `SnapshotSerializer` interface.
fix
Review your custom serializer implementation. It must export an object with at least `test` and `print` methods, and optionally `serialize` and `deserialize`.
Upgrade
Version history
0.10.0latest on npm
Audit
Dependencies
jestrequiredPeer dependency required for testing framework integration.
Agent activity
4 hits · last 30 days
node
4
Resources
snapshot-diff — npm install snapshot-diff · libregistry