# BackstopJS — Visual Regression Testing for Web UIs

> BackstopJS is a visual regression testing tool that compares screenshots of web pages across code changes, catching unintended CSS and layout regressions automatically.

## Install

Save in your project root:

# BackstopJS — Visual Regression Testing for Web UIs

## Quick Use
```bash
npm install -g backstopjs
backstop init        # Create config
backstop reference   # Capture baseline screenshots
backstop test        # Compare current state against baseline
backstop approve     # Promote current screenshots to new baseline
```

## Introduction
BackstopJS automates visual regression testing by capturing screenshots of web pages and comparing them pixel-by-pixel against reference images. When CSS, layout, or content changes cause visual differences, BackstopJS highlights them in a browser-based report. It uses Puppeteer or Playwright as the rendering engine.

## What BackstopJS Does
- Captures screenshots of web pages at configurable viewport sizes (mobile, tablet, desktop)
- Compares test screenshots against approved reference images using pixel diff algorithms
- Generates an interactive HTML report highlighting visual differences with overlay and slider views
- Supports CSS selector targeting to test specific components instead of full pages
- Integrates with CI pipelines via exit codes for pass/fail gating

## Architecture Overview
BackstopJS reads a JSON or JS configuration file that defines test scenarios (URLs, selectors, viewports, and interaction scripts). It launches a headless browser via Puppeteer or Playwright, navigates to each URL, optionally executes click/scroll/type scripts, and captures screenshots. The comparison engine (resemblejs or pixelmatch) produces diff images and a pass/fail report served as a static HTML page.

## Self-Hosting & Configuration
- Install globally or as a dev dependency via npm
- Run backstop init to generate a backstop.json config file
- Define scenarios with url, selectors, viewports, and optional onReady scripts
- Set misMatchThreshold per scenario to control acceptable pixel difference percentage
- Use --docker flag to run in a Docker container for consistent rendering across environments

## Key Features
- Multi-viewport testing to catch responsive layout regressions
- Interactive HTML report with side-by-side, overlay, and slider comparison modes
- Scenario scripting for clicking buttons, filling forms, or waiting for animations
- Docker mode for deterministic font and rendering across CI environments
- Configurable diff thresholds per scenario for pixel-level sensitivity control

## Comparison with Similar Tools
- **Percy (BrowserStack)** — cloud-hosted visual testing; BackstopJS is self-hosted and free
- **Chromatic** — Storybook-focused visual testing SaaS; BackstopJS tests any URL
- **Playwright visual comparisons** — built-in but requires manual baseline management
- **reg-suit** — similar self-hosted approach with S3/GCS storage for baselines
- **Applitools** — AI-powered visual testing SaaS; BackstopJS uses pixel-level diffing

## FAQ
**Q: How do I avoid flaky tests from dynamic content?**
A: Use hideSelectors or removeSelectors in your scenario config to mask clocks, ads, or other dynamic elements before capture.

**Q: Can I test behind authentication?**
A: Yes. Use onBefore engine scripts to set cookies or fill login forms before navigating to protected pages.

**Q: How do I run BackstopJS in CI?**
A: Use the --docker flag for consistent rendering, commit reference images to your repo, and run backstop test in your CI pipeline.

**Q: What browsers does BackstopJS support?**
A: BackstopJS uses Puppeteer (Chromium) by default. Playwright engine support adds Firefox and WebKit options.

## Sources
- https://github.com/garris/BackstopJS
- https://github.com/garris/BackstopJS/wiki

---
Source: https://tokrepo.com/en/workflows/asset-55e855f0
Author: AI Open Source