How to Capture Full-Page Screenshots for Argos CI Visual Tests

Use Argos’s Playwright helper with fullPage: true:

await argosScreenshot(page, "homepage", { fullPage: true });

The helper captures the full scrollable page. Add the Argos Playwright reporter to your Playwright configuration, authenticate CI, and establish a default-branch baseline so pull requests have something to compare against. Full-page capture is only one part of a reliable visual test: the page state, browser, operating system, fonts, and dynamic content also affect the result.

1. Set up Playwright and Argos

Install Playwright and the Argos Playwright integration in your project. The package is a development dependency:

npm install --save-dev @argos-ci/playwright

Configure the Argos reporter in playwright.config.ts. Keep your existing Playwright settings and add the reporter entry:

import { defineConfig } from "@playwright/test";

export default defineConfig({
  reporter: [
    ["list"],
    ["@argos-ci/playwright/reporter"],
  ],
});

If your project already uses a reporter, include it in the reporter array rather than replacing it. The Argos quickstart writes screenshots to ./screenshots by default; add that generated directory to .gitignore if you do not intend to commit it.

See the Argos Playwright quickstart and the official integration documentation for current setup details.

2. Capture a full page in a test

Import the helper, navigate to a deterministic page state, then pass { fullPage: true } as the third argument:

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

test("homepage visual snapshot", async ({ page }) => {
  await page.goto("https://example.com");
  await argosScreenshot(page, "homepage", { fullPage: true });
});

Use a stable, descriptive name for each snapshot. Names help identify the capture in review and should remain consistent for the same page or state across runs. For example, use separate names for a product page before and after opening a menu.

Wait for the state you intend to compare

Argos’s helper waits for fonts, images, and network idle, and hides carets and scrollbars. You should still ensure that application-specific content has loaded and reached the state the test is meant to check. For a page with an explicit ready marker:

await page.goto("https://example.com");
await page.getByTestId("page-ready").waitFor();
await argosScreenshot(page, "homepage", { fullPage: true });

Use a marker that reflects meaningful readiness in your application. A generic delay can make a test slower without guaranteeing that the relevant content is stable.

3. Configure CI and establish a baseline

Run the visual test in CI with the Argos authentication method configured for your project. The quickstart uses ARGOS_TOKEN; GitHub Actions can also use OIDC or tokenless authentication. Consult the current Argos setup for the option supported by your repository.

A typical GitHub Actions workflow needs to check out the repository, set up a supported Node version, install dependencies, install Chromium with its required dependencies, and run Playwright tests. For example, the essential shape is:

name: Visual tests
on: [push, pull_request]
jobs:
  playwright:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm ci
      - run: npx playwright install --with-deps chromium
      - run: npx playwright test
        env:
          ARGOS_TOKEN: ${{ secrets.ARGOS_TOKEN }}

Choose action and runtime versions that your project supports. Store a token in CI secrets rather than committing it to the repository. If using OIDC or tokenless authentication, follow Argos’s GitHub Actions configuration instead of adding a token.

Run the default branch once to establish a baseline. Until then, Argos can show pull-request builds as orphan builds because there is no default-branch capture to compare against.

4. Keep full-page captures stable

A full-page image includes more content than a viewport capture, so it can expose more dynamic regions and rendering differences. Stabilize the captured state before investigating diff thresholds:

Use fixed or seeded test data; avoid live counters, rotating promotions, timestamps, and personalized content.
Wait for application readiness and ensure images and fonts have finished loading.
Keep browser and operating-system environments consistent between the baseline and CI. Font rasterization and anti-aliasing vary across environments.
Hide or mask areas that are intentionally variable. Prefer targeted masking over raising the tolerance for the whole image.
Use screenshot styling or Playwright masks for dynamic regions where appropriate. Check the current Playwright screenshot API for supported options.

Argos handles font, image, network-idle, caret, and scrollbar preparation in its helper. Native Playwright’s screenshot assertions also support full-page capture and options such as masks and screenshot styling; see Playwright’s screenshot documentation.

5. Argos capture versus native Playwright snapshots

Both approaches use Playwright to capture the page. The main difference is how teams store and review comparisons.

Approach	Baseline and review	Fits when
Native Playwright `toHaveScreenshot`	Baselines live with the test and are updated through the repository workflow.	You want snapshots in version control and are comfortable reviewing and approving changes there.
Argos Playwright integration	The helper captures through Playwright and uploads images for hosted comparison and pull-request review.	You want visual results managed through Argos’s hosted review workflow.

Argos is not required to take a full-page screenshot. Choose based on baseline storage, update approval, review experience, rendering consistency, and the service cost that fits your team. The Argos integration changes how screenshots are uploaded and reviewed; Playwright remains the capture layer.

6. Troubleshooting

Why do my Playwright screenshots pass locally but fail in CI?

Local and CI environments may render fonts and pixels differently, and the page may contain dynamic data. Keep the browser and operating system consistent, use stable test data, wait for the intended state, and mask only known variable regions. If the diff is legitimate rendering jitter, adjust the tolerance narrowly rather than hiding broad parts of the page.

Pull-request builds appear as orphan builds

Argos has no default-branch baseline to compare against. Run the visual test on the default branch first, then rerun or create a pull-request build.

No screenshots are uploaded

Check that the reporter is included in playwright.config.ts, the test calls argosScreenshot, and CI uses a supported Argos authentication method. Check the job logs and current Argos quickstart for the expected environment setup.

The capture is missing content near the bottom

Confirm the page has loaded the content before capturing. Lazy-loaded sections may appear only after scrolling or after application-specific readiness conditions. Wait for the content you need and verify the page state in the same browser environment used by CI.

Visual diffs include blinking or personalized regions

Freeze or seed test data if possible. Otherwise, mask or hide the smallest region that must vary. Avoid weakening comparison thresholds across the whole page to solve a localized source of noise.

CI fails while installing or launching Chromium

Ensure the workflow installs the browser and required system dependencies for the runner. The Argos quickstart’s GitHub Actions example uses Playwright’s browser installation with dependencies; adapt it to the browser and runner your project supports.

7. Performance, reliability, and cost

Full-page captures produce larger images and include more page content than viewport captures. Keep the test focused on pages whose full vertical layout matters, and avoid capturing the same page redundantly when one representative state covers the behavior. Waiting for a real readiness condition improves reliability; arbitrary long sleeps increase runtime and can still capture an unsettled page.

For reliable comparisons, pin the browser and runner environment used for both baseline and CI, keep fonts and content stable, and establish the default-branch baseline before relying on pull-request diffs. Review the current Argos plan and pricing directly if hosted comparison cost is part of the decision; this guide does not assume a particular plan or price.

Or skip the browser setup

If you need a clean page image outside a Playwright visual-test workflow, ScreenshotNeo is a website screenshot API and MCP server. One GET request returns an image or PDF. For example, capture a page as WebP with cURL:

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

Equivalent Python:

import requests

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

Equivalent Node.js:

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

See the ScreenshotNeo API documentation for request options. Cookie banners, newsletter popups, and chat widgets are removed before the shot. Bot checks, blank pages, failed loads, and cache hits are never billed, and response headers report the page verdict and billing status. Its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots.

FAQ

Does `fullPage: true` capture the entire scrollable page?

It requests a full-page capture through the Argos Playwright helper. Ensure the page has loaded the content you expect before the helper runs.

Do I need Argos to use Playwright screenshots?

No. Playwright can capture and compare screenshots with its native screenshot assertions. Argos provides a hosted upload and review workflow.

Should I commit the generated screenshots directory?

The Argos quickstart uses ./screenshots by default and suggests adding it to .gitignore. Follow your project’s artifact and baseline storage choices.