garris/backstopjs

★ 7,142JavaScriptAudience · developerComplexity · 3/5Setup · moderate

Mindmap

mindmap
  root((repo))
    What it does
      Screenshot comparison
      Visual diff reports
      Approve changes
    How it works
      Headless browser
      Docker support
      CI integration
    Tech Stack
      JavaScript
      Node.js
      npm
    Use Cases
      CSS regression tests
      Multi-screen testing
      Automated pipelines

mindmap root((repo)) What it does Screenshot comparison Visual diff reports Approve changes How it works Headless browser Docker support CI integration Tech Stack JavaScript Node.js npm Use Cases CSS regression tests Multi-screen testing Automated pipelines

Click or tap to explore — scroll the page freely

Things people build with this

USE CASE 1

Catch CSS changes that accidentally shifted buttons or changed font sizes before they reach production

USE CASE 2

Run automated visual tests in a CI/CD pipeline to block bad deploys

USE CASE 3

Test how a page looks across multiple screen sizes in one command

USE CASE 4

Script user interactions like clicking a menu before taking a screenshot to test hidden states

Tech stack

JavaScriptNode.jsnpmDocker

Getting it running

Difficulty · moderate Time to first run · 30min

Requires Node.js and a headless browser (Playwright or Puppeteer), Docker is recommended for consistent cross-machine results.

In plain English

BackstopJS is a tool for catching unintended visual changes to a website or web app. It works by taking screenshots of your pages and comparing them to a set of approved reference screenshots. When something in the visual layout changes, such as a button shifting position or a font size changing, BackstopJS highlights the difference so you can decide if the change was intentional. The typical workflow has three steps. First you run an initialization command to configure which pages and screen sizes to test. Then you run a test, which takes new screenshots and compares them to the saved references. If the differences look correct, you approve them, which updates the references for future comparisons. This cycle repeats each time you make changes to your CSS or frontend code. The tool uses a browser running in headless mode, meaning it opens web pages in the background without displaying a visible window. You can script user interactions like clicking or scrolling before screenshots are taken, which lets you test states that require navigation. It can also run inside Docker, a container system, to produce consistent results across different machines. BackstopJS generates an in-browser report with a visual diff view that shows old and new screenshots side by side, along with a scrubber to compare them interactively. It also produces reports compatible with continuous integration systems, so it can be integrated into automated build and deployment pipelines. The tool is installed via npm, the standard JavaScript package manager, and can be used from the command line or required directly into a Node.js application. It runs on Windows, macOS, and Linux. The full README is longer than what was shown.

Copy-paste prompts

Prompt 1

I use BackstopJS to test my website. Write me a backstop.json config that tests my homepage and product page at mobile and desktop sizes.

Prompt 2

My BackstopJS test is flagging a difference I want to approve. Walk me through the approve command and when it is safe to use it.

Prompt 3

How do I configure BackstopJS to click a 'Load More' button before taking a screenshot so I can test the expanded state?

Prompt 4

Set up BackstopJS in a GitHub Actions workflow so visual regression tests run on every pull request and fail the build if a diff is found.

Prompt 5

I am running BackstopJS locally but my CI server produces slightly different screenshots. How do I use the Docker mode to get consistent results on both?

Open on GitHub → Explain another repo

← garris on gitmyhub — every repo by this author, as a profile.

Verify against the repo before relying on details.