# Overview
Learn how Argos works and where to start.
Argos is a visual testing platform that catches visual regressions before they reach production. Your tests capture screenshots, Argos compares them against a baseline, and you review the changes on your pull requests.
It works with the tools you already use — Playwright, Storybook, Cypress, Vitest, or any pipeline that produces screenshots.
### How it works
1. **Your tests capture** screenshots in CI.
2. **Your CI uploads** the screenshots to Argos.
3. **Argos compares** them against the [baseline build](/docs/learn/platform-fundamentals/baseline-build).
4. **You review** visual diffs on the pull request.
5. **You approve** expected changes or reject regressions.
6. **Argos updates** the pull request check, so you can merge with confidence.
### When to use Argos
Use Argos when visual changes affect product quality or release confidence:
* **UI regressions**: Catch broken layouts, CSS changes, and missing images, icons, or fonts.
* **Design systems**: Track component changes across themes, browsers, and viewports.
* **Product variants**: Validate white-labeled interfaces, translations, and localized layouts.
* **AI-generated UI**: Visually validate generated changes before merging them.
### Open source and self-hosting
Argos is open source: the whole platform — backend, frontend, and the screenshot comparison engine — is developed in the open in the MIT-licensed [argos-ci/argos](https://github.com/argos-ci/argos) repository. There is no closed-source component behind the diff service.
Argos is operated as a managed cloud service, and that is the supported way to run it. Self-hosting is not officially supported or documented: the production setup targets AWS and depends on PostgreSQL, RabbitMQ, Redis, S3, and DynamoDB, plus integrations such as the GitHub App and Stripe — you would be on your own to deploy and operate them. If your organization has strict hosting or compliance requirements, [contact us](https://argos-ci.com/contact) about the Enterprise plan.
### Get started
Ready to add Argos to your project? Pick your framework in the [Quickstart](/docs/quickstart) — you'll upload your first build and see it on a pull request in a few minutes.
### Explore more
Once Argos is set up, go deeper:
* [Core concepts](/docs/learn/platform-fundamentals) – How Argos compares screenshots and picks a baseline
* [Review workflow](/docs/learn/review-workflow) – Review builds in the dashboard and on your pull requests
* [Stabilize screenshots](/docs/learn/reliability-and-flakiness/flaky-tests) – Keep your visual tests free of flakiness
* [Integrations](/docs/learn/integrations) – Connect GitHub, GitLab, and Slack
# Quickstart
Install Argos, upload your first screenshots, and review your first build.
By the end of this guide, you will have Argos connected to your CI, your first build uploaded, and a pull request check ready to review.
Pick the guide that matches your test setup. If your framework isn't listed, [any test framework](/docs/quickstart/any-test-framework) shows how to upload screenshots with the Argos CLI.
# Playwright Quickstart
Set up visual testing in your Playwright tests with the Argos Playwright SDK.
Set up Argos with [Playwright](https://playwright.dev/) to run visual tests on every pull request: install the SDK, add the reporter, capture screenshots, and run it in CI.
### Prerequisites
* [Playwright](https://playwright.dev/docs/intro#installing-playwright) set up in your project
* [Playwright running on your CI](https://playwright.dev/docs/ci-intro#on-pushpull_request)
* [A project created in Argos](https://app.argos-ci.com/new)
{% stepper %}
{% step %}
### Install
Install the Argos Playwright SDK:
{% tabs %}
{% tab title="npm" %}
```
npm i --save-dev @argos-ci/playwright
```
{% endtab %}
{% tab title="yarn" %}
```
yarn add --dev @argos-ci/playwright
```
{% endtab %}
{% tab title="pnpm" %}
```
pnpm add --save-dev @argos-ci/playwright
```
{% endtab %}
{% tab title="bun" %}
```
bun add --dev @argos-ci/playwright
```
{% endtab %}
{% endtabs %}
{% endstep %}
{% step %}
### Add the Argos reporter to your Playwright config
The Argos reporter uploads screenshots and traces to Argos as your tests run:
{% code title="playwright.config.ts" %}
```js
import { defineConfig } from "@playwright/test";
import { createArgosReporterOptions } from "@argos-ci/playwright/reporter";
export default defineConfig({
// ... other configuration
// Reporter to use
reporter: [
// Use "dot" reporter on CI, "list" otherwise (Playwright default).
process.env.CI ? ["dot"] : ["list"],
// Add Argos reporter.
[
"@argos-ci/playwright/reporter",
createArgosReporterOptions({
// Upload to Argos on CI only.
uploadToArgos: !!process.env.CI,
}),
],
],
// Setup recording option to enable test debugging features.
use: {
// Collect trace when retrying the failed test.
trace: "on-first-retry",
// Capture screenshot after each test failure.
screenshot: "only-on-failure",
// Stabilize text rendering so screenshots match across macOS and CI.
launchOptions: {
args: ["--disable-lcd-text", "--font-render-hinting=none"],
},
},
});
```
{% endcode %}
With `trace` and `screenshot` enabled, Playwright records failure screenshots and traces — the reporter uploads them to Argos automatically, so you can debug failed tests visually.
{% hint style="success" %}
The `launchOptions` above disable subpixel text and font hinting, so glyphs render identically on your machine and on CI. This single change prevents one of the most common causes of flaky screenshots — learn why in [Stabilize text rendering](/docs/learn/reliability-and-flakiness/flaky-tests/stabilize-text-rendering).
{% endhint %}
{% endstep %}
{% step %}
### Capture screenshots
Use the `argosScreenshot` helper to capture stable screenshots in your tests:
{% code title="tests/example.spec.ts" %}
```js
import { test } from "@playwright/test";
import { argosScreenshot } from "@argos-ci/playwright";
test("screenshot homepage", async ({ page }) => {
await page.goto("http://localhost:3000");
await argosScreenshot(page, "homepage");
});
```
{% endcode %}
Screenshots are written to the `./screenshots` directory by default. Add `./screenshots` to your `.gitignore` file to avoid committing them.
Tip: Check out our guides to [screenshot multiple pages](/docs/learn/how-to-guides/visual-coverage/capture-screenshots-from-urls) or [capture multiple viewports](/docs/learn/how-to-guides/visual-coverage/responsive-viewports).
{% endstep %}
{% step %}
### Set up CI
Run your Playwright tests in CI with `ARGOS_TOKEN` set. The Argos reporter uploads screenshots automatically when it detects a CI environment:
{% code title=".github/workflows/argos.yml" %}
```yaml
name: Argos
on:
pull_request:
push:
branches:
- main
jobs:
argos:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- uses: actions/setup-node@v6
- run: npm ci
- run: npx playwright install --with-deps chromium
- run: npx playwright test
env:
ARGOS_TOKEN: ${{ secrets.ARGOS_TOKEN }}
```
{% endcode %}
`ARGOS_TOKEN` is the project token from **Settings → General → Token**. On GitHub Actions, you can also use [OIDC or tokenless authentication](/docs/learn/integrations/github-actions-authentication) to avoid managing a secret. On other CI providers, pass the token with the `ARGOS_TOKEN` environment variable or the reporter's `token` option.
{% endstep %}
{% endstepper %}
### You're all set
Push your changes and open a pull request — the Argos check appears on it once the build is uploaded. Review the visual changes, approve or reject them, and merge with confidence.
{% hint style="info" %}
Argos needs a baseline to compare against. Until a build runs on your default branch, pull request builds are marked as [orphan](/docs/learn/platform-fundamentals/baseline-build#orphan-builds). Merge this setup or run the workflow once on your default branch to establish the baseline.
{% endhint %}
### Next steps
* [Stabilize screenshots](/docs/learn/reliability-and-flakiness/flaky-tests) – Prevent flaky diffs before they reach your pull requests
* [Playwright SDK reference](/docs/reference/playwright) – All options and helpers
* [Playwright example](https://github.com/argos-ci/argos-javascript/tree/main/examples/playwright) – A complete working setup
***
Need help? [Join our Discord](https://argos-ci.com/discord), [open an issue on GitHub](https://github.com/argos-ci/argos/issues), or [send us an email](mailto:contact@argos-ci.com).
# Vitest Quickstart
Set up visual testing in your Vitest browser tests with the Argos Vitest SDK.
Set up Argos with [Vitest](https://vitest.dev/) to run visual tests on every pull request. The Argos Vitest SDK adds visual testing to Vitest in two ways:
* **Screenshots** of your rendered components, captured from [Vitest browser tests](https://vitest.dev/guide/browser/).
* **Snapshots** of any value — objects, JSON, HTML, and more — captured from browser **or** plain Node tests. No browser required.
{% hint style="info" %}
Using **Storybook**? Follow the [Storybook Quickstart](/docs/quickstart/storybook-quickstart) instead — it builds on this same Vitest integration.
{% endhint %}
### Prerequisites
* [Vitest](https://vitest.dev/) set up in your project
* [Vitest running on your CI](https://vitest.dev/guide/cli)
* [A project created in Argos](https://app.argos-ci.com/new)
Capturing **screenshots** additionally requires [Vitest browser mode](https://vitest.dev/guide/browser/) with the [Playwright provider](https://vitest.dev/guide/browser/playwright). **Snapshots** run in any Vitest test and need neither.
{% stepper %}
{% step %}
### Install
Install the Argos Vitest SDK:
{% tabs %}
{% tab title="npm" %}
```
npm i --save-dev @argos-ci/vitest
```
{% endtab %}
{% tab title="yarn" %}
```
yarn add --dev @argos-ci/vitest
```
{% endtab %}
{% tab title="pnpm" %}
```
pnpm add --save-dev @argos-ci/vitest
```
{% endtab %}
{% tab title="bun" %}
```
bun add --dev @argos-ci/vitest
```
{% endtab %}
{% endtabs %}
To capture **screenshots**, also install the [Vitest browser mode](https://vitest.dev/guide/browser/) peer dependencies (skip this if you only need snapshots):
{% tabs %}
{% tab title="npm" %}
```
npm i --save-dev vitest @vitest/browser @vitest/browser-playwright playwright
```
{% endtab %}
{% tab title="yarn" %}
```
yarn add --dev vitest @vitest/browser @vitest/browser-playwright playwright
```
{% endtab %}
{% tab title="pnpm" %}
```
pnpm add --save-dev vitest @vitest/browser @vitest/browser-playwright playwright
```
{% endtab %}
{% tab title="bun" %}
```
bun add --dev vitest @vitest/browser @vitest/browser-playwright playwright
```
{% endtab %}
{% endtabs %}
{% endstep %}
{% step %}
### Add the Argos plugin to your Vitest config
The Argos plugin registers the `argosScreenshot` browser command and, when `uploadToArgos` is enabled, uploads the captured screenshots to Argos at the end of the run:
{% code title="vitest.config.ts" %}
```ts
import { defineConfig } from "vitest/config";
import { playwright } from "@vitest/browser-playwright";
import { argosVitestPlugin } from "@argos-ci/vitest/plugin";
export default defineConfig({
plugins: [
argosVitestPlugin({
// Upload to Argos on CI only.
uploadToArgos: !!process.env.CI,
}),
],
test: {
browser: {
enabled: true,
headless: true,
provider: playwright({
// Stabilize text rendering so screenshots match across macOS and CI.
launchOptions: {
args: ["--disable-lcd-text", "--font-render-hinting=none"],
},
}),
instances: [{ browser: "chromium" }],
},
},
});
```
{% endcode %}
{% hint style="success" %}
The `launchOptions` above disable subpixel text and font hinting, so glyphs render identically on your machine and on CI. This single change prevents one of the most common causes of flaky screenshots — learn why in [Stabilize text rendering](/docs/learn/reliability-and-flakiness/flaky-tests/stabilize-text-rendering).
{% endhint %}
{% hint style="info" %}
The `test.browser` block is only required for screenshots. If you only capture snapshots, you can omit it — the plugin still uploads your snapshots to Argos.
{% endhint %}
{% endstep %}
{% step %}
### Capture screenshots and snapshots
Use the `argosScreenshot` helper to capture a screenshot in a **browser** test:
{% code title="Button.test.tsx" %}
```tsx
import { test } from "vitest";
import { render } from "vitest-browser-react";
import { argosScreenshot } from "@argos-ci/vitest";
import { Button } from "./Button";
test("Button", async () => {
render();
await argosScreenshot("button");
});
```
{% endcode %}
{% hint style="info" %}
Unlike other Argos SDKs, `argosScreenshot` takes no `page` argument here — Vitest browser tests already run in the page context. The name is optional too: omit it and Argos derives one from the current test.
{% endhint %}
Use `argosSnapshot` to capture a snapshot of any value — it works in **browser and Node** tests, no browser required. The value comes first and the name is optional (omit it to auto-name from the current test, or pass `options.name`). Strings are written verbatim; any other value is serialized automatically:
{% code title="user.test.ts" %}
```ts
import { test } from "vitest";
import { argosSnapshot } from "@argos-ci/vitest";
import { fetchUser } from "./api";
test("API response", async () => {
const user = await fetchUser();
await argosSnapshot(user); // -> "src/user.test.ts > API response 1"
});
```
{% endcode %}
{% hint style="success" %}
`argosSnapshot` lets you visually diff **anything**, not just UI — API responses, generated HTML, config files, Markdown, and more. Pass the `extension` option (e.g. `.json`, `.html`, `.yml`) to control how Argos renders and diffs it. See the [SDK reference](/docs/reference/vitest#capturing-snapshots) for details.
{% endhint %}
Both are written to the `./snapshots` directory by default. Add `./snapshots` to your `.gitignore` file to avoid committing them.
Tip: Check out our guides to [capture multiple viewports](/docs/learn/how-to-guides/visual-coverage/responsive-viewports) or [add ARIA snapshots](/docs/learn/how-to-guides/visual-coverage/adding-aria-snapshots-manually).
{% endstep %}
{% step %}
### Set up CI
Run your Vitest tests in CI with `ARGOS_TOKEN` set. The Argos plugin uploads screenshots automatically when `uploadToArgos` is enabled:
{% code title=".github/workflows/argos.yml" %}
```yaml
name: Argos
on:
pull_request:
push:
branches:
- main
jobs:
argos:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- uses: actions/setup-node@v6
- run: npm ci
- run: npx playwright install --with-deps chromium
- run: npx vitest run
env:
ARGOS_TOKEN: ${{ secrets.ARGOS_TOKEN }}
```
{% endcode %}
`ARGOS_TOKEN` is the project token from **Settings → General → Token**. On GitHub Actions, you can also use [OIDC or tokenless authentication](/docs/learn/integrations/github-actions-authentication) to avoid managing a secret. On other CI providers, pass the token with the `ARGOS_TOKEN` environment variable or the plugin's `token` option.
{% endstep %}
{% endstepper %}
### You're all set
Push your changes and open a pull request — the Argos check appears on it once the build is uploaded. Review the visual changes, approve or reject them, and merge with confidence.
{% hint style="info" %}
Argos needs a baseline to compare against. Until a build runs on your default branch, pull request builds are marked as [orphan](/docs/learn/platform-fundamentals/baseline-build#orphan-builds). Merge this setup or run the workflow once on your default branch to establish the baseline.
{% endhint %}
### Next steps
* [Stabilize screenshots](/docs/learn/reliability-and-flakiness/flaky-tests) – Prevent flaky diffs before they reach your pull requests
* [Vitest SDK reference](/docs/reference/vitest) – All options, including `argosSnapshot`
* [Vitest browser mode documentation](https://vitest.dev/guide/browser/) – Vitest's own browser testing guide
***
Need help? [Join our Discord](https://argos-ci.com/discord), [open an issue on GitHub](https://github.com/argos-ci/argos/issues), or [send us an email](mailto:contact@argos-ci.com).
# Storybook Quickstart
Set up Argos with Storybook and Vitest to get visual testing and live deployment URLs on every pull request.
Set up Argos with [Storybook](https://storybook.js.org/) to get **visual testing** and **live deployment URLs** on every pull request. By the end of this guide, every pull request will:
* Run visual tests on your stories with Vitest.
* Deploy your Storybook to a unique URL you can share with your team.
{% hint style="info" %}
If you use Test Runner instead of Vitest, follow the [Storybook Test Runner Quickstart](/docs/quickstart/storybook-quickstart/storybook-test-runner-quickstart).
If you use a legacy version of Storybook (\ {
// Captures a screenshot of the current story and uploads it to Argos
await argosScreenshot(ctx, "example-screenshot");
},
};
```
{% endcode %}
Screenshots are written to the `./screenshots` directory. Add `./screenshots` to your `.gitignore` file to avoid committing them.
{% endstep %}
{% step %}
### Set up CI
Add a workflow that runs your visual tests **and** deploys your Storybook on every pull request. Argos serves the built Storybook on a unique URL — no extra hosting required:
{% code title=".github/workflows/argos.yml" %}
```yaml
name: Argos
on:
pull_request:
push:
branches:
- main
jobs:
argos:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- uses: actions/setup-node@v6
- run: npm ci
# Run visual tests
- run: npx playwright install --with-deps chromium
- run: npx vitest run --project=storybook
env:
ARGOS_TOKEN: ${{ secrets.ARGOS_TOKEN }}
# Build and deploy the Storybook
- run: npm run build-storybook
- run: npx --no-install argos deploy ./storybook-static
env:
ARGOS_TOKEN: ${{ secrets.ARGOS_TOKEN }}
```
{% endcode %}
`ARGOS_TOKEN` is the project token from **Settings → General → Token**. On GitHub Actions, you can also use [OIDC or tokenless authentication](/docs/learn/integrations/github-actions-authentication) to avoid managing a secret.
For other CI providers, follow [Use deployments in CI](/docs/learn/deployments/use-deployments-in-ci).
{% endstep %}
{% endstepper %}
### You're all set
Push your changes and open a pull request — the Argos check appears on it once the build is uploaded, along with a link to your deployed Storybook. Review the visual changes, approve or reject them, and merge with confidence.
{% hint style="info" %}
Argos needs a baseline to compare against. Until a build runs on your default branch, pull request builds are marked as [orphan](/docs/learn/platform-fundamentals/baseline-build#orphan-builds). Merge this setup or run the workflow once on your default branch to establish the baseline.
{% endhint %}
### Next steps
* [Stabilize screenshots](/docs/learn/reliability-and-flakiness/flaky-tests) – Prevent flaky diffs before they reach your pull requests
* [Storybook story modes](/docs/learn/how-to-guides/visual-coverage/storybook-story-modes) – Capture stories in multiple themes and viewports
* [Storybook SDK reference](/docs/reference/storybook) – All options and helpers
* [Storybook + Vitest example](https://github.com/argos-ci/argos-javascript/tree/main/examples/storybook-vitest) – A complete working setup
***
Need help? [Join our Discord](https://argos-ci.com/discord), [open an issue on GitHub](https://github.com/argos-ci/argos/issues), or [send us an email](mailto:contact@argos-ci.com).
# Storybook Test Runner Quickstart
Set up visual testing in Storybook with Test Runner and the Argos CLI.
Set up Argos with [Storybook Test Runner](https://storybook.js.org/docs/writing-tests/integrations/test-runner) to run visual tests on every pull request: capture a screenshot of each story during the test run, then upload them with the Argos CLI.
{% hint style="info" %}
If you use Vitest instead of Test Runner, follow the [Storybook Quickstart](/docs/quickstart/storybook-quickstart).
If you use a legacy version of Storybook (\ --outDir ./screenshots
```
If it isn't deployed, build and serve it before capturing:
```bash
# Build Storybook
npm exec -- storybook build --output-dir ./storybook-static
# Screenshot Storybook with Storycap
npm exec -- storycap --serverCmd "npx http-server ./storybook-static --port 6006" http://127.0.0.1:6006/ --outDir ./screenshots
```
Read the [Storycap documentation](https://github.com/reg-viz/storycap) for advanced usage.
Screenshots are written to the `./screenshots` directory. Add `./screenshots` to your `.gitignore` file to avoid committing them.
{% endstep %}
{% step %}
### Set up CI
Add a workflow that captures the screenshots and uploads them to Argos. If you use another CI provider, adapt the steps accordingly:
{% code title=".github/workflows/argos.yml" %}
```yaml
name: Argos
on:
pull_request:
push:
branches:
- main
jobs:
argos:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- uses: actions/setup-node@v6
- run: npm ci
- name: Build Storybook
run: npm exec -- storybook build --output-dir ./storybook-static
- name: Capture screenshots with Storycap
run: npm exec -- storycap --serverCmd "npx http-server ./storybook-static --port 6006" http://127.0.0.1:6006/ --outDir ./screenshots
- name: Upload screenshots to Argos
run: npm exec -- argos upload ./screenshots
env:
ARGOS_TOKEN: ${{ secrets.ARGOS_TOKEN }}
```
{% endcode %}
`ARGOS_TOKEN` is the project token from **Settings → General → Token**. On GitHub Actions, you can also use [OIDC or tokenless authentication](/docs/learn/integrations/github-actions-authentication) to avoid managing a secret.
{% endstep %}
{% endstepper %}
### You're all set
Push your changes and open a pull request — the Argos check appears on it once the build is uploaded. Review the visual changes, approve or reject them, and merge with confidence.
{% hint style="info" %}
Argos needs a baseline to compare against. Until a build runs on your default branch, pull request builds are marked as [orphan](/docs/learn/platform-fundamentals/baseline-build#orphan-builds). Merge this setup or run the workflow once on your default branch to establish the baseline.
{% endhint %}
### Next steps
* [Stabilize screenshots](/docs/learn/reliability-and-flakiness/flaky-tests) – Prevent flaky diffs before they reach your pull requests
* [CLI reference](/docs/reference/argos-command-line-interface-cli) – All upload options
* [Storybook legacy example](https://github.com/argos-ci/argos-javascript/tree/main/examples/storybook-legacy) – A complete working setup
***
Need help? [Join our Discord](https://argos-ci.com/discord), [open an issue on GitHub](https://github.com/argos-ci/argos/issues), or [send us an email](mailto:contact@argos-ci.com).
# Cypress Quickstart
Set up visual testing in your Cypress tests with the Argos Cypress SDK.
Set up Argos with [Cypress](https://www.cypress.io/) to run visual tests on every pull request: install the SDK, register the command and task, capture screenshots, and run it in CI.
### Prerequisites
* [Cypress](https://docs.cypress.io/guides/getting-started/installing-cypress) set up in your project
* [Cypress running on your CI](https://learn.cypress.io/advanced-cypress-concepts/running-cypress-in-ci)
* [A project created in Argos](https://app.argos-ci.com/new)
{% stepper %}
{% step %}
### Install
Install the Argos Cypress SDK:
{% tabs %}
{% tab title="npm" %}
```
npm i --save-dev @argos-ci/cypress
```
{% endtab %}
{% tab title="yarn" %}
```
yarn add --dev @argos-ci/cypress
```
{% endtab %}
{% tab title="pnpm" %}
```
pnpm add --save-dev @argos-ci/cypress
```
{% endtab %}
{% tab title="bun" %}
```
bun add --dev @argos-ci/cypress
```
{% endtab %}
{% endtabs %}
{% endstep %}
{% step %}
### Set up Argos in your Cypress config
Two pieces wire Argos into Cypress: the support file adds the `cy.argosScreenshot` command, and the task uploads the captured screenshots.
Add the command to your `cypress/support/e2e.js` file:
{% code title="cypress/support/e2e.js" %}
```js
import "@argos-ci/cypress/support";
```
{% endcode %}
If you use TypeScript, add the types to your `tsconfig.json`:
{% code title="tsconfig.json" %}
```json
{
"compilerOptions": {
"types": ["cypress", "@argos-ci/cypress/support"]
}
}
```
{% endcode %}
Then register the Argos task in your Cypress config:
{% code title="cypress.config.js" %}
```js
const { defineConfig } = require("cypress");
const { registerArgosTask } = require("@argos-ci/cypress/task");
module.exports = defineConfig({
// setupNodeEvents can also be defined in "component"
e2e: {
async setupNodeEvents(on, config) {
registerArgosTask(on, config, {
// Upload to Argos on CI only.
uploadToArgos: !!process.env.CI,
});
// include any other plugin code...
},
},
});
```
{% endcode %}
{% endstep %}
{% step %}
### Capture screenshots
Use the `cy.argosScreenshot` command to capture stable screenshots in your tests:
{% code title="cypress/e2e/homepage.cy.js" %}
```js
it("screenshot homepage", () => {
cy.visit("http://localhost:3000/");
cy.argosScreenshot("homepage");
});
```
{% endcode %}
Screenshots are written to the `/cypress/screenshots` directory. Add `/cypress/screenshots` to your `.gitignore` file to avoid committing them.
Tip: Check out our guides to [screenshot multiple pages](/docs/learn/how-to-guides/visual-coverage/capture-screenshots-from-urls) or [capture multiple viewports](/docs/learn/how-to-guides/visual-coverage/responsive-viewports).
{% endstep %}
{% step %}
### Set up CI
Run your Cypress tests in CI with `ARGOS_TOKEN` set. The Argos task uploads screenshots automatically when it detects a CI environment:
{% code title=".github/workflows/argos.yml" %}
```yaml
name: Argos
on:
pull_request:
push:
branches:
- main
jobs:
argos:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- uses: actions/setup-node@v6
- run: npm ci
- name: Run Cypress tests
uses: cypress-io/github-action@v6
with:
start: npm start # command that serves your app
env:
ARGOS_TOKEN: ${{ secrets.ARGOS_TOKEN }}
```
{% endcode %}
`ARGOS_TOKEN` is the project token from **Settings → General → Token**. On GitHub Actions, you can also use [OIDC or tokenless authentication](/docs/learn/integrations/github-actions-authentication) to avoid managing a secret. On other CI providers, pass the token with the `ARGOS_TOKEN` environment variable or the task's `token` option.
{% endstep %}
{% endstepper %}
### You're all set
Push your changes and open a pull request — the Argos check appears on it once the build is uploaded. Review the visual changes, approve or reject them, and merge with confidence.
{% hint style="info" %}
Argos needs a baseline to compare against. Until a build runs on your default branch, pull request builds are marked as [orphan](/docs/learn/platform-fundamentals/baseline-build#orphan-builds). Merge this setup or run the workflow once on your default branch to establish the baseline.
{% endhint %}
### Next steps
* [Stabilize screenshots](/docs/learn/reliability-and-flakiness/flaky-tests) – Prevent flaky diffs before they reach your pull requests
* [Cypress SDK reference](/docs/reference/cypress) – All options and helpers
* [Cypress example](https://github.com/argos-ci/argos-javascript/tree/main/examples/cypress) – A complete working setup
***
Need help? [Join our Discord](https://argos-ci.com/discord), [open an issue on GitHub](https://github.com/argos-ci/argos/issues), or [send us an email](mailto:contact@argos-ci.com).
# WebdriverIO Quickstart
Set up visual testing in your WebdriverIO tests with the Argos WebdriverIO SDK.
Set up Argos with [WebdriverIO](https://webdriver.io/), the Node.js test automation framework for web and mobile applications, to run visual tests on every pull request: capture screenshots with the SDK, then upload them with the Argos CLI.
### Prerequisites
* [WebdriverIO](https://webdriver.io/) set up in your project
* [WebdriverIO running on your CI](https://webdriver.io/docs/automationProtocols/)
* [A project created in Argos](https://app.argos-ci.com/new)
{% stepper %}
{% step %}
### Install
Install the Argos CLI and the Argos WebdriverIO SDK:
{% tabs %}
{% tab title="npm" %}
```
npm i --save-dev @argos-ci/cli @argos-ci/webdriverio
```
{% endtab %}
{% tab title="yarn" %}
```
yarn add --dev @argos-ci/cli @argos-ci/webdriverio
```
{% endtab %}
{% tab title="pnpm" %}
```
pnpm add --save-dev @argos-ci/cli @argos-ci/webdriverio
```
{% endtab %}
{% tab title="bun" %}
```
bun add --dev @argos-ci/cli @argos-ci/webdriverio
```
{% endtab %}
{% endtabs %}
No configuration is needed — the SDK works directly in your tests.
{% endstep %}
{% step %}
### Capture screenshots
Use the `argosScreenshot` helper to capture screenshots in your tests:
{% code title="test/specs/homepage.e2e.js" %}
```js
import { browser } from "@wdio/globals";
import { argosScreenshot } from "@argos-ci/webdriverio";
describe("Integration test with visual testing", () => {
it("covers homepage", async () => {
await browser.url("http://localhost:3000");
await argosScreenshot(browser, "homepage");
});
});
```
{% endcode %}
Screenshots are written to the `./screenshots/argos` directory. Add `screenshots/` to your `.gitignore` file to avoid committing them.
{% endstep %}
{% step %}
### Set up CI
Run your WebdriverIO tests in CI, then upload the screenshots to Argos with the CLI:
{% code title=".github/workflows/argos.yml" %}
```yaml
name: Argos
on:
pull_request:
push:
branches:
- main
jobs:
argos:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- uses: actions/setup-node@v6
- run: npm ci
- name: Run WebdriverIO tests
run: npm test
- name: Upload screenshots to Argos
run: npm exec -- argos upload ./screenshots/argos
env:
ARGOS_TOKEN: ${{ secrets.ARGOS_TOKEN }}
```
{% endcode %}
`ARGOS_TOKEN` is the project token from **Settings → General → Token**. On GitHub Actions, you can also use [OIDC or tokenless authentication](/docs/learn/integrations/github-actions-authentication) to avoid managing a secret.
{% endstep %}
{% endstepper %}
### You're all set
Push your changes and open a pull request — the Argos check appears on it once the build is uploaded. Review the visual changes, approve or reject them, and merge with confidence.
{% hint style="info" %}
Argos needs a baseline to compare against. Until a build runs on your default branch, pull request builds are marked as [orphan](/docs/learn/platform-fundamentals/baseline-build#orphan-builds). Merge this setup or run the workflow once on your default branch to establish the baseline.
{% endhint %}
### Next steps
* [Stabilize screenshots](/docs/learn/reliability-and-flakiness/flaky-tests) – Prevent flaky diffs before they reach your pull requests
* [WebdriverIO SDK reference](/docs/reference/webdriverio) – All options
* [CLI reference](/docs/reference/argos-command-line-interface-cli) – All upload options
***
Need help? [Join our Discord](https://argos-ci.com/discord), [open an issue on GitHub](https://github.com/argos-ci/argos/issues), or [send us an email](mailto:contact@argos-ci.com).
# Puppeteer Quickstart
Set up visual testing in your Puppeteer scripts with the Argos Puppeteer SDK.
Set up Argos with [Puppeteer](https://pptr.dev/) to run visual tests on every pull request: capture screenshots with the SDK, then upload them with the Argos CLI.
### Prerequisites
* [Puppeteer](https://pptr.dev/#getting-started) set up in your project
* [A project created in Argos](https://app.argos-ci.com/new)
{% stepper %}
{% step %}
### Install
Install the Argos CLI and the Argos Puppeteer SDK:
{% tabs %}
{% tab title="npm" %}
```
npm i --save-dev @argos-ci/cli @argos-ci/puppeteer
```
{% endtab %}
{% tab title="yarn" %}
```
yarn add --dev @argos-ci/cli @argos-ci/puppeteer
```
{% endtab %}
{% tab title="pnpm" %}
```
pnpm add --save-dev @argos-ci/cli @argos-ci/puppeteer
```
{% endtab %}
{% tab title="bun" %}
```
bun add --dev @argos-ci/cli @argos-ci/puppeteer
```
{% endtab %}
{% endtabs %}
No configuration is needed — the SDK works directly in your scripts.
{% endstep %}
{% step %}
### Capture screenshots
Use the `argosScreenshot` helper to capture stable screenshots in your tests:
{% code title="screenshot.mjs" %}
```js
import puppeteer from "puppeteer";
import { argosScreenshot } from "@argos-ci/puppeteer";
const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.goto("http://localhost:3000");
await argosScreenshot(page, "homepage");
await browser.close();
```
{% endcode %}
Screenshots are written to the `./screenshots/argos` directory. Add `screenshots/` to your `.gitignore` file to avoid committing them.
Tip: Check out our guides to [screenshot multiple pages](/docs/learn/how-to-guides/visual-coverage/capture-screenshots-from-urls) or [capture multiple viewports](/docs/learn/how-to-guides/visual-coverage/responsive-viewports).
{% endstep %}
{% step %}
### Set up CI
Run your Puppeteer tests in CI, then upload the screenshots to Argos with the CLI:
{% code title=".github/workflows/argos.yml" %}
```yaml
name: Argos
on:
pull_request:
push:
branches:
- main
jobs:
argos:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- uses: actions/setup-node@v6
- run: npm ci
- name: Run Puppeteer tests
run: npm test
- name: Upload screenshots to Argos
run: npm exec -- argos upload ./screenshots/argos
env:
ARGOS_TOKEN: ${{ secrets.ARGOS_TOKEN }}
```
{% endcode %}
`ARGOS_TOKEN` is the project token from **Settings → General → Token**. On GitHub Actions, you can also use [OIDC or tokenless authentication](/docs/learn/integrations/github-actions-authentication) to avoid managing a secret.
{% endstep %}
{% endstepper %}
### You're all set
Push your changes and open a pull request — the Argos check appears on it once the build is uploaded. Review the visual changes, approve or reject them, and merge with confidence.
{% hint style="info" %}
Argos needs a baseline to compare against. Until a build runs on your default branch, pull request builds are marked as [orphan](/docs/learn/platform-fundamentals/baseline-build#orphan-builds). Merge this setup or run the workflow once on your default branch to establish the baseline.
{% endhint %}
### Next steps
* [Stabilize screenshots](/docs/learn/reliability-and-flakiness/flaky-tests) – Prevent flaky diffs before they reach your pull requests
* [Puppeteer SDK reference](/docs/reference/puppeteer) – All options and helpers
* [Puppeteer example](https://github.com/argos-ci/argos-javascript/tree/main/examples/puppeteer) – A complete working setup
***
Need help? [Join our Discord](https://argos-ci.com/discord), [open an issue on GitHub](https://github.com/argos-ci/argos/issues), or [send us an email](mailto:contact@argos-ci.com).
# Any test framework
Set up visual testing with any test framework by uploading screenshots with the Argos CLI.
Argos works with any tool that produces screenshots. If your framework has no dedicated Argos SDK, capture screenshots however you like and upload the folder with the Argos CLI.
### Prerequisites
* Your tests capture screenshots into a folder (e.g. `./screenshots`)
* Your tests run on CI
* [A project created in Argos](https://app.argos-ci.com/new)
{% stepper %}
{% step %}
### Install
Install the Argos CLI:
{% tabs %}
{% tab title="npm" %}
```
npm i --save-dev @argos-ci/cli
```
{% endtab %}
{% tab title="yarn" %}
```
yarn add --dev @argos-ci/cli
```
{% endtab %}
{% tab title="pnpm" %}
```
pnpm add --save-dev @argos-ci/cli
```
{% endtab %}
{% tab title="bun" %}
```
bun add --dev @argos-ci/cli
```
{% endtab %}
{% endtabs %}
{% endstep %}
{% step %}
### Set up CI
Run your tests, then upload the screenshots folder to Argos with the CLI:
{% code title=".github/workflows/argos.yml" %}
```yaml
name: Argos
on:
pull_request:
push:
branches:
- main
jobs:
argos:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- uses: actions/setup-node@v6
- run: npm ci
- name: Run tests and capture screenshots
run: npm test
- name: Upload screenshots to Argos
run: npm exec -- argos upload ./screenshots
env:
ARGOS_TOKEN: ${{ secrets.ARGOS_TOKEN }}
```
{% endcode %}
`ARGOS_TOKEN` is the project token from **Settings → General → Token**. On GitHub Actions, you can also use [OIDC or tokenless authentication](/docs/learn/integrations/github-actions-authentication) to avoid managing a secret. On other CI providers, set `ARGOS_TOKEN` as a secret environment variable.
The CLI detects your CI context (commit, branch, pull request) automatically. See the [CLI reference](/docs/reference/argos-command-line-interface-cli) for all options.
{% endstep %}
{% endstepper %}
### You're all set
Push your changes and open a pull request — the Argos check appears on it once the build is uploaded. Review the visual changes, approve or reject them, and merge with confidence.
{% hint style="info" %}
Argos needs a baseline to compare against. Until a build runs on your default branch, pull request builds are marked as [orphan](/docs/learn/platform-fundamentals/baseline-build#orphan-builds). Merge this setup or run the workflow once on your default branch to establish the baseline.
{% endhint %}
### Next steps
* [Stabilize screenshots](/docs/learn/reliability-and-flakiness/flaky-tests) – Prevent flaky diffs before they reach your pull requests
* [CLI reference](/docs/reference/argos-command-line-interface-cli) – All upload options
* [Screenshot metadata](/docs/reference/screenshot-metadata) – Enrich screenshots with context shown on the build page
***
Need help? [Join our Discord](https://argos-ci.com/discord), [open an issue on GitHub](https://github.com/argos-ci/argos/issues), or [send us an email](mailto:contact@argos-ci.com).
# Core concepts
The core concepts behind Argos — builds, baselines, comparisons, and the statuses you see on your pull requests.
Argos turns the screenshots your tests produce into a review signal on your pull requests. This page defines the concepts you'll meet everywhere else in the docs.
### Builds and snapshots
A **build** is the result of one test run: the set of **screenshots** (and other snapshots, like [ARIA snapshots](/docs/learn/platform-fundamentals/how-argos-detects-visual-differences#what-argos-compares) or [text files](/docs/learn/how-to-guides/visual-coverage/compare-non-image-files)) uploaded together from your CI. Each build belongs to a project and is tied to a commit and branch.
A build goes through three stages:
1. **Upload**: Your CI uploads the snapshots, either automatically through an SDK or with the [CLI](/docs/reference/argos-command-line-interface-cli).
2. **Comparison**: Argos picks a [baseline build](/docs/learn/platform-fundamentals/baseline-build) and diffs each snapshot against its counterpart.
3. **Conclusion**: The build concludes with **No changes detected** or **Changes detected**, and Argos reports it to your Git provider as a commit status.
### Build types
Argos assigns each build a type that describes how it is compared:
* **Check**: The standard build on a feature branch — compared against a baseline and awaiting review when changes are detected.
* **Auto-approved**: A build on an [auto-approved branch](/docs/learn/platform-fundamentals/baseline-build#auto-approved-branches) (your default branch by default) — approved automatically so it can serve as a future baseline.
* **Orphan**: A build with [no baseline to compare against](/docs/learn/platform-fundamentals/baseline-build#orphan-builds) — expected for a project's first builds.
* **Skipped**: A build [intentionally marked as skipped](/docs/learn/how-to-guides/ci-pipelines/skipping-a-build) — reports success without screenshots.
### Review
When a build concludes with **Changes detected**, your team [reviews it](/docs/learn/review-workflow/review-a-build): approve the changes to accept them as the new expected state, or reject them to flag a regression. The review outcome updates the commit status on your pull request, so you can [require it before merging](/docs/learn/review-workflow/summary-checks).
### Go deeper
* [How Argos detects visual differences](/docs/learn/platform-fundamentals/how-argos-detects-visual-differences) – The deterministic diff algorithm behind comparisons
* [Baseline build](/docs/learn/platform-fundamentals/baseline-build) – How Argos chooses the build to compare against
* [Build modes](/docs/learn/platform-fundamentals/build-modes) – CI mode and Monitoring mode, and when to use each
Once the concepts are clear, head to the [Review workflow](/docs/learn/review-workflow) to see how builds are reviewed day to day.
# How Argos detects visual differences
Discover how Argos uses deterministic pixel diffing with the odiff library to surface meaningful visual changes.
Argos uses **deterministic pixel diffing**, not AI-based visual comparison. Instead of compensating for flakiness, Argos focuses on eliminating it at the source. This keeps visual tests precise, explainable, and reliable over time.
### What Argos compares
Argos compares the snapshots produced by your tests against their counterparts in the [baseline build](/docs/learn/platform-fundamentals/baseline-build):
* **Screenshots** — rendered images of your pages, components, or stories.
* **ARIA snapshots** — text representations of your page's accessibility tree, captured by the [Playwright SDK](/docs/reference/playwright#aria-snapshots), that catch regressions invisible in pixels.
* **Text files** — any [non-image file](/docs/learn/how-to-guides/visual-coverage/compare-non-image-files) you upload, such as JSON or Markdown, diffed as text.
For each pair, the question Argos answers is intentionally simple: did it change, or not? No interpretation, no probability, no guesswork.
### The diff algorithm
Argos relies on the open-source [**odiff** library](https://github.com/dmtrKovalenko/odiff) by Dmitriy Kovalenko. The full diff implementation is also open source — you can [inspect it here](https://github.com/argos-ci/argos/blob/main/apps/backend/src/screenshot-diff/diff/image/index.ts).
Each comparison runs in four stages:
1. **Image normalization**: Resolution, color space, and alpha channels are aligned.
2. **Multiple diff passes**: Each pass uses different thresholds to detect both strict and subtle changes.
3. **Pixel clustering**: Random noise is separated from meaningful visual changes.
4. **Final diff output**: A diff mask and score are produced.
Running multiple passes lets Argos stay strict while remaining resilient to minor, explainable noise.
When at least one snapshot differs from the baseline, the build concludes with **Changes detected** and the diffs await [review](/docs/learn/review-workflow/review-a-build). When every snapshot matches, the build concludes with **No changes detected** and the commit status passes.
### Why pixel diffing instead of AI
Some tools use AI or ML models to decide whether a change is acceptable. Argos intentionally does not: AI compensates for flakiness, while Argos removes it. AI-based approaches often hide small changes without clear explanations, mask rendering inconsistencies, and blur the line between what changed and what was approved — which leads to silent regressions and declining trust in the test suite.
Deterministic pixel diffing has the properties that matter in CI:
* **Deterministic**: Same input, same result.
* **Explainable**: The exact pixels that changed are visible.
* **Review-friendly**: Reviewers assess facts, not model guesses.
* **Auditable**: Approvals have a clear meaning.
And because the diff engine is open source, there is no black box and no hidden thresholds — visual testing should be infrastructure, not magic.
### Flakiness is a signal
A flaky visual test usually points to an underlying problem: non-deterministic animations, time-dependent rendering, uncontrolled fonts, async layout shifts, or environment-specific rendering differences. Argos treats flakiness as **technical debt to fix**, not noise to ignore.
Argos gives you the tools for both sides of the problem: [flaky test detection](/docs/learn/reliability-and-flakiness/flaky-test-detection) identifies unstable screenshots automatically, and the [stabilization playbook](/docs/learn/reliability-and-flakiness/flaky-tests) helps you fix them at the source.
# Baseline build
Argos compares screenshots to a chosen baseline build, determined by analyzing the commit history of your Git project.
A **baseline build** is the reference point Argos compares a new build against to detect visual changes. For every new build, Argos looks through the candidate builds in your project and picks the most relevant one.
{% hint style="info" %}
This page covers CI mode, where the baseline comes from your Git history. In [Monitoring mode](/docs/learn/platform-fundamentals/build-modes#monitoring-mode), Argos ignores Git history and compares against the latest approved build instead.
{% endhint %}
### How Argos selects the baseline
Argos selects the baseline by finding the most recent build that satisfies two sets of criteria.
**Criteria on the candidate build itself:**
* **It is complete.** Argos has finished processing it.
* **Its tests passed.** None of the tests that produced the screenshots failed.
* **It is not a** [**subset**](/docs/learn/how-to-guides/ci-pipelines/subset-builds)**.** It uploaded the full set of snapshots.
* **It has no active rejection.** A build whose changes were rejected (and the rejection not [dismissed](/docs/learn/review-workflow/review-a-build)) can never serve as a baseline, whatever its type.
* **It is approved.** It is an auto-approved build, an [orphan](#orphan-builds), or a check build with an approved review or a merged pull request.
**Criteria relative to the new build:**
* **Same build name and mode.** Only builds with the same [build name](/docs/learn/how-to-guides/ci-pipelines/monorepos-setup) and [build mode](/docs/learn/platform-fundamentals/build-modes) are considered.
* **Commit ancestry.** The candidate's commit must be an ancestor of the **merge base** — the closest common commit between your branch and the baseline branch. In practice, this means the baseline reflects the code your branch actually started from.
### Check whether a build can be a baseline
Every completed build shows whether it's **eligible to become a baseline** for future builds. Look for the baseline-eligibility chip next to the build status on the build page, in the [Builds list](/docs/learn/review-workflow/builds-list), and in the build's **Info** panel:
* **Eligible as baseline** — "This build is eligible to be used as a baseline by future builds."
* **Not eligible as baseline** — "This build is not eligible to be used as a baseline by future builds."
When a build isn't eligible, the **Baseline eligibility** section of the Info panel lists which criteria it failed to meet.
{% hint style="info" %}
The chip appears once a build is complete, and it reflects the build on its own. The comparison-dependent criteria — matching build name, mode, and commit ancestry — depend on the build being compared, so Argos evaluates them when a new build looks for its baseline.
{% endhint %}
### The baseline branch
The **baseline branch** is the branch Argos uses as the reference when resolving the merge base:
* For pull request builds, the base branch of the pull request is used.
* For push events, Argos uses the default baseline branch configured in your project.
{% hint style="info" %}
By default, the repository's default branch is used as the baseline branch. You can change this in the Argos project settings.
{% endhint %}
### Auto-approved branches
Builds on **auto-approved branches** are approved automatically, so they can serve as baselines without a manual review. Branches are matched by pattern (e.g., `main`, `master`, or `develop`).
{% hint style="info" %}
By default, Argos auto-approves your default baseline branch. You can configure auto-approved branch patterns in the Argos project settings.
{% endhint %}
### Configure branches in project settings
In the project settings, you can configure both the default baseline branch and the auto-approved branch patterns.
### Choose a custom baseline via SDK
To compare against a specific branch or commit instead of the automatically selected baseline, set one of these environment variables in your CI:
* `ARGOS_REFERENCE_BRANCH`: The branch to use as the baseline.
* `ARGOS_REFERENCE_COMMIT`: The commit hash to select a specific baseline build.
### Orphan builds
An **orphan build** is a build for which Argos found no baseline to compare against. This is expected for a project's first builds: once a build on your baseline branch is approved (or auto-approved), subsequent builds find their baseline automatically.
# Build modes
Compare Argos Continuous Integration mode and Monitoring mode to choose the right one for your workflow.
Argos provides two build modes: **Continuous Integration (CI) mode** and **Monitoring mode**. They differ in one thing — how the baseline is chosen. CI mode follows your Git history to review changes branch by branch; Monitoring mode ignores Git history and tracks drift against the latest approved state.
### CI mode
CI mode is the default. It is designed to review the visual changes introduced by a feature branch and prevent regressions from merging.
On each pull request and on your default branch, your tests capture screenshots and upload them to Argos. Argos compares them against the [baseline build](/docs/learn/platform-fundamentals/baseline-build) selected from your Git history, and reports the result on the pull request.
{% hint style="info" %}
Your CI pipeline must also run on the default branch (main, production, etc.) to keep the baseline up to date.
{% endhint %}
#### Workflow
{% stepper %}
{% step %}
### Develop
A developer creates a feature (or bugfix) branch, commits changes, and opens a pull request.
{% endstep %}
{% step %}
### Capture and upload
During CI, your test framework captures screenshots of the app. At the end of the tests, the [Argos SDK](/docs/reference/playwright) uploads them automatically — or you upload them with the [CLI](/docs/reference/argos-command-line-interface-cli).
{% endstep %}
{% step %}
### Compare
Argos determines the [baseline build](/docs/learn/platform-fundamentals/baseline-build) from your Git history and compares each new screenshot against it.
{% endstep %}
{% step %}
### Report
Once all screenshots are compared, the build concludes:
* **No changes detected** — the commit status passes.
* **Changes detected** — the commit status asks for review, and the diffs are ready in Argos.
Argos posts the status to your Git provider, along with a [pull request comment](/docs/learn/review-workflow/pull-request-comments) on GitHub. If your branch protection requires the Argos check, the pull request is blocked until the changes are reviewed.
{% endstep %}
{% step %}
### Review
The team [reviews the build](/docs/learn/review-workflow/review-a-build): approve intended changes or reject regressions. The commit status updates accordingly, and approved builds become eligible as future baselines.
{% endstep %}
{% endstepper %}
#### When to use CI mode
* **Pull request validation**: Block merging until visual changes are reviewed and approved.
* **Default branch verification**: Validate every merge so the baseline stays trustworthy.
* **Continuous feedback**: Surface regressions commit by commit, where developers work.
CI mode is enabled by default — follow the [Quickstart](/docs/quickstart) to set it up.
### Monitoring mode
Monitoring mode is **opt-in**. It is designed to track visual changes outside the standard CI flow — on a schedule, before a release, or after a deployment.
In this mode, your tests capture screenshots on a chosen branch (e.g., `main` or a release branch). Argos compares them **only against the latest approved build**: Git history is ignored, and the approval status alone defines the baseline.
#### Workflow
{% stepper %}
{% step %}
### Run on a schedule
Your tests capture screenshots on the target branch — daily, weekly, or before a release.
{% endstep %}
{% step %}
### Compare with the latest approved build
Argos compares the screenshots against the most recently approved monitoring build.
{% endstep %}
{% step %}
### Get notified and review
If differences are found, Argos notifies you — enable [Slack notifications](/docs/learn/integrations/slack-integration#set-up-slack-notifications) to alert your team immediately. Review the changes, then approve them or fix the regression.
{% endstep %}
{% endstepper %}
#### Commit statuses in Monitoring mode
Monitoring builds report to your Git provider exactly like CI builds: Argos posts a [commit status](/docs/learn/integrations/github-integration#commit-status-names) (`argos`, or `argos/`) on the commit the screenshots were captured from — including on a pull request, if the commit belongs to one. When changes are detected, the status is **failure** with the description "waiting for your decision"; it turns to **success** once the build is approved.
The difference with CI mode is auto-approval: a CI build on an auto-approved branch (such as your default branch, outside a pull request) passes automatically, while a monitoring build is never auto-approved — a detected change always waits for a review.
#### When to use Monitoring mode
* **Regular health checks**: Catch unexpected changes on a schedule when running CI on every change isn't practical.
* **Pre-release validation**: Confirm no regressions slipped in before a major release.
* **Post-deployment monitoring**: Detect environment-specific issues after staging or production deployments.
* **Third-party integrations**: Ensure external widgets or services that change independently remain visually stable.
#### Enable Monitoring mode
Set the mode in your SDK configuration or pass `--mode=monitoring` to the CLI:
{% tabs %}
{% tab title="CLI" %}
```bash
npm exec -- argos upload --mode=monitoring ./screenshots
```
{% endtab %}
{% tab title="Playwright" %}
{% code title="playwright.config.ts" %}
```ts
import { defineConfig } from "@playwright/test";
import { createArgosReporterOptions } from "@argos-ci/playwright/reporter";
export default defineConfig({
reporter: [
process.env.CI ? ["dot"] : ["list"],
[
"@argos-ci/playwright/reporter",
createArgosReporterOptions({
uploadToArgos: !!process.env.CI,
mode: "monitoring",
}),
],
],
});
```
{% endcode %}
{% endtab %}
{% tab title="Cypress" %}
{% code title="cypress.config.js" %}
```js
const { defineConfig } = require("cypress");
const { registerArgosTask } = require("@argos-ci/cypress/task");
module.exports = defineConfig({
e2e: {
async setupNodeEvents(on, config) {
registerArgosTask(on, config, {
uploadToArgos: !!process.env.CI,
mode: "monitoring",
});
},
},
});
```
{% endcode %}
{% endtab %}
{% endtabs %}
{% hint style="info" %}
Builds in different modes never share baselines: a monitoring build is only ever compared against another monitoring build.
{% endhint %}
# Review workflow
Bring Argos visual changes into your review process across the dashboard, pull requests, and status checks.
Once your builds run, Argos brings visual changes into your everyday review process — in the dashboard, on your pull requests, and through your status checks.
* [Builds list](/docs/learn/review-workflow/builds-list) – Browse, filter, and open the builds for a project
* [Review a build](/docs/learn/review-workflow/review-a-build) – Request reviewers, comment on exactly what changed, and approve or reject together
* [Pull request comments](/docs/learn/review-workflow/pull-request-comments) – The comment Argos posts on each pull request with the latest build status
* [Summary checks](/docs/learn/review-workflow/summary-checks) – The commit status checks Argos reports back to your Git provider
* [Tags](/docs/learn/review-workflow/tags) – Filter screenshots by tag to focus your review
* [Review builds with AI agents](/docs/learn/review-workflow/review-builds-with-ai-agents) – Let an AI agent triage visual changes from your assistant or CI
* [Automations](/docs/learn/review-workflow/automations) – Rules that react to build events and notify Slack, Microsoft Teams, or Discord
# Builds list
Browse, filter, and open builds for a project to scan status and drill into the runs you care about in Argos.
The Builds list is the main view for tracking every Argos build in a project. It helps you scan status, drill into a specific build, and filter down to exactly the runs you care about.
*A project Builds list with status badges, change counts, and filters*
### Open the Builds list
1. Open your project in Argos.
2. Select the **Builds** tab.
### What each row shows
Each row represents a single build:
* **Build number and status** — for example **Auto-approved**, **Changes approved**, **Changes detected**, or **Changes rejected**.
* **Change counts** — changes, additions, and removals when applicable.
* **Pull request metadata** when the build is linked to a PR.
* **Branch and commit** information.
* **Timestamp** for when the build was created.
### Filters
Use the filters at the top of the page to narrow the list:
* **Type**: Filter by [build type](/docs/learn/platform-fundamentals#build-types) — check, orphan, or auto-approved builds.
* **Status**: Filter by review state — approved, changes detected, or rejected.
* **Build name**: Filter to a specific build name when your CI [splits builds](/docs/learn/how-to-guides/ci-pipelines/monorepos-setup).
Build names in the filter are sourced from builds created in the **last month**. Builds can't be deleted, but unused build names drop out of the filter list after about a month of inactivity.
### FAQ
Can I delete a build?
No. Builds are immutable records and cannot be deleted.
Why did a build name disappear from the filter?
The build name list only includes names used in builds created within the last month. If a build name has no recent activity, it no longer appears.
# Review a build
Review visual changes as a team — request reviewers, comment on the exact pixel or line that changed, discuss in threads, and approve or reject in real time.
When a build detects visual changes, the build page is where your team decides what to do with them. Reviewing a build is collaborative: request the people you need, leave comments pinned to exactly what changed, discuss in threads, and approve or reject — with everything updating in real time.
Every reviewer's decision counts on its own, so a build reflects your whole team's input rather than just the last person to weigh in.
### Open a build
You can open a build from several places:
* The [Builds list](/docs/learn/review-workflow/builds-list) in your project.
* The [pull request comment](/docs/learn/review-workflow/pull-request-comments) Argos posts on your PR.
* The [Argos status check](/docs/learn/review-workflow/summary-checks) on your commit or pull request.
The build page shows each screenshot with its **baseline** (the reference) next to the **changes** (the new screenshot), and highlights the visual diff between them. See [How Argos detects visual differences](/docs/learn/platform-fundamentals/how-argos-detects-visual-differences) for how the diff is computed, and use [Tags](/docs/learn/review-workflow/tags) to filter the screenshot list down to what you care about.
### Compare baseline and changes
The diff viewer offers several ways to compare a snapshot:
* **Split view** — baseline and changes side by side. This is the default.
* **Single view** — one image at a time, switching between **Baseline** and **Changes**.
* **Changes overlay** — changed pixels are highlighted with a red overlay. Toggle it on and off, and customize its color and opacity from the toolbar.
* **Highlight and navigate changes** — flash the changed regions and jump from one to the next.
* **Fit or expand** — fit the screenshot to the screen or inspect it at full size; zoom and pan stay in sync between the baseline and changes panes.
* **ARIA view** — when a snapshot has an [ARIA snapshot](/docs/learn/how-to-guides/visual-coverage/adding-aria-snapshots-manually), switch between the screenshot and its accessibility tree.
### Keyboard shortcuts
Press `?` on a build page to see the full list of shortcuts. The ones you'll use most while reviewing:
| Shortcut | Action |
| --------- | ----------------------------------------- |
| `↑` / `↓` | Go to the previous / next snapshot |
| `←` / `→` | Show only the baseline / only the changes |
| `S` | Toggle side-by-side view |
| `D` | Toggle the changes overlay |
| `H` | Highlight the changed regions |
| `J` / `K` | Go to the previous / next change |
| `Space` | Toggle fit to screen |
| `Y` / `N` | Mark a change as accepted / rejected |
| `I` | Ignore a flaky change |
| `C` | Toggle the comment tool |
| `↵` | Open the review popover |
### Request reviewers
Use the **Reviewers** section in the build sidebar to request the people you want to weigh in.
1. In the **Reviewers** section, click the **+** button (**Add reviewer**).
2. Search for and select one or more project members.
You can request several reviewers, add or remove them at any time, and each reviewer's verdict is tracked **individually** — a new review never overwrites someone else's.
Each reviewer shows one of the following states:
| State | Meaning |
| ------------- | ---------------------------------------------------------- |
| **Approved** | The reviewer approved the changes. |
| **Rejected** | The reviewer rejected the changes. |
| **Commented** | The reviewer left feedback without approving or rejecting. |
| **Pending** | The reviewer was requested but hasn't reviewed yet. |
| **Dismissed** | The review was dismissed and no longer counts. |
#### How reviews decide the build status
Only each reviewer's **latest** review counts, and dismissed reviews are ignored. The build status follows two rules:
* **One rejection blocks.** If any reviewer's latest review is a rejection, the build is **rejected** — even if others approved.
* **Otherwise, one approval passes.** With no active rejection, a single approval marks the build **approved**.
Comment reviews and pending requests don't affect the outcome. To unblock a rejected build, the rejecting reviewer can submit a new review, or an administrator can dismiss the rejection.
### Submit a review
Open the review popover from the build header and choose one of three actions:
* **Comment** — submit feedback without approving or rejecting.
* **Reject** — reject the changes.
* **Approve** — approve the changes so the build can be merged.
Add an optional summary in the **Add review summary…** field, written in Markdown. A summary is **required** when you submit a neutral **Comment** review.
As you work through a build, a review-progress chip (for example, **2 / 3 reviewed**) tracks how many changes you've reviewed so far.
#### Draft reviews
You don't have to publish each comment as you go. By default, the comments you add while reviewing are gathered into a **pending review** that stays private to you — each shows a **Pending** badge noting "Only you can see this. It becomes visible when you submit your review." When you submit, all of them are published at once and your reviewers are notified together — GitHub-style.
To post a single comment immediately instead of adding it to your pending review, hold **Alt** while submitting (**Post comment**).
Your in-progress comments are saved locally, so you won't lose a thought if you navigate away before submitting.
### Comment on exactly what changed
Comments are pinned to precisely what they're about:
* On a screenshot, click a point to **pin the comment to that exact spot**.
* In a text-based snapshot, select a **line or a range of lines** to attach the comment to those lines.
The snapshot you're viewing is automatically attached to your comment, and you can detach or reattach it without losing what you've written.
Comments are written in **Markdown** and support:
* **`/` slash commands** for quick formatting.
* **@mentions** to notify a teammate.
### Discuss in threads
Any comment can become a conversation:
* **Reply** to a comment to start a thread.
* **React** with emoji — open the **Add reaction** menu on a comment and pick one.
* **Resolve** a thread once the discussion is settled, and **reopen** it if it comes back up.
### Collaborate in real time
Everything on the build page updates live — comments, replies, reactions, resolutions, and review decisions appear as they happen, with no refresh.
**Presence dots** show who else is on the build and whether they're online, and each teammate's user card shows their role and current local time, so you know who's around before you wait on a review.
Review notifications arrive as a single digest rather than one message per action. To control your own notifications for a build, use the subscribe toggle in the **Activity** section of the sidebar.
### Reference a screenshot
Each screenshot pane has a **⋮** actions menu — on both the **baseline** and the **changes** — that makes it easy to reference a screenshot in a pull request or share it with a teammate:
* **Copy link** — copy a direct link to the screenshot.
* **Copy embed as Markdown** — copy the screenshot as a Markdown image embed, ready to paste into a PR description or comment.
* **Download** — download the screenshot. For a changed screenshot you can also download the **diff mask** and the **composed changes** (the diff overlaid on the screenshot).
### Who can review
* Leaving reviews and comments requires a role that can review builds — team **Owners** and **Members**, or **Contributors** assigned the **Project Reviewer** or **Project Administrator** role. The build must also be in a reviewable state (changes detected, approved, or rejected).
* Dismissing another person's review requires an administrator-level role.
See [Team members & roles](/docs/learn/account-and-access/team-members-and-roles) for the full permission breakdown.
### Review from the API
Every review and comment action is also available in the [Argos REST API](https://argos-ci.com/docs/api-reference): submit, list, and dismiss reviews; create, read, update, and delete comments and replies; add and remove reactions; and resolve or reopen threads. Because these actions are attributed to a user and checked against that user's project permissions, they require a **personal access token** rather than a project token.
You can also submit reviews from the [Argos CLI](/docs/reference/argos-command-line-interface-cli#reviewing-and-commenting) with `argos review create`, or let an [AI agent review builds](/docs/learn/review-workflow/review-builds-with-ai-agents) for you.
# Pull request comments
Get the latest Argos build status and a link to the build page posted automatically on your GitHub pull requests.
Argos posts a comment on your GitHub pull requests with the latest build results, so your team sees visual changes without leaving the PR.
Every time a build status updates, Argos updates the comment with the latest status and a link to the build page.
{% hint style="info" %}
Pull request comments are available on GitHub. On GitLab, Argos reports results through [commit statuses](/docs/learn/review-workflow/summary-checks) instead.
{% endhint %}
### What the comment shows
For each build, the comment lists its status, a link to inspect it, and a **Details** column that summarizes the changes — for example `2 added` or `4 changed, 3 ignored`. [Ignored screenshots](/docs/learn/reliability-and-flakiness/flaky-test-detection#ignore-changes) are counted here too, so you can see at a glance how much was filtered out as noise.
If you [deploy with Argos](/docs/learn/deployments), the comment also lists your deployments with their preview URLs.
### Silence pull request comments
To stop the Argos bot from commenting on your pull requests:
1. Go to your project **Settings** in Argos.
2. In the **Connected Git Repository** section, uncheck **Enable pull request comments**.
3. Save the settings.
Argos stops posting build status updates on your pull requests. Re-enable the checkbox at any time to turn them back on.
# Summary checks
Configure Argos summary checks to combine commit statuses into one required status check before merging.
A **summary check** is a single commit status — `argos/summary` — that combines the result of all Argos builds on a commit. When your CI produces several builds (for example, one per app in a monorepo), the summary check gives you one status to glance at, and one status to require.
By default, Argos adds the summary check **only when a commit has more than one build** — a single build keeps its individual status (`argos`, or `argos/` for a named build) with no summary added. See [Commit status names](/docs/learn/integrations/github-integration#commit-status-names) for the exact context of each status Argos posts.
Summary checks are particularly useful as a [required status check before merging](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#require-status-checks-before-merging): require the summary check instead of each individual build check, and the requirement keeps working as you add or rename builds.
### Options
Argos offers three settings for summary checks:
* **Add a summary check only if there is more than one build** — The default, recommended for most projects. The summary check appears when there are multiple builds to combine, and stays out of the way otherwise.
* **Always add a summary check** — The summary check is posted even for a single build. Choose this if you require the summary check in your branch protection and some commits produce only one build — the required check is then always present.
* **Never add a summary check** — Disable summary checks entirely if they don't add value to your workflow.
Summary checks are an additional layer of status reporting — they never replace the individual build statuses.
### Configure summary checks
1. Go to your project **Settings** in Argos.
2. Locate the **Summary Checks** section.
3. Choose the option that fits your project.
4. Select **Save** to apply the changes.
# Tags
Categorize and filter screenshots by tag so you can focus a build review on the changes you care about.
Tags let you categorize screenshots so you can quickly filter a build down to the changes you care about. For example, you might tag screenshots by page area, feature, or test suite and then review only the relevant subset during a build review.
### Filtering by tags in the UI
1. Open a build in Argos.
2. Click the **Filter button**.
3. Select one or more tags to narrow the screenshot list.
4. Once selected, a filter chip appears.
### Where tags come from
Tags can come from two sources in [screenshot metadata](/docs/reference/screenshot-metadata):
| Source | Field | Description |
| -------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Screenshot** | `tags` | Custom tags you define to categorize the screenshot itself. |
| **Test** | `test.tags` | Tags inherited from the test that generated the screenshot (e.g. Playwright [test tags](https://playwright.dev/docs/test-annotations#tag-tests)). |
### Adding custom tags through SDKs
#### Playwright
Playwright test tags are automatically forwarded to Argos. You have several options for how to add tags to your Playwright tests.
import { test } from "@playwright/test";
import { argosScreenshot } from "@argos-ci/playwright";
// Option 1: At the describe level with the @ prefix
test.describe("Homepage @desktop @homepage", () => {
// Option 2: In the test name with the @ prefix
test("homepage @desktop @homepage", async ({ page }) => {
await page.goto("/");
await argosScreenshot(page, "homepage");
});
// Option 3: As a test option
test("homepage", { tag: ["@desktop", "@homepage"] }, async ({ page }) => {
await page.goto("/");
await argosScreenshot(page, "homepage");
});
// Option 4: In the argosScreenshot options
test("homepage", async ({ page }) => {
await page.goto("/");
await argosScreenshot(page, "homepage", {
tags: ["@desktop", "@homepage"],
});
});
});
Read the [Playwright test tags documentation](https://playwright.dev/docs/test-annotations#tag-tests) for more details on how to use test tags in your tests.
#### Cypress
In Cypress, you can add tags to screenshots through the `tags` option in the `cy.argosScreenshot` command.
{% code title="cypress/e2e/homepage.cy.js" %}
```js
it("screenshot homepage", () => {
cy.visit("http://localhost:3000/");
cy.argosScreenshot("homepage", { tags: ["@desktop", "@homepage"] });
});
```
{% endcode %}
#### Puppeteer
In Puppeteer, you can add tags to screenshots through the `tags` option in the `argosScreenshot` function.
{% code title="screenshot.mjs" %}
```js
import puppeteer from "puppeteer";
import { argosScreenshot } from "@argos-ci/puppeteer";
const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.goto("http://localhost:3000/");
await argosScreenshot(page, "homepage", {
tags: ["@desktop", "@homepage"],
});
await browser.close();
```
{% endcode %}
# Review builds with AI agents
Let an AI agent read Argos build data to summarize visual changes, check intent, and approve or request changes.
Argos lets AI agents review visual changes in a pull request. The agent can use Argos build data to understand what changed, check whether the screenshots match the pull request's intent, and detect regressions.
By default, ask the agent to summarize the visual changes first. If you want it to take action, it can also create an Argos build review to approve the changes or request changes.
### What you need
* A pull request with an Argos build.
* The [Argos CLI](/docs/reference/argos-command-line-interface-cli).
* The [Argos agent skills](/docs/agents/agent-skills), when your assistant supports skills.
* An Argos project token to read build data with `build get` and `build snapshots`.
* A user token to create a build review, only if you want the agent to approve or request changes.
### Quick start
{% stepper %}
{% step %}
#### Install the skills
```bash
npx skills add https://argos-ci.com
```
{% endstep %}
{% step %}
#### Set a project token so the agent can read Argos build data
```bash
export ARGOS_TOKEN=
```
{% endstep %}
{% step %}
#### If you want the agent to create the Argos build review from your local CLI session, authenticate as your Argos user
```bash
npx @argos-ci/cli login
```
{% endstep %}
{% step %}
#### Start a new AI chat and give the agent the pull request URL
```
Use $argos-pr-review to review this pull request with its Argos build.
https://github.com/acme/app/pull/123
```
The `$argos-pr-review` skill contains the detailed review workflow. The `$argos-cli` skill gives the agent the CLI commands, flags, authentication rules, and output formats.
{% endstep %}
{% endstepper %}
### What the agent does
The agent will inspect the pull request, find the Argos build from the pull request status check or Argos comment, and use Argos build data to understand the visual changes.
It should first summarize what changed visually. Then it compares the screenshots with the pull request intent.
When the screenshots match the pull request intent, the agent can suggest approving the build. When they reveal a regression, it can suggest requesting changes and explain which snapshots are affected.
If the build is still pending, the agent should wait before reviewing. If there are no visual changes or the build is already accepted, no visual review is needed.
### Other cases
#### If the agent cannot access the pull request
You can provide the Argos build URL and a short description of the expected change:
```
Use $argos-pr-review to review this Argos build:
https://app.argos-ci.com/acme/app/builds/456
Expected change:
The login page was redesigned with social login options.
```
The build data still lets the agent explain what changed visually, but the pull request context makes the review decision stronger.
#### If your assistant does not support skills
Use a more explicit prompt:
```
Review the visual changes in this pull request with Argos:
https://github.com/acme/app/pull/123
Use the pull request title, description, linked issue, and code diff to understand the intended change.
Find the Argos build, fetch the build metadata, and fetch the snapshots that need review.
Use the diff mask, baseline file, current file, and metadata as visual evidence.
First summarize what changed visually in the build.
Then compare the screenshots with the pull request intent.
If the snapshots match the intent, suggest approving the Argos build.
If they reveal a regression, suggest requesting changes and list the affected snapshot names.
If they look flaky, explain the flake signal and do not suggest approval until it is resolved.
```
To let the assistant create the Argos build review, add an explicit instruction. The CLI must be authenticated as an Argos user with `argos login`, or the assistant must pass a personal access token to `argos review create`:
```
After summarizing the visual changes, create an Argos build review with the appropriate conclusion.
```
#### Authentication details
Reading build data requires a project token. Creating a build review requires a user token because the review is attributed to an Argos user and checked against that user's project permissions.
For details about token precedence, `--token`, and personal access tokens, see [Argos CLI authentication](/docs/reference/argos-command-line-interface-cli#authentication).
### Limits
Argos still performs deterministic visual comparison. AI agents use Argos build data as review evidence; they do not replace your team's ownership of review decisions.
# Automations
Create rules that react to build events and notify Slack, Microsoft Teams, or Discord, so nobody has to watch Argos to know a build needs review.
An automation is a rule on a project: **when** something happens to a build, **if** it matches your conditions, **then** Argos notifies a channel. It replaces the person who would otherwise have to notice a build finished and relay it.
### Open the Automations tab
1. Open your project in Argos.
2. Select the **Automations** tab.
Automations are available on team projects, and the tab requires permission to view project settings.
### The three parts of a rule
Step
What it does
When
The build events that trigger the rule. A rule fires if any selected event happens.
If
Optional conditions that must all match for the rule to act.
Then
The actions Argos runs.
### When: build events
* **Build Completed** — the build finished processing, whatever its outcome.
* **Build Reviewed** — someone approved or rejected the build.
### If: conditions
Conditions narrow a rule so it only fires on the builds you care about. Every condition you add must match.
* **Build conclusion** — `no changes` or `changes detected`.
* **Build type** — `reference`, `check`, or `orphan`. See [build types](/docs/learn/platform-fundamentals#build-types).
* **Build mode** — `CI` or `monitoring`. See [build modes](/docs/learn/platform-fundamentals/build-modes).
* **Build name** — an exact build name, useful when your CI [splits builds](/docs/learn/how-to-guides/ci-pipelines/monorepos-setup).
* **Build branch** — an exact branch name, or a glob pattern such as `release/*`.
Each condition can be negated, so you can express "every branch except `main`" as a negated **Build branch** condition.
{% hint style="info" %}
Conditions are combined with AND. To notify on two unrelated cases — say, failures on `main` and anything on `release/*` — create two automations rather than one rule with both conditions.
{% endhint %}
### Then: actions
* **Post in Slack channel** — posts to a Slack channel. Requires the [Slack integration](/docs/learn/integrations/slack-integration).
* **Post in Microsoft Teams channel** — posts an adaptive card to a channel webhook. Requires the [Microsoft Teams integration](/docs/learn/integrations/microsoft-teams-integration).
* **Post in Discord channel** — posts an embed to a channel webhook. Requires the [Discord integration](/docs/learn/integrations/discord-integration).
If the destination isn't connected yet, the action offers the connection flow.
### Create an automation
{% stepper %}
{% step %}
#### Start a new rule
From the **Automations** tab, select **New Automation** and give it a name that says what it does — for example "Notify #frontend when main has changes".
{% endstep %}
{% step %}
#### Choose the events
Under **When**, select one or more build events.
{% endstep %}
{% step %}
#### Narrow it down
Under **If**, add conditions. Skip this step to act on every build that triggers the events.
{% endstep %}
{% step %}
#### Pick the destination
Under **Then**, choose an action and select the channel it posts to.
{% endstep %}
{% step %}
#### Test and save
Send a test notification to confirm the channel receives it, then save the automation.
{% endstep %}
{% endstepper %}
### Common recipes
Tell the team when a build needs review
**When** Build Completed · **If** Build conclusion is `changes detected` and Build type is `check` · **Then** notify your review channel.
This skips builds with no changes and skips reference builds, so the channel only hears about work that actually needs a human.
Watch a release branch only
**When** Build Completed · **If** Build branch matches `release/*` · **Then** notify your release channel.
Close the loop after review
**When** Build Reviewed · **Then** notify the channel where the build was announced, so the thread ends with the outcome.
### FAQ
Why didn't my automation fire?
Check the conditions first: they are combined with AND, so one non-matching condition stops the rule. Then confirm the event you selected is the one that actually happened — a build finishing raises **Build Completed**, not **Build Reviewed**.
Can an automation call my own endpoint?
Not today. Argos has no user-configurable outgoing webhooks — see [Integrations](/docs/learn/integrations#webhooks) for the alternatives, and tell us if webhooks would unblock your workflow.
Do automations apply to every project in my team?
No. Automations are configured per project, so a rule you create on one project doesn't run on the others.
# Reliability & flakiness
Detect unstable tests and use Argos tools and strategies to track and fix flakiness in your visual suite.
Flaky tests fail or change without a meaningful code change and erode trust in your suite. Argos detects unstable screenshots automatically, ranks them so you know where to act, and gives you a playbook to fix the root causes.
* [Flaky test detection](/docs/learn/reliability-and-flakiness/flaky-test-detection) – How Argos flags unstable tests and ignores noisy changes
* [Tests dashboard](/docs/learn/reliability-and-flakiness/tests-dashboard) – A project-wide view that ranks tests by flakiness
* [Test page](/docs/learn/reliability-and-flakiness/test-page) – Everything Argos knows about one test: its metrics, its changes, and its discussion
* [Ignored changes](/docs/learn/reliability-and-flakiness/ignored-changes) – Review what a project ignores and unignore the changes that went quiet
* [Fix flaky tests with AI agents](/docs/learn/reliability-and-flakiness/fix-flaky-tests-with-ai-agents) – Hand a flaky test to an agent and let it find the non-determinism
* [Stabilize screenshots](/docs/learn/reliability-and-flakiness/flaky-tests) – Strategies for writing stable, deterministic visual tests
# Flaky test detection
See flaky badges, stability scores, and detailed history so you can review changed tests in Argos with confidence.
Argos flags unstable tests so you can decide with confidence. See a flaky badge next to every changed test and dive into detailed history and stability scores on a dedicated test page.
*Example of the flaky indicator in a build review*
### View flaky indicators in your build review
1. Open any build in Argos.
2. Spot the flaky badge beside each changed test.
3. Hover over the badge to see details about the test's stability.
### Explore the test page
Select the flaky badge to open the [test page](/docs/learn/reliability-and-flakiness/test-page), which gathers everything Argos knows about that one test: its flakiness score, how its metrics moved over time, every change it produced, the discussion your team had about it, and a prompt to hand to an AI agent.
### See all flaky tests at a glance
The test page focuses on a single test. For a project-wide view that ranks every test by flakiness score, open the [Tests dashboard](/docs/learn/reliability-and-flakiness/tests-dashboard).
### Ignore changes
When reviewing a build in Argos, you may encounter changes that are not relevant or are caused by flakiness. You can **ignore a specific change** directly from the UI.
From the build page or the test page, select the **Ignore** button next to the change you want to ignore.
Once ignored, Argos will no longer notify you if this **exact same change** happens again in future builds. This lets you filter out noise while keeping future regressions detectable.
#### How Argos recognizes the same change
Each visual change carries a **fingerprint**: a stable signature computed from the shape of its diff. Visually similar diffs on the same test produce the same fingerprint, and an ignored change is a test-plus-fingerprint pair — any future diff matching the pair is ignored automatically. The fingerprint absorbs pixel-level noise such as antialiasing but distinguishes genuinely different changes, so ignoring one flaky change never hides a new regression elsewhere in the screenshot. You'll encounter the fingerprint in the [API](https://argos-ci.com/docs/api-reference) and [CLI](/docs/reference/argos-command-line-interface-cli#silencing-a-flaky-change) as part of a change's identity.
Every change a project ignores is listed on the [Ignored changes](/docs/learn/reliability-and-flakiness/ignored-changes) page, with how often each one still fires — so an ignore that outlived its flake doesn't stay a blind spot.
Ignored screenshots are also reflected in the [pull request comment](/docs/learn/review-workflow/pull-request-comments): the **Details** column reports how many screenshots were ignored alongside the other counts (for example, `4 changed, 3 ignored`).
### Configure what Argos ignores
You control the ignore feature per project from **Project Settings → Flaky detection**.
The **Ignore changes** card has a single toggle, **Enable the ignore feature for this project**, which is on by default. When you turn it off:
* New builds ignore nothing — every change is treated as not ignored.
* Auto-ignore is turned off.
* The **Ignore** button is hidden when reviewing builds.
{% hint style="info" %}
Disabling the feature only changes how **new** builds are computed. Previous builds are not affected — changes already ignored stay ignored on those builds.
{% endhint %}
### Automatically ignore recurring flaky changes
When the ignore feature is enabled, Argos can automatically ignore recurring flaky changes across builds, so you don't have to ignore each one by hand.
To configure auto-ignore:
1. Open your project in Argos.
2. Go to **Project Settings → Flaky detection**.
3. In the **Automatically ignore flaky changes** card, enable **Auto-ignore flaky changes**.
4. Set **Minimum occurrences to consider a change flaky (last 7 days)**.
5. Select **Save**.
A change is considered flaky once it appears at least this many times in auto-approved builds within the last 7 days. The default threshold is **3** occurrences.
#### Best use cases
* Flaky UI elements that appear/disappear randomly or render inconsistently.
* Non-deterministic image rendering (e.g. base64 previews, antialiasing issues).
# Tests dashboard
Get a project-wide view of test stability, with every test ranked by flakiness score in the Argos dashboard.
The Tests dashboard gives you a view of test stability ranked by flakiness score, so the most flaky tests show up first. It comes in two scopes: a **project** dashboard for a single project, and an **account** dashboard that aggregates tests across every project you can access.
***A project Tests dashboard with flakiness metrics***
### Open the project dashboard
1. Open your project in Argos.
2. Select the **Tests** tab.
### How tests are ranked
Tests are sorted by **flakiness score** (descending). The tests at the top are the most flaky.
### Columns explained
* **Test**: The latest screenshot uploaded for the test, the test name, and the build name.
* **Last change**: The most recent change detected on an auto-approved build during the selected period.
* **Flakiness**: A score that summarizes how flaky a test is based on its stability and consistency.
* **Changes**: The number of changes detected for the test during the selected period.
* **Stability**: The ratio of changes to total reference builds. A lower stability rate means the test is more likely to be flaky.
* **Consistency**: The ratio of one-off changes to total changes. A lower consistency rate means the test is more likely to be flaky.
### Filter and time range
* Filter tests by **build name** to focus on a subset of runs.
* Choose a **time period** to control which changes and scores are included.
### Open a test page
Select any row to open the [test page](/docs/learn/reliability-and-flakiness/test-page), which breaks the same metrics down over time, lists every change the test produced, and carries its discussion.
### See tests across all your projects
The account-level **Tests** dashboard aggregates the active tests across every project you can see and ranks them by flakiness, so the noisiest tests surface first — wherever they live.
1. Select your account or team in Argos.
2. Select the **Tests** tab.
It shows the same flakiness, stability, and consistency metrics as the project dashboard, plus a **Project** column so you can tell where each test comes from. A test counts as **active** when it appears in the latest reference build for its build name. You only see tests from projects you have access to.
# Test page
Investigate a single test on its own page: flakiness metrics over time, every change it produced, discussion with your team, and a prompt to hand to an AI agent.
The [Tests dashboard](/docs/learn/reliability-and-flakiness/tests-dashboard) tells you *which* tests are flaky. The test page tells you *why*. It gathers everything Argos knows about one test: how often it changed, what those changes looked like, when they started, what your team said about it, and a prompt you can hand to an AI agent to fix it.
*A test page with its metrics and change history*
### Open a test page
Any of these routes get you there:
* From the [Tests dashboard](/docs/learn/reliability-and-flakiness/tests-dashboard), select a row.
* From a build review, select the [flaky badge](/docs/learn/reliability-and-flakiness/flaky-test-detection) next to a changed test.
* From the [Ignored changes](/docs/learn/reliability-and-flakiness/ignored-changes) page, select the test a change belongs to.
The page header shows the test name and its status:
* **Ongoing** — the test still runs. It appeared in the latest build of its build name.
* **Removed** — it did not, so it was deleted, renamed, or skipped.
### Choose the period
Every number and chart on the page is computed over a period you pick at the top: the last 24 hours, 3 days, 7 days, 30 days, or 90 days. It defaults to the last 7 days, and it lives in the URL — so a link you share opens on the same window you were looking at.
Only **auto-approved builds** count. A change on a branch usually means someone changed the UI on purpose; a change on an auto-approved build means the test moved on its own.
### Read the metrics
| Metric | What it means |
| --------------- | --------------------------------------------------------------------------------------- |
| **Flakiness** | An overall score from 0 to 100 derived from stability and consistency. Higher is worse. |
| **Builds** | How many builds ran the test over the period. |
| **Changes** | How many times it changed over the period. |
| **Stability** | The share of builds where it did *not* change. Lower means it changes often. |
| **Consistency** | The share of changes that were one-offs. Lower means the same change keeps coming back. |
The chart beside them breaks the same counts down over time, which is what tells a test that has *always* been flaky apart from one that only started recently. A cliff in the chart usually points at the commit that introduced the instability.
In the sidebar, **First change** and **Last change** link to the builds where the test first and last changed — regardless of the selected period, so you can find the origin of a long-running flake.
### Explore the changes
A **change** is one exact visual difference, not one occurrence of it. Argos groups every diff that looks the same under a single change, so a screenshot flickering between two states is two changes here — however many builds it flickered in. That grouping is what makes a recurring change visible: it's the one with a high occurrence count.
The changes list is ordered by how often each one came back, and every card tells you which kind you're looking at:
* **Recurring — N×** — it came back N times. Nothing in the UI explains a change that reappears, so this is the flakiness signal to chase.
* **One-off** — it happened once. More likely a real, intentional change.
* **Ignored** — Argos skips it when it reappears. See [Ignored changes](/docs/learn/reliability-and-flakiness/ignored-changes).
Select a card to inspect that change: the baseline next to the captured screenshot, its **Occurrences** out of the total build count, and when it was **First seen** and **Last seen**, each linking to the build.
Use the **All** / **Ignored** toggle above the list to switch between every change and only the ignored ones. Like the period, the filter is in the URL.
From the toolbar you can **Ignore** the change you're looking at, exactly as you would from a build review — see [Ignore changes](/docs/learn/reliability-and-flakiness/flaky-test-detection#ignore-changes).
{% hint style="info" %}
Comment pins aren't available in this view. The changes explorer shows a test's history rather than one build's review, so comments belong to the test as a whole — see below.
{% endhint %}
### Discuss the test with your team
The **Activity** section in the sidebar is the test's own conversation, separate from any build review. Use it for what belongs to the test rather than to one run: "this one has been flaky since we added the carousel", "waiting on the upstream fix", "safe to ignore until Q3".
* **Leave a comment** in the composer at the bottom. Comments are written in Markdown, with `/` slash commands for formatting and **@mentions** to notify a teammate.
* **Reply** to a comment to start a thread, **react** with an emoji, and **resolve** a thread once it's settled — reopening it if it comes back.
* The feed opens with when Argos first saw the test, then every thread, oldest first.
Unlike [build comments](/docs/learn/review-workflow/review-a-build#comment-on-exactly-what-changed), a comment on a test posts immediately: there's no pending review to batch it into.
Use the bell in the **Activity** header to **follow** the test and get notified of new comments. Commenting follows it for you.
Leaving comments requires a role that can review — see [Team members & roles](/docs/learn/account-and-access/team-members-and-roles).
### Fix the flakiness with an AI agent
The **Fix with AI** card gives you a prompt to copy into a coding agent working in your repository — Claude Code, Codex, Cursor, or any other. The prompt names the test, carries the flakiness Argos measured, and tells the agent how to pull the recurring changes and their screenshots for itself before it starts editing.
1. Select **Copy prompt**. Use **Preview the prompt** first if you want to read it.
2. Paste it into your agent, in a session that has access to the repository.
The card expands on its own when the test looks flaky. On a stable test there's nothing to fix, so it stays folded into its header — still one click away.
For what the agent needs to authenticate and what to expect from it, see [Fix flaky tests with AI agents](/docs/learn/reliability-and-flakiness/fix-flaky-tests-with-ai-agents).
### Read the same data from the API or CLI
Everything on this page is available outside the UI, so you can script it or hand it to an agent:
```bash
argos test get --json
argos test changes --json
```
See [Inspecting builds and tests](/docs/reference/argos-command-line-interface-cli#inspecting-builds-and-tests) in the CLI reference for what each command returns, and [Reviewing and commenting](/docs/reference/argos-command-line-interface-cli#reviewing-and-commenting) for `test comment`. The same data is available over the [REST API](https://argos-ci.com/docs/api-reference) and the [MCP server](/docs/agents/mcp-server).
# Ignored changes
Review every change your project has ignored, see how much review noise each one absorbs, and unignore the ones that went quiet.
Ignoring a change is easy to do and easy to forget. The **Ignored** tab lists every change a project currently ignores, so you can tell which ignores are still earning their keep and which have become blind spots.
### Open the Ignored tab
1. Open your project in Argos.
2. Select the **Ignored** tab.
The tab only appears when the ignore feature is enabled for the project. See [Configure what Argos ignores](/docs/learn/reliability-and-flakiness/flaky-test-detection#configure-what-argos-ignores).
### What each row shows
Changes are listed most recently ignored first.
* **Change** — the most recent screenshot carrying this change, with the test name and build name. Select the row to open the change on the test page.
* **Ignored** — when the change was ignored and who ignored it. Changes that [auto-ignore](/docs/learn/reliability-and-flakiness/flaky-test-detection#automatically-ignore-recurring-flaky-changes) muted are attributed to the Argos bot and carry an **Auto** badge.
* **Occurrences** — how many auto-approved builds have shown this exact change since it was ignored. This is the review noise the ignore has absorbed.
* **Last seen** — the last build in which this exact change appeared.
### Decide what to unignore
The two right-hand columns are what make the list worth revisiting.
A change with a high **Occurrences** count is doing its job: it would have interrupted a review that many times. A change that hasn't been seen in weeks is the opposite — the flake behind it has probably been fixed, and the ignore is now hiding any genuine regression that happens to produce the same diff.
{% hint style="info" %}
An ignore is scoped to one test and one diff fingerprint, so it never hides a different change to the same screenshot. See [How Argos recognizes the same change](/docs/learn/reliability-and-flakiness/flaky-test-detection#how-argos-recognizes-the-same-change).
{% endhint %}
### Unignore a change
1. Hover the row you want to unignore.
2. Select **Unignore**, then confirm.
Argos treats the change as a change again, so the next build showing it will ask for review. The confirmation offers **Undo** if you change your mind.
Unignoring requires the **review** permission on the project.
### FAQ
Why does a row show 0 occurrences?
The change hasn't reappeared in an auto-approved build since it was ignored. Either the flake stopped, or the change simply hasn't run again. Check **Last seen** to tell the two apart.
Does turning the ignore feature off clear this list?
No. Ignored changes are kept, and the list is still there when you turn the feature back on. While it's off, new builds ignore nothing.
Can I unignore everything at once?
Not from this page — changes are unignored one at a time. You can also unignore a change from the build page or the test page using the same **Ignore** button that set it.
# Fix flaky tests with AI agents
Hand a flaky test to an AI agent: it reads the flakiness metrics and recurring changes from Argos, finds what makes the screenshot unstable, and fixes it in your repository.
Fixing a flaky visual test is mostly investigation: work out which change keeps coming back, look at what moves in the screenshot, then find the non-determinism in the test or the UI. An AI agent working in your repository can do all of it, because Argos exposes the evidence it needs over the CLI, the MCP server, and the REST API.
The [test page](/docs/learn/reliability-and-flakiness/test-page) hands you a prompt that does exactly that.
### What you need
* A flaky test on the [Tests dashboard](/docs/learn/reliability-and-flakiness/tests-dashboard).
* An AI agent with access to the repository that contains the test.
* The [Argos CLI](/docs/reference/argos-command-line-interface-cli), the [MCP server](/docs/agents/mcp-server), or plain HTTP access to the [REST API](https://argos-ci.com/docs/api-reference) — whichever your agent already has.
* A token the agent can read with. A **project token** is enough to read a test and its changes; ignoring a change needs a [personal access token](/docs/reference/argos-command-line-interface-cli#project-tokens-and-personal-access-tokens).
### Quick start
{% stepper %}
{% step %}
#### Open the flaky test
From the [Tests dashboard](/docs/learn/reliability-and-flakiness/tests-dashboard), select the test you want to fix.
{% endstep %}
{% step %}
#### Give the agent a token
```bash
export ARGOS_TOKEN=
```
Skip this if your agent is already connected to the [MCP server](/docs/agents/mcp-server) or signed in with `argos login`.
{% endstep %}
{% step %}
#### Copy the prompt
In the **Fix with AI** card, select **Copy prompt**. It is filled in with this test's id, its measured flakiness, and the calls to make.
{% endstep %}
{% step %}
#### Paste it into your agent
Run it in a session that has your repository checked out, so the agent can find the test and change it.
{% endstep %}
{% endstepper %}
### What the agent does
The prompt walks the agent through the same investigation you would run by hand:
1. **Read the evidence.** It fetches the test's flakiness metrics and its changes, most frequent first, with the diff mask, baseline, and captured screenshot for each.
2. **Look at what moves.** The changes with the highest occurrence count are the flaky ones — a difference that keeps reappearing while nothing in the UI changed.
3. **Find the non-determinism.** It locates the test in your repository from its name and build name, then looks for the usual culprits: animations and transitions still running, dates and times, random or unordered data, fonts or images that haven't loaded, network timing, scrollbars, and text carets.
4. **Fix the root cause.** Waiting for the real end state instead of a fixed delay, freezing the clock and the random source, ordering the data. The prompt asks it to prefer making the UI deterministic over masking the region.
5. **Report back** what was non-deterministic and what it changed.
If a change turns out to be noise that genuinely cannot be made deterministic, the prompt tells the agent to [ignore it](/docs/learn/reliability-and-flakiness/flaky-test-detection#ignore-changes) instead of contorting the test.
{% hint style="info" %}
[Stabilize screenshots](/docs/learn/reliability-and-flakiness/flaky-tests) documents the same fixes for a human reader. It's worth pointing your agent at when it needs the details for a specific framework.
{% endhint %}
### Without the prompt
The prompt is a convenience, not a requirement — any agent that can reach Argos can do this. The two calls that carry the evidence are:
```bash
argos test get --json # flakiness, stability, consistency, and the trend over time
argos test changes --json # each change with its occurrence count and screenshot URLs
```
Over MCP, they're the `getTest` and `listTestChanges` tools. Over HTTP, they're `GET /projects/{owner}/{project}/tests/{testId}` and `GET /projects/{owner}/{project}/tests/{testId}/changes`.
Install the [Argos agent skills](/docs/agents/agent-skills) to teach your assistant the CLI's commands, flags, and token rules up front:
```bash
npx skills add https://argos-ci.com
```
### Limits
An agent is good at spotting non-determinism and proposing a fix, but it is guessing at intent from a screenshot. Review its change like any other: a test that stops changing because it stopped asserting anything is worse than a flaky one. Argos keeps doing the deterministic comparison either way — a fix that doesn't work will show up as a change again on the next build.
### Related
* [Test page](/docs/learn/reliability-and-flakiness/test-page) — where the prompt lives, and the rest of what Argos knows about a test.
* [Review builds with AI agents](/docs/learn/review-workflow/review-builds-with-ai-agents) — the same idea applied to reviewing a pull request's visual changes.
* [Flaky test detection](/docs/learn/reliability-and-flakiness/flaky-test-detection) — how Argos scores flakiness and what ignoring a change does.
# Stabilize screenshots
A playbook for tackling visual flakiness, with detection, ignoring noisy changes, and stabilization strategies.
The most reliable visual test suite is one where flakiness is fixed at the source. This playbook covers the strategies that make screenshots deterministic — from waiting for loading to freezing dynamic values.
{% hint style="info" %}
Argos also detects and filters flakiness for you: see [Flaky test detection](/docs/learn/reliability-and-flakiness/flaky-test-detection) for flaky badges, ignore, and auto-ignore, and the [Tests dashboard](/docs/learn/reliability-and-flakiness/tests-dashboard) for a project-wide ranking.
{% endhint %}
### Common causes
Visual flakiness usually stems from one of the following:
* **Dynamic content**: Ads, user-generated content, or other data that changes between runs.
* **Asynchronous loading**: Elements or styles that render at inconsistent times.
* **Rendering differences**: Browser, OS, or device variations that alter visual output.
* **External dependencies**: Reliance on third-party systems that introduce variability.
* **Animations and transitions**: Unhandled motion captured mid-frame.
* **Resolution and scaling**: Screen size or pixel density differences between environments.
### Best practices for stable screenshots
Follow these practices — each one targets a common cause above:
{% hint style="info" %}
Most stabilization is automatic. The Argos SDK stabilizes every screenshot by default — waiting for `aria-busy`, fonts, and images to settle, forcing font antialiasing, hiding carets and scrollbars, and more. You can customize or disable any of it through the [`stabilize` option](/docs/reference/playwright). The practices below cover what the SDK can't infer on its own, such as which elements are loaders or which values are dynamic.
{% endhint %}
* **Wait until the page is ready before capturing.** Mark loading elements with `aria-busy` so `argosScreenshot()` waits for them. → [Wait for loading](/docs/learn/reliability-and-flakiness/flaky-tests/wait-for-loading)
* **Wait for CSS background images to load.** Flag elements with `data-visual-test-wait-bg-img` so Argos waits for their backgrounds — or extend the check to the whole page. → [Wait for background images](/docs/learn/reliability-and-flakiness/flaky-tests/wait-for-background-images)
* **Freeze animated GIFs.** GIFs are paused on their first frame by default so they don't capture a random frame on each run. → [Pause animated GIFs](/docs/learn/reliability-and-flakiness/flaky-tests/pause-gifs)
* **Make dates and times deterministic.** Hide or freeze any value that changes between runs. → [Stabilize date & time](/docs/learn/reliability-and-flakiness/flaky-tests/stabilize-date-and-time)
* **Force consistent text rendering.** Disable subpixel text and font hinting so glyphs look identical on every machine. → [Stabilize text rendering](/docs/learn/reliability-and-flakiness/flaky-tests/stabilize-text-rendering)
* **Run the same environment everywhere, and tame rendering quirks.** Use the same OS and browser locally and on CI, and smooth over properties like `border-radius`. → [Browser glitches](/docs/learn/reliability-and-flakiness/flaky-tests/browser-glitches)
* **Mask or hide unavoidable dynamic content.** Use `data-visual-test` attributes for anything you can't stabilize at the source. → [Argos helpers](/docs/learn/reliability-and-flakiness/flaky-tests/argos-helpers)
{% hint style="success" %}
**New to visual testing?** Start with [Stabilize text rendering](/docs/learn/reliability-and-flakiness/flaky-tests/stabilize-text-rendering) and [Wait for loading](/docs/learn/reliability-and-flakiness/flaky-tests/wait-for-loading). Together they prevent the large majority of flaky screenshots.
{% endhint %}
### Emphasis on accessibility
At Argos, we advocate for accessibility-focused end-to-end testing. Improving accessibility (semantic markup, `aria-busy`, predictable focus states) not only supports users with disabilities but also makes tests more deterministic and less prone to flakiness.
# Stabilize text rendering
Disable subpixel text and font hinting in Chromium so glyphs render identically across macOS, Linux, and CI.
Force consistent glyph rendering across operating systems: disable subpixel (LCD) text and font hinting so the same text looks identical on macOS, Linux, and CI—eliminating one of the most common sources of screenshot flakiness.
### Why text causes flaky screenshots
By default, Chromium renders text using two techniques that depend on the underlying operating system, GPU, and font stack:
* **Subpixel (LCD) antialiasing** uses the red, green, and blue subpixels of a screen to smooth glyph edges. It leaves faint red/blue color fringing that differs from one machine to another.
* **Font hinting** snaps glyphs to the pixel grid. The result varies between platforms, shifting antialiasing by a pixel here and there.
The consequence: a screenshot captured locally on macOS rarely matches the exact same screenshot captured on a Linux CI runner. Argos sees these sub-pixel differences as real changes and reports false positives, even though no code changed.
### The fix
Launch Chromium with two flags that make text rendering deterministic:
* `--disable-lcd-text` — forces **grayscale antialiasing** instead of subpixel rendering, removing the red/blue edge fringing.
* `--font-render-hinting=none` — disables font hinting so glyph rasterization is **platform-independent**.
{% tabs %}
{% tab title="Playwright" %}
Add the launch options to the `use` block of your Playwright configuration:
{% code title="playwright.config.ts" %}
```ts
import { defineConfig } from "@playwright/test";
export default defineConfig({
use: {
launchOptions: {
args: ["--disable-lcd-text", "--font-render-hinting=none"],
},
},
});
```
{% endcode %}
{% endtab %}
{% tab title="Storybook (Vitest)" %}
Pass the launch options to the Playwright provider in your Vitest configuration:
{% code title="vitest.config.ts" %}
```ts
import { defineConfig } from "vitest/config";
import { playwright } from "@vitest/browser-playwright";
export default defineConfig({
test: {
browser: {
enabled: true,
provider: playwright({
launchOptions: {
args: ["--disable-lcd-text", "--font-render-hinting=none"],
},
}),
instances: [{ browser: "chromium" }],
},
},
});
```
{% endcode %}
{% endtab %}
{% endtabs %}
{% hint style="success" %}
These flags make text rendering consistent **across** environments, so screenshots captured on your machine match those captured on CI.
{% endhint %}
{% hint style="info" %}
Rendering flakiness is reduced even further when local and CI runs share the **exact same environment** (OS and browser). See [Browser Glitches](/docs/learn/reliability-and-flakiness/flaky-tests/browser-glitches) for more on standardizing environments.
{% endhint %}
# Wait for loading
Use aria-busy so argosScreenshot waits for full page load before capturing, improving screenshot consistency.
A screenshot taken while the page is still loading produces a different image on every run. Mark your loading states with `aria-busy`, and `argosScreenshot()` waits until they are gone before capturing.
### Usage
Add `aria-busy` to your loader components:
```jsx
```
`argosScreenshot()` delays the capture until no element with `aria-busy` remains on the page, so the screenshot always shows the fully loaded state. Make sure your app removes the attribute (or the loader) once loading completes.
{% hint style="info" %}
Waiting for `aria-busy` is part of the SDK's default stabilization (the `stabilize.waitForAriaBusy` option) — there's nothing to enable, you only need to mark your loaders.
{% endhint %}
# Wait for background images
Wait for CSS background images to load before capturing with the waitForBackgroundImages stabilization option.
CSS background images have no native load event, so the SDK can't wait for them the way it waits for `` elements. When a background image is still loading—or re-fetches on a viewport change, as responsive backgrounds often do—the screenshot can capture a half-painted element and turn flaky.
The `waitForBackgroundImages` stabilization option closes that gap: it discovers background image URLs (including those set on `::before` and `::after`), preloads them, and waits for them to finish before the screenshot is taken.
{% hint style="info" %}
A full-document scan for background images is expensive, so by default the scan is limited to the elements you flag with the `data-visual-test-wait-bg-img` attribute. This keeps stabilization fast while still covering the elements that need it.
{% endhint %}
### Flagging elements
Add the `data-visual-test-wait-bg-img` attribute to an element to wait for its background image—and the background images of everything nested inside it—before capturing. This works out of the box with the default `stabilize: true`:
```html
…
```
### Scanning the whole document
Pass `true` to scan every element instead of only the flagged ones:
{% tabs %}
{% tab title="Playwright" %}
```ts
await argosScreenshot(page, "homepage", {
stabilize: { waitForBackgroundImages: true },
});
```
{% endtab %}
{% tab title="Cypress" %}
```ts
cy.argosScreenshot("homepage", {
stabilize: { waitForBackgroundImages: true },
});
```
{% endtab %}
{% endtabs %}
On large pages, narrow the scan to the elements that actually use background images by passing a selector instead:
```ts
await argosScreenshot(page, "homepage", {
stabilize: { waitForBackgroundImages: { selector: ".hero, [data-bg]" } },
});
```
### Disabling it
To turn the scan off entirely, pass `false`:
```ts
await argosScreenshot(page, "homepage", {
stabilize: { waitForBackgroundImages: false },
});
```
A failed background image (for example a 404) is treated as loaded, so a broken URL never blocks stabilization.
{% hint style="info" %}
The scan runs once per viewport before the wait begins, so background images added to the DOM *during* the wait window aren't picked up. For the common responsive-viewport case this is exactly what you want; for `` elements added later, the default `waitForImages` already re-reads the DOM live.
{% endhint %}
See the full [`stabilize` option reference](/docs/reference/playwright) for every stabilization setting.
# Pause animated GIFs
Freeze animated GIFs on their first frame with the pauseGifs stabilization option so they no longer capture a random frame on each run.
Animated GIFs keep playing while your test runs, so each screenshot captures whatever frame happens to be on screen at capture time. That frame is non-deterministic—it depends on network timing, CPU load, and how long stabilization took—so a GIF turns an otherwise-stable page into a flaky one.
The `pauseGifs` stabilization option removes that source of noise: it freezes every animated GIF on its **first frame** before the screenshot is taken, then restores the original animation afterwards.
{% hint style="info" %}
This is on by default. Setting `stabilize: true` (the default) already pauses GIFs—there's nothing to configure unless you want to turn it off.
{% endhint %}
### How it works
For each `` that resolves to a GIF, the SDK loads a fresh copy of the image and draws its first decoded frame to a canvas—an already-rendered `` has been animating since it loaded, so its current frame is unpredictable. The static frame is swapped in for the screenshot and the original GIF is put back once the capture is done.
A cross-origin GIF served without the right CORS headers taints the canvas and can't be frozen; those are left animating rather than blocking the screenshot.
### Flagging GIFs that aren't detected automatically
The SDK recognizes GIFs from their URL—a `.gif` extension or a `data:image/gif` URI. A GIF served from a URL that carries neither (for example a CDN endpoint like `/media/1234`) can't be detected this way, so it keeps animating.
Flag those images explicitly with the `data-image-type="gif"` attribute and they'll be paused like any other GIF:
```html
```
### Disabling it
If you specifically want to capture the live animation, disable the plugin:
{% tabs %}
{% tab title="Playwright" %}
```ts
await argosScreenshot(page, "homepage", {
stabilize: { pauseGifs: false },
});
```
{% endtab %}
{% tab title="Cypress" %}
```ts
cy.argosScreenshot("homepage", {
stabilize: { pauseGifs: false },
});
```
{% endtab %}
{% endtabs %}
See the full [`stabilize` option reference](/docs/reference/playwright) for every stabilization setting.
# Stabilize date & time
Hide or freeze dynamic dates and times to remove a common source of flaky visual diffs in Argos.
Dates and times change between test runs, so any visible timestamp produces a diff on every build. Hide them from screenshots, or freeze them so they render the same value on every run.
### Hide the date
Add the `data-visual-test="transparent"` [Argos helper](/docs/learn/reliability-and-flakiness/flaky-tests/argos-helpers) to render the element invisible in screenshots while keeping its layout space:
```html
```
### Freeze the date
To keep dates visible in your screenshots, make them deterministic instead:
* **Freeze the clock in your tests.** Playwright's [Clock API](https://playwright.dev/docs/clock) pins the browser time to a fixed value:
```js
await page.clock.setFixedTime(new Date("2024-10-10T10:00:00"));
```
* **Pin dates in your test data.** If your UI renders dates from seeded data, run a script that resets those dates just before your tests, so relative labels like "2 days ago" stay constant.
# Browser glitches
Eliminate browser-induced visual discrepancies like border-radius differences with a consistent test environment.
The same page can render differently across operating systems and browser versions. Run your tests in the same environment everywhere — same OS, same browser version, locally and on CI — and smooth over the few properties that still render inconsistently.
{% hint style="info" %}
The most common cross-environment glitch is text rendering. See [Stabilize text rendering](/docs/learn/reliability-and-flakiness/flaky-tests/stabilize-text-rendering) for the launch options that make glyphs render identically everywhere.
{% endhint %}
### Border radius
The `border-radius` property can render differently across browsers and devices. Add the `data-visual-test-no-radius` [Argos helper](/docs/learn/reliability-and-flakiness/flaky-tests/argos-helpers) to remove the border radius in screenshots:
```html
```
# Argos helpers
Use data-visual-test attributes to hide, remove, or mask dynamic elements for consistent, flake-free screenshots.
Argos SDKs recognize `data-visual-test` attributes on your elements, giving you control over how dynamic content appears in screenshots. Use them for anything you can't stabilize at the source — dates, avatars, ads, or third-party widgets.
### Helpers
* `data-visual-test="transparent"`: Renders the element transparent (`visibility: hidden`), keeping its layout space.
* `data-visual-test="removed"`: Removes the element from view (`display: none`).
* `data-visual-test="blackout"`: Masks the element with a blackout effect (Storybook, Playwright, and Cypress SDKs only).
* `data-visual-test-no-radius`: Strips the border radius from the element. See [Browser glitches](/docs/learn/reliability-and-flakiness/flaky-tests/browser-glitches).
* `data-visual-test-wait-bg-img`: Waits for the element's (and its descendants') CSS background images to load before capturing. See [Wait for background images](/docs/learn/reliability-and-flakiness/flaky-tests/wait-for-background-images).
* `data-image-type="gif"`: Flags an image as a GIF so it's paused even when its URL has no `.gif` extension. See [Pause animated GIFs](/docs/learn/reliability-and-flakiness/flaky-tests/pause-gifs).
For example, to hide a clock from the captured screenshot:
```html
...
```
# Deployments
Deploy your Storybook or static build to a unique Argos URL on every pull request to preview and share it.
A **deployment** on Argos is a static build — most commonly a Storybook — served on a unique URL that you can open, share, and review. When you run `argos deploy` in CI, Argos uploads the build, generates a URL, and posts the status back to your pull request.
Deployments pair naturally with visual testing: the same Storybook you test with Argos becomes a live preview reviewers can browse, right from the pull request — with no hosting of your own to maintain.
Use deployments to:
* Preview a Storybook for every pull request.
* Share a live link with designers, product, or stakeholders to review work in context.
* Browse the history of every deployed build across branches and commits.
*Deployments list in the Argos dashboard.*
### How it works
A deployment is created in three phases:
1. **Build** — The Argos CLI scans your local directory and computes a content hash for every file.
2. **Upload** — Argos returns pre-signed upload URLs for the files it doesn't already have. Files that match an existing hash are skipped, so re-deploying an unchanged build is near-instant.
3. **Serve** — Once the upload finishes, Argos finalizes the deployment, assigns it a URL, and reports the status to your Git provider.
Each deployment is **immutable**. Re-running the deploy command always produces a new deployment with its own URL—the previous one keeps working.
### Quickstart
The following steps deploy a Storybook. The same flow works for any static directory (Vite build, Next.js export, plain HTML, etc.).
{% stepper %}
{% step %}
### Install the Argos CLI
{% tabs %}
{% tab title="npm" %}
```
npm i --save-dev @argos-ci/cli
```
{% endtab %}
{% tab title="yarn" %}
```
yarn add --dev @argos-ci/cli
```
{% endtab %}
{% tab title="pnpm" %}
```
pnpm add --save-dev @argos-ci/cli
```
{% endtab %}
{% tab title="bun" %}
```
bun add --dev @argos-ci/cli
```
{% endtab %}
{% endtabs %}
{% endstep %}
{% step %}
### Build your static site
Generate the directory you want to deploy. For Storybook:
```bash
npm run build-storybook
```
This produces a `storybook-static/` directory.
{% endstep %}
{% step %}
### Deploy
{% tabs %}
{% tab title="npm" %}
```
npm exec -- argos deploy ./storybook-static
```
{% endtab %}
{% tab title="yarn" %}
```
yarn run argos deploy ./storybook-static
```
{% endtab %}
{% tab title="pnpm" %}
```
pnpm exec -- argos deploy ./storybook-static
```
{% endtab %}
{% tab title="bun" %}
```
bun x argos deploy ./storybook-static
```
{% endtab %}
{% endtabs %}
The CLI uploads your build and prints a unique URL when the deployment is ready:
```
✔ Deployed: https://my-project-abcd123-acme.argos-ci.live
```
By default, the deployment is created in the **preview** environment. To deploy to **production**, add the `--prod` flag:
{% tabs %}
{% tab title="npm" %}
```
npm exec -- argos deploy ./storybook-static --prod
```
{% endtab %}
{% tab title="yarn" %}
```
yarn run argos deploy ./storybook-static --prod
```
{% endtab %}
{% tab title="pnpm" %}
```
pnpm exec -- argos deploy ./storybook-static --prod
```
{% endtab %}
{% tab title="bun" %}
```
bun x argos deploy ./storybook-static --prod
```
{% endtab %}
{% endtabs %}
See [Environments](/docs/learn/deployments/environments) for the rules that decide which environment a deployment lands in.
{% endstep %}
{% endstepper %}
### Authentication
The deploy command uses the same authentication as the rest of the Argos CLI. Set the `ARGOS_TOKEN` environment variable in CI:
```bash
ARGOS_TOKEN=
```
You can find the project token in **Settings → General → Token**. On GitHub Actions, you can also use [OIDC or tokenless authentication](/docs/learn/integrations/github-actions-authentication) to avoid managing a secret.
### What's next
* [**Environments**](/docs/learn/deployments/environments) — How preview and production deployments are determined, and how to customize the production branch.
* [**URLs and domains**](/docs/learn/deployments/urls-and-domains) — The URLs Argos generates for each deployment, and how to set the production domain.
* [**Access protection**](/docs/learn/deployments/access-protection) — Restrict who can open deployment URLs.
* [**Use in CI**](/docs/learn/deployments/use-deployments-in-ci) — Deploy automatically on every pull request with GitHub Actions.
* [**Lifecycle and retention**](/docs/learn/deployments/retention) — How long deployments last, why they can't be overwritten, and how to pick a deploy cadence.
# Use deployments in CI
Run argos deploy from CI to create a deployment on every pull request, with a GitHub Actions Storybook example.
Running `argos deploy` from CI is the most common setup: a new deployment is created on every push to a pull request, and the deployment link appears in the PR comment alongside Argos visual tests.
This page walks through a GitHub Actions setup for Storybook. The same pattern works for any static build and any CI provider.
### Prerequisites
* A static build step that produces a directory (for Storybook: `npm run build-storybook` → `storybook-static/`).
* An `ARGOS_TOKEN` available as a CI secret. You can also use [OIDC or tokenless authentication](/docs/learn/integrations/github-actions-authentication) to avoid managing a secret.
### GitHub Actions example
{% code title=".github/workflows/argos-deploy.yml" %}
```yaml
name: Deploy Storybook to Argos
on:
pull_request:
push:
branches:
- main
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- uses: actions/setup-node@v6
- run: npm ci
- run: npm run build-storybook
- run: npx --no-install argos deploy ./storybook-static
env:
ARGOS_TOKEN: ${{ secrets.ARGOS_TOKEN }}
```
{% endcode %}
A few notes:
* The workflow listens to both `pull_request` and `push` to `main`. Pull request runs produce **preview** deployments; pushes to `main` produce **production** deployments (because `main` matches the default production branch pattern—see [Environments](/docs/learn/deployments/environments)).
* `actions/checkout` gives Argos the commit SHA and branch it needs to associate the deployment with the right pull request.
* The `ARGOS_TOKEN` is the project token from **Settings → General → Token**.
### Force a production deployment
If your production branch differs from your repository's default branch (or if you want to be explicit), pass the `--prod` flag:
```yaml
- run: npx --no-install argos deploy ./storybook-static --prod
env:
ARGOS_TOKEN: ${{ secrets.ARGOS_TOKEN }}
```
You can keep the same workflow for both preview and production by branching on the event:
```yaml
- name: Deploy
run: |
if [ "${{ github.event_name }}" = "push" ]; then
npx --no-install argos deploy ./storybook-static --prod
else
npx --no-install argos deploy ./storybook-static
fi
env:
ARGOS_TOKEN: ${{ secrets.ARGOS_TOKEN }}
```
### Combine with visual testing
The `deploy` and `upload` commands are independent: you can run both in the same workflow to get a deployment URL **and** Argos visual tests on the same commit.
```yaml
- run: npm run build-storybook
- run: npm run test:visual # Your usual Argos visual test job
env:
ARGOS_TOKEN: ${{ secrets.ARGOS_TOKEN }}
- run: npx --no-install argos deploy ./storybook-static
env:
ARGOS_TOKEN: ${{ secrets.ARGOS_TOKEN }}
```
Argos posts a single pull request comment that lists both the deployment URLs and the visual build results.
GitHub pull request comment showing both the deployment and the Argos visual build.
### Status checks
Each deployment registers a commit status named `argos-deploy/`. The status starts as **pending** when the upload begins and becomes **success** when the deployment is ready. You can require it in your branch protection rules if a missing deployment should block a merge.
### Other CI providers
The `argos deploy` command has no GitHub-specific behavior. To run it on another CI provider:
1. Build your static directory in your pipeline.
2. Set `ARGOS_TOKEN` as a secret.
3. Run `argos deploy ` (add `--prod` for production).
Argos automatically detects the commit SHA, branch, and pull request number from the most common CI environment variables.
### Related
* [Deployments overview](/docs/learn/deployments)
* [Environments](/docs/learn/deployments/environments)
* [GitHub integration](/docs/learn/integrations/github-integration)
* [Argos CLI reference](/docs/reference/argos-command-line-interface-cli)
# Environments
Understand how Argos assigns each deployment to a preview or production environment from your branch patterns.
Every deployment is created in one of two environments:
* **Preview** — A non-production deployment, typically created from a feature branch or pull request. Each preview gets its own URL and never replaces the production deployment.
* **Production** — The deployment served on your project's production domain. Only deployments from a production branch are promoted here.
The environment is decided when the deployment is created and cannot be changed afterwards.
### How the environment is determined
Argos picks the environment in this order:
1. **Explicit override.** If you pass `--prod` to the CLI (or `environment: "production"` to the SDK), the deployment is created as production.
2. **Branch match.** Otherwise, the branch name is matched against the project's **production branch pattern**. A match → production. No match → preview.
By default, the production branch pattern follows your Git repository's default branch (usually `main`). You can override it from project settings.
### Preview deployments
Preview deployments are the default. They are created when:
* You run `argos deploy ` without `--prod`, **and**
* The branch does not match the production branch pattern.
Each preview deployment gets:
* A unique, immutable **deployment URL** — always points to that exact build.
* A **branch URL** — always points to the latest preview on that branch. Useful to share a link that follows a feature branch as it evolves.
See [URLs and domains](/docs/learn/deployments/urls-and-domains) for the full list of URLs Argos generates.
When a preview deployment is linked to a pull request, the deployment status appears in the [pull request comment](/docs/learn/review-workflow/pull-request-comments) and as a commit status check on the PR.
### Production deployments
A production deployment is created when:
* You run `argos deploy --prod`, **or**
* The branch matches the production branch pattern.
When a new production deployment becomes ready, it is **promoted**: the project's production domain immediately starts serving the new build. Earlier production deployments remain available at their own URLs.
The Argos dashboard shows a **Current** badge next to the deployment that is currently serving the production domain.
*The deployments list highlights the deployment currently promoted to production.*
### Configure the production branch
By default, Argos uses your Git repository's default branch as the production branch. You can customize this from **Settings → Deployments → Production deployment branch**.
*Project Settings → Deployments → Production deployment branch.*
To customize:
1. Disable **Use GitHub repository's default branch**.
2. Enter a [glob pattern](https://github.com/isaacs/minimatch) that matches your production branches.
Examples:
* `main` — Only the `main` branch.
* `{main,production}` — Either `main` or `production`.
* `release/**` — Any branch under `release/` (for example `release/2024-q4`).
Any branch matching the pattern produces a production deployment on the next CLI run, even without `--prod`.
### Forcing an environment from the CLI
You can force a production deployment regardless of the branch with the `--prod` flag:
```bash
npm exec -- argos deploy ./storybook-static --prod
```
This is useful when you want to:
* Deploy a one-off production build from a local machine.
* Promote a deployment from a non-standard branch (for example, a release branch that doesn't match the configured pattern).
There is no flag to force a preview from a branch that matches the production pattern — a matching branch always deploys to production. If you need previews from such a branch, narrow the production branch pattern instead.
### Related
* [Deployments overview](/docs/learn/deployments)
* [URLs and domains](/docs/learn/deployments/urls-and-domains)
* [Use deployments in CI](/docs/learn/deployments/use-deployments-in-ci)
# URLs and domains
Understand the deployment, branch, and production URLs Argos generates and when to share each one.
Every deployment is reachable through one or more URLs. The exact URLs depend on the deployment's environment and the project's configuration. All deployment URLs are served from the shared root domain `argos-ci.live`.
### Deployment URL
Every deployment has an **immutable deployment URL** that always points to that exact build. It looks like:
```
https://--.argos-ci.live
```
For example: `https://storybook-gdhgxamjo-acme.argos-ci.live`
The deployment URL never changes and never moves. It's the safest URL to share when you want a stable reference to a specific build—for example, in a pull request review or a bug report.
### Branch URL
In addition to the deployment URL, each deployment registers a **branch URL** that follows the latest deployment on that branch:
```
https://--.argos-ci.live
```
For example, on a branch named `fix-stripe`: `https://storybook-fix-stripe-acme.argos-ci.live`
When you push a new commit on the same branch and re-deploy, the branch URL is updated to point at the new build. The previous deployment is still available at its own deployment URL.
Branch names containing characters that are not URL-safe are slugified.
{% hint style="info" %}
Branch URLs are useful in pull request templates and review checklists: a reviewer can bookmark the same link and always see the latest version of a feature.
{% endhint %}
### Production domain
Production deployments are additionally served on the project's **production domain**:
```
https://.argos-ci.live
```
The production domain is shared across all production deployments. When a new production deployment is promoted, the domain immediately starts serving the new build—older production deployments stay reachable on their own deployment URLs.
#### Configure the production domain
The production domain slug defaults to your project name. You can change it in **Settings → Deployments → Production domain**.
Project Settings → Deployments → Production domain.
Rules for the slug:
* Lowercase, up to 48 characters.
* Must start and end with an alphanumeric character.
* Dashes are allowed in the middle.
The final domain is `.argos-ci.live`.
{% hint style="warning" %}
Changing the production domain takes effect immediately. Any existing links that used the previous domain will stop resolving.
{% endhint %}
### Summary
| URL type | Stability | When it exists |
| ----------------- | ------------------------------------------------------ | --------------------------- |
| Deployment URL | Immutable — always points at one build | Every deployment |
| Branch URL | Updates when a new deployment lands on the same branch | Every deployment |
| Production domain | Updates when a new production deployment is promoted | Production deployments only |
All URLs above appear in the **Deployments** tab of your project in Argos.
The Deployments tab shows the deployment URL, branch URL, and—for production—the production domain.
### Related
* [Environments](/docs/learn/deployments/environments) — How preview vs production is decided.
* [Access protection](/docs/learn/deployments/access-protection) — Restrict who can open these URLs.
# Access protection
Require viewers to sign in before opening deployment URLs to keep your Argos previews private per project.
By default, deployment URLs are reachable by anyone who has the link. For most internal projects, that's not what you want—a Storybook can leak unreleased designs, copy, or features. Argos lets you require viewers to sign in with an Argos account before opening any deployment URL.
Access protection is configured per project, and applies to every deployment under it.
### Protection modes
Argos supports three modes:
| Mode | Preview URLs | Production domain | Available on |
| ----------------------- | ----------------- | ----------------- | ------------ |
| **Public** | No login required | No login required | All plans |
| **Standard protection** | Login required | No login required | All plans |
| **All deployments** | Login required | Login required | Team plans |
When login is required, only Argos users who have access to the project can open the deployment. Everyone else sees the Argos sign-in screen.
#### Public
Everyone with the link can open the deployment. Use this if your project is fully public (for example, an open-source design system) or if the build is intentionally meant to be shared.
#### Standard protection
Login required for every URL **except** the production domain. The production domain stays public; all preview URLs and the immutable deployment URLs require sign-in.
This is the right default for most teams: production is browsable by anyone (designers, customers, stakeholders), while previews stay private to your team.
#### All deployments
Login required for **all** URLs, including the production domain. Use this when the production build itself contains sensitive material—for example, internal tools or a Storybook for unreleased features.
This option requires a Team plan.
### Configure access protection
1. Open your project in Argos.
2. Go to **Settings → Deployments**.
3. Under **Deployment authentication**, pick the protection mode.
*Project Settings → Deployments → Deployment authentication.*
Changes take effect immediately on the next request.
### Who can access protected deployments
When login protection is enabled, a viewer must:
1. Be signed in to Argos.
2. Have access to the project the deployment belongs to.
Project access follows the [team roles and permissions](/docs/learn/account-and-access/team-members-and-roles) rules: team members, contributors invited to the project, and account owners.
A viewer who does not have access sees a 404-style screen rather than a sign-in prompt, so the existence of the project is not disclosed.
# Lifecycle and retention
How long Argos deployments last, why they can't be overwritten, and how to pick a deploy cadence without cleaning up old builds.
Deployments are permanent, immutable records. Once a deployment is ready, it keeps working at its own URL and Argos never expires it, replaces it in place, or removes it automatically. This page explains what that means for how you deploy and how often.
### How long deployments last
A deployment has no expiration. It stays reachable at its immutable [deployment URL](/docs/learn/deployments/urls-and-domains#deployment-url) for as long as the project exists—whether it was created minutes ago or months ago.
There is no retention window to configure and nothing that ages deployments out. The only way a deployment stops existing is if you delete the whole project (see [Deleting deployments](#deleting-deployments)).
### Overwriting a deployment
You can't overwrite a deployment. Every `argos deploy` run creates a **new** deployment with its own immutable URL—the previous one keeps working untouched.
What moves instead of being overwritten are the shared URLs:
* The [branch URL](/docs/learn/deployments/urls-and-domains#branch-url) always points at the latest deployment on that branch. Re-deploying the same branch updates the branch URL to the new build; the previous deployment stays available at its own deployment URL.
* The [production domain](/docs/learn/deployments/urls-and-domains#production-domain) always serves the latest promoted production deployment. A new production deployment takes over the domain immediately; earlier production builds stay reachable on their own URLs.
So from a reviewer's point of view, a new deploy on the same branch effectively supersedes the old one—the link they use keeps showing the latest build—without any manual cleanup, and without losing the older builds' stable URLs.
### Deleting deployments
Individual deployments can't be deleted, the same way [builds are immutable records](/docs/learn/review-workflow/builds-list#faq). There's no bulk-delete and nothing you need to clear out: deployments don't age, and they don't count toward your [screenshot quota](/docs/learn/billing-and-subscription/pricing-plans) (that quota applies to visual testing, not deployments).
If you ever need to remove every deployment for a project, delete the project from **Settings → General**. This removes the project entirely, including its builds and deployments, and can't be undone.
### Choosing a deploy cadence
Because deployments never pile up in a way you have to manage, you can deploy as often—or as rarely—as fits your workflow:
* **On every pull request** — The most common setup. Each PR push creates a preview deployment and the link appears in the [pull request comment](/docs/learn/review-workflow/pull-request-comments). See [Use deployments in CI](/docs/learn/deployments/use-deployments-in-ci).
* **On a subset of pull requests** — If you don't need a preview on every PR, gate the deploy step on a label (for example, only run `argos deploy` when a `deploy-preview` label is present) or on changes to the relevant directory.
* **On releases** — Deploy to [production](/docs/learn/deployments/environments#production-deployments) from your release branch, either by matching the [production branch pattern](/docs/learn/deployments/environments#configure-the-production-branch) or by passing `--prod`.
Attaching previews to a PR label and running production deploys on releases is a perfectly reasonable setup—there's no downside to old deployments sticking around, and no cleanup step to schedule.
### FAQ
How long do deployments stick around?
Indefinitely. Deployments don't expire—each one stays reachable at its immutable deployment URL for as long as the project exists.
Can I overwrite a previous deployment?
No. Every deploy creates a new immutable deployment. The branch URL and production domain automatically move to point at the latest build, so the links people share stay current, while older builds remain available at their own URLs.
Do I have to bulk-delete old deployments to clear them out?
No. There's nothing to clean up—deployments don't age out and don't count toward your screenshot quota. Individual deployments can't be deleted; the only way to remove them all is to delete the project.
### Related
* [Deployments overview](/docs/learn/deployments)
* [URLs and domains](/docs/learn/deployments/urls-and-domains)
* [Environments](/docs/learn/deployments/environments)
# Media sharing
Upload a standalone image or video to Argos and get a shareable link with ready-to-paste Markdown, so a screenshot or a screen recording can go straight into a pull request.
**Media** on Argos is a standalone image or video: uploaded on its own, with no build and no test run behind it. Argos stores it, serves it at a share URL, and hands you the Markdown to embed it. It belongs to a project, so it inherits that project's access and moves with it when the project is transferred.
It exists because GitHub has no public API for comment attachments. Dragging an image into a pull request needs a signed-in browser session, which an agent — or a CI job — does not have. Committing the image bloats the repository, and release assets are a workaround nobody wants to maintain.
Use media sharing to:
* Put a before/after of a UI change in the pull request that made it, so the reviewer doesn't check out the branch.
* Attach a screen recording of a bug reproduction to an issue.
* Share a screenshot with your team by link, straight from the terminal.
* Point at a spot on a screenshot an agent produced and have it read your comment back — see [Reading the feedback](/docs/learn/media/standalone-media-upload#reading-the-feedback-left-on-a-media).
{% hint style="info" %}
Media is **not** visual testing. Nothing is compared to a baseline and nothing gates a build — it is a file with a link. To detect visual changes, see [Core concepts](/docs/learn/platform-fundamentals).
{% endhint %}
### How it works
A media is an **identity** — what the picture is *of* — and every upload is a **version** of it. Uploading `checkout.png` again doesn't create a second link: it adds a version under the same media, and the share URL always shows the newest one. That is what makes re-uploading after review work — the Markdown already pasted in a pull request updates itself, and the version a reviewer commented on survives underneath.
An upload takes three calls, which the CLI does in one command:
1. **Register** — Argos records the file's name, type, size and content hash, and returns a signed upload target. The share URL is allocated from this point.
2. **Upload** — the file goes straight to Argos storage, never through the API.
3. **Finalize** — Argos reads the file's first bytes back to check it really is the type it was declared as, records an image's dimensions, and makes it reachable. A file that isn't what it claims to be is rejected and its bytes are deleted.
A file Argos already holds — same contents, uploaded before — skips the last two steps entirely.
There is no processing step. Argos does not transcode, re-encode or rewrite your file: it stores the bytes you sent and serves them from its image CDN, which derives WebP and AVIF variants — and a video's poster frame — on request. **A media is fully usable the moment the upload finishes.**
### Quickstart
{% stepper %}
{% step %}
#### Install the Argos CLI
{% tabs %}
{% tab title="npm" %}
```
npm i --save-dev @argos-ci/cli
```
{% endtab %}
{% tab title="yarn" %}
```
yarn add --dev @argos-ci/cli
```
{% endtab %}
{% tab title="pnpm" %}
```
pnpm add --save-dev @argos-ci/cli
```
{% endtab %}
{% tab title="bun" %}
```
bun add --dev @argos-ci/cli
```
{% endtab %}
{% endtabs %}
{% endstep %}
{% step %}
#### Upload a file
```bash
ARGOS_TOKEN= npx argos media upload after.png
```
The CLI prints the share URL and a Markdown embed:
```
Media (1)
after.png
ID: 4821
staged
image/webp · 25 KB · 1440x900 · team · ready
Expires: 2027-08-10T09:12:00.000Z
URL: https://app.argos-ci.com/m/kQ8vN2pXr4tYw7cD1sZ0
File: https://files.argos-ci.com/media/42/9f86d081884c7d65…webp
Markdown: 
```
The PNG went out as WebP: the CLI [compresses images before upload](/docs/learn/media/standalone-media-upload#image-compression), and the media keeps your file's name and extension regardless.
{% endstep %}
{% step %}
#### Paste the Markdown
Put the `Markdown` line in a pull request, an issue, or a chat message. Copy it verbatim rather than writing your own — for a video, the embed is a poster frame wrapped in a link, which is the only form GitHub renders.
{% endstep %}
{% endstepper %}
### Attach it to a pull request — even one that doesn't exist yet
A media can attach to a **pull request** or to a **branch**. Pass `--pr ` when the pull request already exists. Pass `--branch ` while you are still working: the media is **staged**, and when a pull request opens for that branch, Argos publishes everything staged there and posts a single managed comment listing it — unasked, with nothing to come back and connect. See [Getting media into a pull request](/docs/learn/media/standalone-media-upload#getting-media-into-a-pull-request).
### Where to find your uploads
A media is reached by its link — there is no browsing UI. From the terminal, `argos media list` lists a project's uploads, and `--branch` narrows it to everything uploaded for the work in hand. Each media's share page shows the file with pan and zoom, its version history, its comment threads, and a copy-Markdown button.
### What's next
* [**Upload media**](/docs/learn/media/standalone-media-upload) — the CLI, the SDK, the API and the MCP server, plus getting media into a pull request and reading the feedback pinned on it.
* [**Share links, retention and limits**](/docs/learn/media/share-links-retention-and-limits) — who can open a link, how long a file lasts, accepted formats and sizes, and what an upload costs.
# Upload media
Upload images and videos to Argos from the CLI, the Node.js SDK, the REST API or an AI agent, and get them into a pull request with a managed comment.
Every surface uses the same three-step flow described in [How it works](/docs/learn/media#how-it-works). The CLI is the shortest path; the API is there when you are not in a Node.js environment.
### From the CLI
```bash
argos media upload before.png after.png
```
Pass as many files as you like. Each one is validated up front — an unsupported type, an unreadable path or a name collision fails the batch before anything is transferred — then uploaded in turn and printed with its own share URL and Markdown embed. Add `--json` when you parse the output.
| Flag | What it does |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--branch ` | Stage the media on a branch. Argos publishes it — and posts the pull request comment — by itself once a pull request opens for that branch. |
| `--pr ` | Publish the media to an existing pull request. Detected with the GitHub CLI when neither this nor `--branch` is given. |
| `--no-pr` | Skip that detection and upload the media unattached. |
| `--state ` | Which half of a before/after pair these files are. Inferred from a file name ending in `-before` or `-after`. |
| `--description ` | Prose shown under the media in the pull request comment. |
| `--visibility ` | Who can open the share page. Defaults to your project's visibility — `public` for a public project, `team` for a private one. See [Share links](/docs/learn/media/share-links-retention-and-limits). |
| `--no-compress` | Upload images exactly as they are instead of converting them to WebP. |
| `--project ` | Project to upload to. Required with a personal access token; also `ARGOS_PROJECT`. |
Media belongs to a **project**, so it inherits that project's access and moves with it when the project is transferred. In CI, `media upload` authenticates like every other Argos command: `ARGOS_TOKEN`, or tokenless GitHub Actions authentication with no token at all. See [Tokens and permissions](#tokens-and-permissions) for the other commands.
### Getting media into a pull request
An agent produces screenshots while it is still doing the work; the pull request comes after, if it comes at all. So a media attaches to a **branch** or to a **pull request**:
* `--branch ` — the media is **staged**. It is real from the start: shareable, listed, with its URL. When a pull request opens for that branch, Argos attaches everything staged there and posts its comment, unasked. Naming a branch needs no GitHub connection and no open pull request.
* `--pr ` — the media is **published** to that pull request immediately.
```bash
argos media upload checkout-before.png checkout-after.png --branch feat/checkout
```
A media keeps its branch after publishing, as a record of where it came from, so `argos media list --branch ` finds everything uploaded for the work in hand across the moment the pull request opens.
#### When you pass neither
Argos asks the [GitHub CLI](https://cli.github.com) for the pull request of the branch you are on:
```bash
argos media upload after.png # publishes to the pull request you are working in
```
Only when you pass neither flag. `--pr` is taken as given, and `--branch` is already an answer to the question — detecting a pull request over it would publish immediately and discard the staging you asked for.
Detection never fails an upload. `gh` not installed, not signed in, no pull request open for the branch yet, not a git repository at all — all mean the same thing, "nothing to attach to", and the media uploads with its share URL either way. Pass `--no-pr` to skip the lookup, for a screenshot that has nothing to do with the branch that happens to be checked out.
{% hint style="info" %}
CI is the case where detection usually finds nothing: `gh` is often absent, and a checkout is frequently in a detached HEAD. Pass `--pr` or `--branch` explicitly in a workflow rather than relying on it.
{% endhint %}
Two boundaries: publishing needs the project connected to a GitHub repository with [pull request comments](/docs/learn/review-workflow/pull-request-comments) enabled, and a pull request opened from a **fork** never claims a branch's staged media.
#### The managed comment
Argos maintains **one** comment per pull request — "Media uploaded by Argos" — listing every media published to it in a table, and edits it in place on each change. Attaching a media to a pull request and showing it there are the same act, not two. A [before/after pair](#before-and-after-pairs) shares a single row, descriptions appear in a Notes column, and the table lists up to 20 media.
The comment is separate from the [Argos build comment](/docs/learn/review-workflow/pull-request-comments): standalone media has no build behind it, and a media upload never rewrites a status comment reviewers rely on. If a reviewer deletes the comment, Argos takes the hint and never recreates it on that pull request. Deleting a media removes its row immediately.
### Before and after pairs
A file named `checkout-before.png` uploads as `checkout.png` labelled `before` — the suffix is lifted off the name, case-insensitively, and the extension stays. Uploading `checkout-after.png` alongside it gives the pair one identity, one row in the pull request comment, and a share page that compares the two side by side with synced pan and zoom.
`--state before` or `--state after` sets the label for files not named that way. It applies to **every** file in the invocation — passing it to an already-suffixed pair would make both files collide on one identity, which the CLI refuses rather than silently versioning:
```bash
argos media upload before/checkout.png --state before
argos media upload after/checkout.png --state after
```
### Versions: re-upload, same link
A media's identity within its pull request (or on its branch) is its **name**. Re-uploading the same name adds a **version** rather than a second media: the id, the share token and therefore the URL are unchanged, and the share page — and any Markdown already pasted in a pull request — shows the newest upload. The version a reviewer commented on survives underneath, in the share page's history.
Re-uploading a file whose bytes haven't changed does nothing: Argos recognizes the content hash, skips the transfer, and adds no version.
While a media is **staged**, `argos media update` can rename it, edit its description, or move it to another branch (`--no-branch` detaches it, so no pull request will publish it). Once **published**, name and branch are fixed — the pull request comment and its review threads are built on them:
```bash
argos media update 4821 --description "After the alignment fix"
argos media update 4821 --name checkout-v2.png # staged media only
```
### Image compression
The CLI converts PNG and JPEG images to WebP before uploading — a 252 KB PNG screenshot typically goes out at a tenth of the size, at a quality (85) where text and 1-pixel borders survive. The media's name keeps your file's extension: `checkout.png` stays `checkout.png` even when WebP bytes are sent, so a `--no-compress` re-run adds a version instead of creating a second media.
Compression is skipped whenever it would not help: videos, already-efficient WebP and AVIF, GIFs and animated PNGs, images past WebP's 16383-pixel dimension limit (a long full-page capture reaches it), and conversions that came out no smaller. A file that can't be converted is uploaded as-is rather than failing the upload. Pass `--no-compress` to upload every image untouched.
Converting applies a photo's EXIF orientation, then drops the rest of its metadata — including GPS coordinates. A file uploaded untouched keeps its metadata in the stored original; see [What Argos does to your file](/docs/learn/media/share-links-retention-and-limits#what-argos-does-to-your-file).
### Embedding the result
Copy the `Markdown` line the command prints. It is a picture wrapped in a link to the share page — `[](url)` — so the media shows inline, and clicking it lands on the page where it can be compared, versioned and commented on.
**Do not hand-write the embed from the share URL.** `url` is an HTML page: `` renders as a broken image everywhere you paste it. The image part has to point at the file, which is what the `Markdown` line already does.
The picture is the file itself for an image, and the **poster frame** for a video. That difference is not cosmetic: GitHub renders an inline video player only for media it hosts itself, so a `
```
### Disabling it
If you specifically want to capture the live animation, disable the plugin:
{% tabs %}
{% tab title="Playwright" %}
```ts
await argosScreenshot(page, "homepage", {
stabilize: { pauseGifs: false },
});
```
{% endtab %}
{% tab title="Cypress" %}
```ts
cy.argosScreenshot("homepage", {
stabilize: { pauseGifs: false },
});
```
{% endtab %}
{% endtabs %}
See the full [`stabilize` option reference](/docs/reference/playwright) for every stabilization setting.
# Stabilize date & time
Hide or freeze dynamic dates and times to remove a common source of flaky visual diffs in Argos.
Dates and times change between test runs, so any visible timestamp produces a diff on every build. Hide them from screenshots, or freeze them so they render the same value on every run.
### Hide the date
Add the `data-visual-test="transparent"` [Argos helper](/docs/learn/reliability-and-flakiness/flaky-tests/argos-helpers) to render the element invisible in screenshots while keeping its layout space:
```html
```
### Freeze the date
To keep dates visible in your screenshots, make them deterministic instead:
* **Freeze the clock in your tests.** Playwright's [Clock API](https://playwright.dev/docs/clock) pins the browser time to a fixed value:
```js
await page.clock.setFixedTime(new Date("2024-10-10T10:00:00"));
```
* **Pin dates in your test data.** If your UI renders dates from seeded data, run a script that resets those dates just before your tests, so relative labels like "2 days ago" stay constant.
# Browser glitches
Eliminate browser-induced visual discrepancies like border-radius differences with a consistent test environment.
The same page can render differently across operating systems and browser versions. Run your tests in the same environment everywhere — same OS, same browser version, locally and on CI — and smooth over the few properties that still render inconsistently.
{% hint style="info" %}
The most common cross-environment glitch is text rendering. See [Stabilize text rendering](/docs/learn/reliability-and-flakiness/flaky-tests/stabilize-text-rendering) for the launch options that make glyphs render identically everywhere.
{% endhint %}
### Border radius
The `border-radius` property can render differently across browsers and devices. Add the `data-visual-test-no-radius` [Argos helper](/docs/learn/reliability-and-flakiness/flaky-tests/argos-helpers) to remove the border radius in screenshots:
```html
```
# Argos helpers
Use data-visual-test attributes to hide, remove, or mask dynamic elements for consistent, flake-free screenshots.
Argos SDKs recognize `data-visual-test` attributes on your elements, giving you control over how dynamic content appears in screenshots. Use them for anything you can't stabilize at the source — dates, avatars, ads, or third-party widgets.
### Helpers
* `data-visual-test="transparent"`: Renders the element transparent (`visibility: hidden`), keeping its layout space.
* `data-visual-test="removed"`: Removes the element from view (`display: none`).
* `data-visual-test="blackout"`: Masks the element with a blackout effect (Storybook, Playwright, and Cypress SDKs only).
* `data-visual-test-no-radius`: Strips the border radius from the element. See [Browser glitches](/docs/learn/reliability-and-flakiness/flaky-tests/browser-glitches).
* `data-visual-test-wait-bg-img`: Waits for the element's (and its descendants') CSS background images to load before capturing. See [Wait for background images](/docs/learn/reliability-and-flakiness/flaky-tests/wait-for-background-images).
* `data-image-type="gif"`: Flags an image as a GIF so it's paused even when its URL has no `.gif` extension. See [Pause animated GIFs](/docs/learn/reliability-and-flakiness/flaky-tests/pause-gifs).
For example, to hide a clock from the captured screenshot:
```html