PageAssertions

PageAssertions 类提供了断言方法，可用于对测试中的 Page 状态进行断言。

¥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');

请注意，屏幕截图断言仅适用于 Playwright 测试运行程序。

¥Note that screenshot assertions only work with Playwright test runner.

参数

¥Arguments

name string | Array<string>#

快照名称。

¥Snapshot name.

options Object (optional)

animations "disabled" | "allow"（可选）#

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

当设置为 "disabled" 时，停止 CSS 动画、CSS 转场和 Web 动画。动画根据其持续时间得到不同的处理：

¥When set to "disabled", stops CSS animations, CSS transitions and Web Animations. Animations get different treatment depending on their duration:
- 有限动画会快进完成，因此它们会触发 transitionend 事件。
  
  ¥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.
默认为 "disabled"，禁用动画。

¥Defaults to "disabled" that disables animations.
caret "hide" | "initial"（可选）#

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

当设置为 "hide" 时，屏幕截图将隐藏文本插入符。当设置为 "initial" 时，文本插入符行为将不会更改。默认为 "hide"。

¥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 坐标

¥x-coordinate of top-left corner of clip area

y number

剪辑区域左上角的 y 坐标

¥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)#

如果为 true，则截取完整可滚动页面的屏幕截图，而不是当前可见的视口。默认为 false。

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

mask Array<Locator> (optional)#

指定截取屏幕截图时应屏蔽的定位器。被遮罩的元素将被一个粉色框 #FF00FF（由 maskColor 定制）覆盖，完全覆盖其边界框。

¥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#

指定屏蔽元素的覆盖框的颜色，以 CSS 颜色格式为单位。默认颜色为粉色 #FF00FF。

¥Specify the color of the overlay box for masked elements, in CSS color format. Default color is pink #FF00FF.

maxDiffPixelRatio number (optional)#

可接受的不同于像素总数的像素比例，介于 0 和 1 之间。默认值可通过 TestConfig.expect 配置。默认情况下取消设置。

¥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)#

可接受的像素数量，可能有所不同。默认值可通过 TestConfig.expect 配置。默认情况下取消设置。

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

omitBackground boolean (optional)#

隐藏默认的白色背景并允许捕获透明的屏幕截图。不适用于 jpeg 图片。默认为 false。

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

scale "css" | "device"（可选）#

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

当设置为 "css" 时，屏幕截图页面上的每个 css 像素将有一个像素。对于高 dpi 设备，这将使屏幕截图保持较小。使用 "device" 选项将为每个设备像素生成一个像素，因此高 dpi 设备的屏幕截图将是原来的两倍甚至更大。

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

默认为 "css"。

¥Defaults to "css".
- stylePath string | Array<string> (optional) Added in: v1.41#

包含制作屏幕截图时要应用的样式表的文件名。你可以在此处隐藏动态元素、使元素不可见或更改其属性以帮助你创建可重复的屏幕截图。该样式表穿透 Shadow DOM 并应用于内部框架。

¥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)#

比较图片中相同像素之间可接受的 YIQ 色彩空间感知色差，介于零（严格）和一（宽松）之间，默认值可通过 TestConfig.expect 配置。默认为 0.2。

¥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)#

重试断言的时间（以毫秒为单位）。默认为 TestConfig.expect 中的 timeout。

¥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();

请注意，屏幕截图断言仅适用于 Playwright 测试运行程序。

¥Note that screenshot assertions only work with Playwright test runner.

参数

¥Arguments

options Object (optional)

animations "disabled" | "allow"（可选）#

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

当设置为 "disabled" 时，停止 CSS 动画、CSS 转场和 Web 动画。动画根据其持续时间得到不同的处理：

¥When set to "disabled", stops CSS animations, CSS transitions and Web Animations. Animations get different treatment depending on their duration:
- 有限动画会快进完成，因此它们会触发 transitionend 事件。
  
  ¥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.
默认为 "disabled"，禁用动画。

¥Defaults to "disabled" that disables animations.
caret "hide" | "initial"（可选）#

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

当设置为 "hide" 时，屏幕截图将隐藏文本插入符。当设置为 "initial" 时，文本插入符行为将不会更改。默认为 "hide"。

¥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 坐标

¥x-coordinate of top-left corner of clip area

y number

剪辑区域左上角的 y 坐标

¥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)#

如果为 true，则截取完整可滚动页面的屏幕截图，而不是当前可见的视口。默认为 false。

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

mask Array<Locator> (optional)#

指定截取屏幕截图时应屏蔽的定位器。被遮罩的元素将被一个粉色框 #FF00FF（由 maskColor 定制）覆盖，完全覆盖其边界框。

¥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#

指定屏蔽元素的覆盖框的颜色，以 CSS 颜色格式为单位。默认颜色为粉色 #FF00FF。

¥Specify the color of the overlay box for masked elements, in CSS color format. Default color is pink #FF00FF.

maxDiffPixelRatio number (optional)#

可接受的不同于像素总数的像素比例，介于 0 和 1 之间。默认值可通过 TestConfig.expect 配置。默认情况下取消设置。

¥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)#

可接受的像素数量，可能有所不同。默认值可通过 TestConfig.expect 配置。默认情况下取消设置。

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

omitBackground boolean (optional)#

隐藏默认的白色背景并允许捕获透明的屏幕截图。不适用于 jpeg 图片。默认为 false。

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

scale "css" | "device"（可选）#

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

当设置为 "css" 时，屏幕截图页面上的每个 css 像素将有一个像素。对于高 dpi 设备，这将使屏幕截图保持较小。使用 "device" 选项将为每个设备像素生成一个像素，因此高 dpi 设备的屏幕截图将是原来的两倍甚至更大。

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

默认为 "css"。

¥Defaults to "css".
- stylePath string | Array<string> (optional) Added in: v1.41#

threshold number (optional)#

比较图片中相同像素之间可接受的 YIQ 色彩空间感知色差，介于零（严格）和一（宽松）之间，默认值可通过 TestConfig.expect 配置。默认为 0.2。

timeout number (optional)#

重试断言的时间（以毫秒为单位）。默认为 TestConfig.expect 中的 timeout。

¥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#

重试断言的时间（以毫秒为单位）。默认为 TestConfig.expect 中的 timeout。

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

¥Returns

Promise<void>#

toHaveURL

Added in: v1.20

pageAssertions.toHaveURL

确保页面导航到给定的 URL。

¥Ensures the page is navigated to the given URL.

用法

¥Usage

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

参数

¥Arguments

urlOrRegExp string | RegExp Added in: v1.18#

预期的 URL 字符串或正则表达式。

¥Expected URL string or RegExp.

options Object (optional)
- ignoreCase boolean (optional) Added in: v1.44#

是否进行不区分大小写的匹配。如果指定，ignoreCase 选项优先于相应的正则表达式标志。

¥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#

重试断言的时间（以毫秒为单位）。默认为 TestConfig.expect 中的 timeout。

¥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

使断言检查相反的条件。例如，此代码测试页面 URL 是否不包含 "error"：

¥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

方法​

toHaveScreenshot(name)​

toHaveScreenshot()​

toHaveTitle​

toHaveURL​

属性​

not​

方法

toHaveScreenshot(name)

toHaveScreenshot()

toHaveTitle

toHaveURL

属性

not