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.

用法

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

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

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

参数

name string | Array<string>#

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

Promise<void>#

toHaveScreenshot(options)

Added in: v1.23

pageAssertions.toHaveScreenshot(options)

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

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

用法

await expect(page).toHaveScreenshot();

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

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

参数

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

Promise<void>#

toHaveTitle

Added in: v1.20

pageAssertions.toHaveTitle

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

🌐 Ensures the page has the given title.

用法

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

参数

titleOrRegExp string | RegExp Added in: v1.18#

预期的标题或正则表达式。
options Object (optional)
- timeout number (optional) Added in: v1.18#
  
  是时候以毫秒为单位重试断言了。TestConfig.expect 中默认为 timeout。

Promise<void>#

toHaveURL

Added in: v1.20

pageAssertions.toHaveURL

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

🌐 Ensures the page is navigated to the given URL.

用法

// Check for the page URL to be 'https://playwright.nodejs.cn/docs/intro' (including query string)
await expect(page).toHaveURL('https://playwright.nodejs.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 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 | function(URL):boolean Added in: v1.18#

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

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

用法

expect(page).not

类型

PageAssertions

方法​

toHaveScreenshot(name)​

toHaveScreenshot(options)​

toHaveTitle​

toHaveURL​

属性​

not​

方法

toHaveScreenshot(name)

toHaveScreenshot(options)

toHaveTitle

toHaveURL

属性

not