Skip to main content

PageAssertions

The PageAssertions class provides assertion methods that can be used to make assertions about the Page state in the tests.

import { test, expect } from '@playwright/test';

test('navigates to login', async ({ page }) => {
  // ...
  await page.getByText('Sign in').click();
  await expect(page).toHaveURL(/.*\/login/);
});

Methods​

toHaveScreenshot(name)​

Added in: v1.23pageAssertions.toHaveScreenshot(name)

This function will wait until two consecutive page screenshots yield the same result, and then compare the last screenshot with the expectation.

Usage

await expect(page).toHaveScreenshot('image.png');

Note that screenshot assertions only work with Playwright test runner.

Arguments

  • name string|Array<string>#

    Snapshot name.

  • options Object (optional)

    • animations "disabled"|"allow" (optional)#

      When set to "disabled", stops CSS animations, CSS transitions and Web Animations. Animations get different treatment depending on their duration:

      • finite animations are fast-forwarded to completion, so they'll fire transitionend event.
      • infinite animations are canceled to initial state, and then played over after the screenshot.

      Defaults to "disabled" that disables animations.

    • caret "hide"|"initial" (optional)#

      When set to "hide", screenshot will hide text caret. When set to "initial", text caret behavior will not be changed. Defaults to "hide".

    • clip Object (optional)#

      • x number

        x-coordinate of top-left corner of clip area

      • y number

        y-coordinate of top-left corner of clip area

      • width number

        width of clipping area

      • height number

        height of clipping area

      An object which specifies clipping of the resulting image.

    • fullPage boolean (optional)#

      When true, takes a screenshot of the full scrollable page, instead of the currently visible viewport. Defaults to false.

    • mask Array<Locator> (optional)#

      Specify locators that should be masked when the screenshot is taken. Masked elements will be overlaid with a pink box #FF00FF that completely covers its bounding box.

    • maxDiffPixelRatio number (optional)#

      An acceptable ratio of pixels that are different to the total amount of pixels, between 0 and 1. Default is configurable with TestConfig.expect. Unset by default.

    • maxDiffPixels number (optional)#

      An acceptable amount of pixels that could be different. Default is configurable with TestConfig.expect. Unset by default.

    • omitBackground boolean (optional)#

      Hides default white background and allows capturing screenshots with transparency. Not applicable to jpeg images. Defaults to false.

    • scale "css"|"device" (optional)#

      When set to "css", screenshot will have a single pixel per each css pixel on the page. For high-dpi devices, this will keep screenshots small. Using "device" option will produce a single pixel per each device pixel, so screenshots of high-dpi devices will be twice as large or even larger.

      Defaults to "css".

    • threshold number (optional)#

      An acceptable perceived color difference in the YIQ color space between the same pixel in compared images, between zero (strict) and one (lax), default is configurable with TestConfig.expect. Defaults to 0.2.

    • timeout number (optional)#

      Time to retry the assertion for. Defaults to timeout in TestConfig.expect.

toHaveScreenshot()​

Added in: v1.23pageAssertions.toHaveScreenshot()

This function will wait until two consecutive page screenshots yield the same result, and then compare the last screenshot with the expectation.

Usage

await expect(page).toHaveScreenshot();

Note that screenshot assertions only work with Playwright test runner.

Arguments

  • options Object (optional)

    • animations "disabled"|"allow" (optional)#

      When set to "disabled", stops CSS animations, CSS transitions and Web Animations. Animations get different treatment depending on their duration:

      • finite animations are fast-forwarded to completion, so they'll fire transitionend event.
      • infinite animations are canceled to initial state, and then played over after the screenshot.

      Defaults to "disabled" that disables animations.

    • caret "hide"|"initial" (optional)#

      When set to "hide", screenshot will hide text caret. When set to "initial", text caret behavior will not be changed. Defaults to "hide".

    • clip Object (optional)#

      • x number

        x-coordinate of top-left corner of clip area

      • y number

        y-coordinate of top-left corner of clip area

      • width number

        width of clipping area

      • height number

        height of clipping area

      An object which specifies clipping of the resulting image.

    • fullPage boolean (optional)#

      When true, takes a screenshot of the full scrollable page, instead of the currently visible viewport. Defaults to false.

    • mask Array<Locator> (optional)#

      Specify locators that should be masked when the screenshot is taken. Masked elements will be overlaid with a pink box #FF00FF that completely covers its bounding box.

    • maxDiffPixelRatio number (optional)#

      An acceptable ratio of pixels that are different to the total amount of pixels, between 0 and 1. Default is configurable with TestConfig.expect. Unset by default.

    • maxDiffPixels number (optional)#

      An acceptable amount of pixels that could be different. Default is configurable with TestConfig.expect. Unset by default.

    • omitBackground boolean (optional)#

      Hides default white background and allows capturing screenshots with transparency. Not applicable to jpeg images. Defaults to false.

    • scale "css"|"device" (optional)#

      When set to "css", screenshot will have a single pixel per each css pixel on the page. For high-dpi devices, this will keep screenshots small. Using "device" option will produce a single pixel per each device pixel, so screenshots of high-dpi devices will be twice as large or even larger.

      Defaults to "css".

    • threshold number (optional)#

      An acceptable perceived color difference in the YIQ color space between the same pixel in compared images, between zero (strict) and one (lax), default is configurable with TestConfig.expect. Defaults to 0.2.

    • timeout number (optional)#

      Time to retry the assertion for. Defaults to timeout in TestConfig.expect.

toHaveTitle​

Added in: v1.20pageAssertions.toHaveTitle

Ensures the page has the given title.

Usage

await expect(page).toHaveTitle(/.*checkout/);

Arguments

  • titleOrRegExp string|RegExp Added in: v1.18#

    Expected title or RegExp.

  • options Object (optional)

    • timeout number (optional) Added in: v1.18#

      Time to retry the assertion for. Defaults to timeout in TestConfig.expect.

toHaveURL​

Added in: v1.20pageAssertions.toHaveURL

Ensures the page is navigated to the given URL.

Usage

await expect(page).toHaveURL(/.*checkout/);

Arguments

  • urlOrRegExp string|RegExp Added in: v1.18#

    Expected URL string or RegExp.

  • options Object (optional)

    • timeout number (optional) Added in: v1.18#

      Time to retry the assertion for. Defaults to timeout in TestConfig.expect.

Properties​

not​

Added in: v1.20pageAssertions.not

Makes the assertion check for the opposite condition. For example, this code tests that the page URL doesn't contain "error":

await expect(page).not.toHaveURL('error');

Usage

expect(page).not

Type