How to Compare ScreenshotMachine CLI Screenshots for Visual Changes

To compare ScreenshotMachine screenshots for visual changes, save an approved screenshot as a baseline, capture the same page again with matching settings, and compare the two image files with a separate image-diff tool. The reviewed ScreenshotMachine documentation describes an HTTP GET screenshot API and capture parameters; it does not establish a ScreenshotMachine CLI command or built-in visual-diff feature. The capture and comparison steps are separate.

This guide uses cURL, Python, and Node.js to capture the images. If you mean a particular ScreenshotMachine CLI, verify its command syntax in that project’s first-party documentation before relying on it; no exact ScreenshotMachine CLI interface is established by the sources cited here.

1. Understand the capture-and-compare workflow

A visual comparison needs two images of the same page: an approved reference (also called a baseline or golden image) and a new capture. A comparison tool can show where they differ, but a reviewer decides whether each difference is a defect or an intended design change. Android’s screenshot-testing guide describes this reference-and-review approach and notes that rendering differences can arise from operating systems, libraries, or hardware.

1. Choose a URL and the exact page state to capture.
2. Capture a baseline and save the settings used to make it.
3. Capture the page again after the code or content change, with the same settings.
4. Compare the files using a separate image-diff tool.
5. Review the original images and the diff, then either fix a regression or deliberately approve the new image as the baseline.

Do not let a diff tool silently replace its reference when it finds a change. Reviewing before updating the baseline preserves the value of the comparison.

2. Make ScreenshotMachine captures reproducible

Use the same URL, dimensions or device profile, format, zoom, and relevant page state for both captures. ScreenshotMachine’s documented GET API supports an API key, target URL, dimensions, device, format, cache age, delay, and zoom. The official documentation is the source of truth for accepted parameter names and current behavior: ScreenshotMachine documentation. The dossier identifies these settings but does not include the endpoint or exact parameter spellings, so the examples below intentionally use placeholders instead of inventing a request URL or CLI command.

Setting	How to use it for comparisons
Target URL	Keep the exact URL stable, including query parameters that affect content.
Dimensions or device	Choose a fixed viewport or device profile. Record it with the baseline and reuse it.
Format	Use PNG when lossless pixel review matters. Keep the format identical between captures.
Delay	ScreenshotMachine documents a default delay of 200 ms and accepts 0–10000 ms. Increase it when content needs time to settle; its documentation suggests 2000 ms or more for some long pages with images or animations.
Cache age	The documented default cache age is 14 days, and the cache control accepts 0–14 days. Set cacheLimit=0 when requesting a fresh image for a new comparison.
Zoom	Keep zoom the same for both images, because scaling changes can alter many pixels.

Also stabilize the page itself. Use deterministic test data where possible, wait for asynchronous content, and avoid capturing at different animation frames. If the page depends on login, locale, time, or personalization, keep those inputs consistent. Store the settings beside each baseline so a later comparison can be reproduced.

3. Capture and save a baseline

Open ScreenshotMachine’s official documentation and use its documented GET endpoint and parameter names. Substitute your API key and URL, choose explicit dimensions or a device, request PNG if available, and set an intentional delay and cache age. Save the returned image as a baseline file such as baseline.png. Keep a small metadata record with the URL, date, dimensions/device, delay, cache setting, and any other capture parameters.

The following are request templates, not copy-paste-ready ScreenshotMachine commands: the reviewed material does not provide the endpoint or parameter spelling needed to make them exact. Replace the placeholders with the values from ScreenshotMachine’s current first-party API documentation.

cURL template

curl -G "SCREENSHOTMACHINE_GET_ENDPOINT" \
  --data-urlencode "key=YOUR_API_KEY" \
  --data-urlencode "url=https://example.com/page" \
  --data-urlencode "dimension=1200x800" \
  --data-urlencode "format=png" \
  --data-urlencode "delay=2000" \
  --data-urlencode "cacheLimit=0" \
  -o baseline.png

Python template

import requests

endpoint = "SCREENSHOTMACHINE_GET_ENDPOINT"
params = {
    "key": "YOUR_API_KEY",
    "url": "https://example.com/page",
    "dimension": "1200x800",
    "format": "png",
    "delay": 2000,
    "cacheLimit": 0,
}
response = requests.get(endpoint, params=params, timeout=90)
response.raise_for_status()
with open("baseline.png", "wb") as image:
    image.write(response.content)

Node.js template

const endpoint = "SCREENSHOTMACHINE_GET_ENDPOINT";
const params = new URLSearchParams({
  key: "YOUR_API_KEY",
  url: "https://example.com/page",
  dimension: "1200x800",
  format: "png",
  delay: "2000",
  cacheLimit: "0",
});
const response = await fetch(`${endpoint}?${params}`);
if (!response.ok) {
  throw new Error(`Screenshot request failed: ${response.status} ${response.statusText}`);
}
const bytes = new Uint8Array(await response.arrayBuffer());
await import("node:fs/promises").then(({ writeFile }) => writeFile("baseline.png", bytes));

Check ScreenshotMachine’s documented parameter names before running the templates. In particular, do not assume the example key or dimension names are valid; they are placeholders for the API documentation’s names.

4. Capture the new image and compare the files

After the page changes, repeat the capture with the same URL and settings. Save it as current.png. Then give baseline.png and current.png to your chosen comparison tool. That tool is a separate part of the workflow: its command, threshold behavior, report format, and support for independently captured images depend on the tool you choose.

When selecting a comparator, check whether it:

• Accepts two image files captured independently.
• Shows the baseline and current images as well as a diff image.
• Lets you configure tolerance or thresholds and explains what they mean.
• Can save comparison metadata or a report for code review or CI.
• Runs in a consistent environment and supports intentional baseline updates.

One independently documented project, refactorau/screenshot-cli, has its own capture and compare workflow, threshold and minimum-change options, optional diff images, saved comparison data, and HTML/PDF reports. Its commands belong to that project; they are not ScreenshotMachine CLI commands or a ScreenshotMachine integration. Another separate example is mmcc007/screenshots, a Flutter-oriented project with expected-image comparison and red-highlighted diff images. Choose a tool whose input model fits your separately captured ScreenshotMachine files, and follow that tool’s own documentation for exact commands.

5. Interpret the diff and manage baselines

A changed pixel is a signal to inspect, not an automatic failure verdict. First compare the two full images, then inspect the diff. Decide whether the change reflects a bug, a legitimate interface update, dynamic page content, or rendering noise. If it is intentional, approve the new image as the reference through your normal review process.

Thresholds can reduce noise from small rendering variations, but a permissive threshold can also hide a real regression. Start with strict comparison while establishing stable captures, then tune only after you understand the source of recurring noise. Keep the threshold documented and consistent across local and CI runs.

Reference collections can become cumbersome, especially when many pages, viewport sizes, or states are represented. Android’s guide discusses source control, Git LFS, and cloud storage as options, and recommends minimizing redundant screenshot combinations. Keep only meaningful page-state and viewport combinations, and make baseline changes reviewable alongside the code that caused them.

6. Troubleshooting

Symptom	Likely cause	What to do
The two images differ everywhere	Viewport, device, zoom, or format changed.	Compare saved capture settings and rerun both captures with matching values.
The image looks stale	The API returned a cached capture.	Request a fresh capture with ScreenshotMachine’s documented cacheLimit=0 setting.
Images, fonts, or widgets are missing	The page had not finished loading when captured.	Use an appropriate documented delay, within the 0–10000 ms range, and check whether the content loads asynchronously.
Small regions flicker in the diff	Animation, timestamps, rotating content, personalization, or environment variation.	Capture a stable state, use deterministic data if available, and keep the rendering conditions aligned. Apply tolerance cautiously.
Image cannot be opened or comparator rejects it	The response may be an API error or non-image body saved with a PNG extension.	Inspect the HTTP status and response headers/body before saving; confirm the selected format and API parameters against ScreenshotMachine’s documentation.
Authentication or request error	Missing/invalid API key, malformed URL encoding, or incorrect parameter names.	Check the key, encode the target URL, and verify endpoint and parameter spelling in first-party documentation.
CLI command is unknown	The command may belong to a separate comparison project, or the assumed ScreenshotMachine CLI may not exist.	Use ScreenshotMachine’s documented HTTP API for capture and the comparator’s own documentation for comparison. Verify any claimed ScreenshotMachine CLI syntax with its first-party source.
CI fails but local comparison passes	Different OS, browser or rendering libraries, hardware, fonts, or timing.	Use the same CI image and rendering environment for baseline generation and later captures, then update references only after review.

7. Performance, reliability, and cost considerations

Two captures are required for each comparison cycle: the reference capture and the new capture. Reuse an approved baseline rather than recapturing it for every run. Keep the page set and viewport matrix focused, since each additional page state creates another image to store and review.

Cache behavior affects freshness and repeatability: a cached image can be useful when the same page state is intended, but a stale image is misleading after a change. For a new capture intended to reflect the current page, use the documented zero cache age. Longer delays can allow slow content to settle but increase waiting time; choose a delay that matches the page rather than using the maximum by default.

Cost depends on ScreenshotMachine’s current plan and billing rules, which are not specified in the reviewed research. Check its current pricing and API terms before estimating a production capture budget. Also account for the storage and review burden of retained reference images and diff reports.

Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server. It returns an image or PDF from one GET request; its documentation is at ScreenshotNeo docs. For a quick capture you can compare with your separate diff tool, use the documented endpoint:

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

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)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

ScreenshotNeo accepts cookie and consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks, blank pages, timeouts, and failed loads are never billed, and cache hits cost nothing; response headers identify the page verdict and billing status. An MCP server provides screenshot tools for AI agents. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots. Use consistent capture settings for your before-and-after images, and still review the diff before changing a baseline.

Sign up free for 1,000 screenshots a month, with no card required.

FAQ

Does ScreenshotMachine have a CLI diff command?

The reviewed first-party material establishes a screenshot HTTP API, not a ScreenshotMachine CLI command or built-in diff. Verify a specific CLI claim with ScreenshotMachine’s own documentation before publishing or adopting it.

Should I compare PNG or JPEG?

Use PNG when lossless pixel review matters and keep the format identical for the baseline and new capture. A lossy format can introduce differences unrelated to the page change.

When should I replace the baseline?

After a reviewer confirms the visible change is intended. Keep the updated reference tied to the code or content change that explains it.