Add each visual-regression case as an object in BackstopJS’s top-level scenarios array. Every scenario needs a label and a url. Put settings shared by multiple cases in scenarioDefaults, then override them on individual scenarios where needed. For repeated routes, use a JavaScript configuration to generate the scenario objects from data.
Add scenarios to the configuration
BackstopJS reads its configuration from backstop.json in the project root by default. To scaffold a configuration, the project README documents backstop init. Add cases to the top-level scenarios array:
As an Amazon Associate I earn from qualifying purchases.
{
"scenarios": [
{
"label": "Product listing",
"url": "https://example.test/products"
},
{
"label": "Product detail",
"url": "https://example.test/products/example"
}
]
}Use a label that makes the page easy to identify in reports and targeted runs. BackstopJS uses labels in screenshot naming, and the CLI’s --filter option matches labels with a regular expression. Keep labels distinct enough that filtering one route does not accidentally select unrelated cases.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Required and optional fields
The README identifies label and url as required. Other scenario properties are optional: add them only when the page or capture needs them. For example, a readiness selector can wait for an important page element before capture:
#1 Best Overall
{
"label": "Product listing",
"url": "https://example.test/products",
"readySelector": "main"
}Check the configuration schema and engine behavior for the BackstopJS version installed in your project before relying on version-sensitive options; the project README is on a moving master branch.
Share settings with scenarioDefaults
When several scenarios need the same values, put them in scenarioDefaults rather than copying the same properties into every object. Common candidates include a cookie file, wait behavior, or selectors. A property set directly on a scenario takes precedence over its default.
{
"scenarioDefaults": {
"readySelector": "main"
},
"scenarios": [
{
"label": "Product listing",
"url": "https://example.test/products"
},
{
"label": "Account page",
"url": "https://example.test/account",
"readySelector": "[data-page-ready]"
}
]
}In this example the listing inherits main; the account scenario uses its own readiness selector instead.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →Rank #2
Watch for explicit empty arrays
An empty array is still an explicit scenario-level value. In particular, a scenario with "selectors": [] overrides selectors supplied through scenarioDefaults; it does not mean “inherit the defaults.” Remove the property when you want inheritance, or provide the selectors the scenario should use.
Generate reusable scenarios from JavaScript data
JSON works well for a static list. Use a JavaScript configuration when you want comments, functions, or a list generated from route data. BackstopJS documents JavaScript configuration files, including a configuration function that returns a config object; pass the file path with --config.
const routes = [
{ label: 'Product listing', path: '/products' },
{ label: 'Product detail', path: '/products/example' }
];
const scenarios = routes.map(({ label, path }) => ({
label,
url: `https://example.test${path}`,
readySelector: 'main'
}));
module.exports = {
id: 'shop',
viewports: [{ label: 'desktop', width: 1280, height: 800 }],
scenarios
};This uses ordinary JavaScript to build the documented configuration shape; the route array and file organization are project choices, not special BackstopJS requirements. Keep route data and shared settings in one place when that makes updates safer, but avoid adding an abstraction for a handful of scenarios that rarely change.
The Node API also accepts a config object directly, so another Node application or task runner can construct the same configuration and pass it to BackstopJS. That is useful when the scenario list already comes from application data or a build process.
Free tools Windows power users keep installed
One-click scans. No signup required.
Run one scenario or the full suite
Use backstop test to capture test images and compare them with the current references. To focus on matching labels, provide a regular expression with --filter:
backstop test --filter="Product listing"For example, a broader expression can select a family of related cases; because matching is regular-expression based, verify that the expression selects the intended labels before using it in a scripted run.
Understand reference, test, and approve
These commands have different effects, so adding a scenario is not itself a reason to replace a baseline:
backstop referencecreates baseline screenshots. It captures the scenario’surlunless that scenario has areferenceUrl, in which case it uses that URL. It does not compare images.backstop testcaptures test images and compares them with the current references.backstop approvepromotes the latest test images into the reference collection. Review visual differences first and approve only changes that are intentional.
For CI, the project documentation describes incorporating BackstopJS into a build process; the Node API is another way to invoke it from a Node application or task runner. Treat baseline approval as an explicit review decision rather than an automatic side effect of adding a route.
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Repair Windows errors before they cause bigger problems3Scan for outdated or missing drivers - takes under a minuteChoose a reuse approach
| Need | Approach |
|---|---|
| Static cases and straightforward edits | JSON configuration with objects in scenarios |
| Shared fields across scenarios | scenarioDefaults, with scenario-level overrides where necessary |
| Repeated route patterns or generated cases | JavaScript configuration that maps ordinary data into scenario objects |
| Run only selected cases while iterating | backstop test --filter=<label-regex> |
| References from a separate page or environment | Set referenceUrl on the relevant scenario |
Troubleshooting scenario setup
- A scenario is missing or configuration fails: confirm it is inside the top-level
scenariosarray and has bothlabelandurl. Check JSON punctuation if usingbackstop.json. - A default selector does not apply: inspect the scenario for an explicit property. In particular,
selectors: []overrides a default selector array. - A filtered run selects too much or too little: remember
--filteris a regular expression matched against labels. Tighten or escape the expression as needed and check the labels it matches. - A reference seems to come from the wrong page: check whether the scenario defines
referenceUrl; that URL is used for reference capture instead ofurl. - You expected a comparison after creating references:
backstop referenceonly creates baselines. Runbackstop testto compare, and usebackstop approveonly after reviewing test differences. - A JavaScript configuration is not being loaded: pass its path with
--config, and confirm that the module exports the expected configuration object or documented config-returning function for your installed version.
Or skip the browser setup
BackstopJS is for maintaining visual-regression scenarios, references, and comparisons. If you only need a website screenshot returned by an API, ScreenshotNeo is a separate option; it does not replace BackstopJS’s scenario and baseline workflow. One GET request can capture an image or PDF. See the ScreenshotNeo API documentation.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.test/products -o shot.webpScreenshotNeo removes cookie banners, newsletter popups, and chat widgets before capture; bot checks, blank pages, and failed loads are not billed. Its MCP server lets AI agents take screenshots. The Free plan includes 1,000 screenshots per month with no card, and paid plans start at $5 for 3,000. Sign up for free and get 1,000 screenshots a month with no card.
Frequently Asked Questions
Can I give a scenario a different reference page from the page under test?
Yes. Set that scenario’s referenceUrl; BackstopJS uses it for the reference capture instead of the scenario’s url.
Can I pass BackstopJS a config without keeping it in a JSON file?
The Node API accepts a configuration object directly, so a Node application or task runner can construct and pass one.
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.
