> For the complete documentation index, see [llms.txt](https://argos-ci.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://argos-ci.com/docs/learn/how-to-guides/ci-pipelines/subset-builds.md).

# 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)](/docs/learn/how-to-guides/ci-pipelines/cached-pipelines.md) for the full setup.

{% hint style="info" %}
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](/docs/learn/platform-fundamentals/baseline-build.md).
{% endhint %}

### 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.

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

#### CLI

Use the `--subset` flag with the CLI.

{% tabs %}
{% tab title="npm" %}

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

{% endtab %}

{% tab title="yarn" %}

```
yarn run argos upload --subset ./screenshots
```

{% endtab %}

{% tab title="pnpm" %}

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

{% endtab %}

{% tab title="bun" %}

```
bun x argos upload --subset ./screenshots
```

{% endtab %}
{% endtabs %}

#### SDK option

Most SDKs expose a `subset` option on the upload configuration.

{% code title="upload.js" %}

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

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

{% endcode %}

### Examples

#### Playwright

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

{% code title=".github/workflows/ci.yml" %}

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

{% endcode %}

#### Cypress

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

{% code title=".github/workflows/ci.yml" %}

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

{% endcode %}

### Troubleshooting / FAQ

<details>

<summary>Why are removed screenshots ignored?</summary>

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.

</details>

<details>

<summary>Do omitted screenshots count toward my quota?</summary>

A subset build does not copy baseline screenshots omitted from the upload into the new build. Omitted screenshots are ignored for comparison. They are neither removals nor carried-over screenshots.

Only screenshots captured and uploaded in the subset build are registered. Each registered screenshot counts toward your quota, even when it is unchanged from the baseline. Baseline screenshots omitted from the upload do not consume quota merely because they exist in the baseline. See [How usage is counted](/docs/learn/billing-and-subscription/spend-management.md#how-usage-is-counted).

</details>

<details>

<summary>Why can’t a subset build be a baseline?</summary>

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

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://argos-ci.com/docs/learn/how-to-guides/ci-pipelines/subset-builds.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.