PageAssertions

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

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

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

方法

toHaveScreenshot(name)

添加于：v1.23

pageAssertions.toHaveScreenshot(name)

此函数将等待直到两个连续的页面截图产生相同的结果，然后将最后一次截图与预期进行比较。

用法

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

注意，截图断言仅适用于 Playwright 测试运行器。

参数

name string | Array<string>#

快照名称。
options Object (可选)
- animations "disabled" | "allow" (可选)#
  
  设置为 "disabled" 时，停止 CSS 动画、CSS 过渡和 Web 动画。动画的处理方式因其持续时间而异
  - 有限动画会快进到完成，因此它们会触发 transitionend 事件。
  - 无限动画会取消到初始状态，然后在截图后重新播放。
  默认为 "disabled"，表示禁用动画。
- caret "hide" | "initial" (可选)#
  
  设置为 "hide" 时，截图将隐藏文本插入符号。设置为 "initial" 时，文本插入符号行为不会更改。默认为 "hide"。
- clip Object (可选)#
  - x 数字
    
    裁剪区域左上角的 x 坐标
  - y 数字
    
    裁剪区域左上角的 y 坐标
  - width number
    
    裁剪区域的宽度
  - height number
    
    裁剪区域的高度
  一个指定结果图像裁剪的对象。
- fullPage boolean (可选)#
  
  当为 true 时，截取整个可滚动页面的截图，而不是当前可见的视口。默认为 false。
- mask Array<Locator> (可选)#
  
  指定在截图时应被遮盖的定位器。被遮盖的元素将被一个完全覆盖其边界框的粉色框 #FF00FF（可通过 maskColor 自定义）覆盖。该遮罩也适用于不可见元素，请参阅仅匹配可见元素以禁用此行为。
- maskColor 字符串 (可选)添加于：v1.35#
  
  指定遮盖元素的覆盖框颜色，采用 CSS 颜色格式。默认颜色为粉红色 #FF00FF。
- maxDiffPixelRatio number (可选)#
  
  像素差异与总像素量的可接受比率，介于 0 和 1 之间。默认可通过 TestConfig.expect 配置。默认未设置。
- maxDiffPixels number (可选)#
  
  可接受的像素差异数量。默认可通过 TestConfig.expect 配置。默认未设置。
- omitBackground boolean (可选)#
  
  隐藏默认的白色背景并允许捕获透明截图。不适用于 jpeg 图像。默认为 false。
- scale "css" | "device" (可选)#
  
  设置为 "css" 时，截屏将具有页面上每个 CSS 像素的单个像素。对于高 DPI 设备，这将保持截屏较小。使用 "device" 选项将产生每个设备像素的单个像素，因此高 DPI 设备的截屏将大两倍或更大。
  
  默认为 "css"。
- stylePath string | Array<string> (optional)新增于: v1.41#
  
  包含在进行截图时应用的样式表的文件名。你可以在此处隐藏动态元素、使元素不可见或更改其属性，以帮助创建可重复的截图。此样式表会穿透 Shadow DOM 并应用于内部框架。
- threshold number (可选)#
  
  在比较的图像中，相同像素之间在 YIQ 颜色空间中可接受的感知颜色差异，范围从零（严格）到一（宽松），默认值可通过 TestConfig.expect 配置。默认为 0.2。
- timeout number (可选)#
  
  重试断言的超时时间（以毫秒为单位）。默认为 TestConfig.expect 中的 timeout。

Promise<void>#

toHaveScreenshot(options)

添加于：v1.23

pageAssertions.toHaveScreenshot(options)

此函数将等待直到两个连续的页面截图产生相同的结果，然后将最后一次截图与预期进行比较。

用法

await expect(page).toHaveScreenshot();

注意，截图断言仅适用于 Playwright 测试运行器。

参数

options Object (可选)
- animations "disabled" | "allow" (可选)#
  
  设置为 "disabled" 时，停止 CSS 动画、CSS 过渡和 Web 动画。动画的处理方式因其持续时间而异
  - 有限动画会快进到完成，因此它们会触发 transitionend 事件。
  - 无限动画会取消到初始状态，然后在截图后重新播放。
  默认为 "disabled"，表示禁用动画。
- caret "hide" | "initial" (可选)#
  
  设置为 "hide" 时，截图将隐藏文本插入符号。设置为 "initial" 时，文本插入符号行为不会更改。默认为 "hide"。
- clip Object (可选)#
  - x 数字
    
    裁剪区域左上角的 x 坐标
  - y 数字
    
    裁剪区域左上角的 y 坐标
  - width number
    
    裁剪区域的宽度
  - height number
    
    裁剪区域的高度
  一个指定结果图像裁剪的对象。
- fullPage boolean (可选)#
  
  当为 true 时，截取整个可滚动页面的截图，而不是当前可见的视口。默认为 false。
- mask Array<Locator> (可选)#
  
  指定在截图时应被遮盖的定位器。被遮盖的元素将被一个完全覆盖其边界框的粉色框 #FF00FF（可通过 maskColor 自定义）覆盖。该遮罩也适用于不可见元素，请参阅仅匹配可见元素以禁用此行为。
- maskColor 字符串 (可选)添加于：v1.35#
  
  指定遮盖元素的覆盖框颜色，采用 CSS 颜色格式。默认颜色为粉红色 #FF00FF。
- maxDiffPixelRatio number (可选)#
  
  像素差异与总像素量的可接受比率，介于 0 和 1 之间。默认可通过 TestConfig.expect 配置。默认未设置。
- maxDiffPixels number (可选)#
  
  可接受的像素差异数量。默认可通过 TestConfig.expect 配置。默认未设置。
- omitBackground boolean (可选)#
  
  隐藏默认的白色背景并允许捕获透明截图。不适用于 jpeg 图像。默认为 false。
- scale "css" | "device" (可选)#
  
  设置为 "css" 时，截屏将具有页面上每个 CSS 像素的单个像素。对于高 DPI 设备，这将保持截屏较小。使用 "device" 选项将产生每个设备像素的单个像素，因此高 DPI 设备的截屏将大两倍或更大。
  
  默认为 "css"。
- stylePath string | Array<string> (optional)新增于: v1.41#
  
  包含在进行截图时应用的样式表的文件名。你可以在此处隐藏动态元素、使元素不可见或更改其属性，以帮助创建可重复的截图。此样式表会穿透 Shadow DOM 并应用于内部框架。
- threshold number (可选)#
  
  在比较的图像中，相同像素之间在 YIQ 颜色空间中可接受的感知颜色差异，范围从零（严格）到一（宽松），默认值可通过 TestConfig.expect 配置。默认为 0.2。
- timeout number (可选)#
  
  重试断言的超时时间（以毫秒为单位）。默认为 TestConfig.expect 中的 timeout。

Promise<void>#

toHaveTitle

新增于: v1.20

pageAssertions.toHaveTitle

确保页面具有给定的标题。

用法

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

参数

titleOrRegExp string | RegExp新增于: v1.18#

预期的标题或正则表达式。
options Object (可选)
- timeout 数字 (可选)新增于: v1.18#
  
  重试断言的超时时间（以毫秒为单位）。默认为 TestConfig.expect 中的 timeout。

Promise<void>#

toHaveURL

新增于: v1.20

pageAssertions.toHaveURL

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

用法

// Check for the page URL to be 'https://playwright.net.cn/docs/intro' (including query string)
await expect(page).toHaveURL('https://playwright.net.cn/docs/intro');

// Check for the page URL to contain 'doc', followed by an optional 's', followed by '/'
await expect(page).toHaveURL(/docs?\//);

// Check for the page URL to match the URL pattern
await expect(page).toHaveURL(new URLPattern({ pathname: '/docs/*' }));

// Check for the predicate to be satisfied
// For example: verify query strings
await expect(page).toHaveURL(url => {
  const params = url.searchParams;
  return params.has('search') && params.has('options') && params.get('id') === '5';
});

参数

url string | RegExp | [URLPattern] | function(URL):boolean新增于: v1.18#

要匹配的预期 URL 字符串、RegExp 或接收 URL 的断言函数。当通过上下文选项提供 baseURL 且 url 参数为字符串时，这两个值将通过 new URL() 构造函数合并，并用于与当前的浏览器 URL 进行比较。
options Object (可选)
- ignoreCase boolean (可选)新增于：v1.44#
  
  是否执行不区分大小写的匹配。如果指定了 ignoreCase 选项，它将优先于相应的正则表达式参数。提供的谓词会忽略此标志。
- timeout 数字 (可选)新增于: v1.18#
  
  重试断言的超时时间（以毫秒为单位）。默认为 TestConfig.expect 中的 timeout。

Promise<void>#

toMatchAriaSnapshot(expected)

添加于: v1.60

pageAssertions.toMatchAriaSnapshot(expected)

断言页面主体与给定的无障碍快照匹配。

用法

await page.goto('https://demo.playwright.dev/todomvc/');
await expect(page).toMatchAriaSnapshot(`
  - heading "todos"
  - textbox "What needs to be done?"
`);

参数

expected string #
options Object (可选)
- timeout number (可选)#
  
  重试断言的超时时间（以毫秒为单位）。默认为 TestConfig.expect 中的 timeout。

Promise<void>#

toMatchAriaSnapshot(options)

添加于: v1.60

pageAssertions.toMatchAriaSnapshot(options)

断言页面主体与给定的无障碍快照匹配。

快照存储在单独的 .aria.yml 文件中，该位置由配置文件中的 expect.toMatchAriaSnapshot.pathTemplate 和/或 snapshotPathTemplate 属性配置。

用法

await expect(page).toMatchAriaSnapshot();
await expect(page).toMatchAriaSnapshot({ name: 'home.aria.yml' });

参数

options Object (可选)
- name string (可选)#
  
  存储在此测试对应的快照文件夹中的快照名称。如果未指定，将生成连续的名称。
- timeout number (可选)#
  
  重试断言的超时时间（以毫秒为单位）。默认为 TestConfig.expect 中的 timeout。

Promise<void>#

属性

not

新增于: v1.20

pageAssertions.not

使断言检查相反的条件。

用法

例如，以下代码测试页面 URL 不包含 "error"

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

类型

PageAssertions

方法​

toHaveScreenshot(name)​

toHaveScreenshot(options)​

toHaveTitle​

toHaveURL​

toMatchAriaSnapshot(expected)​

toMatchAriaSnapshot(options)​

属性​

not​

方法

toHaveScreenshot(name)

toHaveScreenshot(options)

toHaveTitle

toHaveURL

toMatchAriaSnapshot(expected)

toMatchAriaSnapshot(options)

属性

not