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 number
    
    裁剪区域左上角的 x 坐标
  - y number
    
    裁剪区域左上角的 y 坐标
  - width number
    
    裁剪区域宽度
  - height number
    
    裁剪区域高度
  指定结果图像裁剪区域的对象。
- fullPage boolean (可选)#
  
  为 true 时，会截取整个可滚动页面的截图，而不仅是当前可视区域。默认为 false。
- mask Array<Locator> (可选)#
  
  指定截图时应被遮罩的定位器。被遮罩的元素会被粉色盒子 #FF00FF（可通过 maskColor 自定义）完全覆盖其边界框。遮罩也会应用于不可见元素，参见仅匹配可见元素来禁用此行为。
- maskColor string (可选) 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> (可选) 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 number
    
    裁剪区域左上角的 x 坐标
  - y number
    
    裁剪区域左上角的 y 坐标
  - width number
    
    裁剪区域的宽度
  - height number
    
    裁剪区域的高度
  指定结果图像裁剪区域的对象。
- fullPage boolean (可选)#
  
  当为 true 时，会截取整个可滚动页面的截图，而不仅仅是当前可见的视口。默认为 false。
- mask Array<Locator> (可选)#
  
  指定截图时应被遮罩的定位器。被遮罩的元素会用粉色盒子 #FF00FF（可通过 maskColor 自定义）完全覆盖其边界框。遮罩也会应用于不可见元素，参见仅匹配可见元素来禁用此行为。
- maskColor string (可选) 添加于: 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> (可选) 添加于: v1.41#
  
  包含在截图时应用的样式表的文件名。可用于隐藏动态元素、使元素不可见或更改其属性以帮助创建可重复的截图。此样式表会穿透 Shadow DOM 并应用到内部框架。
- threshold number (可选)#
  
  在 YIQ 色彩空间中比较图像相同像素时可接受的感知色差，介于 0（严格）和 1（宽松）之间，默认值可通过 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 number (可选) 添加于: v1.18#
  
  断言重试的超时时间（毫秒）。默认为 TestConfig.expect 中的 timeout 值。

返回值

Promise<void>#

toHaveURL

添加于: v1.20

pageAssertions.toHaveURL

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

用法

// 检查页面 URL 是否为 'https://playwright.dev/docs/intro'（包括查询字符串）
await expect(page).toHaveURL('https://playwright.dev/docs/intro');

// 检查页面 URL 是否包含 'doc'，后跟可选的 's'，再后跟 '/'
await expect(page).toHaveURL(/docs?\//);

// 检查谓词是否满足
// 例如：验证查询字符串
await expect(page).toHaveURL(url => {
  const params = url.searchParams;
  return params.has('search') && params.has('options') && params.get('id') === '5';
});

参数

url string | RegExp | function(URL):boolean 添加于: v1.18#

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

Promise<void>#

属性

not

添加于: v1.20

pageAssertions.not

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

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

用法

expect(page).not

类型

PageAssertions

方法​

toHaveScreenshot(name)​

toHaveScreenshot(options)​

toHaveTitle​

toHaveURL​

属性​

not​

方法

toHaveScreenshot(name)

toHaveScreenshot(options)

toHaveTitle

toHaveURL

属性

not