How to Approve Only Selected Visual Changes in BackstopJS

To approve only selected visual changes in BackstopJS, review the latest test report, identify the capture filenames you want to accept, then run backstop approve --filter='<image_filename_regex>'. The filter matches image filenames, so only matching captures from the most recent test batch are promoted to references. Without a filter, BackstopJS promotes every changed image in that batch. BackstopJS README.

1. Run a test and inspect the report

BackstopJS captures the configured scenarios, compares the new screenshots with the approved references, and presents the differences in its report. First run the test:

backstop test

Use the visual report or CLI output to identify the exact image filename for each capture you intend to accept. Filenames normally include scenario and viewport names. Build the approval pattern from filenames actually shown in your report, rather than guessing their format.

2. Approve only matching captures

Pass a regular expression with --filter to backstop approve. For example:

backstop approve --filter='checkout.*desktop'

This example is illustrative: it approves changed captures whose image filenames match the expression. Confirm that the pattern matches only the intended scenario and viewport. If a test used a custom configuration file, pass that same file to approval:

backstop approve --config=backstop.staging.js --filter='checkout.*desktop'

Use the actual config path from your test command. After approval, review the reference images or rerun the test to confirm that the intended captures now compare against the accepted baseline.

3. Keep test selection separate from approval selection

BackstopJS has filters at two different stages:

• backstop test --filter=<scenarioLabelRegex> limits which scenarios are run.
• backstop approve --filter=<image_filename_regex> limits which captures from the latest test batch are promoted.

Filtering the test run does not replace careful approval selection. Inspect that run’s report, then use an approval filter if you want to accept only some of its changed captures. An unfiltered approval promotes all changed images in the most recent test batch.

4. Make the filename pattern safe

• Match the capture filename: the approval filter is documented as an image-filename regex, not a scenario-label filter.
• Be specific about the viewport: include the viewport portion when only one viewport should be accepted.
• Check for unintended matches: regex characters such as . match more than a literal period. Escape them if your actual filename contains a period and you need an exact match.
• Quote the expression: shell quoting keeps characters such as * from being expanded by the shell. Single quotes are suitable for patterns that do not themselves contain a single quote.
• Use the latest test batch: approval updates references using captures from the most recent test batch. Run the relevant test again if you are unsure which batch is current.

The report is the source of truth for the filenames. If several captures share a partial name, use a narrower expression or approve one exact filename at a time.

5. Understand what approval settings do

The filename filter controls which captures are promoted. It does not change how BackstopJS decides whether a capture differs from its reference.

Setting	What it affects	Documented default
misMatchThreshold	Percentage of visual difference tolerated before an image is marked failed.	0.1
requireSameDimensions	Whether a screenshot dimension change causes failure.	true

Adjust comparison configuration when the comparison result itself is wrong for your project. Use the approval filter when the comparison is valid but you want to accept only some changed captures. See the official README for the project’s command and configuration details.

Common problems and fixes

Symptom	Likely cause	Fix
More screenshots were promoted than intended	The regex matched multiple filenames, or approval ran without a filter.	Inspect the report filenames, narrow the regex, and verify the command includes --filter before approving.
The intended screenshot was not promoted	The expression does not match the image filename, or the capture was not part of the latest batch.	Copy the filename from the report, check the pattern against it, and rerun the intended test if necessary.
Approval uses the wrong setup	The test used a custom config, but approval did not receive that config path.	Pass the same --config path used for the test.
A scenario test filter seems to have no effect on approval	Test filtering selects scenarios; approval filtering selects image filenames at a later stage.	Use the appropriate filter for each command, and inspect the report before approving.
An unchanged capture was not updated	Approval promotes images with changes from the latest test batch.	Confirm the capture is reported as changed and that your filename regex matches it.
The comparison fails on a size change	requireSameDimensions is enabled, which is the documented default.	Check whether the dimension change is intentional, then adjust comparison configuration if that matches your project’s policy.

Reliability and workflow notes

Reference approval changes what future runs treat as the expected appearance. Keep the selection tied to a reviewed report, and include the scenario and viewport in the filter when those distinctions matter. For a large batch, approving captures in small, reviewable groups makes it easier to spot an overly broad pattern before it updates references.

BackstopJS’s approval operation concerns the captured reference images in the latest test batch. It does not, by itself, establish whether a visual change is correct; that decision comes from reviewing the differences against the intended UI change.

Or skip the browser setup

If your immediate need is to capture a page rather than compare and approve a BackstopJS reference set, ScreenshotNeo provides a one-request screenshot API and an MCP server for AI agents. Here is a cURL capture:

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

See the ScreenshotNeo API documentation for request options. The same call can be made from Python:

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

Or Node.js:

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
const fs = await import('node:fs/promises');
await fs.writeFile('shot.webp', Buffer.from(await res.arrayBuffer()));

• Cookie banners, newsletter popups, and chat widgets can be removed before the shot; each cleanup step can be turned off.
• Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed. Response headers report the page verdict and billing status.
• 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 per month with no card. Paid plans start at $5 for 3,000 screenshots; every feature is available on every plan.

Start with 1,000 free screenshots a month, no card required.

FAQ

Does backstop approve --filter filter by scenario label?

No. The approval filter matches image filenames. Scenario selection for a test run uses the test command’s scenario-label filter.

Can I approve one viewport while leaving another unchanged?

Yes. Use a filename pattern that matches the intended scenario and viewport, based on the report’s actual filenames.

Will changing the mismatch threshold limit which references are approved?

No. The mismatch threshold affects comparison failure behavior. The approval filter determines which changed captures are promoted.