Skip to main content

Argos Playwright SDK

Improve test debugging and boost your visual testing capabilities by combining Argos with your Playwright tests.

Get started​

Please refer to our Quickstart guide to get started with Argos and Playwright.

Setup Visual Testing​

Argos presents a significant advantage over traditional Playwright visual tests with its streamlined approach to managing and reviewing test results:

  • Visual Testing on CI: With Argos, there's no need to run tests locally or commit screenshots to your repository. This not only saves time but also keeps your repository clean and focused on code rather than binary assets.
  • Fluid UI for Comparison: Argos intuitive interface makes it easy to spot discrepancies and understand visual changes without the need for cumbersome manual checks.
  • Enhanced Stabilization: The Argos integration with Playwright takes visual testing to the next level by ensuring stability and consistency in the screenshots captured. Fonts, images, animations, loaders, everything is just stable.

To enable Visual Testing with Playwright, first you have to setup the Argos reporter in your Playwright config:

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

export default defineConfig({
  // ... other configurations

  // Setup Argos reporter to send screenshots and traces to Argos.
  reporter: [
    // Use "dot" reporter on CI, "list" otherwise (Playwright default).
    process.env.CI ? ["dot"] : ["list"],

    // Add Argos reporter.
    [
      "@argos-ci/playwright/reporter",
      // Upload only on CI.
      { uploadToArgos: !!process.env.CI },
    ],
  ],
});

And use argosScreenshot helper to capture stable screenshots in your E2E tests:

tests/example.spec.ts
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");
});

Setup Tests Debugging​

The Argos Playwright reporter automatically reports failure screenshots and playwright traces. You can access them directly in Argos UI. If you are tired to download traces from artifact and run a command to see them, it is the solution for you.

  • Failure Screenshots: View failure screenshots from your CI tests directly in Argos. No extra steps, just immediate clarity where you need it most.
  • Playwright Traces: “Time travel” through your failing tests with remote Playwright traces. Gain a complete, step-by-step visual journey to the heart of any test issue.

To enable Test Debugging, you have to add Argos reporter and to turn on Playwright test use options in your Playwright config:

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

export default defineConfig({
  // ... other configurations

  // Setup Argos reporter to send screenshots and traces to Argos.
  reporter: [
    // Use "dot" reporter on CI, "list" otherwise (Playwright default).
    process.env.CI ? ["dot"] : ["list"],

    // Add Argos reporter.
    [
      "@argos-ci/playwright/reporter",
      // Upload only on CI.
      { 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",
  },
});

Tests Sharding​

Argos seamlessly integrates with Playwright test sharding, enabling efficient test distribution without the need for manual configuration. Argos Sharding/Parallel mode is automatically configured for you.

Helper Attributes for Visual Testing​

For tailored visual testing, the data-visual-test attributes provide control over how elements appear in Argos screenshots. This can be especially useful for obscuring or modifying elements with dynamic content, like dates.

  • [data-visual-test="transparent"]: Renders the element transparent (visiblity: hidden).
  • [data-visual-test="removed"]: Removes the element from view (display: none).
  • [data-visual-test="blackout"]: Masks the element with a blackout effect.
  • [data-visual-test-no-radius]: Strips the border radius from the element.

Example: Using a helper attribute to hide a div from the captured screenshot:

<div id="clock" data-visual-test="transparent">...</div>

API Overview​

argosScreenshot(page, name[, options])​

  • page: Instance of the Playwright Page.
  • name: Unique name for the screenshot.
  • options: Explore Page.screenshot command options for details.
  • options.element: Use an ElementHandle or string selector to capture a specific element's screenshot.
  • options.viewports: Define specific viewports for capturing screenshots. More on viewports configuration.
  • options.argosCSS: Specific CSS applied during the screenshot process. More on injecting CSS
  • options.disableHover: Disable hover effects by moving the mouse to the top-left corner of the page. Default to true.

Unlike Playwright's screenshot method, set fullPage option to true by default. Feel free to override this option if you prefer partial screenshots of your pages.

Playwright reporter​

The Argos reporter offers extensive configuration options. Specifically, all upload parameters are available for customizing the reporter.

playwright.config.ts
import { defineConfig } from "@playwright/test";
import type { ArgosReporterOptions } from "@argos-ci/playwright/reporter";

export default defineConfig({
  // ... other configurations

  reporter: [
    // Use "dot" reporter on CI, "list" otherwise (Playwright default).
    process.env.CI ? ["dot"] : ["list"],

    // Argos reporter
    [
      "@argos-ci/playwright/reporter",
      {
        uploadToArgos: !!process.env.CI,
        buildName: "custom-build-name",
      } as ArgosReporterOptions,
    ],
  ],
});

Upgrading from v0.0.x​

Step 1: Setup Argos in your Playwright config​

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

export default defineConfig({
  // ... other configuration

  // Add Argos reporter.
  reporter: [
    ["list"],
    [
      "@argos-ci/playwright/reporter",
      {
        // Upload artefacts to Argos on CI.
        uploadToArgos: !!process.env.CI,
      },
    ],
  ],

  // Setup recording option to enable test debugging features
  use: {
    // Setting to capture screenshot only when a test fails
    screenshot: "only-on-failure",
    // Setting to retain traces only when a test fails
    trace: "retain-on-failure",
  },
});

Step 2: Phase Out CLI Usage:​

  • Remove argos upload calls from your CI. (Note: Screenshots now upload through the reporter.)
  • Delete @argos-ci/cli from package.json.

Additional Resources​