home / skills / shotaiuchi / dotclaude / test-snapshot

test-snapshot skill

safe

This skill helps you create comprehensive snapshot and golden tests for UI, API, and serialization contracts to detect unintended changes.

npx playbooks add skill shotaiuchi/dotclaude --skill test-snapshot

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

2.1 KB

---
name: test-snapshot
description: >-
  Snapshot and golden test creation. Apply when creating baseline capture
  tests for UI components, API response formats, serialization contracts,
  and detecting unintended output changes.
user-invocable: false
---

# Snapshot/Golden Tests

Create snapshot and golden tests that detect unintended output changes.

## Test Creation Checklist

### UI Snapshot Capture
- Capture visual snapshots for all component states (default, loading, error)
- Test across relevant viewport sizes and screen densities
- Include snapshots for light/dark themes and accessibility modes
- Verify interactive states (hover, focus, disabled, selected)
- Establish pixel tolerance thresholds for acceptable rendering variance

### API Response Baselines
- Capture baseline responses for all endpoint success cases
- Record error response structures for each error category
- Snapshot pagination metadata and envelope format
- Verify header values and content-type consistency
- Test response format stability across API versions

### Serialization Contract Tests
- Snapshot JSON/XML/Protobuf serialization output for domain models
- Verify backward compatibility when fields are added or deprecated
- Test deserialization of historical format versions
- Check that optional fields serialize/deserialize correctly
- Validate enum and union type serialization stability

### Change Detection Strategy
- Configure meaningful diff output for failed snapshot comparisons
- Exclude volatile fields (timestamps, random IDs) from comparisons
- Implement review workflow for intentional snapshot updates
- Group related snapshots for batch approval when schemas change
- Set up CI integration to block merges on unexpected snapshot diffs

## Output Format

Report test plan with priority ratings:

| Priority | Description |
|----------|-------------|
| Must | Contract snapshots preventing breaking serialization changes |
| Should | UI snapshots for primary components and key states |
| Could | Response baselines for secondary endpoints and formats |
| Won't | Snapshots for internal representations with no external contract |

Overview

This skill helps teams create snapshot and golden tests to detect unintended output changes across UI, APIs, and serialization contracts. It defines a practical checklist, change-detection strategy, and a prioritized test plan to focus effort where it prevents regressions. The goal is repeatable baselines that integrate with CI and a review workflow for intentional updates.

How this skill works

The skill guides capture of deterministic baselines: visual snapshots for component states, API response baselines, and serialized model outputs. It prescribes excluding volatile fields, setting pixel tolerances, and organizing diffs for clear failure triage. It also recommends CI gating and grouping snapshots for batch approval when schema changes are intentional.

When to use it

When introducing UI components or updating visual states (themes, densities, interaction states)
When stabilizing API surface contracts or adding new endpoints
When evolving serialization formats (JSON, XML, Protobuf) that must remain compatible
When hardening release pipelines to block regressions via CI snapshot checks
When onboarding a review process for intentional baseline updates

Best practices

Capture all relevant UI states and test across viewports and densities to catch platform-specific regressions
Exclude or normalize volatile fields (timestamps, generated IDs) before comparison to avoid noise
Set and document pixel tolerance thresholds for visual tests to allow acceptable rendering variance
Record and version baselines per API version and include header/content-type checks
Integrate snapshot checks into CI and require human review for baseline updates

Example use cases

Create visual snapshots for a button component across default, hover, focus, disabled, and high-contrast modes
Record API success and error response baselines, including pagination envelopes and headers
Snapshot model serialization for backward compatibility when adding or deprecating fields
Block merges in CI when snapshot diffs appear until a reviewer approves intentional changes
Group related schema changes and update multiple golden files together with a documented approval note

FAQ

How do I avoid flaky snapshot tests?

Normalize or exclude volatile data, set pixel tolerances, and run captures in stable deterministic environments (fixed fonts, viewport, and seed values).

When should I update a snapshot baseline?

Only update baselines when a change is intentional and reviewed; document the reason and scope, and update grouped snapshots if the change affects multiple artifacts.