Skip to main content

Snapshot Testing

This tutorial walks you through setting up and running snapshot tests for your component storybook. By the end, you'll have baseline screenshots for your components and know how to catch unintended visual changes.

Prerequisites​

That's it — Holt uses doco to run a Caddy server and headless Chrome inside Docker containers, so there's nothing else to install.

Step 1: Run Your First Snapshot Test​

From your project root (where holt.toml lives), run:

holt snapshot

You'll see output like:

Holt Visual Regression Testing
================================

Running trunk build...
Build complete: /path/to/dist

Processing 12 story variants...

  [new] card/default (new baseline)
  [new] card/fixed_width (new baseline)
  ...

================================
Results: 0 passed, 12 new

The first run creates baselines for every variant — there's nothing to compare against yet.

Step 2: Explore the Baseline Directory​

Check what was created:

ls -la tests/visual-baselines/

You'll see a directory structure like:

tests/visual-baselines/
├── card/
│   ├── default.png
│   ├── fixed_width.png
│   └── minimal.png
└── button/
    ├── default.png
    └── secondary.png

Each story variant gets its own screenshot, organized by story name.

Step 3: Verify Baselines Pass​

Run the test again:

holt snapshot

Now you should see:

Processing 12 story variants...

  [ok] card/default matches baseline
  [ok] card/fixed_width matches baseline
  ...

================================
Results: 12 passed, 0 failed

All tests pass because the screenshots match the baselines.

Step 4: Make a Visual Change​

Let's see what happens when a component changes. Open one of your components and make a visible change — perhaps change a padding value, border color, or font size.

For example, if you have a Card component:

// Change this:
let base_classes = "rounded-lg border bg-card";
// To this:
let base_classes = "rounded-xl border-2 bg-card";

Step 5: See the Diff​

Run the snapshot tests again:

holt snapshot

For any changed component, a comparison window opens showing:

  • Baseline tab: The original screenshot
  • New Screenshot tab: What the component looks like now

You can toggle between views to spot the differences.

Step 6: Accept or Reject the Change​

In the comparison window:

  • Click Accept to update the baseline with the new screenshot
  • Click Reject to keep the old baseline (test stays failed)

If you accept, the baseline file is updated immediately.

On headless systems (SSH sessions, containers), Holt falls back to terminal mode — it opens both images in your default viewer and prompts you to accept or reject.

Step 7: Commit Your Baselines​

Baseline images should be committed to version control so CI can compare against them:

git add tests/visual-baselines/
git commit -m "Update baselines for card component"

Troubleshooting​

Docker not running​

Holt needs Docker to run the Caddy server and browser. Make sure the Docker daemon is running:

docker info

Comparison window doesn't open​

On headless systems (like SSH sessions), Holt falls back to terminal mode. It will print file paths and ask for yes/no input instead of showing a GUI.

Next Steps​