{"id":15235,"library":"snapshot-diff","title":"Jest Snapshot Diffing Utility","description":"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.","status":"active","version":"0.10.0","language":"javascript","source_language":"en","source_url":"https://github.com/thymikee/snapshot-diff","tags":["javascript","typescript"],"install":[{"cmd":"npm install snapshot-diff","lang":"bash","label":"npm"},{"cmd":"yarn add snapshot-diff","lang":"bash","label":"yarn"},{"cmd":"pnpm add snapshot-diff","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency required for testing framework integration.","package":"jest","optional":false}],"imports":[{"note":"The primary `snapshotDiff` function is a default export for direct usage. Avoid named import syntax for the main function.","wrong":"import { snapshotDiff } from 'snapshot-diff';","symbol":"snapshotDiff","correct":"import snapshotDiff from 'snapshot-diff';"},{"note":"This custom Jest matcher is a named export. Ensure it's imported with destructuring.","wrong":"import toMatchDiffSnapshot from 'snapshot-diff';","symbol":"toMatchDiffSnapshot","correct":"import { toMatchDiffSnapshot } from 'snapshot-diff';"},{"note":"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.","wrong":"require('snapshot-diff/extend-expect');","symbol":"extend-expect (side-effect)","correct":"import 'snapshot-diff/extend-expect';"},{"note":"Named export for the serializer designed to prevent Jest from adding extraneous quotes around diff strings. Prefer ESM import syntax.","wrong":"const { getSnapshotDiffSerializer } = require('snapshot-diff');","symbol":"getSnapshotDiffSerializer","correct":"import { getSnapshotDiffSerializer } from 'snapshot-diff';"},{"note":"Named export providing the default array of serializers. Useful when configuring custom serializers to retain built-in functionality (e.g., React component serialization).","wrong":"const { defaultSerializers } = require('snapshot-diff');","symbol":"defaultSerializers","correct":"import { defaultSerializers } from 'snapshot-diff';"}],"quickstart":{"code":"import React from 'react';\nimport { toMatchDiffSnapshot, getSnapshotDiffSerializer } from 'snapshot-diff';\n\n// Extend Jest's expect with the custom matcher\nexpect.extend({ toMatchDiffSnapshot });\n\n// Add the custom serializer to prevent extra quotes in snapshots\nexpect.addSnapshotSerializer(getSnapshotDiffSerializer());\n\n// Define a simple React component for demonstration\ninterface ComponentProps {\n  value: string;\n}\n\nconst MyComponent: React.FC<ComponentProps> = ({ value }) => {\n  return (\n    <div>\n      <p>Current value: {value}</p>\n      <button onClick={() => console.log('clicked')}>Click Me</button>\n    </div>\n  );\n};\n\ndescribe('snapshot-diff usage', () => {\n  test('should diff changes in React component props', () => {\n    const initialElement = <MyComponent value=\"initial\" />;\n    const updatedElement = <MyComponent value=\"changed\" />;\n\n    // Compare the two React elements directly with the custom matcher\n    expect(initialElement).toMatchDiffSnapshot(updatedElement);\n  });\n\n  test('should diff differences between two strings', () => {\n    const stringA = 'The quick brown fox jumps over the lazy dog.';\n    const stringB = 'The quick red fox jumps over the sleeping cat.';\n\n    // Compare two strings directly\n    expect(stringA).toMatchDiffSnapshot(stringB);\n  });\n\n  test('should diff two plain objects', () => {\n    const objA = { id: 1, name: 'Alice', age: 30 };\n    const objB = { id: 1, name: 'Alicia', age: 31, city: 'NY' };\n\n    // Compare two plain objects\n    expect(objA).toMatchDiffSnapshot(objB);\n  });\n});","lang":"typescript","description":"This quickstart demonstrates using `toMatchDiffSnapshot` for comparing React component states, strings, and plain objects, along with configuring the recommended snapshot serializer."},"warnings":[{"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`.","message":"snapshot-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.","severity":"breaking","affected_versions":">=0.5.0"},{"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.","message":"TypeScript users experienced breaking changes in type definitions due to updates to `@types/jest` and internal type refactorings.","severity":"breaking","affected_versions":">=0.6.0"},{"fix":"Add `expect.addSnapshotSerializer(getSnapshotDiffSerializer());` in your Jest setup file (e.g., `setupFilesAfterEnv`) to ensure diffs are clean and human-readable.","message":"Jest'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.","severity":"gotcha","affected_versions":"all"},{"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.","message":"When setting custom serializers with `setSerializers`, the default React serializer is replaced. If you intend to diff React components, you must explicitly include `defaultSerializers`.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","cause":"The Jest `expect` object was not correctly extended with the `toMatchDiffSnapshot` custom matcher.","error":"TypeError: expect.extend is not a function"},{"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.","cause":"This error typically occurs when React Test Renderer dependencies are misconfigured or multiple versions exist, often in conjunction with snapshot testing utilities.","error":"Invariant Violation: `ReactTestRenderer` is a dependency of `react-test-renderer`"},{"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.","cause":"TypeScript compiler cannot locate the package's type definitions.","error":"TS2307: Cannot find module 'snapshot-diff' or its corresponding type declarations."},{"fix":"Review your custom serializer implementation. It must export an object with at least `test` and `print` methods, and optionally `serialize` and `deserialize`.","cause":"A custom serializer provided to `expect.addSnapshotSerializer` or `snapshotDiff.setSerializers` does not conform to Jest's `SnapshotSerializer` interface.","error":"Error: Jest: a snapshot serializer must be an object with a `print` method."}],"ecosystem":"npm"}