Set up authentication in Playwright, then pass the authenticated page to Argos. Argos captures and uploads the browser state; it does not supply your application’s login cookie. For a normal login flow, save Playwright’s authenticated browser state and load it in the project that takes screenshots. If you already have a suitable test cookie value, add it to the browser context before navigating to the protected page.
Choose how Playwright should authenticate
Use saved storageState when your application creates a session through its login flow or authentication depends on more than one cookie. Use browserContext.addCookies() when the test has a known cookie value and direct injection is appropriate. In both cases, the browser must be authenticated before Argos takes the screenshot.
As an Amazon Associate I earn from qualifying purchases.
| Approach | Best fit | What it carries | Important consideration |
|---|---|---|---|
Saved storageState |
Authentication established by a login flow | Cookies and supported browser storage, including local storage and IndexedDB | The state can expire and must be protected like a credential. Session storage needs separate handling. |
addCookies() |
A known, valid test cookie that can be scoped to the target site | The cookies you explicitly supply | Cookie scope, expiry, and security attributes must match the application; it will not supply other required storage. |
Playwright’s authentication documentation describes reusable browser state and its security implications. Its BrowserContext cookie API documents direct cookie injection.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Fix the driver behind crashes, sound loss and screen glitches3Repair Windows errors before they cause bigger problemsPreferred method: save state after a real login
Use a Playwright setup project to sign in, wait until the authenticated page is reached, and write the context state to a file. Make the screenshot project depend on that setup and configure it to load the file. Playwright runs project dependencies before the dependent project, so the state is created before screenshot tests start.
#1 Best Overall
1. Create an authentication setup test
For example, save the following as tests/auth.setup.ts. Replace the example credentials and selectors with your application’s test-login details. The example assumes the application redirects to https://staging.example.com/ after login.
import { test as setup, expect } from "@playwright/test";
setup("sign in and save browser state", async ({ page }) => {
await page.goto("https://staging.example.com/login");
await page.getByLabel("Email").fill(process.env.TEST_USER_EMAIL!);
await page.getByLabel("Password").fill(process.env.TEST_USER_PASSWORD!);
await page.getByRole("button", { name: "Sign in" }).click();
await page.waitForURL("https://staging.example.com/");
await expect(page.getByRole("link", { name: "Account" })).toBeVisible();
await page.context().storageState({ path: "playwright/.auth/user.json" });
});Use assertions that indicate the login really succeeded, not merely that a navigation occurred. Adjust the final URL and authenticated-page assertion to fit the application.
2. Configure setup and screenshot projects
In playwright.config.ts, declare a setup project and make the screenshot project depend on it. The authenticated project then loads the saved state for its tests.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteRank #2
- Used Book in Good Condition
import { defineConfig, devices } from "@playwright/test";
export default defineConfig({
testDir: "./tests",
projects: [
{
name: "auth-setup",
testMatch: /auth.setup.ts/,
},
{
name: "screenshots",
testMatch: /.*.spec.ts/,
dependencies: ["auth-setup"],
use: {
...devices["Desktop Chrome"],
storageState: "playwright/.auth/user.json",
},
},
],
});Keep the setup test out of the screenshot project’s normal test match, as above, so it is not treated as an ordinary screenshot test. Run the configured Playwright suite with npx playwright test.
3. Capture the authenticated page with Argos
In a test running in the project configured with storageState, navigate to the protected route and pass the page to Argos:
import { test, expect } from "@playwright/test";
import { argosScreenshot } from "@argos-ci/playwright";
test("capture authenticated account page", async ({ page }) => {
await page.goto("https://staging.example.com/account");
await expect(page.getByRole("heading", { name: "Account" })).toBeVisible();
await argosScreenshot(page, "account");
});This is the Argos Playwright integration pattern: argosScreenshot(page, name) captures the supplied page. The Argos reporter handles upload in CI; the Argos quickstart documents CI configuration, including ARGOS_TOKEN and GitHub Actions OIDC or tokenless authentication options. The quickstart says screenshots are written to ./screenshots by default; ignore that generated directory in version control.
Rank #3
Alternative: inject a known cookie
For a legitimate test-only cookie whose value is already available to the test, add it to the browser context before loading the protected page. Playwright requires each cookie to have a name and value, plus either a url or both a domain and path. The example uses environment variables for the secret and scopes the cookie to the staging origin:
import { test, expect } from "@playwright/test";
import { argosScreenshot } from "@argos-ci/playwright";
test("capture account with a test cookie", async ({ page }) => {
const name = process.env.TEST_COOKIE_NAME;
const value = process.env.TEST_COOKIE_VALUE;
if (!name || !value) {
throw new Error("Set TEST_COOKIE_NAME and TEST_COOKIE_VALUE");
}
await page.context().addCookies([
{
name,
value,
url: "https://staging.example.com",
httpOnly: true,
secure: true,
sameSite: "Lax",
},
]);
await page.goto("https://staging.example.com/account");
await expect(page.getByRole("heading", { name: "Account" })).toBeVisible();
await argosScreenshot(page, "account");
});Replace the hostname and cookie attributes with the application’s actual settings. Do not guess a cookie’s domain, path, expiry, or security flags: incorrect scope or an expired value can make an otherwise valid cookie ineffective. Do not print cookie values in test output or logs. Prefer a dedicated test account and session rather than copying a personal browser cookie.
Keep browser authentication separate from Argos upload authentication
There are two distinct credentials in this workflow. The site’s cookie authenticates the Playwright browser to the application. The Argos token or supported CI identity authorizes the screenshot upload to Argos. Supplying one does not substitute for the other. Configure the application session in the browser context and configure Argos upload authentication through its CI integration.
Argos’s Playwright helper captures the page state produced by the test browser; it does not log into the application, create a session, or bypass access controls. Check the page’s authenticated state before calling argosScreenshot().
Protect and renew saved authentication state
Playwright warns: “The browser state file may contain sensitive cookies and headers that could be used to impersonate you or your test account.” Treat playwright/.auth/user.json as a credential:
- Add the authentication-state directory to
.gitignore; do not commit the generated file. - Prefer generating state during the CI job. If your workflow stores or transfers it, restrict access using your CI system’s secret and artifact controls.
- Use a test account with only the access the visual tests require.
- Regenerate state when the session expires; do not assume a saved state remains valid indefinitely.
Troubleshoot screenshots that are still unauthenticated
The screenshot shows a login page
- Confirm the test is running in the project that sets
storageState, not a project using a fresh context. - Confirm the setup project completed successfully and wrote the expected file before the screenshot project ran.
- Check the login assertion and the protected page’s final URL or authenticated UI before taking the screenshot.
Direct cookie injection has no effect
- Check the cookie’s URL or domain-and-path scope against the page origin and route.
- Check expiry and the application’s required
secure,httpOnly, andsameSitebehavior. - Confirm the application actually authenticates from that cookie. It may also require local storage, IndexedDB, or other state; saved Playwright state handles more supported browser storage than a manually added cookie.
The state file is missing or rejected
- Make sure the setup test’s output path and the project’s
storageStatepath match exactly. - Ensure the setup ran before dependent tests and that the CI job does not discard the generated file between setup and screenshot execution.
- If the file exists but the app returns to login, recreate it through the login flow; its session may have expired or been revoked.
Argos does not receive the screenshot
- Check the Argos reporter and the CI upload authentication separately from the application’s cookie setup.
- Verify the screenshot test reaches
argosScreenshot(page, "account")and that the page assertion before it passes. - Consult the Argos CI quickstart for the reporter and upload-authentication setup relevant to your CI provider.
If the project uses Cypress instead
Do not use Playwright’s storageState or addCookies() APIs in Cypress. Cypress documents cy.setCookie() for a known cookie and cy.session() for caching and restoring login-created cookies and web storage; it also clears cookies and web storage between tests by default. Argos’s Cypress integration has its own task registration and uses cy.argosScreenshot(). See the Cypress setCookie documentation, Cypress session documentation, and Argos Cypress integration.
Or skip the browser setup
If you need a screenshot API rather than an authenticated Playwright visual-test workflow, ScreenshotNeo is a separate option. It supports custom cookies, though the cookie parameters and authentication requirements for your site should be checked in the API documentation. It is not a replacement for Argos’s Playwright reporter or a way to configure your application’s login.
For a direct screenshot request, replace the target URL with the page you want to capture and use your ScreenshotNeo API key:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://staging.example.com/account -o shot.webpScreenshotNeo removes supported cookie-consent banners, newsletter popups, and chat widgets before capture; those cleanup steps can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and billing status. Its MCP server provides screenshot tools for AI agents. The Free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots.
Sign up for ScreenshotNeo’s free plan: 1,000 screenshots a month, no card required.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
