0
# Configuration
1

2
Tools for creating, validating, and migrating Percy configuration files across different formats. Percy supports multiple configuration file formats and provides commands to manage configuration lifecycle.
3

4
## Capabilities
5

6
### Config Create
7

8
Create a new Percy configuration file in the format of your choice. Automatically generates a configuration file with common options and helpful comments.
9

10
```bash { .api }
11
/**
12
 * Create new Percy configuration file
13
 * Generates a config file with default settings and documentation
14
 * 
15
 * Usage: percy config create [filepath]
16
 * 
17
 * Arguments:
18
 *   filepath                      Optional path where to create config file
19
 * 
20
 * Options (format selection - mutually exclusive):
21
 *   --rc                         Create .percyrc file (JSON format)
22
 *   --yaml                       Create .percy.yaml file
23
 *   --yml                        Create .percy.yml file
24
 *   --json                       Create .percy.json file
25
 *   --js                         Create .percy.js file (JavaScript module)
26
 * 
27
 * Default: Creates .percy.yml if no format specified
28
 */
29
percy config create [filepath]
30
```
31

32
**Usage Examples:**
33

34
```bash
35
# Create default config (.percy.yml)
36
percy config create
37

38
# Create specific format configs
39
percy config create --rc         # .percyrc (JSON)
40
percy config create --yaml       # .percy.yaml
41
percy config create --yml        # .percy.yml
42
percy config create --json       # .percy.json
43
percy config create --js         # .percy.js
44

45
# Create config at specific path
46
percy config create config/percy.yaml --yaml
47
percy config create .percyrc --rc
48
```
49

50
### Config Validate
51

52
Validate a Percy configuration file against the current schema. Checks syntax, validates option values, and reports any errors or warnings.
53

54
```bash { .api }
55
/**
56
 * Validate Percy configuration file
57
 * Checks config syntax and validates against current schema
58
 * 
59
 * Usage: percy config validate [filepath]
60
 * 
61
 * Arguments:
62
 *   filepath                      Optional path to config file to validate
63
 *                                Default: searches for config in current directory
64
 * 
65
 * Exit codes:
66
 *   0 - Configuration is valid
67
 *   1 - Configuration has errors or file not found
68
 */
69
percy config validate [filepath]
70
```
71

72
**Usage Examples:**
73

74
```bash
75
# Validate config in current directory (auto-discovery)
76
percy config validate
77

78
# Validate specific config file
79
percy config validate .percy.yml
80
percy config validate config/percy.json
81
percy config validate package.json  # Validates 'percy' field
82
```
83

84
### Config Migrate
85

86
Migrate configuration file to the latest version and format. Handles version upgrades and format conversions while preserving all settings.
87

88
```bash { .api }
89
/**
90
 * Migrate configuration to latest version
91
 * Updates config schema version and converts deprecated options
92
 * 
93
 * Usage: percy config migrate [filepath] [output]
94
 * 
95
 * Arguments:
96
 *   filepath                      Path to config file to migrate
97
 *   output                        Optional output path for migrated config
98
 * 
99
 * Options:
100
 *   --dry-run, -d                Print new config without writing to file
101
 * 
102
 * Exit codes:
103
 *   0 - Migration completed successfully
104
 *   1 - Migration failed or no changes needed
105
 */
106
percy config migrate [filepath] [output]
107
```
108

109
**Usage Examples:**
110

111
```bash
112
# Migrate config in-place
113
percy config migrate .percy.yml
114

115
# Migrate to new file
116
percy config migrate old-config.json new-config.yml
117

118
# Preview migration without writing
119
percy config migrate .percy.yml --dry-run
120

121
# Migrate with different output format
122
percy config migrate .percyrc percy.config.js
123
```
124

125
## Configuration File Formats
126

127
### YAML Format
128

129
```yaml
130
# .percy.yml or .percy.yaml
131
version: 2
132

133
snapshot:
134
  widths: [375, 768, 1280]
135
  minHeight: 1024
136
  percyCSS: |
137
    .dynamic-content { display: none; }
138
    .timestamp { visibility: hidden; }
139

140
discovery:
141
  allowedHostnames:
142
    - "*.example.com"
143
    - "cdn.assets.com"
144
  disallowedHostnames:
145
    - "ads.example.com"
146
  networkIdleTimeout: 100
147
  concurrency: 5
148

149
agent:
150
  assetDiscovery:
151
    networkIdleTimeout: 100
152
    pagePoolSizeMin: 1
153
    pagePoolSizeMax: 5
154
```
155

156
### JSON Format
157

158
```json
159
{
160
  "version": 2,
161
  "snapshot": {
162
    "widths": [375, 768, 1280],
163
    "minHeight": 1024,
164
    "percyCSS": ".ads { display: none; }"
165
  },
166
  "discovery": {
167
    "allowedHostnames": ["*.example.com"],
168
    "disallowedHostnames": ["ads.example.com"],
169
    "networkIdleTimeout": 100,
170
    "concurrency": 5
171
  }
172
}
173
```
174

175
### JavaScript Format
176

177
```javascript
178
// .percy.js or percy.config.js
179
export default {
180
  version: 2,
181
  snapshot: {
182
    widths: [375, 768, 1280],
183
    minHeight: 1024,
184
    percyCSS: `
185
      .dynamic-content { display: none; }
186
      .timestamp { visibility: hidden; }
187
    `
188
  },
189
  discovery: {
190
    allowedHostnames: ['*.example.com'],
191
    disallowedHostnames: ['ads.example.com'],
192
    networkIdleTimeout: 100,
193
    concurrency: 5
194
  }
195
};
196
```
197

198
### Package.json Integration
199

200
```json
201
{
202
  "name": "my-app",
203
  "scripts": {
204
    "test": "percy exec -- jest"
205
  },
206
  "percy": {
207
    "version": 2,
208
    "snapshot": {
209
      "widths": [375, 768, 1280]
210
    }
211
  }
212
}
213
```
214

215
## Configuration Options
216

217
### Core Configuration
218

219
```yaml { .api }
220
# Schema version (required)
221
version: 2
222

223
# Snapshot configuration
224
snapshot:
225
  widths: [375, 768, 1280]        # Viewport widths to capture
226
  minHeight: 1024                 # Minimum screenshot height
227
  percyCSS: string                # CSS to inject into pages
228
  enableLayout: boolean           # Enable layout diffing
229
  
230
# Discovery configuration  
231
discovery:
232
  allowedHostnames: string[]      # Allowed hostname patterns
233
  disallowedHostnames: string[]   # Disallowed hostname patterns
234
  networkIdleTimeout: number      # Network idle timeout (ms)
235
  concurrency: number             # Asset discovery concurrency
236
  userAgent: string               # Custom user agent
237
  requestHeaders: object          # Custom request headers
238
  authorization: object           # Authorization headers
239
  captureMockedServiceWorker: boolean  # Capture mocked service workers
240
  captureSrcset: boolean          # Capture responsive images
241
  
242
# Agent configuration (advanced)
243
agent:
244
  assetDiscovery:
245
    networkIdleTimeout: number    # Asset network idle timeout
246
    pagePoolSizeMin: number       # Minimum browser pages
247
    pagePoolSizeMax: number       # Maximum browser pages
248
    cacheResponses: boolean       # Cache HTTP responses
249
  clientInfo: string              # Client identification
250
  environmentInfo: string         # Environment identification
251
```
252

253
### Discovery Configuration
254

255
Control how Percy discovers and processes web assets:
256

257
```yaml
258
discovery:
259
  # Hostname filtering
260
  allowedHostnames:
261
    - "*.mysite.com"
262
    - "cdn.assets.com"
263
    - "fonts.googleapis.com"
264
  
265
  disallowedHostnames:
266
    - "ads.example.com"
267
    - "analytics.google.com"
268
    - "*.facebook.com"
269
  
270
  # Network timing
271
  networkIdleTimeout: 100         # Wait for network idle (ms)
272
  
273
  # Performance tuning
274
  concurrency: 5                  # Parallel asset requests
275
  
276
  # Request customization
277
  userAgent: "Percy/1.0 Custom"
278
  requestHeaders:
279
    "X-Percy-Test": "true"
280
    "Authorization": "Bearer token123"
281
```
282

283
### Snapshot Configuration
284

285
Control visual snapshot capture settings:
286

287
```yaml
288
snapshot:
289
  # Responsive testing
290
  widths: [375, 768, 1024, 1280]
291
  
292
  # Screenshot sizing
293
  minHeight: 1024                 # Minimum screenshot height
294
  
295
  # Visual modifications
296
  percyCSS: |
297
    /* Hide dynamic content */
298
    .timestamp { visibility: hidden; }
299
    .ads { display: none; }
300
    .loading-spinner { display: none; }
301
    
302
    /* Stabilize animations */
303
    *, *::before, *::after {
304
      animation-duration: 0s !important;
305
      animation-delay: 0s !important;
306
      transition-duration: 0s !important;
307
      transition-delay: 0s !important;
308
    }
309
  
310
  # Advanced options
311
  enableLayout: true              # Enable layout-based diffing
312
```
313

314
## Configuration Discovery
315

316
Percy searches for configuration files in this order:
317

318
1. `.percyrc` (JSON)
319
2. `.percy.json`
320
3. `.percy.yaml`
321
4. `.percy.yml`
322
5. `.percy.js`
323
6. `.percy.cjs`
324
7. `percy.config.js`
325
8. `percy.config.cjs`
326
9. `package.json` (`percy` field)
327

328
### Environment Override
329

330
Environment variables can override configuration values:
331

332
```bash
333
# Override specific config values
334
PERCY_LOGLEVEL=debug percy exec -- npm test
335
PERCY_CONFIG=./custom-config.yml percy exec -- npm test
336

337
# Discovery overrides
338
PERCY_NETWORK_IDLE_TIMEOUT=200 percy snapshot ./dist
339
PERCY_CONCURRENCY=10 percy snapshot ./dist
340
```
341

342
## Migration Examples
343

344
### Version 1 to Version 2
345

346
```yaml
347
# Old format (version 1)
348
widths: [375, 768, 1280]
349
minHeight: 1024
350
css: ".ads { display: none; }"
351

352
# New format (version 2)
353
version: 2
354
snapshot:
355
  widths: [375, 768, 1280]
356
  minHeight: 1024
357
  percyCSS: ".ads { display: none; }"
358
```
359

360
Migration handles:
361
- Schema version updates
362
- Option renames (`css` → `percyCSS`)
363
- Structure changes (flat → nested)
364
- Deprecated option warnings
365

366
### Format Conversion
367

368
```bash
369
# Convert JSON to YAML
370
percy config migrate .percy.json .percy.yml
371

372
# Convert package.json to standalone config
373
percy config migrate package.json .percy.yml
374

375
# Convert JavaScript to JSON
376
percy config migrate percy.config.js .percy.json
377
```
378

379
## Validation Examples
380

381
### Valid Configuration
382

383
```yaml
384
version: 2
385
snapshot:
386
  widths: [375, 768, 1280]
387
  minHeight: 1024
388
discovery:
389
  networkIdleTimeout: 100
390
```
391

392
### Invalid Configurations
393

394
```yaml
395
# Missing version
396
snapshot:
397
  widths: [375, 768, 1280]
398
# Error: Missing required 'version' field
399

400
# Invalid width values  
401
version: 2
402
snapshot:
403
  widths: [-100, 0, "invalid"]
404
# Error: Widths must be positive integers
405

406
# Invalid timeout
407
version: 2  
408
discovery:
409
  networkIdleTimeout: "invalid"
410
# Error: networkIdleTimeout must be a number
411
```
412

413
## Integration Patterns
414

415
### Development Workflow
416

417
```bash
418
# Create initial config
419
percy config create --yaml
420

421
# Edit config file
422
vim .percy.yml
423

424
# Validate before committing
425
percy config validate
426

427
# Test configuration
428
percy exec -- npm test
429
```
430

431
### CI/CD Integration
432

433
```bash
434
# Validate config in CI
435
percy config validate || exit 1
436

437
# Use different configs per environment
438
PERCY_CONFIG=.percy.staging.yml percy exec -- npm test  # Staging
439
PERCY_CONFIG=.percy.prod.yml percy exec -- npm test     # Production
440
```
441

442
### Team Collaboration
443

444
```bash
445
# Standardize team config
446
percy config create --yaml
447
git add .percy.yml
448
git commit -m "Add Percy configuration"
449

450
# Validate in pre-commit hook
451
percy config validate || {
452
  echo "Percy config validation failed"
453
  exit 1
454
}
455
```