How to Update Accepted Screenshots in Argos CI After a UI Change

To update accepted screenshots in Argos CI, rerun the screenshot-producing tests after your UI change, open the resulting Argos build, review each visual diff, and approve the intended changes. Approval records the new accepted screenshots as the baseline for later comparisons. It does not regenerate screenshots; your test job or upload step does that.

Approve only diffs that match the intended change. Reject unexpected differences, fix the UI or capture setup, then rerun and review. Argos selects pull-request baselines from approved builds at the merge-base commit; you generally do not update a separate set of baseline image files in your repository. Argos review workflow · Argos baseline and diff behavior

1. Regenerate and upload the screenshots

Run the same Playwright, Cypress, Storybook, or other screenshot job that normally creates the Argos build. Argos integrations capture during the test run. If your tests create image files without an Argos integration, upload the resulting directory with the CLI:

npx @argos-ci/cli upload ./screenshots

Use the same capture names, viewport sizes, and test coverage as the existing run. The comparison is most useful when the only meaningful difference is the UI change under review. For the CLI upload workflow, see Argos Diff documentation.

2. Open the new build and inspect the diffs

Open the Argos build created by the run, usually from the pull request status check or its Argos link. Compare each changed screenshot with its baseline. The review page supports side-by-side and single-image views, overlays, and comments pinned to a location on a screenshot. Argos review tools

• Expected change: the changed pixels correspond to the UI work described by the pull request. Approve after reviewing the affected viewports and states.
• Unexpected change: the difference is unrelated, clips content, breaks a responsive state, or reflects an unstable capture. Reject or request changes, fix the cause, and rerun.
• No change detected: confirm the changed UI is included in the test run and that the run captured the intended commit and route.

A review decision is consequential: an approval updates what future builds compare against, while an active rejection blocks the build. Do not approve a change simply to clear a pending check.

3. Approve the intended changes in the Argos UI

1. Open the build and inspect every changed screenshot, including relevant mobile, desktop, and alternate-state captures.
2. Use the side-by-side view or overlay to identify what moved. Add a pinned comment if a teammate needs context.
3. Approve the reviewed changes or build if they match the intended UI update.
4. Reject unexpected changes. Correct the source or capture instability, rerun the screenshot job, and review the new build.

Accepted screenshots become the baseline for subsequent comparisons. For pull requests, Argos chooses the latest approved build on the merge-base commit with the base branch. Builds on main or another configured branch pattern can be auto-approved and provide a current baseline. How Argos selects baselines

4. Review from the command line

CLI review is useful when you want build data and review actions in a terminal or automation workflow. Install the CLI as a development dependency, then fetch the build and list snapshots that need review:

npm install -D @argos-ci/cli

# Read the build details
npx argos build get <build>

# List only snapshots awaiting a decision
npx argos build snapshots <build> --needs-review

After inspecting the images and confirming that the changes are intended, submit the decision:

npx argos review create <build> --event approve \
  --body "Matches the intended UI update."

To reject a build with unexpected changes:

npx argos review create <build> --event reject \
  --body "Unexpected visual change; investigating the affected snapshot."

Replace <build> with the build reference accepted by your CLI invocation. Build reads can use a project token; submitting a review requires a personal access token and respects the user’s project permissions. Keep tokens out of committed files and logs. See the Argos CLI review documentation for the documented command sequence and authentication distinction.

5. Confirm the next comparison uses the accepted baseline

After approval, later pull-request builds use the approved build associated with the merge-base commit. If the next run still shows the same difference as new, verify which commit and base branch the build used, and check whether the intended approval was recorded on the build you expected. Configured auto-approved branches can keep the baseline current without manually approving every branch build. Argos baseline selection

Common problems and fixes

Symptom	Likely cause	What to do
The old screenshot still appears	The capture job did not rerun, uploaded a different directory, or ran against a different commit than the UI change.	Check the CI job logs and upload path. Rerun the screenshot-producing job for the intended commit.
The build has no changed screenshots	The changed page or state was not captured, or the test ran against stale application output.	Confirm the affected route and state are covered, and ensure the app build deployed to the test environment contains the change.
Every screenshot changes unexpectedly	The environment, data, viewport, fonts, or other capture inputs may differ from the baseline run.	Compare the run configuration and test data. Stabilize the capture inputs before accepting a broad diff.
Approval does not clear the pull-request check	A different build may be pending, or another review has rejected the build.	Open the exact build linked from the check and inspect its current review state. Argos documents that one rejection blocks the build. Review status behavior
CLI can read the build but cannot submit a review	Read operations and review submission use different credential requirements.	Use a personal access token with the necessary project permissions for review submission; a project token can read build and snapshot data.
CLI cannot find the build or snapshots	The build reference may be wrong, the token may not access its project, or the build may not yet exist.	Copy the build reference from Argos and verify project access and that the capture/upload job completed.
A partial test run makes screenshots appear removed	The run may not include the full screenshot suite.	Run the full suite when you intend to establish a complete baseline. Argos also documents subset builds for partial suites; understand their missing-snapshot behavior before relying on them. Subset builds

Performance, reliability, and cost considerations

Updating a baseline adds no separate image-commit step in the hosted Argos workflow: the approved build and commit history inform later comparisons. Runtime is primarily determined by your screenshot-producing tests and upload job; this update procedure does not require a second browser capture after approval. Avoid approving noisy diffs to save review time: stabilizing test data and capture conditions reduces repeated investigation.

Review every relevant changed viewport before approving. If a change is expected only at one size or state, investigate changes elsewhere instead of treating the entire build as one decision. The research available for this guide does not establish Argos plan pricing or a performance benchmark, so no price or timing estimate is included.

Or skip the browser setup

For a one-off screenshot outside the Argos baseline workflow, ScreenshotNeo is a website screenshot API and MCP server from Yorker Media. It returns an image or PDF from one request and offers an MCP server for Claude, Cursor, and other MCP clients. It can help inspect the rendered result, though it does not approve an Argos build or update an Argos baseline.

See the ScreenshotNeo API documentation. cURL:

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

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)

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 bytes = new Uint8Array(await res.arrayBuffer());
await import('node:fs/promises').then(fs => fs.writeFile('shot.webp', bytes));

• Cookie banners, popups, and chat widgets are removed before the shot; each cleanup step can be turned off.
• Bot checks, blank pages, timeouts, failed loads, and cache hits are never billed; response headers identify the page verdict and billing status.
• An MCP server lets AI agents take screenshots.
• 1,000 screenshots a month are free with no card; paid plans start at $5 for 3,000 screenshots.

Create a free ScreenshotNeo account.

FAQ

Do I need to commit new baseline PNGs?

Not for the hosted Argos baseline flow described here. Approving the build records the accepted result, and Argos selects later pull-request baselines using approved builds and Git history.

Does approving a build rerun my tests?

No. Rerun the capture job to send the changed UI to Argos; approval records the review decision for screenshots already in the build.

Can I approve from a terminal?

Yes. The CLI can fetch build details, list snapshots that need review, and submit an approval or rejection. Review submission requires a personal access token.

Can ScreenshotNeo accept an Argos visual change?

No. ScreenshotNeo captures a URL; Argos handles its own build review and baseline decisions.