Skip to main content

Using eyes.check in Tests

The eyes object provided by the Applitools Eyes Playwright integration allows you to perform visual checkpoints using the eyes.check method. This method captures screenshots and compares them against their corresponding baselines.

Importing test and using eyes​

In your test files, import test from @applitools/eyes-playwright/fixture instead of @playwright/test.

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

test('Visual Test', async ({ page, eyes }) => {
  // Your test code...
});

To use Playwright's native expect.toHaveScreenshot methods with Applitools Eyes, import expect from @applitools/eyes-playwright/fixture:

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

Note: Tests using Playwright's expect(page).toHaveScreenshot() will work seamlessly with Applitools Eyes when imported from @applitools/eyes-playwright/fixture. However, it is recommended to use eyes.check for advanced visual testing features.

Performing visual checkpoints​

Use eyes.check within your tests to perform visual validations.

  • You can use multiple eyes.check calls within a single test.
  • The SDK automatically aligns and compares the checkpoints with the appropriate baseline steps.
  • Newly added or removed checks are automatically identified and addressed.
test('Multiple checkpoints', async ({ page, eyes }) => {
  await page.goto('https://example.com');

  // Check the home page
  await eyes.check('Home Page', {
    fully: true,
  });

  // Navigate and check another page
  await page.click('.dashboard-link');
  await eyes.check('Dashboard', {
    matchLevel: 'Layout',
  });
});

eyes.check method​

Syntax​

await eyes.check(name?, options?);

Parameters​

  • name (string, optional):
    The name of the checkpoint. This name appears in the HTML report and in the Applitools Dashboard.
  • options (object, optional):
    Configuration options for the visual checkpoint.

Options for eyes.check​

  • region (string | object):
    Specifies a region of the page to capture.

    • Selector:
      region: '#header',
    • Playwright Locator:
      region: page.locator('.content-section'),
    • Coordinates:
      { x: 100, y: 200, height: 50, width: 150 },

  • frames (array):
    Specifies frames to capture.

    frames: ['#main-frame', { frame: page.frame('sub-frame') }],

  • matchLevel (string):
    Overrides the match level for this checkpoint.
    Possible values: 'Strict', 'Layout', 'IgnoreColors', 'Dynamic'.

    matchLevel: 'Layout',

  • ignoreRegions (array):
    Regions to ignore during visual comparison.

ignoreRegions: [
  page.locator('.dynamic-banner'),
  { x: 100, y: 200, width: 300, height: 50 },
],
  • layoutRegions, strictRegions, dynamicRegions, contentRegions, floatingRegions:
    Regions with specific match levels or behaviors.
layoutRegions: [page.locator('.sidebar')],
floatingRegions: [
  {
    region: page.locator('.floating-button'),
    maxUpOffset: 10,
    maxDownOffset: 10,
    maxLeftOffset: 5,
    maxRightOffset: 5,
  },
],
  • accessibilityRegions (array):
    Regions with specific accessibility levels.
  accessibilityRegions: [
    {
      region: page.locator('.important-text'),
      type: 'LargeText',
    },
  ],

  • fully (boolean):
    If true, captures a full-page screenshot.

    fully: true,

  • scrollRootElement (string | object):
    Overrides the global scrollRootElement for this checkpoint.

  scrollRootElement: '#content',
  // Or using a locator:
  scrollRootElement: page.locator('#content'),
  • hooks (object):
    JavaScript code to run before capturing the screenshot.
  hooks: {
    beforeCaptureScreenshot: "document.querySelector('#ad-banner').style.display = 'none';",
  },

  • waitBeforeCapture (number | function):
    Time in milliseconds to wait before capturing the screenshot, or a function (sync or async) to execute before capturing.

    waitBeforeCapture: 500,

    waitBeforeCapture: async () => { /* custom logic */ },

  • sendDom (boolean):
    If true, sends the DOM snapshot along with the screenshot.

    sendDom: true,

  • useDom (boolean):
    If true, uses the DOM information to assist in visual comparisons.

    useDom: true,

  • enablePatterns (boolean):
    Enables pattern matching in visual comparisons for this checkpoint.

    enablePatterns: true,

  • ignoreDisplacements (boolean):
    If true, ignores vertical shifts in content during visual comparisons. It is useful for reducing diff noise when the UI changes frequently.

    ignoreDisplacements: true,

  • ignoreCaret (boolean):
    If true, ignores the blinking caret in text inputs during visual comparisons.

    ignoreCaret: true,

  • layoutBreakpoints (boolean | number[] | { breakpoints: boolean | number[], reload?: boolean }):
    Enables responsive design testing at specified breakpoints.

    • If true, breakpoints are inferred from the application's CSS.
    • If an array of numbers, specifies the widths at which to capture screenshots.
    • If an object with breakpoints and reload: true, the page is reloaded at each breakpoint instead of just resized. Use this for applications that determine their layout only on the initial page load and do not adapt automatically when the browser window is resized.

    Note: This option is relevant only for UFG. It allows the SDK to fetch viewport-specific resources, which are subsequently used for rendering on the UFG. This is rarely needed, but when necessary, it's crucial for accurate rendering.

// Array form
layoutBreakpoints: [320, 768, 1024],

// Object form — reloads the page at each breakpoint
layoutBreakpoints: { breakpoints: [320, 768, 1024], reload: true },

  • visualGridOptions (object):
    Additional options for the Ultrafast Grid rendering.

    • chromeHeadless (boolean):
      Set to false to use regular Chrome instead of Headless Chrome.

    • polyfillAdoptedStyleSheets (boolean):
      Controls the polyfill for Adopted StyleSheets.

visualGridOptions: {
  chromeHeadless: false,
  polyfillAdoptedStyleSheets: true,
},

Example usage​

test('Visual Test with Regions', async ({ page, eyes }) => {
  await page.goto('https://example.com');

  await eyes.check('Main Page', {
    fully: true,
    matchLevel: 'Strict',
    ignoreRegions: [page.locator('.dynamic-content')],
    layoutRegions: [page.locator('.sidebar')],
    floatingRegions: [
      {
        region: page.locator('.floating-ad'),
        maxUpOffset: 10,
        maxDownOffset: 10,
        maxLeftOffset: 5,
        maxRightOffset: 5,
      },
    ],
    accessibilityRegions: [
      {
        region: page.locator('.important-heading'),
        type: 'BoldText',
      },
    ],
    hooks: {
      beforeCaptureScreenshot:
        "document.querySelector('.modal').style.display = 'none';",
    },
    waitBeforeCapture: 1000,
  });
});

Multiple Pages (Tabs / Popups / Windows) Screenshot​

You can capture a screenshot of a new tab, popup, or browser window by calling expect().toHaveScreenshot() and explicitly passing the corresponding Page object for that tab, popup, or window.

In Playwright, each tab or window is represented as a separate Page instance. To capture a screenshot of a specific tab or popup, you must pass its Page reference to expect().

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

test('Multiple windows in one Eyes session using Fixtures', async ({ page, context, eyes }) => {
  await page.goto('https://the-internet.herokuapp.com/windows');

  // Screenshot of initial page
  await expect(page).toHaveScreenshot('Initial Page', { fullPage: true });

  // Wait for new tab to open
  const [newTab] = await Promise.all([
    page.waitForEvent('popup'),
    page.click('//a[normalize-space()="Click Here"]')
  ]);

  await newTab.waitForLoadState('load');

  // Screenshot of new tab
  await expect(newTab).toHaveScreenshot('New Tab Page', { fullPage: true });

  // Screenshot of initial page again
  await expect(page).toHaveScreenshot('Initial Page Back Again', { fullPage: true });
});