BackstopJS: Component Scoping, Custom Scripts & CI

Component-Scoped vs Full-Page Scenarios

• A full-page capture changes (and needs re-approval) whenever ANYTHING on that page changes, even something unrelated to what you're actually testing.

• selectors scopes a scenario to a specific component -- isolates the test, reduces noise/false failures from unrelated page changes.

• removeSelectors/hideSelectors excludes elements that legitimately vary (timestamps, ads, randomized content) before the comparison, avoiding spurious diffs.

• misMatchThreshold tolerates a small amount of pixel-level rendering noise (anti-aliasing) while still catching real visual regressions.

Custom Setup Scripts

{
  "label": "Authenticated Dashboard",
  "url": "http://localhost:3000/dashboard",
  "onBeforeScript": "puppet/setAuthCookie.js",
  "onReadyScript": "puppet/dismissConsentBanner.js"
}

// puppet/setAuthCookie.js -- runs BEFORE navigation
module.exports = async (page, scenario, vp) => {
  await page.setCookie({
    name: 'session',
    value: process.env.TEST_SESSION_TOKEN,
    url: scenario.url,
  });
};

// puppet/dismissConsentBanner.js -- runs once the page is READY
module.exports = async (page, scenario, vp) => {
  const banner = await page.$('.cookie-consent button');
  if (banner) await banner.click();
};

CI Integration

# GitHub Actions -- run against a PR preview deployment, diffing
# against the checked-in reference images
name: Visual Regression
on: pull_request
jobs:
  backstop:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npm ci
      - run: npx backstop test
      - uses: actions/upload-artifact@v4
        if: failure()
        with:
          name: backstop-report
          path: backstop_data/html_report

BackstopJS vs Cloud Visual Testing Services

• BackstopJS: self-hosted, open-source, free -- the team runs it (locally/CI), stores reference images, and builds any review workflow beyond the local HTML report.

• Chromatic/Percy: managed cloud services -- hosted snapshot storage, diffing infra, and a review UI, at a per-snapshot/subscription cost.

• BackstopJS scenarios can also diff two live environments directly (e.g. production vs. a PR preview URL) instead of only comparing against a stored baseline.