BackstopJS uses Puppeteer by default to capture pages and compare them with approved screenshot references. Define scenarios and viewports, make page state repeatable, create a baseline with backstop reference, then run backstop test and review the visual report before approving intentional changes. The project documentation is at BackstopJS on GitHub.
How BackstopJS visual regression testing works
BackstopJS describes itself as automating visual regression testing by comparing screenshots over time. It orchestrates scenarios, browser captures and image comparisons: your configuration identifies pages and states, Puppeteer renders them, and BackstopJS reports differences from the approved references. A mismatch is a signal to inspect, not proof that a change is defective.
A scenario needs a label and URL, and the configuration needs at least one viewport. Depending on what you need to protect, a scenario can capture a page, a viewport, or a selected element. See the project documentation for configuration details and version-specific options.
Install and initialize BackstopJS
Run these commands from your project directory. The repository documents installing BackstopJS as a project dependency, then initializing its default backstop.json configuration:
#1 Best Overall
- Carefully designed questions: Ensuring a solid understanding of concepts
- Engaging activities: Offering a mix of enjoyable exercises
- Problem-solving techniques: Providing strategies for tackling challenges
- Vibrant, full-color visuals: Enhancing learning with captivating illustrations
npm install --save-dev backstopjs
npx backstop initInitialization creates a starter configuration. BackstopJS also supports a JavaScript configuration file. Check the installed version’s documentation before copying configuration options or browser flags: defaults and compatibility can change.
Configure scenarios and viewports
Each scenario should have a meaningful label and target URL. Viewports establish the dimensions at which the page is captured. This minimal illustrative configuration shows the shape of the setup; adapt it to the configuration generated by your installed BackstopJS version and your application:
{
"viewports": [
{ "label": "desktop", "width": 1440, "height": 900 }
],
"scenarios": [
{
"label": "Home page",
"url": "http://localhost:3000/",
"readySelector": "main"
}
]
}BackstopJS configuration supports many additional scenario and engine options. Use the repository documentation as the reference for exact property names and accepted values for the version installed in your project.
Choose a capture scope
| Scope | Useful when | Trade-off |
|---|---|---|
| Whole document | You need to catch page-wide layout changes, including content beyond the initial viewport. | More of the page can contain dynamic content, increasing the work needed to stabilize comparisons. |
| Viewport | The visible first screen or a fixed viewport is the behavior under test. | Changes outside that viewport are not covered by that capture. |
| Selected element | You want to focus on a component or region. | Surrounding layout changes may not appear in the captured image. |
Selectors use CSS notation. By default, the first matching element is captured; use selector expansion when the test should capture repeated matching elements. Pick the scope that matches the risk you intend to detect, rather than treating one scope as universally best.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Rank #2
- Dual Functionality: Our Pocket Eye Chart set includes both the 2 eye charts, offering a versatile solution for measuring visual acuity at a distance and in limited spaces. This 2-in-1 design caters to various vision testing needs
- Compact and Convenient: Sized at 6.5*3.5 inches, these pocket eye charts are designed for portability. Whether you're a professional optometrist, student, or need a handy tool for vision tests on the go, our compact pocket eye chart set fits conveniently in your pocket
- Color Vision Test: The eye chart features Red and Green color bars, providing an easy and helpful color vision test. This additional feature enhances the versatility of our pocket eye chart set, making it suitable for a range of vision examinations
- Durable and Washable: Crafted from durable plastic, our pocket eye charts are built to last. The washable material ensures easy maintenance and hygiene, making them ideal for repeated use in optometry practices, schools, and offices
- Pupil Gauge and Non-Reflective:The plastic pocket eye chart includes a pupil gauge, adding practicality to vision examinations. The non-reflective surface ensures accurate readings. This set is a reliable tool for professionals and a handy resource for quick vision assessments
Make browser state repeatable
Visual comparisons become noisy when the reference and test captures show different data, timing, or rendering environments. Stabilize those inputs before interpreting a diff.
Wait for a meaningful ready state
Prefer a readySelector or application-emitted readyEvent over an arbitrary delay. These state-based signals wait for something meaningful in the interface. A delay can still help after readiness when a known animation or transition needs time to finish, but delay alone can be either wasteful or too short.
Prepare authentication and interactions
BackstopJS supports before scripts for setup such as cookies and ready scripts for interactions such as clicks or hovers. Use them to put the page into a defined state, rather than relying on whatever a previous test or browser session left behind. Custom scripts receive the browser page and scenario context, which can also support setup such as user-agent or viewport-specific behavior.
Control variable content
- Use known static data or application stubs where practical so the same content appears in reference and test runs.
- If content must remain dynamic, consider masking it with a fixed-size region to preserve layout while excluding unstable pixels.
- Remove an unpredictable region only when that region is outside the behavior being tested.
Masking or removing content narrows what the test can detect. Use either deliberately and document the reason in the scenario or team conventions.
Keep the rendering environment aligned
Text and other rendering can differ between environments. Keep the browser, fonts, operating environment, viewport and data aligned between baseline creation and test runs. The BackstopJS documentation describes Docker rendering as an option for improving consistency; weigh that against the extra environment and runtime setup.
Create references, run tests and review changes
- Create the baseline: run
npx backstop referenceafter the application is in the intended state. These screenshots become the approved references. - Run a comparison: after a code or design change, run
npx backstop test. BackstopJS captures the configured scenarios and compares them with the current references. - Inspect the report: examine the changed areas and decide whether each difference is a regression, expected design work, or test noise.
- Approve only intended changes: run
npx backstop approveto promote the most recent test captures into the reference collection. Be careful when filtering approvals so you update only the scenarios you reviewed.
Do not approve a run merely to make a failing test pass. Approval changes the baseline against which later runs are judged; it is a deliberate acceptance of the current appearance.
Set comparison tolerance with care
The repository documents a default mismatch threshold of 0.1 percent and requireSameDimensions defaulting to true. Treat these as documented defaults, not universal recommendations. A threshold that is too strict can flag harmless rendering noise; one that is too loose can hide meaningful changes. Calibrate against the application and inspect the diff. Keeping dimension matching enabled is appropriate when size changes themselves should fail the comparison; change it only when the test’s purpose justifies doing so.
Run BackstopJS in CI
BackstopJS can run from a build pipeline through its CLI and produce reports, including JUnit output. The repository documentation says CI reporting uses JUnit format by default, and documents exit code 0 for successful tests and 1 when a test fails. A pipeline can therefore use the test command’s exit status to gate a build, while retaining the report for review.
Free tools Windows power users keep installed
One-click scans. No signup required.
Rank #4
- Creating calmer and happier mornings and bedtimes for the whole family by showing your child what they need to do to get ready.
- Encourages independence and therefore boosts self esteem as children are no longer dependent on you reminding them what comes next.
- Allows for processing time - the pictures, or pecs cards for autism, don't disappear like words do and therefore these are great for children with special educational needs, autism, ADHD, speech and language delay, ASD.
- Eliminates the need for you to nag - children can see what they need to do for themselves in this routine chart.
- Pictures cards can be moved around thanks to being attached using VELCRO Brand hook and loop, meaning you can order the routine to suit your family.
npx backstop testRun CI captures in an environment aligned with the one used to create references. Otherwise, font, browser or operating-system differences can create persistent mismatches that obscure actual application changes. Make baseline updates a reviewed code or artifact change in your team’s process rather than silently regenerating references during every build.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Puppeteer engine choices and project maintenance
Puppeteer is BackstopJS’s default rendering engine. Engine options and navigation parameters are configurable, and the README describes headless defaults and a gotoParameters example. Confirm flags and option names against your installed BackstopJS and Puppeteer versions before adopting them.
If the test requirement includes Firefox or WebKit, BackstopJS documents Playwright as an alternative rendering engine. That is a reason to consider another engine when browser coverage matters; it is not necessary to introduce Playwright merely to perform basic screenshot comparisons.
The BackstopJS repository README currently says, “BackstopJS needs a new maintainer/owner.” That is relevant when choosing a tool for long-lived test infrastructure. The README statement alone does not establish a current release cadence, supported-version policy, vulnerability-response process, or future support lifetime; check project activity and your own maintenance requirements before depending on it.
Best Value
Common problems and fixes
| Symptom | Likely cause | What to check |
|---|---|---|
| Differences appear on every run | Uncontrolled data, asynchronous readiness, animations, or environment drift. | Stub dynamic data, wait for a selector or ready event, allow only necessary animation time, and align browser, fonts, operating environment and viewport. |
| A page is captured before it is usable | The test relies on navigation completion or an arbitrary delay rather than application readiness. | Set a meaningful readySelector or readyEvent; use a delay only for a known remaining transition. |
| An element scenario misses repeated items | The selector matches multiple elements but the default capture selects only the first. | Use selector expansion if every matching instance should be captured, and confirm the exact option syntax in the installed-version documentation. |
| Text differs between local and CI runs | Fonts or rendering environments differ. | Align fonts and operating environment, keep the browser consistent, or consider the documented Docker rendering option. |
| Approving one change updates more than intended | Approval filtering selected additional scenarios, or the reviewed set was broader than expected. | Review the selected scenarios and latest captures before running backstop approve; approve only the intended changes. |
| Engine flags do not work as expected | Configuration is incompatible with the installed BackstopJS or Puppeteer version. | Verify the option and flag names against the documentation matching the installed versions instead of assuming defaults remain unchanged. |
Or skip the browser setup
For a one-off screenshot rather than an approved visual-regression baseline, ScreenshotNeo provides a website screenshot API and MCP server. BackstopJS remains the choice here for defining scenarios, maintaining references and reviewing visual diffs; ScreenshotNeo is an alternative when you need a screenshot response without configuring a browser capture yourself.
One GET request returns a PNG, JPEG or WebP image, or a PDF. See the ScreenshotNeo API documentation.
curl -G "https://api.screenshotneo.com/v1/shot"
-d access_key=YOUR_API_KEY
--data-urlencode url=https://stripe.com
-o shot.webpScreenshotNeo accepts cookie or consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups and chat widgets before capture; each of those steps can be turned off. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads and cache hits are not billed, and responses include X-Page-Verdict and X-Billed headers. Its MCP server offers take_screenshot, get_page_info and capture_pdf tools for Claude, Cursor and other MCP clients. The free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots.
Sign up for ScreenshotNeo’s free plan to get 1,000 screenshots a month with no card.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problemsQuick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
