Capture naming guide
Make evidence understandable outside the tool.
A consistent name helps humans pair captures and recover context months later. It does not replace trusted metadata in a test run or issue tracker.
Recommended pattern
product__route__locale__viewport__state__theme__platform__build.png
Example: shop__checkout-payment__ar-EG__390x844__card-error__dark__ios-webkit__2026.08.29.png
- Use two underscores between fields and hyphens inside a field.
- Prefer lowercase ASCII for file-system portability, while preserving canonical locale capitalization in the report itself if your tooling requires it.
- Use explicit, stable state names rather than “new,” “final,” or “test2.”
- Keep personal names, account IDs, order numbers, and secrets out of filenames.
Field guidance
| Field | Example | Guidance |
|---|---|---|
| Product | shop | Stable short identifier, not a marketing slogan. |
| Route or screen | checkout-payment | Human-recognizable screen or component name. |
| Locale | ar-EG | Use the actual test locale. Language-only tags are insufficient when region changes behaviour. |
| Viewport | 390x844 | CSS viewport when known; record device pixel ratio elsewhere. |
| State | card-error | Fixture, validation, expansion, or interaction state. |
| Theme | dark | Include only when themes are meaningful to the matrix. |
| Platform | ios-webkit | Rendering context, not merely a device nickname. |
| Build | 2026.08.29 | Release, commit, or test-run identifier approved by your team. |
Baseline and localized pairs
Keep all fields stable except locale when locale is the intended variable. If the baseline deliberately uses a different build, theme, viewport, or fixture, state that difference in the finding instead of hiding it in a long filename.
Do not assume an “English” image is a universal baseline. Record the exact locale, such as en-CA or en-US.
Filename boundaries
Does the workbench trust locale labels in filenames?
No filename should be treated as authoritative. Enter or verify review context in the interface and in your external test record.
Should translated words appear in filenames?
Usually no. Stable identifiers are easier to search across file systems. Preserve the actual localized string in the screenshot, finding, or approved test data.
What if a field is unknown?
Use a documented token such as unknown-build rather than inventing a value. Missing provenance should remain visible.