To set up BackstopJS, initialize it in your project, define the pages and viewport sizes to capture, save an approved reference set, and run tests against it. Inspect each reported difference before approving new references: a visual mismatch may be an intended change, unstable content, a timing issue, or a genuine regression.
What BackstopJS does
BackstopJS captures browser screenshots for configured scenarios and compares later captures with a reference set. Its report helps you inspect visual differences; it does not determine whether a difference is a bug. The project guide documents a lifecycle of reference capture, test, report review, and approval. BackstopJS project guide
Install and initialize BackstopJS
Choose local npm or Docker
For a local setup, use the npm installation and execution instructions in the project guide, then run backstop init from the project directory where you want the configuration and generated files. Exact installation commands and supported configuration options can vary by installed version, so use the guide for the version you choose.
Docker is an alternative when you want captures to run in a more consistent environment across a team or CI. Check the image version before adopting it: the Docker Hub listing describes a BackstopJS 3.x image, which should not be assumed to match every current BackstopJS release.
Free tools Windows power users keep installed
One-click scans. No signup required.
#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.
Run the initial reference and test cycle
- In the intended project directory, run
backstop init. - Configure at least one viewport and one scenario with a readable label and URL.
- Run
backstop referenceto capture the state you intend to treat as the baseline. - Run
backstop testto capture the configured scenarios again and compare them with the references. - Open and inspect the generated report before deciding what to do with any differences.
The DrupalSouth presentation uses this basic sequence and also shows reference and test URL workflows. Presentation PDF
Configure scenarios and viewports
Choose scenarios that cover meaningful states
A scenario identifies a page or state to capture. Give it a label that makes failures recognizable in the report and point it to a stable URL. Cover important page templates and user-visible states rather than adding many nearly identical URLs without a reason. At minimum, the project guide requires a scenario label and URL. BackstopJS project guide
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.
Include relevant viewport sizes
Configure at least one viewport. Include sizes that exercise the site’s important layout breakpoints and audience devices; a single desktop capture cannot reveal a mobile-only layout regression. The project guide documents viewport configuration, but the right set depends on your site’s responsive design. BackstopJS project guide
Handle readiness and dynamic content deliberately
Some pages need a wait before they are visually ready. The presentation lists delay, readiness event or selector, and before scripts among the scenario settings. The project guide also describes readiness waits, scripts, selector handling, cookies or browser state, and mismatch thresholds; confirm exact option names and behavior against your installed version. Presentation PDF BackstopJS project guide
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.
For pages with timestamps, rotating promotions, or other expected variation, stabilize the page where practical or hide only the narrowly defined unstable region. Broad masking can conceal real regressions, so keep each exclusion intentional and limited.
Select a rendering engine
The project guide identifies Puppeteer as the default and documents Playwright as an option, including Chromium, Firefox, or WebKit engine choices. Choose based on the browser behavior you want the test to exercise; a capture in one engine is not a guarantee of identical rendering in every browser used by your visitors. BackstopJS project guide
Rank #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
Choose a reference strategy
Use a stable approved baseline when your goal is to detect changes between a known-good version and a new build. Alternatively, configure separate reference and test URLs when the goal is to compare two environments, such as a production page and a candidate deployment. The DrupalSouth presentation demonstrates both models. Presentation PDF
Whichever model you choose, capture references only from the state you want future runs to treat as correct. A baseline is not merely a fresh screenshot: it is the accepted point of comparison for subsequent runs.
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 →Best 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.
Review differences and approve intentional changes
- Run
backstop testafter a code, content, or environment change. - Inspect the report and identify whether each difference is intended, caused by dynamic content or timing, or a likely defect.
- Fix genuine regressions or stabilize captures that are inconsistent for reasons unrelated to the change under test.
- When a visual change is intentional and reviewed, run
backstop approveto promote test captures to the new references. The project guide also describes filtering approval to selected captures.
Do not approve a report wholesale just to make a run pass. Approval changes the comparison baseline and can make an unreviewed defect appear normal in later tests. BackstopJS project guide
Run BackstopJS reliably in a team or CI
BackstopJS documents Docker execution and CI reporting. A container can reduce differences caused by machines rendering screenshots differently, but keep the container and BackstopJS versions compatible and stable. CI details depend on how your application starts and where it runs; ensure the test job can reach the site, start any required services, run the browser or container, and preserve the report and screenshot artifacts for review. BackstopJS project guide Presentation PDF
Troubleshoot common visual-test failures
- Many unrelated differences appear on every run: Check whether the browser environment differs between local and CI, then use a consistent containerized runtime and stable versions.
- A page is captured before its content appears: Add an appropriate readiness wait, selector, delay, or setup script supported by your installed version.
- Only a dynamic region differs: Stabilize its data or selectively exclude the changing region; avoid broad masking that could hide layout or styling defects.
- A test cannot reach the target URL: Verify that the URL is stable and accessible from the machine or CI job running BackstopJS, including any required authentication or service startup.
- Docker behavior does not match local behavior: Check the image’s BackstopJS version against the project version; the image listing describes a 3.x image, not universal compatibility with every release. Docker Hub image page
- Approval would overwrite changes you have not reviewed: Stop before running approval, inspect the report, and approve only the intentional captures using the filtering support documented for your version.
Or skip the browser setup
If you need screenshots from a URL without configuring a browser runner, ScreenshotNeo offers a screenshot API and MCP server. Its one-call cURL example is:
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 documentation for API options. Cookie banners, popups, and chat widgets are removed before the shot; bot checks, blank pages, and failed loads are never billed. An MCP server lets AI agents take screenshots, and the Free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Sign up for ScreenshotNeo free.
Frequently Asked Questions
Does BackstopJS tell me whether a screenshot difference is a bug?
No. It reports visual differences for you to inspect; you decide whether each one is an intended change, capture instability, or a regression.
Can BackstopJS compare two deployed environments instead of a build with a saved baseline?
Yes. Its configuration can use separate reference and test URLs when environment-to-environment comparison is the goal.
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.
