Migrate from BackstopJS

Migrate visual testing from self-hosted BackstopJS to Argos. Turn backstop.json scenarios into Playwright screenshots with cloud baselines and pull request review.

BackstopJS runs visual tests locally: you describe scenarios in backstop.json, capture baselines to a folder, and diff against them on your machine or CI. This guide moves that setup to Argos so baselines live in the cloud, comparisons are consistent across machines, and changes are reviewed on the pull request instead of in a local HTML report.

Why teams move off BackstopJS

BackstopJS is a solid self-hosted tool, but running it as a team surfaces gaps:

• Baselines are local files. bitmaps_reference/ is committed to Git or regenerated per machine — bloating the repo and drifting between environments.
• Approval is manual and local. backstop approve promotes images on one machine; there's no shared review, no history, and no per-change approval.
• No pull request integration. BackstopJS doesn't post a status or comment on your PR. You wire up reporting yourself.
• You maintain the infrastructure. Browsers, parallelization, storage, and flaky-content handling are all on you.

Argos keeps the same idea — visit a page, screenshot it, diff it — but selects baselines from your Git history, runs the comparison in the cloud, and turns each change into a reviewable PR check.

Concept mapping

BackstopJS	Argos
backstop.json scenarios (URL + selectors)	A Playwright test that visits URLs and calls argosScreenshot
viewports	Responsive viewports
backstop reference	Run on your default branch (baseline is automatic)
backstop test	Run on your pull request branch
backstop approve	Approve in the Argos review UI
bitmaps_reference/ (local baselines)	Cloud baselines from Git history
Local HTML report	Build review + PR comment
hideSelectors / removeSelectors	Injected CSS / stabilization
misMatchThreshold	Diff algorithm
clickSelector / hoverSelector / onReadyScript	Playwright interactions before the screenshot

Migrate the project

Argos captures screenshots from a test framework rather than a JSON scenario file. Playwright is the closest match to BackstopJS's browser-driving model, so this guide translates scenarios into a small Playwright test. (If you drive a fully custom pipeline, you can also capture images yourself and upload them with argos upload.)

1

Install Playwright and the Argos SDK

npm

npm i --save-dev @playwright/test @argos-ci/playwright

yarn

pnpm

bun

2

Add the Argos reporter

playwright.config.ts

import { defineConfig } from "@playwright/test";
import { createArgosReporterOptions } from "@argos-ci/playwright/reporter";

export default defineConfig({
  reporter: [
    process.env.CI ? ["dot"] : ["list"],
    [
      "@argos-ci/playwright/reporter",
      createArgosReporterOptions({
        uploadToArgos: !!process.env.CI,
      }),
    ],
  ],
  use: {
    launchOptions: {
      args: ["--disable-lcd-text", "--font-render-hinting=none"],
    },
  },
});

3

Translate scenarios into a test

Each BackstopJS scenario becomes a goto + argosScreenshot. Interaction fields map to Playwright actions before the screenshot.

Before (backstop.json)

{
  "scenarios": [
    {
      "label": "Homepage",
      "url": "http://localhost:3000/"
    },
    {
      "label": "Menu open",
      "url": "http://localhost:3000/",
      "clickSelector": ".menu-toggle"
    }
  ],
  "viewports": [
    { "label": "mobile", "width": 375, "height": 667 },
    { "label": "desktop", "width": 1280, "height": 800 }
  ]
}

After (tests/visual.spec.ts)

import { test } from "@playwright/test";
import { argosScreenshot } from "@argos-ci/playwright";

test("Homepage", async ({ page }) => {
  await page.goto("http://localhost:3000/");
  await argosScreenshot(page, "Homepage");
});

test("Menu open", async ({ page }) => {
  await page.goto("http://localhost:3000/");
  await page.click(".menu-toggle");
  await argosScreenshot(page, "Menu open");
});

To reproduce viewports, add a Playwright project per viewport. If your scenarios are just a list of URLs with no interactions, the Capture screenshots from URLs guide shows a compact loop.

4

Seed the baseline and wire up CI

There's no backstop reference step — run the tests on your default branch and Argos captures the baseline automatically. Until that build exists, pull request builds stay orphan.

- run: npx playwright install --with-deps chromium
- run: npx playwright test
  env:
    ARGOS_TOKEN: ${{ secrets.ARGOS_TOKEN }}

ARGOS_TOKEN comes from Settings → General → Token. On GitHub Actions you can use OIDC or tokenless authentication instead of a secret.

5

Remove BackstopJS

Delete backstop.json, the backstop_data/ directory (bitmaps_reference/, bitmaps_test/, html_report/), and the backstopjs dependency. Baselines and reports now live in Argos.

Migrating BackstopJS options

Hiding or removing elements (hideSelectors / removeSelectors)

Neutralize dynamic content before the screenshot with injected CSS (for example visibility: hidden) or the stabilization helpers, rather than per-scenario selector lists.

Ready scripts and delays (onReadyScript / delay)

Replace these with normal Playwright waits — await page.waitForSelector(...), await expect(locator).toBeVisible() — before calling argosScreenshot. See Wait for loading.

Mismatch threshold (misMatchThreshold)

Argos uses its own diff algorithm with anti-aliasing tolerance, so you don't set a per-scenario threshold.

Frequently asked questions

Do I have to use Playwright?

No. Playwright is the closest match to how BackstopJS drives a browser, but Argos also works with Cypress, WebdriverIO, Puppeteer, or any pipeline via argos upload. If you already capture images, you can skip the framework and just upload them.

Where do baselines and reports live now?

In Argos. Baselines are selected from your Git history, and every run produces a reviewable build with a PR status and comment — no committed bitmaps_reference/ or local HTML report.

How do I approve changes without backstop approve?

Open the build in the Argos review UI and approve or request changes. The PR check updates automatically.

Next steps

• Playwright quickstart
• Capture screenshots from URLs — closest to a scenario list.
• Keep your screenshots stable