0
# Jest Image Snapshot
1

2
Jest Image Snapshot is a Jest matcher that performs image comparisons for visual regression testing. It extends Jest's testing capabilities by enabling pixel-perfect comparison of images using pixelmatch or SSIM algorithms, with features like customizable difference thresholds, Gaussian blur for noise reduction, and flexible diff layout options.
3

4
## Package Information
5

6
- **Package Name**: jest-image-snapshot
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install --save-dev jest-image-snapshot`
10

11
## Core Imports
12

13
```javascript
14
const { toMatchImageSnapshot, configureToMatchImageSnapshot } = require('jest-image-snapshot');
15

16
expect.extend({ toMatchImageSnapshot });
17
```
18

19
For ES modules:
20

21
```javascript
22
import { toMatchImageSnapshot, configureToMatchImageSnapshot } from 'jest-image-snapshot';
23

24
expect.extend({ toMatchImageSnapshot });
25
```
26

27
## Basic Usage
28

29
```javascript
30
const { toMatchImageSnapshot } = require('jest-image-snapshot');
31

32
expect.extend({ toMatchImageSnapshot });
33

34
it('should match image snapshot', async () => {
35
  // Get image buffer (e.g., from Puppeteer, Playwright, etc.)
36
  const page = await browser.newPage();
37
  await page.goto('https://example.com');
38
  const image = await page.screenshot();
39

40
  // Compare with snapshot
41
  expect(image).toMatchImageSnapshot();
42
});
43

44
// With custom options
45
it('should match with custom threshold', () => {
46
  expect(imageBuffer).toMatchImageSnapshot({
47
    failureThreshold: 0.01,
48
    failureThresholdType: 'percent'
49
  });
50
});
51
```
52

53
## Architecture
54

55
Jest Image Snapshot operates through several key components:
56

57
- **Matcher Function**: `toMatchImageSnapshot` extends Jest's expect functionality
58
- **Configuration Factory**: `configureToMatchImageSnapshot` creates matchers with default options
59
- **Image Comparison Engine**: Uses pixelmatch or SSIM algorithms for pixel-level comparison
60
- **Snapshot Management**: Integrates with Jest's snapshot system for baseline storage and updates
61
- **Diff Generation**: Creates visual diff images showing differences between baseline and received images
62
- **Process Management**: Supports both in-process and child-process execution for performance
63

64
## Capabilities
65

66
### Core Matcher
67

68
The primary Jest matcher function that performs image comparison against stored snapshots. Handles snapshot creation, comparison, and updating through Jest's standard workflow.
69

70
```javascript { .api }
71
function toMatchImageSnapshot(options?: MatcherOptions): void;
72

73
interface MatcherOptions {
74
  customDiffConfig?: CustomDiffConfig;
75
  comparisonMethod?: 'pixelmatch' | 'ssim';
76
  customSnapshotIdentifier?: string | CustomSnapshotIdentifierFunction;
77
  customSnapshotsDir?: string;
78
  customDiffDir?: string;
79
  customReceivedDir?: string;
80
  customReceivedPostfix?: string;
81
  storeReceivedOnFailure?: boolean;
82
  diffDirection?: 'horizontal' | 'vertical';
83
  onlyDiff?: boolean;  
84
  noColors?: boolean;
85
  failureThreshold?: number;
86
  failureThresholdType?: 'pixel' | 'percent';
87
  updatePassedSnapshot?: boolean;
88
  blur?: number;
89
  runInProcess?: boolean;
90
  dumpDiffToConsole?: boolean;
91
  dumpInlineDiffToConsole?: boolean;
92
  allowSizeMismatch?: boolean;
93
  maxChildProcessBufferSizeInBytes?: number;
94
  runtimeHooksPath?: string;
95
}
96
```
97

98
[Core Matcher](./core-matcher.md)
99

100
### Configuration Factory
101

102
Factory function for creating customized matchers with default options, useful for sharing configuration across multiple tests.
103

104
```javascript { .api }
105
function configureToMatchImageSnapshot(defaultOptions?: MatcherOptions): typeof toMatchImageSnapshot;
106
```
107

108
[Configuration](./configuration.md)
109

110
### Snapshot Reporter
111

112
Jest reporter for tracking and cleaning up obsolete snapshot files that are no longer referenced by tests.
113

114
```javascript { .api }
115
class OutdatedSnapshotReporter {
116
  static markTouchedFile(filePath: string): void;
117
  static readTouchedFileListFromDisk(): string[];
118
  onRunStart(): void;
119
  onRunComplete(): void;
120
}
121
```
122

123
[Snapshot Management](./snapshot-management.md)
124

125
### Snapshot State Utility
126

127
Internal utility function for updating Jest snapshot state, primarily used for advanced integrations and testing scenarios.
128

129
```javascript { .api }
130
function updateSnapshotState(originalSnapshotState: object, partialSnapshotState: object): object;
131
```
132

133
## Types
134

135
```javascript { .api }
136
interface CustomDiffConfig {
137
  // Pixelmatch options
138
  threshold?: number;
139
  includeAA?: boolean;
140
  alpha?: number;
141
  aaColor?: [number, number, number];
142
  diffColor?: [number, number, number];
143
  diffColorAlt?: [number, number, number];
144
  // SSIM options  
145
  ssim?: 'bezkrovny' | 'fast';
146
}
147

148
interface CustomSnapshotIdentifierFunction {
149
  (params: {
150
    testPath: string;
151
    currentTestName: string;
152
    counter: number;
153
    defaultIdentifier: string;
154
  }): string;
155
}
156

157
interface RuntimeHooks {
158
  onBeforeWriteToDisc(params: {
159
    buffer: Buffer;
160
    destination: string;
161
    testPath: string;
162
    currentTestName: string;
163
  }): Buffer;
164
}
165
```