How to Run Applitools Eyes with Playwright

To run Applitools Eyes with Playwright, install @applitools/eyes-playwright, set APPLITOOLS_API_KEY, import Applitools’ Playwright test fixture, and call eyes.check() at the UI states you want to compare. Eyes captures each checkpoint, compares it with a stored baseline, and reports visual differences for review.

1. Install and configure the SDK

Applitools’ March 2026 onboarding guide recommends installing the Playwright SDK and running its setup command. The setup flow configures imports and settings and adds a demo test. Check the current SDK setup guide if the command differs from the version you install.

npm install @applitools/eyes-playwright
npx eyes-playwright setup

Set the API key from your Applitools account as an environment variable. Keep it out of source files and version control; the dashboard documentation recommends this approach for the key used to execute tests.

# macOS or Linux
export APPLITOOLS_API_KEY="your-applitools-api-key"

# PowerShell
$env:APPLITOOLS_API_KEY="your-applitools-api-key"

In CI, add the key through the CI provider’s secret or environment-variable settings. Do not print it in job logs. See Applitools’ API key documentation.

2. Add a visual checkpoint to a Playwright test

Import test from @applitools/eyes-playwright/fixture instead of Playwright’s ordinary test import in files that use Eyes. The fixture supplies both Playwright’s page and an eyes object. Keep navigation and user interactions in Playwright, then add a descriptive checkpoint name at the state worth protecting.

import { test } from '@applitools/eyes-playwright/fixture';

test('homepage visual check', async ({ page, eyes }) => {
  await page.goto('https://example.com');

  await eyes.check('Homepage', {
    fully: true,
    matchLevel: 'Strict',
  });
});

This follows the documented integration example. The fixture handles Eyes lifecycle work such as opening and closing tests. Consult the current Applitools Playwright integration documentation for SDK-version-specific details.

A useful checkpoint name describes the visible state, such as Product page — details loaded or Checkout — address step. Add checks after the application has reached a stable, meaningful state rather than after every low-level action.

3. Choose full-page or focused capture

Use fully: true when the complete rendered page is the regression signal. For an isolated component, pass a locator as region so the checkpoint focuses on that component.

import { test } from '@applitools/eyes-playwright/fixture';

test('product card visual check', async ({ page, eyes }) => {
  await page.goto('https://example.com/products');

  const productCard = page.locator('[data-testid="product-card"]');
  await productCard.waitFor({ state: 'visible' });

  await eyes.check('Product card', {
    region: productCard,
    matchLevel: 'Strict',
  });
});

Checkpoint choice	Use it when	Trade-off
Full page with `fully: true`	Page composition, content placement, and page-wide rendering matter.	More of the page can vary, so unrelated dynamic content may complicate review.
Locator in `region`	A component has a distinct visual contract or needs independent coverage.	Changes outside the selected region are not covered by that checkpoint.

4. Tune visual matching only for known variation

The integration supports options that change what differences Eyes considers significant. Configure them around the regression signal the test is meant to protect, and keep the reason for each exception clear.

Option	Purpose	Practical guidance
`matchLevel`	Controls how a checkpoint is compared with its baseline. The guide recommends `Strict`.	Choose the matching behavior deliberately for the content under test; verify accepted values in the docs for your SDK version.
`region`	Limits a check to a locator or area.	Use for a component-level checkpoint with a clear boundary.
`ignoreRegions`	Marks areas whose visual differences should not affect comparison.	Ignore only expected variation that is outside the purpose of the test.
`floatingRegions`	Describes elements or containers that may move within a bounded area.	Use when position can vary but the element itself remains relevant.
`IgnoreDisplacements`	Suppresses differences caused by elements shifting position.	Use only when displacement is not the regression you need to catch.

Ignored or displacement-tolerant areas can hide real bugs if they cover too much. Start with the smallest exception that accounts for a known, harmless source of variation, then inspect subsequent results to ensure the checkpoint still tests what you intended. The option descriptions are documented in the integration guide.

5. Configure the Playwright report and Eyes behavior

To include Eyes visual-test information in Playwright’s enhanced HTML report, configure the Applitools reporter and open the report with Playwright’s report command.

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

export default defineConfig({
  reporter: [
    ['@applitools/eyes-playwright/reporter'],
    ['html'],
  ],
});

npx playwright show-report

The integration documentation also describes global eyesConfig options, including appName, batch, and failTestsOnDiff. The latter can be set to 'afterEach', 'afterAll', or false. Select failure timing to fit your CI and triage process. If diffs must block a deployment, avoid configuring them to be silently ignored.

// Example shape; confirm the supported config location and types
// for the SDK version in your project.
export default defineConfig({
  reporter: [['@applitools/eyes-playwright/reporter'], ['html']],
  use: {
    eyesConfig: {
      appName: 'Storefront',
      batch: 'Pull request checks',
      failTestsOnDiff: 'afterEach',
    },
  },
});

The configuration shape and supported options can vary by SDK version; use the current integration reference rather than copying an example blindly into an older project. The documented reporter adds Eyes details to the report and supports reviewing visual differences.

6. Review diffs and update baselines deliberately

Open the Playwright/Eyes report or the batch results in Eyes Test Manager.
Compare the current checkpoint with its baseline and inspect the highlighted differences.
Decide whether the UI change is intentional. Accept an intentional change to save the new baseline; reject an unintended change and investigate it.
After changing application code or a baseline, rerun the relevant test so the result reflects the current code and reference image.

A baseline is the reference used for future comparisons. Accepting a visual change updates that reference, so review the changed area before accepting. The dashboard documentation covers result review and baseline decisions.

7. Organize checks as the suite grows

For a first test, an inline eyes.check() is straightforward. In a larger suite, keep checks near the page actions that create the visible state. Applitools recommends descriptive checkpoint names and organizing visual checks in page-object methods or custom fixtures.

export class ProductPage {
  constructor(private page: import('@playwright/test').Page) {}

  async open(url: string) {
    await this.page.goto(url);
  }

  async expectProductDetails(eyes: {
    check(name: string, options?: Record<string, unknown>): Promise<unknown>;
  }) {
    await eyes.check('Product details', {
      region: this.page.locator('[data-testid="product-details"]'),
    });
  }
}

This is an organizational sketch; align fixture and type imports with the installed SDK version. Keep checkpoint names stable enough to understand results over time, and split checks when separate components or user-visible states need independent review.

8. Understand the capture and comparison flow

Your test drives the application in Playwright. At each visual checkpoint, the Eyes SDK captures the rendered state and sends it to Eyes Server. The server compares it with stored baselines and reports differences for review in Eyes Test Manager. Teams can review and update baselines or mark bugs and annotate regions. Applitools documents public cloud, dedicated cloud, and on-premises server configurations; choose the arrangement that matches your organization’s setup.

9. Troubleshooting

Symptom	Likely cause	What to do
Import for `@applitools/eyes-playwright/fixture` fails	The package is missing, the installed version differs from the example, or the project setup is incomplete.	Install the package, run the documented setup flow, and check the integration docs for the installed version’s import path.
Eyes cannot connect or tests are not associated with the account	`APPLITOOLS_API_KEY` is unset, misspelled, or unavailable to the test process.	Confirm the variable is set in the shell or CI job that launches Playwright. Keep the key secret and do not commit it.
Checkpoint is blank or captures the wrong state	The page has not navigated, loaded, or reached the intended UI state before the check.	Wait for a meaningful locator or application condition before `eyes.check()`; inspect the test’s navigation and interactions.
Many unexpected diffs appear	Dynamic content, an unstable test state, or a changed rendering environment may affect the checkpoint.	Stabilize the application state first. If a specific area is intentionally variable, configure a narrowly scoped ignore or floating region.
Every visual difference fails immediately	`failTestsOnDiff` may use an earlier failure point than the team’s review workflow expects.	Choose the documented `'afterEach'`, `'afterAll'`, or `false` behavior intentionally; ensure differences remain visible for review.
Eyes details do not show in the HTML report	The Applitools reporter may not be configured or the report may not have been opened.	Configure `@applitools/eyes-playwright/reporter` and run `npx playwright show-report`.
A setup or configuration option is unrecognized	Documentation and installed package versions may not match.	Check the current package documentation and migration guidance before changing a working project configuration.

10. Migration notes, runtime, and cost

Applitools’ March 11, 2026 SDK article says the updated Playwright SDK maintains backward compatibility and recommends trying a few tests in both SDK patterns, moving simpler tests first, then migrating critical tests gradually. Treat this as migration guidance, not a guarantee that every older project configuration works unchanged. Review the SDK launch article alongside your installed package version.

Each visual checkpoint adds capture and comparison work to a test run, and the documented flow sends captures to Eyes Server. The reviewed sources provide no measured runtime or performance figures, so measure your own suite with representative pages and checkpoints. Avoid redundant checkpoints that inspect the same state without adding coverage. For reliability, make the page state deterministic before capture, use focused regions where they match the test’s purpose, and review diffs rather than automatically accepting them.

Visual comparisons use the Eyes service and API key; check your Applitools account and plan for applicable usage and cost details. The sources reviewed for this guide do not establish current pricing, quotas, or a universal cost per checkpoint.

Or skip the browser setup

For a one-off screenshot or a capture pipeline that does not need a Playwright test, ScreenshotNeo is a website screenshot API and MCP server. A GET request returns a PNG, JPEG, WebP, or PDF. Here is the one-call WebP example; see the ScreenshotNeo API docs for options and response details.

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

ScreenshotNeo accepts cookie and consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets before the capture; each step can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits cost nothing, with the page verdict and billing status shown in response headers. Its MCP server gives AI agents tools to take screenshots, get page information, and capture PDFs. The free plan includes 1,000 screenshots each month with no card; paid plans start at $5 for 3,000 screenshots.

FAQ

Does Eyes replace Playwright assertions?

No. Keep functional assertions for behavior and use visual checkpoints to compare rendered appearance.

Should every test have an Eyes checkpoint?

No. Add checks at states where a visual regression would matter, and keep them distinct enough to provide useful coverage.

What happens when I accept a diff?

Accepting an intentional change updates the baseline used for future comparisons. Reject an unintended change so it remains available for investigation.