Applitools Eyes Playwright Tutorial for Indian QA Testers

To use Applitools Eyes with Playwright, install @applitools/eyes-playwright, configure your Applitools API key, import Playwright’s test fixture from the Applitools package, and add a named eyes.check() checkpoint after the page reaches the state you want to compare. Review each difference before accepting it as a new baseline.

This tutorial uses JavaScript with the Playwright Test runner and the Applitools Eyes Playwright fixture. The same language path works in a TypeScript project with suitable TypeScript configuration. Applitools also lists Playwright SDK paths for Java, C#, and Python; those are separate SDK instructions. There is no India-specific SDK variant. See the Applitools Playwright integration documentation and SDK selection guide.

1. Prerequisites and project setup

You need Node.js, npm, an IDE, basic JavaScript familiarity, and a Playwright project. If you do not have one yet, make a project and add Playwright Test:

mkdir eyes-playwright-demo
cd eyes-playwright-demo
npm init -y
npm install -D @playwright/test
npx playwright install

Applitools cloud execution requires an Applitools account and API key. Keep the key in an environment variable; do not commit it to source control or paste it into a test file.

# macOS or Linux, for the current terminal session
export APPLITOOLS_API_KEY="YOUR_API_KEY"

# PowerShell, for the current terminal session
$env:APPLITOOLS_API_KEY="YOUR_API_KEY"

In CI, add APPLITOOLS_API_KEY through the CI platform’s protected secret settings. The official Applitools Playwright workshop identifies this environment variable as required for visual tests to connect to the Applitools cloud.

2. Install the Applitools Playwright SDK

Install the package as a development dependency and run its setup CLI:

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

The setup tool can add configuration to Playwright, adjust imports where it can, and add a demo test. Review the changed files before keeping them: automated import changes may not cover every project structure, so follow up manually when needed. Consult the current npm package instructions for the latest setup behavior; package versions and CLI details can change.

For the documented JavaScript fixture path, import test from @applitools/eyes-playwright/fixture. This extended test fixture supplies the eyes object to each test callback.

3. Add your first visual checkpoint

Create tests/homepage.spec.js with a stable page state and a descriptive checkpoint name:

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

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

  // Wait for a meaningful page condition if navigation alone is not enough.
  await page.getByRole('heading', { name: 'Example Domain' }).waitFor();

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

Run it with Playwright Test:

npx playwright test tests/homepage.spec.js

fully: true requests a full-page checkpoint rather than only the currently visible viewport. matchLevel: 'Strict' selects strict visual matching, a documented recommended value. The checkpoint name makes results identifiable in the dashboard. Use a stable target URL and wait for the content that defines the intended visual state before capturing.

4. Choose checkpoint scope and comparison behavior

Need	Option	Effect and guidance
Compare an entire page	`fully: true`	Captures the full page, including content below the initial viewport. Use when page-wide layout matters.
Compare one component	`region: locator`	Limits the checkpoint to a selected element or region. Useful for a navigation bar, card, or form whose appearance matters independently.
Choose visual sensitivity	`matchLevel`	Controls how Eyes compares the image with its baseline. The integration docs demonstrate `Strict` and `Layout`; choose deliberately for the UI contract being checked.
Exclude unpredictable pixels	`ignoreRegions`	Excludes known dynamic areas from visual comparison. Keep ignored regions as small as possible so genuine regressions remain visible.
Allow elements to move	`floatingRegions`	Identifies regions whose position can vary while their visual content remains relevant; use only for genuinely movable content.
Suppress position shifts	`IgnoreDisplacements`	The docs list this option for displacement differences. Verify the exact option syntax for the installed SDK before using it.

For example, to check just a navigation element with a layout-oriented comparison:

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

test('navigation layout', async ({ page, eyes }) => {
  await page.goto('https://example.com');
  const navigation = page.locator('nav');
  await navigation.waitFor();

  await eyes.check('Primary navigation', {
    region: navigation,
    matchLevel: 'Layout',
  });
});

To ignore a genuinely changing region, such as a rotating promotion, use a locator:

await eyes.check('Homepage without rotating promotion', {
  fully: true,
  matchLevel: 'Strict',
  ignoreRegions: [page.locator('[data-testid="rotating-promotion"]')],
});

Do not mask a large area to silence failures. If the area is important to users, stabilize its data or test a controlled state instead. The current SDK’s precise accepted values and option types should be checked against its integration docs and package types.

5. Review visual diffs and update baselines carefully

Open the enhanced Applitools report after a run. It presents the current image and baseline for comparison, with differences highlighted. For each change, ask whether it matches the intended design or behavior:

Inspect the changed pixels and the surrounding page context.
Check the associated code or design change and confirm the difference is expected.
Accept an intentional change to save the new checkpoint as the baseline.
Reject an unexpected change so it remains a failure to investigate.

Accepting a diff updates the reference image; it does not prove the new UI is correct. Baseline review is a design decision, so teams should agree who can approve it and when. The enhanced report supports side-by-side review and accept or reject actions. See the report and review guidance.

6. Configure the enhanced Playwright report

The integration documentation shows this reporter configuration in playwright.config.ts:

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

export default defineConfig<EyesFixture>({
  testDir: './tests',
  reporter: '@applitools/eyes-playwright/reporter',
});

If your project uses the Applitools setup CLI, the reporter setting may already be present. After the run, open the report with:

npx playwright show-report

Review the generated report and CI artifact handling against the current package version. The documentation also describes saving reports as CI artifacts for team review.

7. Set shared Eyes configuration

For suite-wide defaults, the documentation demonstrates eyesConfig in Playwright’s config. For example:

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

export default defineConfig<EyesFixture>({
  testDir: './tests',
  use: {
    eyesConfig: {
      appName: 'My Web App',
      failTestsOnDiff: 'afterEach',
    },
  },
});

The documented shared settings include:

appName: a default application name for organizing visual tests.
batch: batch information used to group tests.
failTestsOnDiff: when differences cause exceptions; documented values include 'afterEach', 'afterAll', or false.

Pick failure timing to match how your runner and CI report results. Confirm option types against the installed package because SDK configuration evolves.

8. Organize checks for a growing suite

For a small suite, keeping eyes.check() in the test is straightforward. If multiple tests share page setup and checkpoint behavior, a page object can hold the Playwright page and Eyes fixture and expose a named visual-check method. This is optional; use it when it reduces duplication.

export class HomePage {
  constructor(page, eyes) {
    this.page = page;
    this.eyes = eyes;
  }

  async open() {
    await this.page.goto('https://example.com');
  }

  async checkAppearance() {
    await this.eyes.check('Homepage', { fully: true });
  }
}

Then a test can construct the page object and call its methods. Keep the checkpoint name meaningful and avoid hiding important test state transitions inside a generic helper.

9. India-specific setup and account notes

The SDK installation and Playwright fixture steps described here are the same documented integration regardless of the tester’s location. This research does not establish India-specific pricing, plan limits, payment methods, data residency, or regional availability for Applitools, so verify current terms directly with Applitools before making a purchasing or data-handling decision. JavaScript familiarity is recommended in the referenced Playwright course; a QA tester new to JavaScript should first become comfortable with imports, async functions, npm, and Playwright locators.

10. Troubleshooting

Symptom	Likely cause	Fix
`Cannot find module '@applitools/eyes-playwright/fixture'`	The package is missing, install failed, or the test imports from the wrong path.	Run `npm install -D @applitools/eyes-playwright`, then use the documented fixture import and rerun setup if needed.
`eyes` is undefined in the callback	The test imported Playwright’s standard `test` instead of the Applitools fixture.	Import `test` from `@applitools/eyes-playwright/fixture` and use the `eyes` fixture parameter.
Cloud connection or API-key error	`APPLITOOLS_API_KEY` is unset, misspelled, unavailable to the process, or invalid.	Set the environment variable in the same shell or CI job that runs Playwright; keep the value out of committed files.
Setup CLI did not change an import or config	The CLI could not automatically handle that project structure.	Inspect its changes and add the fixture import or documented config manually.
Unexpected full-page differences	The page was captured before it reached a stable state, or has time-dependent content.	Wait for a meaningful locator, control test data where possible, and ignore only the smallest truly unpredictable region.
Element checkpoint is empty or incorrect	The locator matched the wrong element, no element was ready, or the region is outside the intended state.	Use a precise locator, wait for it to appear, and confirm that it identifies the component being checked.
Every changed baseline is being treated as correct	Accepting differences was used as a shortcut rather than a review decision.	Compare with the intended design and investigate unexpected pixels before accepting; rejection keeps the difference flagged.
Reporter configuration type or module error	The config does not match the project’s module format or installed SDK version.	Compare the import and reporter setup with current Applitools integration docs and review CLI-generated configuration.

11. Performance, reliability, and cost considerations

Visual checks add capture and comparison work to a browser test, and full-page checks cover more content than an element checkpoint. Use a whole-page checkpoint when the page as a whole is the contract; use a region when a component is the target. Stable page state, deterministic test data, and narrow ignore regions reduce noisy review work. The sources reviewed here do not establish a benchmark or an India-specific price, so do not estimate speed or local cost from this tutorial.

For reliability, protect the API key, make CI secrets available to the test process, keep checkpoint names stable, review diffs, and preserve reports as CI artifacts when the team needs shared review. An accepted baseline should represent an intentional and reviewed UI state.

Or skip the browser setup

If you need a screenshot of a URL rather than an automated visual regression test, ScreenshotNeo is a website screenshot API and MCP server. One GET request can return a PNG, JPEG, WebP, or PDF. Its browser setup can accept cookie or consent banners and remove more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers report the page verdict and billing status. An MCP server exposes screenshot tools for AI agents. The free plan includes 1,000 screenshots per month without a card; paid plans start at $5 for 3,000.

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

See the ScreenshotNeo API documentation for request options. It is an alternative for capturing page images, not a replacement for Applitools’ baseline review workflow.

FAQ

Can I use Applitools Eyes with Playwright in Python?

Applitools lists a Playwright for Python SDK path, alongside Java and C#. This tutorial’s fixture code and npm package are specifically for JavaScript/TypeScript; use the matching language’s official SDK instructions.

Should every checkpoint capture the full page?

No. Use full-page capture when page-wide appearance matters. A region checkpoint is more focused when the test is about one component.

Does accepting a diff mean the design change is correct?

No. It saves the new image as the baseline. Review it against the intended design before accepting.

Do I need page objects to add visual checks?

No. Inline checks are suitable for small suites. Page objects are an organizational option when they make shared navigation and checkpoints easier to maintain.