BackstopJS "Mismatch errors found" in CI

By Daniel Zoghalchali·Latchkey

BackstopJS ran test, compared each scenario against its reference with resemble.js, and at least one exceeded misMatchThreshold. It exits non-zero and writes an HTML report showing the diff for each failing scenario.

What this error means

The backstop test step fails with "Mismatch errors found." The generated report under backstop_data/html_report shows which scenarios differ and by what percentage.

COMMAND | Executing core for "test"
...
report | 3 Passed
report | 1 Failed
Mismatch errors found.

Common causes

A real visual change beyond the threshold

A scenario genuinely changed and its mismatch percentage exceeds misMatchThreshold. The report diff shows the delta.

Environment rendering differences from the reference

The reference was captured in a different environment (OS, fonts, Chromium version) than the CI runner, so text and edges differ.

How to fix it

Review the report, then approve or fix

1. Open backstop_data/html_report/index.html (or the CI artifact) to inspect the diff.
2. If the change is intended, run backstop approve and commit the updated references.
3. If it is a rendering difference, regenerate references in the CI container.

npx backstop approve

Set a sensible mismatch threshold

Allow a small mismatch percentage per scenario so anti-aliasing noise does not fail the run.

"scenarios": [
  { "label": "Home", "url": "http://host.docker.internal:3000/", "misMatchThreshold": 0.1 }
]

How to prevent it

• Generate references in the same container CI uses.
• Set a small misMatchThreshold to absorb rendering noise.
• Publish the HTML report as a CI artifact for review.

Frequently asked questions

Related guides

References

• GitHub Actions documentation