0
# Configuration
1

2
The configuration system in jest-image-snapshot allows you to create customized matchers with default options and fine-tune comparison algorithms for your specific testing needs.
3

4
## Capabilities
5

6
### Configuration Factory
7

8
Creates a customized `toMatchImageSnapshot` matcher with predefined default options, useful for sharing configuration across multiple tests.
9

10
```javascript { .api }
11
/**
12
 * Creates a customized toMatchImageSnapshot matcher with default options
13
 * @param defaultOptions - Default configuration applied to all comparisons
14
 * @returns Configured toMatchImageSnapshot function
15
 */
16
function configureToMatchImageSnapshot(defaultOptions?: MatcherOptions): typeof toMatchImageSnapshot;
17
```
18

19
**Usage Examples:**
20

21
```javascript
22
const { configureToMatchImageSnapshot } = require('jest-image-snapshot');
23

24
// Create matcher with default threshold
25
const toMatchImageSnapshot = configureToMatchImageSnapshot({
26
  failureThreshold: 0.01,
27
  failureThresholdType: 'percent',
28
  customDiffConfig: { threshold: 0.1 }
29
});
30

31
expect.extend({ toMatchImageSnapshot });
32

33
// Use in tests - default options are applied
34
it('visual test with defaults', () => {
35
  expect(imageBuffer).toMatchImageSnapshot(); // Uses 0.01% threshold
36
});
37

38
// Override defaults per test
39
it('visual test with override', () => {
40
  expect(imageBuffer).toMatchImageSnapshot({
41
    failureThreshold: 0.05 // Overrides default 0.01
42
  });
43
});
44
```
45

46
### Custom Diff Configuration
47

48
Configuration options for the underlying comparison algorithms (pixelmatch and SSIM).
49

50
```javascript { .api }
51
interface CustomDiffConfig {
52
  /** Pixelmatch configuration options */
53
  threshold?: number;
54
  includeAA?: boolean;
55
  alpha?: number;
56
  aaColor?: [number, number, number];
57
  diffColor?: [number, number, number];
58
  diffColorAlt?: [number, number, number];
59
  
60
  /** SSIM configuration options */
61
  ssim?: 'bezkrovny' | 'fast';
62
}
63
```
64

65
#### Pixelmatch Configuration
66

67
Pixelmatch is the default comparison method, providing pixel-by-pixel comparison.
68

69
```javascript { .api }
70
interface PixelmatchDiffConfig {
71
  /** Per-pixel sensitivity threshold (0-1, default: 0.01) */
72
  threshold?: number;
73
  /** Whether to include anti-aliasing detection (default: false) */
74
  includeAA?: boolean;
75
  /** Alpha channel blending factor (0-1, default: 0.1) */
76
  alpha?: number;
77
  /** Anti-aliasing color [R, G, B] (default: [255, 255, 0]) */
78
  aaColor?: [number, number, number];
79
  /** Diff highlight color [R, G, B] (default: [255, 0, 255]) */
80
  diffColor?: [number, number, number];
81
  /** Alternative diff color [R, G, B] */
82
  diffColorAlt?: [number, number, number];
83
}
84
```
85

86
**Pixelmatch Examples:**
87

88
```javascript
89
// High sensitivity - detects small differences
90
expect(imageBuffer).toMatchImageSnapshot({
91
  customDiffConfig: {
92
    threshold: 0.001 // Very sensitive
93
  }
94
});
95

96
// Low sensitivity - ignores minor differences  
97
expect(imageBuffer).toMatchImageSnapshot({
98
  customDiffConfig: {
99
    threshold: 0.1 // Less sensitive
100
  }
101
});
102

103
// Custom diff colors
104
expect(imageBuffer).toMatchImageSnapshot({
105
  customDiffConfig: {
106
    threshold: 0.01,
107
    diffColor: [255, 0, 0], // Red highlights
108
    aaColor: [0, 255, 0]    // Green for anti-aliasing
109
  }
110
});
111
```
112

113
#### SSIM Configuration
114

115
SSIM (Structural Similarity Index) provides perceptual comparison focusing on structural changes.
116

117
```javascript { .api }
118
interface SSIMDiffConfig {
119
  /** SSIM algorithm variant: 'bezkrovny' (fast, default) or 'fast' (accurate) */
120
  ssim?: 'bezkrovny' | 'fast';
121
}
122
```
123

124
**SSIM Examples:**
125

126
```javascript
127
// Fast SSIM (default) - optimized for speed
128
expect(imageBuffer).toMatchImageSnapshot({
129
  comparisonMethod: 'ssim',
130
  customDiffConfig: {
131
    ssim: 'bezkrovny' // 9x faster, slight accuracy loss  
132
  },
133
  failureThreshold: 0.01,
134
  failureThresholdType: 'percent'
135
});
136

137
// Accurate SSIM - higher precision
138
expect(imageBuffer).toMatchImageSnapshot({
139
  comparisonMethod: 'ssim', 
140
  customDiffConfig: {
141
    ssim: 'fast' // More accurate, slower
142
  },
143
  failureThreshold: 0.01,
144
  failureThresholdType: 'percent'
145
});
146
```
147

148
### Runtime Hooks
149

150
Runtime hooks allow custom processing of images before they are written to disk.
151

152
```javascript { .api }
153
interface RuntimeHooks {
154
  /**
155
   * Called before writing any image to disk
156
   * @param params - Hook parameters including buffer and metadata
157
   * @returns Modified buffer to write to disk
158
   */
159
  onBeforeWriteToDisc(params: {
160
    buffer: Buffer;
161
    destination: string;
162
    testPath: string;
163
    currentTestName: string;
164
  }): Buffer;
165
}
166
```
167

168
**Runtime Hooks Example:**
169

170
```javascript
171
// runtimeHooks.js
172
module.exports = {
173
  onBeforeWriteToDisc({ buffer, destination, testPath, currentTestName }) {
174
    // Add EXIF metadata or modify image before saving
175
    console.log(`Writing ${destination} for test ${currentTestName}`);
176
    return buffer; // Return modified buffer
177
  }
178
};
179

180
// In test file
181
expect(imageBuffer).toMatchImageSnapshot({
182
  runtimeHooksPath: require.resolve('./runtimeHooks.js')
183
});
184
```
185

186
### Global Configuration Patterns
187

188
Common patterns for configuring jest-image-snapshot across your test suite.
189

190
**Setup File Configuration:**
191

192
```javascript
193
// jest-setup.js
194
const { configureToMatchImageSnapshot } = require('jest-image-snapshot');
195

196
const toMatchImageSnapshot = configureToMatchImageSnapshot({
197
  // Default options for all tests
198
  failureThreshold: 0.01,
199
  failureThresholdType: 'percent',
200
  customDiffConfig: {
201
    threshold: 0.01
202
  },
203
  blur: 1, // Reduce noise from scaling
204
  allowSizeMismatch: false,
205
  storeReceivedOnFailure: true
206
});
207

208
expect.extend({ toMatchImageSnapshot });
209
```
210

211
**Environment-Specific Configuration:**
212

213
```javascript
214
const isCI = process.env.CI === 'true';
215

216
const toMatchImageSnapshot = configureToMatchImageSnapshot({
217
  // Stricter thresholds in CI
218
  failureThreshold: isCI ? 0.001 : 0.01,
219
  failureThresholdType: 'percent',
220
  // Store received images in CI for debugging
221
  storeReceivedOnFailure: isCI,
222
  // Disable colors in CI logs
223
  noColors: isCI
224
});
225
```
226

227
**Device-Specific Configuration:**
228

229
```javascript
230
const getDeviceConfig = (deviceType) => {
231
  const baseConfig = {
232
    failureThreshold: 0.01,
233
    failureThresholdType: 'percent'
234
  };
235

236
  switch (deviceType) {
237
    case 'mobile':
238
      return {
239
        ...baseConfig,
240
        customSnapshotsDir: './snapshots/mobile',
241
        blur: 1 // Account for rendering differences
242
      };
243
    case 'desktop':
244
      return {
245
        ...baseConfig,
246
        customSnapshotsDir: './snapshots/desktop',
247
        allowSizeMismatch: true // Different screen sizes
248
      };
249
    default:
250
      return baseConfig;
251
  }
252
};
253
```