How to Set a Consistent Viewport Size for Argos CI Screenshots

Set an explicit width and height in your browser test framework, then use the same dimensions for Argos baseline and comparison captures. For Playwright, configure use.viewport; for Cypress, set viewportWidth and viewportHeight. Keep the browser, operating system, and device scale factor consistent too, because viewport dimensions alone do not eliminate every visual difference.

1. Set the viewport in Playwright

Argos captures screenshots from your test runner. Its Playwright quickstart uses the @argos-ci/playwright reporter and argosScreenshot(page, "homepage") helper to upload captures. Install and configure that integration as shown in the Argos Playwright quickstart, then set a fixed viewport in Playwright configuration:

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

export default defineConfig({
  use: {
    viewport: { width: 1280, height: 720 },
    deviceScaleFactor: 1,
  },
});

The 1280 × 720 dimensions are an example, not a universal standard. Choose a size that represents the layout you intend to review and keep it unchanged between the baseline run and later CI runs. The device scale factor is pinned to 1 in this example; choose the value appropriate for your project and keep it stable.

A typical test capture, once the Argos Playwright integration is configured, looks like this:

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");
});

Use the capture helper and project setup documented by the Argos SDK version in your repository. Argos notes that a baseline should exist on the default branch before pull request builds can be compared normally.

One viewport or responsive variants?

If the test covers one layout, configure one fixed viewport. If it covers responsive behavior, define deliberate viewport variants and capture each as a separate case. Do not let dimensions depend on a developer’s monitor or an implicit runner default. Argos screenshot metadata represents the viewport with numeric width and height fields, for example { "width": 1280, "height": 720 } (Argos screenshot metadata reference).

2. Set the viewport in Cypress

Cypress supports project-wide dimensions in configuration. This example makes the intended size explicit:

import { defineConfig } from "cypress";

export default defineConfig({
  viewportWidth: 1280,
  viewportHeight: 720,
});

For a test that deliberately covers another responsive layout, change the viewport in the test:

cy.viewport(390, 844);
cy.visit("https://example.com");
// Run assertions or take the visual capture at this size.

Cypress documents that cy.viewport(width, height) changes the current test viewport and that it returns to configured defaults between tests. Its documented default is 1000 by 660 pixels; explicitly configure your chosen dimensions rather than relying on that default. See the Cypress viewport documentation for the supported command options.

3. Keep the rendering environment stable

A fixed viewport prevents one major source of layout movement, but it does not make every pixel deterministic. Argos’s guidance on flaky visual tests recommends keeping the operating system and browser version consistent and pinning viewport and device scale factor. Scrollbars can also affect available content width, and their appearance can vary by operating system (Argos guide to flaky visual tests).

Match baseline and comparison dimensions. A width change can trigger responsive reflow and produce broad diffs.
Keep browser and OS consistent. Run baseline and pull request captures in the same CI image or equivalent environment.
Pin device scale factor. Use a deliberate value supported by your framework and keep it stable.
Check scrollbar behavior. If scrollbars are visible in captures and cause unwanted diffs, CSS can hide them as Argos describes. Do this only if that matches the rendering you intend to validate.
Establish the baseline. Follow Argos’s setup instructions and create the default-branch baseline before expecting ordinary pull request comparisons.

4. Troubleshoot viewport differences

Symptom	Likely cause	What to check
Large layout diff across the page	Width or height differs from the baseline, causing responsive reflow.	Compare the configured width and height in the baseline and current runner. Set them explicitly in the project configuration.
Text or components shift by a few pixels	Browser version, OS rendering, or device scale factor differs.	Pin the CI browser and environment; check the configured scale factor.
Content width differs near the right edge	Scrollbar behavior differs between environments.	Compare captures in the same OS and browser environment. Consider hiding scrollbars only if that reflects the product’s intended view.
Pull request has no useful comparison	The Argos integration may not be configured as expected, or the default-branch baseline may be missing.	Verify the reporter installation and configuration against the Argos quickstart, then ensure a baseline exists on the default branch.
A responsive test appears to use the wrong size	A per-test viewport change may not be applied where expected, or the framework restores its configured default between tests.	Set the desired size explicitly in the test and verify it after navigation; for Cypress, account for its reset to configured defaults between tests.

5. A practical consistency checklist

Choose viewport dimensions for the layout under test.
Set both width and height in Playwright or Cypress configuration.
Pin device scale factor where supported.
Use the same browser version and OS environment for baseline and comparison.
For responsive coverage, declare each intended viewport deliberately and capture it as its own variant.
Confirm the Argos SDK/reporter is configured and the default branch has a baseline.
Inspect scrollbar behavior if content width varies across captures.

Or skip the browser setup

If your goal is to capture a URL at a fixed size outside a visual test runner, ScreenshotNeo is a website screenshot API and MCP server. Pass the viewport dimensions in a single request. See the ScreenshotNeo API documentation for available parameters.

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

import requests

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

const q = new URLSearchParams({
  access_key: 'YOUR_API_KEY',
  url: 'https://stripe.com',
  width: '1280',
  height: '720',
});
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
const fs = await import('node:fs/promises');
await fs.writeFile('shot.webp', Buffer.from(await res.arrayBuffer()));

ScreenshotNeo accepts cookie and consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each cleanup step can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers report the page verdict and billing status. Its MCP server lets AI agents use screenshot, page-info, and PDF capture tools. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 shots.

Performance, reliability, and cost notes

For Argos CI, explicit dimensions and a stable rendering environment reduce avoidable visual diffs; they do not control changes in the page itself, such as dynamic content. Keep test data and page state predictable where your application allows it. No benchmark or runtime guarantee is implied here.

ScreenshotNeo is useful for standalone URL captures and automation through its API or MCP server, while the Argos workflow in this guide captures pages from browser tests for visual comparison. ScreenshotNeo’s free tier is 1,000 shots per month; paid options are Starter at $5 for 3,000, Growth at $15 for 15,000, Pro at $39 for 60,000, Scale at $99 for 250,000, and Business at $249 for 1,000,000. Yearly billing gives two months free, and all features are available on every plan. For Argos usage or pricing, consult Argos’s own current documentation; no Argos pricing claims are made here.

Frequently asked questions

Does changing my monitor resolution change the CI viewport?

The browser test framework controls the viewport. Set its dimensions explicitly so the capture does not rely on a machine’s screen size.

Should every test use the same viewport?

Use the same size for captures that represent the same layout. Use separate, intentional sizes when the purpose is to verify responsive layouts.

Where can I confirm the dimensions Argos received?

Argos screenshot metadata describes viewport dimensions as numeric width and height values. Check the metadata reference and your capture configuration when diagnosing a mismatch.