Skip to main content

Snapshot Testing

Snapshot tests catch visual regressions. Every time you change a template, the tests take a screenshot and compare it to the last known good screenshot. If something changed, the test fails and shows you exactly what is different.

How it works​

  1. Each template has a samples.json file with live API URLs
  2. The test runner builds Ceres, starts a local server, and opens each template with each sample URL
  3. It waits for the document to fully render (fonts loaded, images loaded)
  4. It takes a full-page screenshot
  5. It compares the screenshot against the saved baseline in __snapshots__/
  6. If the screenshots differ by more than a small threshold, the test fails

Running snapshot tests​

# Run all snapshot tests
npm run test:snapshots

# Update the baseline screenshots (after you intentionally changed something)
npm run test:snapshots:update

Adding test samples for your template​

Open your template's samples.json and add named API URLs:

{
  "simple-invoice": "aHR0cHM6Ly9hcGkucmVmcmVucy5jb20vaW52b2ljZXMvMTIzND9fYXQ9YWJjJnBvcHVsYXRlQnVzaW5lc3M9dHJ1ZQ==",
  "invoice-with-gst": "aHR0cHM6Ly9hcGkucmVmcmVucy5jb20vaW52b2ljZXMvNTY3OD9fYXQ9ZGVmJnBvcHVsYXRlQnVzaW5lc3M9dHJ1ZQ=="
}

Each entry creates one snapshot test. Name them descriptively so you can tell which case they cover.

When a test fails​

The test runner will output something like:

Screenshot comparison failed for basic-invoice-example/simple-invoice
Expected: __snapshots__/basic-invoice-example/simple-invoice.png
Actual:   test-results/basic-invoice-example/simple-invoice-actual.png
Diff:     test-results/basic-invoice-example/simple-invoice-diff.png

Open the diff image. Changed pixels will be highlighted. Then decide:

  • The change is intentional (you changed the CSS or layout on purpose): Run npm run test:snapshots:update to save the new screenshot as the baseline.
  • The change is a bug: Fix your template and run the tests again.

Tips​

  • Use at least two sample URLs per template: one simple case and one edge case (lots of line items, long text, etc.)
  • Commit the __snapshots__/ folder to version control. These are the baselines.
  • Do not commit test-results/. That folder is generated when tests fail, so you can inspect the diffs.