How to Use the BackstopJS Reference, Test, and Approve Flow in CI

BackstopJS separates baseline creation (reference) from comparison (test) and acceptance (approve), so CI runs test while reference and approve happen deliberately.

Create baselines with backstop reference, compare with backstop test in CI, and promote intended changes with backstop approve when you review a diff.

Steps

Define scenarios and viewports in backstop.json.
Run backstop reference to capture baselines and commit them.
Run backstop test in CI to compare.
Run backstop approve locally to accept intended changes.

Commands

Terminal

npx backstop reference   # create baselines
npx backstop test        # compare (used in CI)
npx backstop approve     # promote diffs to baselines

Workflow

.github/workflows/ci.yml

jobs:
  backstop:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npx backstop test
      - uses: actions/upload-artifact@v4
        if: failure()
        with:
          name: backstop-report
          path: backstop_data/html_report/

Gotchas

Never run backstop approve inside CI; it would rubber-stamp every diff.
Commit bitmaps_reference/ so the runner has baselines to compare against.