How to Configure Argos CI to Compare Only Selected Pages

To make Argos compare only selected pages, capture screenshots only in tests for those pages. If a CI run intentionally executes only part of your normal suite, also enable Argos subset mode with ARGOS_SUBSET=true so screenshots from tests that did not run are not treated as missing. Keep a full suite run on your main branch for baseline updates: subset builds cannot become baselines.

1. Choose the right kind of selection

There are two controls, and they solve different problems:

Goal	What to configure
Always compare the same small set of routes	Limit your Playwright tests or screenshot calls to those routes.
Run only affected tests on a branch or in a partial CI job	Mark the Argos upload as a subset.
Create or update the complete reference set	Run the full visual test suite on the main branch.

Argos’s workflow captures screenshots in tests, uploads them from CI, compares them with a baseline, and presents visual differences for review. It documents integrations for Playwright, Storybook, Cypress, and Vitest. See the Argos documentation for the current integration details.

2. Capture only the routes you want

Keep a stable route list and give every captured page a stable, unique screenshot name. The example assumes your Playwright baseURL is configured; otherwise use absolute URLs or configure it in playwright.config.ts.

import { argosScreenshot } from "@argos-ci/playwright";
import { test } from "@playwright/test";

const pages = [
  { name: "homepage", path: "/" },
  { name: "account-settings", path: "/settings/account" },
];

test.describe("selected visual pages", () => {
  for (const { name, path } of pages) {
    test(name, async ({ page }) => {
      await page.goto(path);
      await argosScreenshot(page, name);
    });
  }
});

Only the tests that call argosScreenshot produce captures for this selection. Add another route by adding an item to the list, or remove a route by removing its item or test. Keep names unchanged when the route is logically the same page; changing a name can make Argos treat a capture as a different screenshot instead of matching its existing baseline.

3. Configure Playwright to upload captures

Register the Argos reporter in Playwright’s configuration so CI uploads captures. The exact reporter configuration depends on your installed Argos integration version and project setup; follow the current Argos Playwright setup instructions rather than copying a version-specific snippet blindly. Argos’s published example conditionally enables its reporter in CI.

// playwright.config.ts
import { defineConfig } from "@playwright/test";

export default defineConfig({
  // Add the Argos reporter using the configuration documented
  // for your installed @argos-ci/playwright version.
  // Keep your other Playwright settings and reporters here.
});

Configure the Argos project credentials in your CI environment as directed by Argos. Do not commit access tokens to the repository. A screenshot call without the Argos reporter or upload step may run as a browser test without reaching Argos for comparison.

4. Mark a partial CI run as a subset

If a job deliberately runs only some of the normal visual tests, set ARGOS_SUBSET to the string true for that job. For example:

- name: Run selected Playwright tests
  run: npx playwright test tests/visual/selected-pages.spec.ts
  env:
    ARGOS_SUBSET: "true"

This tells Argos that the upload is incomplete by design. Screenshots missing because their tests did not execute are ignored; captures from tests that did run can still be reported as changed or added. You can alternatively pass --subset to the Argos upload CLI or use subset: true in an SDK upload configuration, where applicable.

Do not assume that filtering tests automatically marks an upload as partial. Set the subset option explicitly whenever the run omits part of the normal capture set. A subset build is not eligible to become a baseline, so it cannot replace the complete reference build.

5. Keep baseline updates complete

Use route selection to decide which pages your regular visual checks capture.
For a branch job that intentionally skips some tests, enable subset mode for that upload.
Run the full suite on the main branch when you need a complete baseline build.
Review the resulting diffs in Argos before accepting visual changes.

A subset run is useful for validating affected pages, but it does not prove that skipped pages are unchanged. Keep a full run in the workflow that maintains your reference set.

6. Troubleshoot common problems

Symptom	Likely cause	Fix
Pages you did not intend to compare still appear	Other tests or capture calls still invoke `argosScreenshot`.	Search the suite for capture calls, then narrow the test selection or shared route list. Check that the CI command runs the intended test files.
Unrun pages appear as removed or missing	The CI run is partial but subset mode was not enabled.	Set `ARGOS_SUBSET=true` in the job or use the documented CLI/SDK subset option.
A subset run cannot update the baseline	This is expected behavior: subset builds are not baseline eligible.	Run the full suite on the main branch for baseline creation or updates.
A capture does not reach Argos	The reporter or upload configuration may be absent, misconfigured, or not active in CI.	Confirm the Playwright integration is registered, the CI job uses that configuration, and required Argos credentials are available as CI secrets.
A page is matched as a new screenshot	The screenshot name may have changed or may not be unique and stable.	Use a consistent name for each intended page and avoid deriving names from unstable data.
A selected route fails to load	The path may rely on a missing base URL, authentication, seeded data, or an unavailable service.	Set Playwright’s `baseURL`, establish the needed test state before navigation, and verify the route is reachable in the CI environment.

7. Performance, reliability, and cost considerations

Capturing fewer pages reduces the number of browser navigations and screenshots in that run, which can shorten the visual-check portion of CI. The actual time and service cost depend on your suite, CI environment, and Argos plan; no fixed savings can be inferred from the configuration alone.

For reliable comparisons, make route names stable, ensure each test establishes predictable page state, and distinguish a deliberately partial run from a full run. Subset mode protects against interpreting unexecuted tests as missing screenshots, but it does not increase coverage or permit a partial build to replace a full baseline.

Or skip the browser setup

If your goal is to capture selected pages for documentation, review, or an automated workflow outside Argos visual diffs, ScreenshotNeo is a website screenshot API and MCP server. One GET request returns an image or PDF, and the API docs describe its options.

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}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await Bun.write('shot.webp', res);

Cookie and consent banners, newsletter 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 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.

FAQ

Can I use subset mode for my regular, fixed list of pages?

If the fixed list is the complete set you intend to compare, scope your tests to that list. Subset mode is for an upload that intentionally omits screenshots from the normal suite.

Can a subset build become the baseline later?

No. Run a full suite on the main branch to create or update the complete baseline.

Does Argos automatically detect that I filtered Playwright tests?

The documented guidance calls for explicitly enabling subset mode for partial runs. Set the environment variable or upload option in the job that filters tests.