0
# Static Snapshots
1

2
Capture visual snapshots of static directories, file lists, or sitemaps without requiring a test runner. Perfect for static sites, documentation sites, or when you have pre-built assets to test.
3

4
## Capabilities
5

6
### Percy Snapshot
7

8
Snapshot static content from directories, configuration files, or sitemaps. This command discovers and captures visual snapshots of web content without needing to run a full test suite.
9

10
```bash { .api }
11
/**
12
 * Snapshot static directory, file list, or sitemap
13
 * Discovers web content and captures visual snapshots
14
 * 
15
 * Usage: percy snapshot <dir|file|sitemap>
16
 * 
17
 * Arguments:
18
 *   dir|file|sitemap    Static directory path, snapshots file, or sitemap URL (required)
19
 * 
20
 * Options:
21
 *   --base-url, -b <url>       Base URL for hosted pages
22
 *   --include <pattern>        Glob patterns to include (multiple)
23
 *   --exclude <pattern>        Glob patterns to exclude (multiple)
24
 *   --clean-urls               Remove file extensions from snapshot names
25
 */
26
percy snapshot <dir|file|sitemap>
27
```
28

29
## Static Directory Snapshots
30

31
Snapshot all HTML files in a directory, typically used for static site generators or pre-built sites.
32

33
**Usage Examples:**
34

35
```bash
36
# Snapshot a build directory
37
percy snapshot ./dist
38
percy snapshot ./public
39
percy snapshot ./build
40

41
# With base URL for absolute links
42
percy snapshot ./dist --base-url https://example.com
43

44
# Include/exclude specific patterns
45
percy snapshot ./dist --include "**/*.html" --exclude "**/admin/**"
46

47
# Clean URLs (remove .html extensions)
48
percy snapshot ./dist --clean-urls
49
```
50

51
**Directory Structure Example:**
52

53
```
54
dist/
55
├── index.html           → snapshot: "/"
56
├── about.html           → snapshot: "/about"
57
├── products/
58
│   ├── index.html       → snapshot: "/products"
59
│   └── laptop.html      → snapshot: "/products/laptop"
60
└── assets/
61
    ├── style.css        → discovered as asset
62
    └── app.js           → discovered as asset
63
```
64

65
## Configuration File Snapshots
66

67
Use configuration files to define complex snapshot scenarios with custom options per page.
68

69
### JavaScript Configuration
70

71
```javascript
72
// snapshots.js
73
export default [
74
  {
75
    name: 'Homepage',
76
    url: 'http://localhost:3000/',
77
    widths: [375, 768, 1280]
78
  },
79
  {
80
    name: 'Product Page',
81
    url: 'http://localhost:3000/products/laptop',
82
    percyCSS: '.dynamic-content { display: none; }'
83
  },
84
  {
85
    name: 'Dashboard',
86
    url: 'http://localhost:3000/dashboard',
87
    additionalSnapshots: [
88
      { suffix: ' - Mobile', widths: [375] },
89
      { suffix: ' - Desktop', widths: [1280] }
90
    ]
91
  }
92
];
93
```
94

95
```bash
96
# Use JavaScript config
97
percy snapshot snapshots.js
98
```
99

100
### JSON Configuration
101

102
```json
103
{
104
  "snapshots": [
105
    {
106
      "name": "Homepage",
107
      "url": "http://localhost:3000/",
108
      "widths": [375, 768, 1280]
109
    },
110
    {
111
      "name": "About Page", 
112
      "url": "http://localhost:3000/about",
113
      "minHeight": 1024
114
    }
115
  ]
116
}
117
```
118

119
```bash
120
# Use JSON config
121
percy snapshot snapshots.json
122
```
123

124
### YAML Configuration
125

126
```yaml
127
# snapshots.yaml
128
snapshots:
129
  - name: Homepage
130
    url: http://localhost:3000/
131
    widths: [375, 768, 1280]
132
  - name: Contact Form
133
    url: http://localhost:3000/contact
134
    percyCSS: |
135
      .captcha { display: none; }
136
      .timestamp { visibility: hidden; }
137
```
138

139
```bash
140
# Use YAML config
141
percy snapshot snapshots.yaml
142
```
143

144
## Sitemap Snapshots
145

146
Automatically discover pages from XML sitemaps, perfect for large sites with dynamic content.
147

148
**Usage Examples:**
149

150
```bash
151
# Snapshot from sitemap URL
152
percy snapshot https://example.com/sitemap.xml
153

154
# Local sitemap file
155
percy snapshot ./sitemap.xml
156

157
# With filtering
158
percy snapshot https://example.com/sitemap.xml --include "**/blog/**" --exclude "**/admin/**"
159
```
160

161
**Sitemap Example:**
162

163
```xml
164
<?xml version="1.0" encoding="UTF-8"?>
165
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
166
  <url>
167
    <loc>https://example.com/</loc>
168
    <priority>1.0</priority>
169
  </url>
170
  <url>
171
    <loc>https://example.com/about</loc>
172
    <priority>0.8</priority>
173
  </url>
174
  <url>
175
    <loc>https://example.com/products/laptop</loc>
176
    <priority>0.6</priority>
177
  </url>
178
</urlset>
179
```
180

181
## Configuration Options
182

183
### Base URL Option
184

185
When snapshots reference relative links, use `--base-url` to resolve them correctly:
186

187
```bash
188
# Static files with relative links
189
percy snapshot ./dist --base-url https://mysite.com
190

191
# Local development server
192
percy snapshot ./public --base-url http://localhost:3000
193
```
194

195
### Include/Exclude Patterns
196

197
Use glob patterns to control which content gets snapshotted:
198

199
```bash
200
# Include only specific patterns
201
percy snapshot ./dist --include "**/*.html" --include "**/pages/**"
202

203
# Exclude admin or private sections
204
percy snapshot ./dist --exclude "**/admin/**" --exclude "**/private/**"
205

206
# Complex filtering
207
percy snapshot ./dist \
208
  --include "**/*.html" \
209
  --exclude "**/test/**" \
210
  --exclude "**/temp/**"
211
```
212

213
### Clean URLs
214

215
Remove file extensions from snapshot names for cleaner URLs:
216

217
```bash
218
# Without clean URLs
219
percy snapshot ./dist
220
# Creates: "index.html", "about.html", "contact.html"
221

222
# With clean URLs  
223
percy snapshot ./dist --clean-urls
224
# Creates: "/", "/about", "/contact"
225
```
226

227
## Advanced Configuration
228

229
### Per-Snapshot Options
230

231
In configuration files, you can specify detailed options for each snapshot:
232

233
```javascript
234
// advanced-snapshots.js
235
export default [
236
  {
237
    name: 'Homepage - Desktop',
238
    url: 'http://localhost:3000/',
239
    widths: [1280],
240
    minHeight: 800,
241
    percyCSS: `
242
      .ads { display: none; }
243
      .dynamic-timestamp { visibility: hidden; }
244
    `
245
  },
246
  {
247
    name: 'Homepage - Mobile',
248
    url: 'http://localhost:3000/',
249
    widths: [375],
250
    enableLayout: true,
251
    additionalSnapshots: [
252
      { 
253
        suffix: ' - Menu Open',
254
        execute: () => {
255
          document.querySelector('.menu-button').click();
256
        }
257
      }
258
    ]
259
  }
260
];
261
```
262

263
### Discovery Options
264

265
Control how Percy discovers and processes assets:
266

267
```bash
268
# Custom discovery settings
269
percy snapshot ./dist \
270
  --allowed-hostname "*.example.com" \
271
  --disallowed-hostname "ads.example.com" \
272
  --network-idle-timeout 1000 \
273
  --disable-cache
274
```
275

276
## Integration Examples
277

278
### Static Site Generators
279

280
```bash
281
# Gatsby
282
gatsby build
283
percy snapshot ./public --base-url https://mysite.com
284

285
# Next.js static export
286
next build
287
next export
288
percy snapshot ./out --clean-urls
289

290
# Jekyll
291
bundle exec jekyll build
292
percy snapshot ./_site --base-url https://mysite.com
293

294
# Hugo
295
hugo
296
percy snapshot ./public --base-url https://mysite.com
297
```
298

299
### Documentation Sites
300

301
```bash
302
# GitBook
303
gitbook build
304
percy snapshot ./_book
305

306
# VuePress
307
vuepress build
308
percy snapshot ./.vuepress/dist --clean-urls
309

310
# Docusaurus
311
npm run build
312
percy snapshot ./build --base-url https://docs.example.com
313
```
314

315
### Multi-Environment Testing
316

317
```bash
318
# Test multiple environments
319
percy snapshot https://staging.example.com/sitemap.xml
320
percy snapshot https://production.example.com/sitemap.xml
321

322
# Local vs production comparison
323
percy snapshot ./dist --base-url http://localhost:3000
324
percy snapshot https://mysite.com/sitemap.xml
325
```
326

327
## File Type Support
328

329
### Configuration Files
330
- `.js`, `.cjs`, `.mjs` - JavaScript modules with default export
331
- `.json` - JSON objects with `snapshots` array
332
- `.yaml`, `.yml` - YAML files with `snapshots` key
333

334
### Static Content
335
- `.html` - HTML files are snapshotted
336
- `.htm` - Alternative HTML extension
337
- Assets (CSS, JS, images) are automatically discovered and included
338

339
### Sitemaps
340
- Local XML files
341
- Remote HTTP(S) sitemap URLs
342
- Sitemap index files (references to multiple sitemaps)