BackstopJS tests web pages for visual regressions by comparing new browser screenshots with approved reference screenshots. Define representative scenarios, run backstop test, review the report, and use backstop approve only when the differences are intentional.
How the BackstopJS screenshot-diff workflow works
BackstopJS automates visual regression testing: it captures the page state you configure and compares each test screenshot with an accepted reference. A difference is a signal to investigate, not proof by itself that the page is broken. The reference should change only after someone reviews and accepts the new appearance.
- Run
backstop initto create the project setup. - Configure at least one viewport and one scenario with a label and URL.
- Run
backstop testto capture pages and generate a comparison report. - Inspect the reference, test, and difference views for each failure.
- Run
backstop approveto promote the latest test captures only when the visual changes are expected.
BackstopJS documents this workflow in its project README. You can also filter test runs with --filter to rerun selected scenarios; the README describes filtering which captures are promoted during approval.
Set up scenarios that represent real page states
Start with viewports and scenarios
The viewports configuration is an array of screen sizes, and at least one viewport is required. Each scenario identifies a page state to capture; its required properties include a label and URL. Add scenarios for the pages and states where visual regressions matter, rather than relying on a single screenshot to represent an entire application.
#1 Best Overall
- Read Before You Buy — No Video Output: These adapters support charging and USB 2.0 data transfer, but cannot transmit video signals. Except for standard USB webcams (which use USB data only), they are not compatible with HDMI/DisplayPort cables, video-capable USB-C hubs, or docking stations with video output.
- Convert USB-A Ports to USB-C: Designed to connect USB-C earphones, cables, flash drives, card readers, and other USB-C accessories to standard USB-A ports. Plug-and-play with no drivers or software required.
- Aluminum Alloy Housing: Built with a sturdy aluminum alloy shell that aids in heat dissipation and protects against daily wear and scratches. Designed to maintain a stable and secure connection.
- Compact & Travel-Friendly: The ultra-compact design allows the adapter to stay plugged into your device without blocking adjacent ports or adding bulk, reducing wear and tear on your original USB ports.
- 12-Month Warranty: Backed by a 12-month manufacturer warranty for peace of mind. Designed to meet strict quality control standards for reliable everyday performance.
By default, a scenario captures the document. Use selectors to restrict a capture to particular DOM elements when that is more useful than a full-page comparison.
Wait for the application, not just the browser
For asynchronous pages and single-page applications, use readySelector or readyEvent to identify when the application is actually ready. A delay can add time after that condition, but a fixed wait alone may be unreliable: it can be longer than necessary on fast runs and still too short on slow ones.
Use onBeforeScript and onReadyScript for browser state and interactions needed to reach the intended view, such as opening a menu or setting up a page before capture. Keep those actions repeatable so the reference and test runs reach the same state.
Control dynamic content thoughtfully
BackstopJS recommends using known static content stubs for dynamic applications, ideally with content of varying lengths. This helps reproduce the expected result while exercising layouts that respond to short or long content.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →Rank #2
- 5-in-1 USB-C Hub: Experience comprehensive connectivity featuring a Power Delivery input, two USB-A 2.0 ports, a USB-A 3.0 port, and an HDMI port. (Note: The USB-C power delivery input port is only for connecting an external wall charger to power your laptop and cannot power peripheral devices.)
- 90W Pass-Through Charging: Achieve optimal charging with 90W pass-through power to your laptop, supported by a total input of 100W, with the hub reserving 10W for operational efficiency. (Note: Wall charger not included.)
- Quick Data Transfers: Accelerate your productivity with rapid data transfers using a high-speed 5Gbps USB 3.0 port and two 480Mbps USB 2.0 ports.
- 4K HDMI Display: Enhance your visual experience with a hub capable of delivering 4K resolution at 30Hz in both mirror and extend modes. Please note that this hub is compatible with MacBook (macOS 12 and newer), Windows 10 and 11, ChromeOS, and laptops equipped with DP Alt Mode and Power Delivery. Note: This device is not compatible with Linux.
- What You Get: Anker USB-C Hub (5-in-1, 4K HDMI), welcome guide, 18-month warranty, and our friendly customer service.
- Use
hideSelectorsfor a changing element whose space should remain in the layout. - Use
removeSelectorswhen the variable element should be removed from the DOM and its space should no longer affect layout.
For example, hiding an ad with fixed dimensions can preserve the surrounding layout. Removing content whose size changes can be more appropriate when the layout should reflow without it. Choose based on the behavior the test is meant to protect.
Choose a rendering engine and keep captures consistent
The README says Puppeteer and Playwright are installed by default, with Puppeteer used by the default configuration. It describes Playwright as the option for Chromium, Firefox, or WebKit, and calls for the corresponding Playwright onBefore and onReady scripts. Playwright storage state can provide cookies and local storage for authenticated captures.
There is no universally best engine in the documentation: choose based on the browsers your pages need and the environment in which your tests will run. Keep the engine and capture environment consistent between creating references and running tests. BackstopJS notes that the same page can render differently across environments, particularly text.
The optional --docker flag runs rendering tests in a container and is intended to reduce cross-environment differences. It does not eliminate every source of nondeterminism; use it when the container matches your project’s workflow and CI setup.
Rank #3
- Sleek 7-in-1 USB-C Hub: Features an HDMI port, two USB-A 3.0 ports, and a USB-C data port, each providing 5Gbps transfer speeds. It also includes a USB-C PD input port for charging up to 100W and dual SD and TF card slots, all in a compact design.
- Flawless 4K@60Hz Video with HDMI: Delivers exceptional clarity and smoothness with its 4K@60Hz HDMI port, making it ideal for high-definition presentations and entertainment. (Note: Only the HDMI port supports video projection; the USB-C port is for data transfer only.)
- Double Up on Efficiency: The two USB-A 3.0 ports and a USB-C port support a fast 5Gbps data rate, significantly boosting your transfer speeds and improving productivity.
- Fast and Reliable 85W Charging: Offers high-capacity, speedy charging for laptops up to 85W, so you spend less time tethered to an outlet and more time being productive.
- What You Get: Anker USB-C Hub (7-in-1), welcome guide, 18-month warranty, and our friendly customer service.
Read the diff and set a useful mismatch threshold
The misMatchThreshold option sets the percentage of differing pixels allowed before a screenshot fails. The project README documents 0.1 as its default. That is a tool default, not a universal recommendation: the right sensitivity depends on how stable your pages and capture environment are.
Inspect the reference, test, and difference views before deciding whether a failure matters. If small changes are expected noise, stabilize the page or tune the threshold deliberately rather than approving every failure. The README notes that default mismatch reporting does not detect mismatches below 0.01%; it documents usePreciseMatching for cases that need a threshold below that level.
Approve a new baseline only after review
When a report shows a difference, first determine whether it is an unintended regression or an intended design or content change. If it is intended, run backstop approve to make the latest test captures the new references. If it is a bug, fix the page and rerun the test instead of promoting the screenshot.
Because approval updates the baseline, treat it as a review decision in the same way you would review a code change. Use scenario filtering when you want to focus a rerun or constrain which captures are promoted, as documented in the README.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchRank #4
- Dual Converters, Infinite Potential：Includes 2× USB C male to USB A female adapters and 2× USB A male to USB C female adapters. Perfect for a wide range of uses—tablets with Bluetooth keyboards, expand USB ports on macbook, and more. Two different converters for all your daily needs
- Next-Level 10Gbps & 3A Charging: No more slow 480Mbps, this usb to usb c adapter has a transfer speed of up to 10Gbps, allowing you to do more transferring in less time. This usb adapter fits both USB A and USB C charger, supporting up to 3A fast charging
- Upgraded Exquisite Craftsmanship: With an aluminum alloy housing and metal connector, the usbc to usb adapter is extremely durable and sturdy. Rigorously tested to withstand more than 10,000 times of plugging and unplugging, ensuring long-lasting performance
- Broad Compatible: The usb c to usb adapter widely supports all USB C/ USB A devices like laptops, tablets, cellphones, car chargers, and phone chargers. Such as compatible with MacBook Pro/Air 2023/2022, Thunderbolt 4/3 Devices,Apple MagSafe Watch 9/8/7/SE/Ultra, iPad Pro 2022/2021, Samsung Galaxy S23/S20/S10, and iPhone 17/16/15 Pro. Plug and play
- Please Note: To reach 10Gbps speed, keep the cable under 3.3 ft. For USB A Male to USB C adapters, try flipping the USB C connector. USB C Male to USB A adapters support bidirectional 10Gbps transfer within 3.3 ft
Troubleshoot common BackstopJS capture failures
Tests time out in Docker
The project README identifies Chrome headless memory use as one possible source of timeout trouble in Docker. Check the container’s available resources and the CI environment before assuming the page itself is stuck. Exact behavior depends on the host and container setup.
A Docker run cannot reach localhost
Inside Docker, localhost may refer to the container rather than the host machine. The README notes that Mac and Windows users may need a host-accessible URL such as host.docker.internal. The correct address depends on the host environment and container configuration.
Images differ between local and CI runs
Rendering differences between environments can affect comparisons, including text. Keep browser engine, environment, viewport, page state, and test data as consistent as you can. Docker may reduce environmental variation when it fits the workflow, but it cannot make changing content or application state deterministic.
A dynamic page is captured too early
Replace a blind reliance on a longer delay with an application-specific readySelector or readyEvent when possible. Then use a delay only for any extra settling time required after readiness, and use static stubs for content that would otherwise vary between runs.
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Clear out junk files and repair common Windows errors3Fix the driver behind crashes, sound loss and screen glitchesBest Value
- 5-in-1 Connectivity: Equipped with a 4K HDMI port, a 5 Gbps USB-C data port, two 5 Gbps USB-A ports, and a USB C 100W PD-IN port. Note: The USB C 100W PD-IN port supports only charging and does not support data transfer devices such as headphones or speakers.
- Powerful Pass-Through Charging: Supports up to 85W pass-through charging so you can power up your laptop while you use the hub. Note: Pass-through charging requires a charger (not included). Note: To achieve full power for iPad, we recommend using a 45W wall charger.
- Transfer Files in Seconds: Move files to and from your laptop at speeds of up to 5 Gbps via the USB-C and USB-A data ports. Note: The USB C 5Gbps Data port does not support video output.
- HD Display: Connect to the HDMI port to stream or mirror content to an external monitor in resolutions of up to 4K@30Hz. Note: The USB-C ports do not support video output.
- What You Get: Anker 332 USB-C Hub (5-in-1), welcome guide, our worry-free 18-month warranty, and friendly customer service.
Small visual changes do not fail the test
Review the configured misMatchThreshold and whether the default precision is sufficient. For thresholds below 0.01%, the README documents usePreciseMatching; verify the setting against the version and configuration you use.
Project stewardship and adoption
As of the BackstopJS project README accessed October 3, 2026, the repository included a notice saying it needed a new maintainer or owner. That notice establishes that the project was seeking a maintainer when the page was accessed; it does not establish whether one has since been appointed or indicate a release cadence. Before adopting BackstopJS for a long-lived project, check current repository activity and compatibility with your dependency and CI requirements.
Or skip the browser setup
If you need a screenshot endpoint rather than a self-managed visual regression workflow, ScreenshotNeo is a website screenshot API and MCP server. A single GET request returns a screenshot or PDF; it is not a replacement for BackstopJS’s reference comparison and approval workflow.
For example, using cURL:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for request options. Before capture, it accepts cookie or consent banners like a visitor and removes 60+ known consent platforms, newsletter popups, and chat widgets; each cleanup step can be turned off. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and each response indicates the page verdict and billing status in headers. An MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. The Free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots.
Recommended Free Tools
Sign up free for 1,000 screenshots a month, with no card required.
Quick 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.
