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.23

pageAssertions.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 (customized by maskColor) that completely covers its bounding box.
- maskColor string (optional) Added in: v1.35#
  
  Specify the color of the overlay box for masked elements, in CSS color format. Default color is pink #FF00FF.
- 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".
- stylePath string | Array<string> (optional) Added in: v1.41#
  
  File name containing the stylesheet to apply while making the screenshot. This is where you can hide dynamic elements, make elements invisible or change their properties to help you creating repeatable screenshots. This stylesheet pierces the Shadow DOM and applies to the inner frames.
- 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 in milliseconds. Defaults to timeout in TestConfig.expect.

Returns

Promise<void>#

toHaveScreenshot()

Added in: v1.23

pageAssertions.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 (customized by maskColor) that completely covers its bounding box.
- maskColor string (optional) Added in: v1.35#
  
  Specify the color of the overlay box for masked elements, in CSS color format. Default color is pink #FF00FF.
- 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".
- stylePath string | Array<string> (optional) Added in: v1.41#
  
  File name containing the stylesheet to apply while making the screenshot. This is where you can hide dynamic elements, make elements invisible or change their properties to help you creating repeatable screenshots. This stylesheet pierces the Shadow DOM and applies to the inner frames.
- 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 in milliseconds. Defaults to timeout in TestConfig.expect.

Returns

Promise<void>#

toHaveTitle

Added in: v1.20

pageAssertions.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 in milliseconds. Defaults to timeout in TestConfig.expect.

Returns

Promise<void>#

toHaveURL

Added in: v1.20

pageAssertions.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)
- ignoreCase boolean (optional) Added in: v1.44#
  
  Whether to perform case-insensitive match. ignoreCase option takes precedence over the corresponding regular expression flag if specified.
- timeout number (optional) Added in: v1.18#
  
  Time to retry the assertion for in milliseconds. Defaults to timeout in TestConfig.expect.

Returns

Promise<void>#

Properties

not

Added in: v1.20

pageAssertions.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

PageAssertions

Methods​

toHaveScreenshot(name)​

toHaveScreenshot()​

toHaveTitle​

toHaveURL​

Properties​

not​

Methods

toHaveScreenshot(name)

toHaveScreenshot()

toHaveTitle

toHaveURL

Properties

not