Subset builds

Run subset builds to upload a partial test run without affecting the baseline of screenshots it didn't cover.

Subset builds are designed for CI runs that don't execute the full E2E test suite on a branch. When a build is marked as subset, Argos ignores removed screenshots and only notifies you about changed and added screenshots from the tests you did run.

This is helpful for speeding up feature-branch validation while still getting reliable visual feedback from the relevant tests. It's a key ingredient of pipelines where a task cache decides which suites run — see Cached CI pipelines (Turborepo, Nx) for the full setup.

You still need to run your full test suite on your main branch to create and update baseline builds. Subset builds are not eligible as baselines. See Baseline build.

Enable subset builds

You can enable subset builds in any Argos SDK or the CLI.

Environment variable

Set the environment variable ARGOS_SUBSET to "true" in your CI configuration.

steps:
  - name: Run tests
    run: npm test
    env:
      ARGOS_SUBSET: "true"

CLI

Use the --subset flag with the CLI.

npm

npm exec -- argos upload --subset ./screenshots

yarn

yarn run argos upload --subset ./screenshots

pnpm

pnpm exec -- argos upload --subset ./screenshots

bun

bun x argos upload --subset ./screenshots

SDK option

Most SDKs expose a subset option on the upload configuration.

upload.js

import { upload } from "@argos-ci/core";

await upload({
  root: "./screenshots",
  subset: true,
});

Examples

Playwright

For Playwright, simply set ARGOS_SUBSET=true in your CI job. The reporter will mark the build as a subset build.

.github/workflows/ci.yml

steps:
  - uses: actions/checkout@v6
  - uses: actions/setup-node@v6
  - run: npm ci
  - name: Run Playwright tests
    env:
      ARGOS_SUBSET: "true"
    run: npx playwright test

Cypress

For Cypress, set ARGOS_SUBSET=true in your CI job that runs Cypress and uploads screenshots.

.github/workflows/ci.yml

steps:
  - uses: actions/checkout@v6
  - uses: actions/setup-node@v6
  - run: npm ci
  - name: Run Cypress tests
    env:
      ARGOS_SUBSET: "true"
    run: npx cypress run

Troubleshooting / FAQ

Why are removed screenshots ignored?

Subset builds only include a portion of your test suite, so missing screenshots may simply be from skipped tests, not actual deletions. Ignoring removals avoids false positives.

Why can’t a subset build be a baseline?

Baselines must represent the full test suite. Subset builds are incomplete by design and would cause missing screenshots in comparisons.