Skip to main content
JUMP TO:Quick StartCLI CommandsConfigurationPlaywright APIMCP ServerGitHub Actions
Guides / Migrate from BackstopJS(22 of 37)

Migrate from BackstopJS

MANUAL MIGRATION. Frontguard does not claim a lossless one-command BackstopJS conversion.

Translate BackstopJS scenarios, viewports, selectors, and percentage thresholds into a single typed frontguard.config.ts file.

Local-First Privacy Boundary and Legacy VRT Migration Workflow
FIG 01 · MIGRATION MATRIX — SCENARIOS TO ROUTES, MISMATCH THRESHOLD RATIO & GIT ORPHAN BASELINES

Scope

  • Map scenario URLs to routes and viewport widths.
  • Convert misMatchThreshold percentages to Frontguard ratios by dividing by 100.
  • Start the app, review captures, run frontguard update-baselines --confirm-baselines, and push frontguard-baselines.
  • Keep both tools in CI until the new comparisons are independently reviewed.

Configuration mapping

BackstopJS (backstop.json)Frontguard (frontguard.config.ts)Migration Notes
viewports: [{ label, width, height }]viewports: [375, 768, 1440]Specify widths as positive integers in CSS pixels (use top-level viewportHeight to override default height).
scenarios[].urlbaseUrl + routes: ["/pricing", ...]Extract shared origin to baseUrl and list relative paths in routes.
scenarios[].misMatchThreshold: 1.5threshold: 0.015Divide BackstopJS percentage (0–100) by 100 to get Frontguard ratio (0–1).
scenarios[].hideSelectors / removeSelectorsignore: [{ selector: ".ad-banner" }]Masks volatile DOM elements before capture.
scenarios[].readySelector / delayactions: [{ type: "waitForSelector", selector }, { type: "wait", ms }]Combine with waitForStability: true for automatic frame convergence.
bitmaps_reference/frontguard-baselines git orphan branchManaged via frontguard update-baselines --confirm-baselines; keeps main branch free of PNG blobs.
Before (backstop.json) vs After (frontguard.config.ts)
// Before: backstop.json
// { "viewports": [{ "name": "desktop", "width": 1440, "height": 900 }],
//   "scenarios": [{ "label": "Pricing", "url": "http://localhost:3000/pricing",
//     "hideSelectors": [".chat-widget"], "misMatchThreshold": 1.0 }] }

// After: frontguard.config.ts
export default {
  version: 1,
  baseUrl: 'http://localhost:3000',
  viewports: [1440],
  routes: ['/pricing'],
  ignore: [{ selector: '.chat-widget' }],
  threshold: 0.01, // 1.0% divided by 100
  waitForStability: true,
}

Baseline migration

Because BackstopJS uses its own Puppeteer/Playwright viewport framing and reference directory structure, do not copy old bitmaps_reference PNGs directly. Instead, boot your application, run frontguard update-baselines --confirm-baselines once to establish fresh Chromium baselines, inspect them, and push frontguard-baselines.

Thresholds

BackstopJS expresses misMatchThreshold on a 0–100 percentage scale (where 0.1 means 0.1%), whereas Frontguard uses a 0–1 ratio scale (where 0.001 means 0.1% and 0.01 means 1%). Always divide your BackstopJS threshold by 100.