BackstopJS: Scenarios, Config & Workflow

BackstopJS is a self-hosted, open-source visual regression testing tool -- it captures screenshots via headless Puppeteer/Playwright and diffs them pixel-by-pixel against approved reference images, flagging unintended UI changes.

Setup & backstop.json

npm install --save-dev backstopjs
npx backstop init   # scaffolds a starter backstop.json

{
  "id": "my-site",
  "viewports": [
    { "label": "phone", "width": 375, "height": 667 },
    { "label": "desktop", "width": 1440, "height": 900 }
  ],
  "scenarios": [
    {
      "label": "Homepage",
      "url": "http://localhost:3000/",
      "delay": 500,
      "misMatchThreshold": 0.1,
      "removeSelectors": [".ad-banner", ".live-timestamp"]
    },
    {
      "label": "Product Card - Component",
      "url": "http://localhost:3000/products/1",
      "selectors": [".product-card"]
    },
    {
      "label": "Dropdown - Open State",
      "url": "http://localhost:3000/",
      "clickSelectors": [".dropdown-trigger"],
      "selectors": [".dropdown-menu"],
      "delay": 300
    }
  ],
  "paths": {
    "bitmaps_reference": "backstop_data/bitmaps_reference",
    "bitmaps_test": "backstop_data/bitmaps_test",
    "html_report": "backstop_data/html_report"
  },
  "engine": "puppeteer",
  "report": ["browser"]
}

The Workflow

# First run: establish the approved baseline
npx backstop reference

# After changes: capture new screenshots, diff against reference
npx backstop test
# Opens an HTML report -- side-by-side + diff overlay per scenario,
# filterable by pass/fail

# If the diffs are an intentional change (not a regression),
# promote the latest test captures to be the new reference
npx backstop approve