How to Set Up Argos CI for a Static HTML Website

To check how a static HTML website looks, serve its built files in CI, open selected pages with Playwright, and capture them with Argos’s Playwright reporter. Give each page a stable snapshot name, provide CI authentication, and run the default branch once to create a baseline before relying on pull request comparisons. Argos also supports HTML source diffs and static preview deployments, but those are separate outcomes from rendered screenshot comparison.

1. Choose what you want Argos to review

Goal	Use	What the reviewer sees
Catch changes in layout, typography, color, and other rendered details	Playwright screenshots with the Argos Playwright reporter	Rendered browser screenshots compared with a baseline
Review changes to generated HTML, CSS, JavaScript, or other text files	Argos CLI text snapshot upload	Text diffs; these do not show browser rendering
Let reviewers open the built site for a pull request	`argos deploy <directory>`	A hosted preview of the static build, not a snapshot comparison by itself

You can use screenshot uploads and preview deployment in the same workflow if both outcomes are useful. For rendered visual regression checks, continue with Playwright below.

2. Serve the static site and install the capture package

Argos does not replace the browser step: Playwright opens your site and captures the page, while the Argos reporter uploads the capture from CI. First make sure your static site can be built and served at a predictable local address. The exact build and serve commands depend on your project. For a plain directory of HTML files, a simple local static server is sufficient; keep its command and port consistent with the Playwright configuration.

Install Playwright and the Argos Playwright integration as development dependencies:

npm install --save-dev @playwright/test @argos-ci/playwright
npx playwright install chromium

Ensure the test runner waits until the local server is ready before it navigates to the site. The example below uses Playwright’s webServer setting; replace the command and readiness URL with those for your build. If your build must happen first, make that command part of the server script or CI workflow.

3. Configure Playwright and capture stable page names

Add an Argos reporter to the Playwright configuration. Upload only in CI, keep local runs useful for debugging, and preserve snapshot names as routes and pages evolve.

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

export default defineConfig({
  testDir: './tests',
  reporter: process.env.CI
    ? [['list'], ['@argos-ci/playwright']]
    : [['list']],
  use: {
    baseURL: 'http://127.0.0.1:4173',
    trace: 'on-first-retry',
    screenshot: 'only-on-failure',
    launchOptions: {
      // The Argos quickstart uses Chromium flags to reduce rendering variation.
      args: ['--font-render-hinting=none'],
    },
  },
  webServer: {
    command: 'npm run preview -- --host 127.0.0.1',
    url: 'http://127.0.0.1:4173',
    reuseExistingServer: !process.env.CI,
    timeout: 30_000,
  },
});

Use the helper in a test after navigating to the page. This example captures two routes under fixed names:

// tests/visual.spec.ts
import { test } from '@playwright/test';
import { argosScreenshot } from '@argos-ci/playwright';

const pages = [
  { name: 'homepage', path: '/' },
  { name: 'about', path: '/about.html' },
];

for (const pageInfo of pages) {
  test(`visual: ${pageInfo.name}`, async ({ page }) => {
    await page.goto(pageInfo.path);
    await argosScreenshot(page, pageInfo.name);
  });
}

Change the page list to match your site. Names such as homepage and about should remain stable across commits so Argos can associate each capture with its baseline. The default screenshot directory is ./screenshots; add it to .gitignore if your workflow generates it locally.

# .gitignore
screenshots/

If the page depends on fonts, images, or client-side scripts, wait for the relevant content to be ready before capture. Prefer waiting on a meaningful page element over adding a long fixed sleep. If pages contain dynamic timestamps, rotating content, or personalized data, make those values deterministic or hide them for the test run so they do not create irrelevant diffs.

4. Run the checks in GitHub Actions

Add a workflow that installs dependencies and Chromium, starts the site through Playwright’s webServer configuration, and runs the tests on pull requests and the default branch. Put the Argos project token in repository secrets as ARGOS_TOKEN; do not run an interactive personal login in CI.

# .github/workflows/visual.yml
name: Visual regression

on:
  pull_request:
  push:
    branches: [main]

jobs:
  visual:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - run: npx playwright install --with-deps chromium
      - run: npx playwright test
        env:
          ARGOS_TOKEN: ${{ secrets.ARGOS_TOKEN }}

Create the token in Argos project settings and store it as a repository secret. Argos also documents GitHub Actions OIDC or tokenless authentication options; on other CI systems use the documented token environment variable or reporter token option for that environment. Check the current Argos setup instructions when choosing an authentication method.

5. Establish and review the baseline

Push or run the workflow on the repository’s default branch.
Confirm the screenshots upload successfully and the build is visible in Argos.
Open a pull request that changes a page and inspect the associated Argos check.
Review each changed capture and approve or reject the visual change as part of code review.

The first default-branch build is necessary: Argos says pull-request builds are marked orphan until a default-branch baseline exists. A passing Playwright run alone does not establish that comparison baseline; verify the Argos upload and build status.

6. Optional: compare generated HTML and other text files

If you want to review generated source rather than its rendered appearance, use the Argos CLI to upload stable-named text artifacts. For example, from a directory containing the generated files:

argos upload ./dist -f "**/*.{txt,json,yaml,yml,xml,html,md,css,js}"

Keep the glob limited to the intended output and use stable file paths so files match their baselines between runs. HTML uploaded this way is a text snapshot, not a screenshot. The CLI can infer commit, branch, and pull request details from supported CI environments. For non-Git environments, the docs require ARGOS_COMMIT and ARGOS_BRANCH; the commit must be the full 40-character SHA. The CLI reference specifies Node.js 22 or newer, and lists limits of 50 MB per snapshot and 5,000 snapshots per build. Confirm current CLI help and documentation before relying on command flags or limits.

7. Optional: publish a static preview

To let reviewers open the built pull request site, run argos deploy against the output directory after building it:

argos deploy ./dist

Argos documents plain HTML directories as valid static deployment targets. A deployment gives reviewers a preview URL; it does not perform visual snapshot comparison on its own. Use the screenshot upload flow as well when you need visual diffs.

Stability, performance, and CI cost

Keep capture scope intentional. Each page test adds browser navigation and image upload work. Start with the routes where visual changes matter most, then expand coverage as CI time allows.
Use stable rendering conditions. Run the same browser engine and viewport in CI, wait for page content to settle, and avoid uncontrolled animation or changing data in captures.
Control concurrency if needed. Parallel browser tests can reduce elapsed time but use more CI resources and can expose server or resource contention. Tune Playwright workers for your runner rather than assuming more is always faster.
Keep assets available locally. A static build that references unavailable remote resources may capture missing images or fonts. Prefer deterministic assets and check failed network requests when a snapshot changes unexpectedly.
Separate the costs you control. The workflow consumes your CI runner time for building, launching Chromium, and uploading artifacts. Argos plan and usage details can change; check its pricing and current CLI documentation for account-specific limits.
Use traces and failure screenshots to diagnose flakiness. They help explain a failed navigation or unstable page, but do not guarantee identical rendering in every environment.

Troubleshooting

Symptom	Likely cause	Fix
Pull request build appears orphaned or has no comparison	No baseline has been uploaded from the default branch	Run the workflow on the default branch, confirm its upload succeeded, then rerun or update the pull request build.
Playwright cannot connect to the local URL	The static server did not start, uses a different port, or serves a different host	Make the configured `webServer.command`, readiness URL, and `baseURL` agree. Check the server logs and build output.
Argos upload is unauthorized	The token is missing, invalid, or unavailable to this event	Check the repository secret name and project token. Confirm the job exposes `ARGOS_TOKEN`; use the CI authentication method Argos documents for that provider.
Snapshots are treated as new instead of matching prior pages	Capture names or paths changed between runs	Restore stable names and routes, and avoid deriving names from transient values such as branch names or timestamps.
Screenshots differ on every run	Dynamic content, unfinished fonts or images, animation, or rendering variation	Wait for required content, stabilize data and animations, confirm assets load, and inspect Playwright traces and failure screenshots. Keep the browser and viewport consistent.
Local screenshots appear as untracked files	The generated screenshots directory is not ignored	Add the default `./screenshots` output directory to `.gitignore`.
CLI cannot infer commit or branch metadata	Upload runs outside a recognized Git or CI environment	Provide `ARGOS_COMMIT` with the full 40-character SHA and `ARGOS_BRANCH`, as required by the CLI documentation.
Text upload misses files or exceeds a limit	The file glob excludes intended artifacts, includes unintended files, or a snapshot/build exceeds documented limits	Run the upload from the expected directory, narrow or correct the glob, and check current CLI docs for supported files and limits.
Preview deploy succeeds but there is no visual diff	Static deployment and snapshot upload are different workflows	Keep `argos deploy` for the preview, and add the Playwright capture and reporter upload for visual comparisons.

Or skip the browser setup

For a one-off page capture, a debugging artifact, or a screenshot outside your CI test suite, ScreenshotNeo returns a screenshot from one GET request. The API accepts image format and other capture options; see the ScreenshotNeo API documentation for the supported parameters.

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

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://example.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({
  access_key: 'YOUR_API_KEY',
  url: 'https://example.com',
});
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await Bun.write('shot.webp', res);

ScreenshotNeo accepts cookie and consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each of those steps can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits cost nothing, and response headers report the page verdict and billing status. Its MCP server lets AI agents use take_screenshot, get_page_info, and capture_pdf. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000. Every feature is available on every plan. Sign up for ScreenshotNeo’s free plan.

FAQ

Does Argos host a static website?

argos deploy can publish a static build as a preview. That preview is separate from the Argos screenshot and text snapshot comparison flows.

Can I compare HTML without running a browser?

Yes. Upload HTML files as text snapshots with the CLI. This compares source text, not the page’s rendered appearance.

Do I need to approve every difference?

Review changed snapshots in the Argos check associated with the pull request and approve or reject the change as part of your review process.

Can the same workflow capture multiple pages?

Yes. Define a stable list of page names and paths, then create one Playwright capture test per entry.