To test responsive breakpoints with BackstopJS, configure viewport sizes that match your project’s CSS layout transitions, capture reference screenshots with backstop reference, then run backstop test to compare later renders. BackstopJS tests the widths you specify; it does not discover your CSS breakpoints automatically.
Choose viewport sizes that exercise your breakpoints
Start with the breakpoints defined by your application’s CSS, then test at the transition itself and at widths on either side. Include additional widths where the layout is particularly sensitive, such as where a navigation menu changes form or a multi-column component stacks. Those choices are test-design guidance, not automatic BackstopJS breakpoint detection.
BackstopJS requires at least one viewport. Add labeled width-and-height objects to the root viewports array in your configuration. The labels make results easier to interpret.
{
"viewports": [
{ "label": "mobile-below", "width": 767, "height": 900 },
{ "label": "mobile-at", "width": 768, "height": 900 },
{ "label": "tablet-wide", "width": 1024, "height": 900 },
{ "label": "desktop", "width": 1280, "height": 900 }
]
}The values above illustrate the configuration shape only. Replace them with widths derived from the breakpoints and layout risks in your own application; generic phone, tablet, and desktop sizes may miss a transition that matters to your CSS.
Free tools Windows power users keep installed
One-click scans. No signup required.
#1 Best Overall
Configure scenarios for the pages and states you need
A scenario identifies a page state to capture. Give each scenario a meaningful label and URL. Use separate scenarios when route, content, or application state differs; BackstopJS applies the configured viewport list across the relevant scenarios.
{
"scenarios": [
{
"label": "Product listing",
"url": "http://localhost:3000/products"
},
{
"label": "Navigation open",
"url": "http://localhost:3000/products",
"clickSelector": "button[aria-label='Open menu']"
}
]
}Keep scenario labels and viewport labels specific. They appear in capture names and reports, helping you identify which page state and screen width produced a difference.
Capture and compare reference images
-
Make sure the target page and state are correct, then run
backstop reference. This creates the reference screenshots used as the approved baseline. -
After a code change, run
backstop test. BackstopJS captures test bitmaps at the configured viewports, compares them with the current references, and presents a report for inspection.Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy. -
Review each reported difference. If a visual change is intentional and correct, run
backstop approveto promote the latest changed captures to the reference collection. Future tests compare against those approved references.
Approval is a deliberate baseline update, not a shortcut for making a failed test pass. If a change is unexpected, fix the page or test setup rather than approving it away.
Select the capture scope that reveals the problem
BackstopJS can capture different parts of a page. Choose based on what the breakpoint test needs to show:
| Capture scope | Useful for | Trade-off |
|---|---|---|
document |
Checking the whole page, including content below the first screen. | More page content must render consistently for comparisons to be useful. |
viewport |
Focusing on the visible area at a particular screen size. | Does not show layout issues outside the current viewport. |
| CSS selector | Isolating a component whose layout changes at a breakpoint. | Provides less context than a page-level capture. |
Use the smallest scope that still exposes the failure. A page-level capture and a component capture can complement each other when you need both broad coverage and a focused diagnosis.
Make asynchronous pages stable before capture
If content loads after the initial page response, configure a readiness condition so BackstopJS captures the intended state. The documented options include:
readySelectorto wait for a specific selector.readyEventto wait for an application console event.delayto add a fixed pause before capture.
Prefer an explicit readiness signal when you can add or identify one. A fixed delay can be fragile when load time varies. For dynamic content, use static data stubs where practical so the same content appears on each run. BackstopJS also documents hiding or removing unstable elements when appropriate, but do not hide an area whose size or responsive behavior is what you are testing.
Set pixel and dimension rules separately
Two settings address different comparison questions:
misMatchThresholdcontrols the percentage of different pixels tolerated before a scenario fails. The documented BackstopJS default is0.1.requireSameDimensionscontrols whether changed image dimensions cause failure; the documented default istrue.
Decide how much pixel variation is acceptable separately from whether a changed capture size should fail. Review real diffs before relaxing either rule: an overly permissive threshold can mask small layout defects, while disabling dimension checks can conceal a meaningful change in captured size.
Debug a failing or inconsistent run
-
A screenshot is blank or incomplete: Check that the scenario URL is reachable and inspect the readiness condition. A selector or event that never becomes available can leave the capture in the wrong state; use a readiness signal that matches the page or adjust it for the application.
-
Only one viewport fails: Rerun only the matching scenario label with
--filter, then inspect that viewport’s report. Check the CSS transition and component state before changing references. -
Differences appear only in dynamic regions: Prefer stable test data or static data stubs. Hide or remove a region only if it is not part of the responsive behavior under test.
-
Results differ across operating systems: The BackstopJS project recommends Docker rendering to reduce environment-related variation and notes that text can render differently between environments. Docker can improve repeatability, but it does not guarantee identical output for every application or dependency.
Recommended Free Tools
Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy. -
Many small differences fail the run: Inspect whether the page is truly stable before raising
misMatchThreshold. Review sample diffs so a tolerance change does not hide a breakpoint regression. -
A capture-size change causes failure: Decide whether the dimension change is itself a defect before changing
requireSameDimensions; it is separate from pixel mismatch tolerance.
Or skip the browser setup
For a one-off screenshot rather than a repeatable BackstopJS regression suite, ScreenshotNeo can return a screenshot through one GET request. This example captures a page as WebP; see the ScreenshotNeo API documentation for request options.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpCookie banners are accepted and removed before the shot, along with known newsletter popups and chat widgets. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed. An MCP server provides screenshot tools for AI agents, and the free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. This is useful for individual captures, but it does not replace configuring responsive viewports and approved visual baselines in a BackstopJS test suite.
Sign up for ScreenshotNeo’s free plan to get 1,000 screenshots a month with no card.
Frequently Asked Questions
Does BackstopJS find my site’s CSS breakpoints automatically?
No. You choose and configure viewport sizes; BackstopJS compares captures at those sizes.
Can I use BackstopJS for both a whole page and one component?
Yes. Configure document, viewport, or CSS-selector captures according to whether you need page-wide coverage or a focused component view.
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.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →
