LocatorAssertions

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

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

test('status becomes submitted', async ({ page }) => {
  // ...
  await page.getByRole('button').click();
  await expect(page.locator('.status')).toHaveText('Submitted');
});

方法

toBeAttached

添加于: v1.33

locatorAssertions.toBeAttached

确保 Locator 指向的元素已连接到 Document 或 ShadowRoot。

用法

await expect(page.getByText('Hidden text')).toBeAttached();

参数

options Object (可选)
- attached boolean (可选)#
- timeout number (可选)#
  
  重试断言的超时时间（毫秒）。默认为 TestConfig.expect 中的 timeout 值。

Promise<void>#

toBeChecked

添加于: v1.20

locatorAssertions.toBeChecked

确保 Locator 指向一个已选中的输入框。

用法

const locator = page.getByLabel('Subscribe to newsletter');
await expect(locator).toBeChecked();

参数

options Object (可选)
- checked boolean (可选) 添加于: v1.18#
  
  指定要断言的状态。默认断言输入框为选中状态。当 indeterminate 设为 true 时不可使用此选项。
- indeterminate boolean (可选) 添加于: v1.50#
  
  断言元素处于不确定（混合）状态。仅支持复选框和单选按钮。当提供 checked 参数时此选项不能为 true。
- timeout number (可选) 添加于: v1.18#
  
  重试断言的时间（毫秒）。默认为 TestConfig.expect 中的 timeout 值。

返回值

Promise<void>#

toBeDisabled

添加于: v1.20

locatorAssertions.toBeDisabled

确保 Locator 指向一个被禁用的元素。如果元素具有 "disabled" 属性或通过 'aria-disabled' 被禁用，则该元素被视为禁用状态。请注意，只有原生控件元素如 HTML button、input、select、textarea、option、optgroup 可以通过设置 "disabled" 属性来禁用。其他元素上的 "disabled" 属性会被浏览器忽略。

用法

const locator = page.locator('button.submit');
await expect(locator).toBeDisabled();

参数

options Object (可选)
- timeout number (可选) 添加于: v1.18#
  
  重试断言的超时时间（毫秒）。默认为 TestConfig.expect 中的 timeout 值。

返回值

Promise<void>#

toBeEditable

添加于: v1.20

locatorAssertions.toBeEditable

确保 Locator 指向一个可编辑的元素。

用法

const locator = page.getByRole('textbox');
await expect(locator).toBeEditable();

参数

options Object (可选)
- editable boolean (可选) 添加于: v1.26#
- timeout number (可选) 添加于: v1.18#
  
  重试断言的时间（毫秒）。默认为 TestConfig.expect 中的 timeout 值。

返回值

Promise<void>#

toBeEmpty

v1.20 版本新增

locatorAssertions.toBeEmpty

确保 Locator 指向一个空的可编辑元素或没有文本内容的 DOM 节点。

用法

const locator = page.locator('div.warning');
await expect(locator).toBeEmpty();

参数

options Object (可选)
- timeout number (可选) v1.18 版本新增#
  
  重试断言的超时时间（毫秒）。默认为 TestConfig.expect 中的 timeout 值。

返回值

Promise<void>#

toBeEnabled

添加于: v1.20

locatorAssertions.toBeEnabled

确保 Locator 指向一个已启用的元素。

用法

const locator = page.locator('button.submit');
await expect(locator).toBeEnabled();

参数

options Object (可选)
- enabled boolean (可选) 添加于: v1.26#
- timeout number (可选) 添加于: v1.18#
  
  重试断言的超时时间（毫秒）。默认为 TestConfig.expect 中的 timeout 值。

返回值

Promise<void>#

toBeFocused

添加于: v1.20

locatorAssertions.toBeFocused

确保 Locator 指向一个获得焦点的 DOM 节点。

用法

const locator = page.getByRole('textbox');
await expect(locator).toBeFocused();

参数

options Object (可选)
- timeout number (可选) 添加于: v1.18#
  
  重试断言的时间（毫秒）。默认为 TestConfig.expect 中的 timeout 值。

返回值

Promise<void>#

toBeHidden

添加于: v1.20

locatorAssertions.toBeHidden

确保 Locator 要么不解析为任何 DOM 节点，要么解析为不可见的节点。

用法

const locator = page.locator('.my-element');
await expect(locator).toBeHidden();

参数

options Object (可选)
- timeout number (可选) 添加于: v1.18#
  
  重试断言的超时时间（毫秒）。默认为 TestConfig.expect 中的 timeout 值。

Promise<void>#

toBeInViewport

发布于: v1.31

locatorAssertions.toBeInViewport

确保 Locator 指向的元素与视口相交，依据 intersection observer API 规范。

用法

const locator = page.getByRole('button');
// 确保元素至少部分与视口相交
await expect(locator).toBeInViewport();
// 确保元素完全位于视口之外
await expect(locator).not.toBeInViewport();
// 确保至少一半元素与视口相交
await expect(locator).toBeInViewport({ ratio: 0.5 });

参数

options Object (可选)
- ratio number (可选)#
  
  元素与视口相交的最小比例。设为 0 时表示元素只需以任意正比例与视口相交。默认为 0。
- timeout number (可选)#
  
  断言重试的超时时间（毫秒）。默认为 TestConfig.expect 中的 timeout 值。

返回值

Promise<void>#

toBeVisible

添加于: v1.20

locatorAssertions.toBeVisible

确保 Locator 指向一个已附加且可见的 DOM 节点。

要检查列表中至少有一个元素可见，可以使用 locator.first()。

用法

// 检查特定元素是否可见
await expect(page.getByText('Welcome')).toBeVisible();

// 检查列表中至少有一个项目可见
await expect(page.getByTestId('todo-item').first()).toBeVisible();

// 检查两个元素中至少有一个可见（可能两个都可见）
await expect(
    page.getByRole('button', { name: 'Sign in' })
        .or(page.getByRole('button', { name: 'Sign up' }))
        .first()
).toBeVisible();

参数

options Object (可选)
- timeout number (可选) 添加于: v1.18#
  
  重试断言的超时时间（毫秒）。默认为 TestConfig.expect 中的 timeout 值。
- visible boolean (可选) 添加于: v1.26#

返回值

Promise<void>#

toContainClass

添加于: v1.52

locatorAssertions.toContainClass

确保 Locator 指向具有给定 CSS 类的元素。断言值中的所有类（以空格分隔）必须以任意顺序存在于 Element.classList 中。

用法

<div class='middle selected row' id='component'></div>

const locator = page.locator('#component');
await expect(locator).toContainClass('middle selected row');
await expect(locator).toContainClass('selected');
await expect(locator).toContainClass('row middle');

当传入数组时，该方法会断言定位到的元素列表与预期的类列表数组相匹配。每个元素的 class 属性会与数组中对应的类进行匹配：

<div class='list'>
  <div class='component inactive'></div>
  <div class='component active'></div>
  <div class='component inactive'></div>
</div>

const locator = page.locator('.list > .component');
await expect(locator).toContainClass(['inactive', 'active', 'inactive']);

参数

expected string | Array<string>#

包含预期类名的字符串（以空格分隔），或用于断言多个元素的此类字符串数组。
options Object (可选)
- timeout number (可选)#
  
  重试断言的超时时间（毫秒）。默认为 TestConfig.expect 中的 timeout 值。

返回值

Promise<void>#

toContainText

添加于: v1.20

locatorAssertions.toContainText

确保 Locator 指向的元素包含给定的文本。计算元素文本内容时会考虑所有嵌套元素。也可以使用正则表达式作为匹配值。

用法

const locator = page.locator('.title');
await expect(locator).toContainText('substring');
await expect(locator).toContainText(/\d messages/);

如果传入数组作为期望值，则需满足以下条件：

Locator 解析为元素列表
这些元素中的子集分别包含期望数组中的文本
匹配的元素子集顺序与期望数组一致
期望数组中的每个文本值都能被列表中的某个元素匹配

例如，考虑以下列表：

<ul>
  <li>Item Text 1</li>
  <li>Item Text 2</li>
  <li>Item Text 3</li>
</ul>

让我们看看如何使用这个断言：

// ✓ 包含正确顺序的正确项
await expect(page.locator('ul > li')).toContainText(['Text 1', 'Text 3']);

// ✖ 顺序错误
await expect(page.locator('ul > li')).toContainText(['Text 3', 'Text 2']);

// ✖ 没有项包含此文本
await expect(page.locator('ul > li')).toContainText(['Some 33']);

// ✖ Locator 指向外部列表元素而非列表项
await expect(page.locator('ul')).toContainText(['Text 3']);

参数

expected string | RegExp | Array<string | RegExp> 添加于: v1.18#

期望的子字符串、正则表达式或其数组
options Object (可选)
- ignoreCase boolean (可选) 添加于: v1.23#
  
  是否执行不区分大小写的匹配。如果指定了 ignoreCase 选项，它将优先于相应的正则表达式标志。
- timeout number (可选) 添加于: v1.18#
  
  重试断言的超时时间（毫秒）。默认为 TestConfig.expect 中的 timeout 值。
- useInnerText boolean (可选) 添加于: v1.18#
  
  获取 DOM 节点文本时是否使用 element.innerText 而非 element.textContent。

Promise<void>#

详情

当 expected 参数是字符串时，Playwright 会在匹配前对实际文本和期望字符串进行空白符和换行符的标准化处理。使用正则表达式时，实际文本会按原样匹配。

toHaveAccessibleDescription

添加于: v1.44

locatorAssertions.toHaveAccessibleDescription

确保 Locator 指向具有指定无障碍描述的元素。

用法

const locator = page.getByTestId('save-button');
await expect(locator).toHaveAccessibleDescription('Save results to disk');

参数

description string | RegExp #

预期的无障碍描述。
options Object (可选)
- ignoreCase boolean (可选)#
  
  是否执行不区分大小写的匹配。如果指定了 ignoreCase 选项，它将优先于对应的正则表达式标志。
- timeout number (可选)#
  
  重试断言的超时时间（毫秒）。默认为 TestConfig.expect 中的 timeout 值。

返回值

Promise<void>#

toHaveAccessibleErrorMessage

添加于: v1.50

locatorAssertions.toHaveAccessibleErrorMessage

确保 Locator 指向具有指定 aria errormessage 属性的元素。

用法

const locator = page.getByTestId('username-input');
await expect(locator).toHaveAccessibleErrorMessage('Username is required.');

参数

errorMessage string | RegExp #

预期的无障碍错误信息。
options Object (可选)
- ignoreCase boolean (可选)#
  
  是否执行不区分大小写的匹配。如果指定了 ignoreCase 选项，它将优先于相应的正则表达式标志。
- timeout number (可选)#
  
  重试断言的时间（毫秒）。默认为 TestConfig.expect 中的 timeout 值。

Promise<void>#

toHaveAccessibleName

新增于: v1.44

locatorAssertions.toHaveAccessibleName

确保 Locator 指向具有指定可访问名称的元素。

用法

const locator = page.getByTestId('save-button');
await expect(locator).toHaveAccessibleName('保存到磁盘');

参数

name string | RegExp #

预期的可访问名称。
options Object (可选)
- ignoreCase boolean (可选)#
  
  是否执行不区分大小写的匹配。如果指定了 ignoreCase 选项，它将优先于相应的正则表达式标志。
- timeout number (可选)#
  
  重试断言的时间（毫秒）。默认为 TestConfig.expect 中的 timeout 值。

返回值

Promise<void>#

toHaveAttribute(name, value)

添加于: v1.20

locatorAssertions.toHaveAttribute(name, value)

确保 Locator 指向具有指定属性的元素。

用法

const locator = page.locator('input');
await expect(locator).toHaveAttribute('type', 'text');

参数

name string 添加于: v1.18#

属性名称。
value string | RegExp 添加于: v1.18#

预期的属性值。
options Object (可选)
- ignoreCase boolean (可选) 添加于: v1.40#
  
  是否执行不区分大小写的匹配。如果指定了 ignoreCase 选项，它将优先于相应的正则表达式标志。
- timeout number (可选) 添加于: v1.18#
  
  重试断言的时间（毫秒）。默认为 TestConfig.expect 中的 timeout 值。

Promise<void>#

toHaveAttribute(name)

添加于: v1.39

locatorAssertions.toHaveAttribute(name)

确保 Locator 指向具有指定属性的元素。该方法会断言属性是否存在。

const locator = page.locator('input');
// 断言属性存在
await expect(locator).toHaveAttribute('disabled');
await expect(locator).not.toHaveAttribute('open');

用法

await expect(locator).toHaveAttribute(name);
await expect(locator).toHaveAttribute(name, options);

参数

name string #

属性名称。
options Object (可选)
- timeout number (可选)#
  
  重试断言的时间（毫秒）。默认为 TestConfig.expect 中的 timeout 值。

返回值

Promise<void>#

toHaveClass

添加于: v1.20

locatorAssertions.toHaveClass

确保 Locator 指向具有给定 CSS 类的元素。当提供字符串时，它必须完全匹配元素的 class 属性。要匹配单个类，请使用 expect(locator).toContainClass()。

用法

<div class='middle selected row' id='component'></div>

const locator = page.locator('#component');
await expect(locator).toHaveClass('middle selected row');
await expect(locator).toHaveClass(/(^|\s)selected(\s|$)/);

当传入数组时，该方法会断言定位到的元素列表与预期的类值列表相对应。每个元素的 class 属性会与数组中对应的字符串或正则表达式进行匹配：

const locator = page.locator('.list > .component');
await expect(locator).toHaveClass(['component', 'component selected', 'component']);

参数

expected string | RegExp | Array<string | RegExp> 添加于: v1.18#

预期的类名或正则表达式，或其列表。
options Object (可选)
- timeout number (可选) 添加于: v1.18#
  
  重试断言的超时时间（毫秒）。默认为 TestConfig.expect 中的 timeout 值。

Promise<void>#

toHaveCount

添加于: v1.20

locatorAssertions.toHaveCount

确保 Locator 解析为精确数量的 DOM 节点。

用法

const list = page.locator('list > .component');
await expect(list).toHaveCount(3);

参数

count number 添加于: v1.18#

期望的数量。
options Object (可选)
- timeout number (可选) 添加于: v1.18#
  
  重试断言的时间（毫秒）。默认为 TestConfig.expect 中的 timeout 值。

Promise<void>#

toHaveCSS

添加于: v1.20

locatorAssertions.toHaveCSS

确保 Locator 解析为具有指定计算 CSS 样式的元素。

用法

const locator = page.getByRole('button');
await expect(locator).toHaveCSS('display', 'flex');

参数

name string 添加于: v1.18#

CSS 属性名称。
value string | RegExp 添加于: v1.18#

CSS 属性值。
options Object (可选)
- timeout number (可选) 添加于: v1.18#
  
  重试断言的超时时间（毫秒）。默认为 TestConfig.expect 中的 timeout 值。

Promise<void>#

toHaveId

v1.20 版本新增

locatorAssertions.toHaveId

确保 Locator 指向具有指定 DOM 节点 ID 的元素。

用法

const locator = page.getByRole('textbox');
await expect(locator).toHaveId('lastname');

参数

id string | RegExp v1.18 版本新增#

元素 ID。
options Object (可选)
- timeout number (可选) v1.18 版本新增#
  
  重试断言的时间（毫秒）。默认为 TestConfig.expect 中的 timeout 值。

返回值

Promise<void>#

toHaveJSProperty

添加于: v1.20

locatorAssertions.toHaveJSProperty

确保 Locator 指向具有指定 JavaScript 属性的元素。注意该属性可以是基本类型，也可以是可序列化的普通 JavaScript 对象。

用法

const locator = page.locator('.component');
await expect(locator).toHaveJSProperty('loaded', true);

参数

name string 添加于: v1.18#

属性名称。
value Object 添加于: v1.18#

属性值。
options Object (可选)
- timeout number (可选) 添加于: v1.18#
  
  断言重试的超时时间（毫秒）。默认为 TestConfig.expect 中的 timeout 值。

返回值

Promise<void>#

toHaveRole

添加于: v1.44

locatorAssertions.toHaveRole

确保 Locator 指向具有指定 ARIA 角色的元素。

注意：角色匹配是基于字符串的，不考虑 ARIA 角色层级关系。例如，在具有子类角色 "switch" 的元素上断言父类角色 "checkbox" 将会失败。

用法

const locator = page.getByTestId('save-button');
await expect(locator).toHaveRole('button');

参数

role "alert" | "alertdialog" | "application" | "article" | "banner" | "blockquote" | "button" | "caption" | "cell" | "checkbox" | "code" | "columnheader" | "combobox" | "complementary" | "contentinfo" | "definition" | "deletion" | "dialog" | "directory" | "document" | "emphasis" | "feed" | "figure" | "form" | "generic" | "grid" | "gridcell" | "group" | "heading" | "img" | "insertion" | "link" | "list" | "listbox" | "listitem" | "log" | "main" | "marquee" | "math" | "meter" | "menu" | "menubar" | "menuitem" | "menuitemcheckbox" | "menuitemradio" | "navigation" | "none" | "note" | "option" | "paragraph" | "presentation" | "progressbar" | "radio" | "radiogroup" | "region" | "row" | "rowgroup" | "rowheader" | "scrollbar" | "search" | "searchbox" | "separator" | "slider" | "spinbutton" | "status" | "strong" | "subscript" | "superscript" | "switch" | "tab" | "table" | "tablist" | "tabpanel" | "term" | "textbox" | "time" | "timer" | "toolbar" | "tooltip" | "tree" | "treegrid" | "treeitem"#

必需的 ARIA 角色。
options Object (可选)
- timeout number (可选)#
  
  重试断言的超时时间（毫秒）。默认为 TestConfig.expect 中的 timeout 值。

Promise<void>#

toHaveScreenshot(name)

新增于: v1.23

locatorAssertions.toHaveScreenshot(name)

此函数会等待直到连续两次定位器截图结果相同，然后将最后一次截图与预期结果进行比较。

用法

const locator = page.getByRole('button');
await expect(locator).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"。
- 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>#

toHaveScreenshot(options)

添加于: v1.23

locatorAssertions.toHaveScreenshot(options)

此函数会等待直到连续两次定位器截图结果相同，然后将最后一次截图与预期结果进行比较。

用法

const locator = page.getByRole('button');
await expect(locator).toHaveScreenshot();

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

参数

options Object (可选)
- animations "disabled" | "allow" (可选)#
  
  当设置为 "disabled" 时，会停止 CSS 动画、CSS 过渡和 Web 动画。动画根据其持续时间会有不同处理方式：
  - 有限动画会快进到完成状态，因此会触发 transitionend 事件
  - 无限动画会重置到初始状态，然后在截图后重新播放
  默认为 "disabled" 禁用动画。
- caret "hide" | "initial" (可选)#
  
  当设置为 "hide" 时，截图会隐藏文本光标。当设置为 "initial" 时，文本光标行为不会改变。默认为 "hide"。
- 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>#

toHaveText

添加于: v1.20

locatorAssertions.toHaveText

确保 Locator 指向具有给定文本的元素。在计算元素的文本内容时，所有嵌套元素都会被考虑在内。你也可以使用正则表达式作为匹配值。

用法

const locator = page.locator('.title');
await expect(locator).toHaveText(/Welcome, Test User/);
await expect(locator).toHaveText(/Welcome, .*/);

如果传递数组作为期望值，则需满足以下条件：

Locator 解析为元素列表
元素数量与数组中期望值的数量相等
列表中的元素按顺序依次匹配数组中的期望文本

例如，考虑以下列表：

<ul>
  <li>Text 1</li>
  <li>Text 2</li>
  <li>Text 3</li>
</ul>

让我们看看如何使用这个断言：

// ✓ 正确顺序匹配
await expect(page.locator('ul > li')).toHaveText(['Text 1', 'Text 2', 'Text 3']);

// ✖ 顺序错误
await expect(page.locator('ul > li')).toHaveText(['Text 3', 'Text 2', 'Text 1']);

// ✖ 最后一项不匹配
await expect(page.locator('ul > li')).toHaveText(['Text 1', 'Text 2', 'Text']);

// ✖ Locator 指向外部列表元素而非列表项
await expect(page.locator('ul')).toHaveText(['Text 1', 'Text 2', 'Text 3']);

参数

expected string | RegExp | Array<string | RegExp> 添加于: v1.18#

期望的字符串、正则表达式或其列表
options Object (可选)
- ignoreCase boolean (可选) 添加于: v1.23#
  
  是否执行不区分大小写的匹配。如果指定了 ignoreCase 选项，它将优先于正则表达式对应的标志
- timeout number (可选) 添加于: v1.18#
  
  重试断言的时间（毫秒）。默认为 TestConfig.expect 中的 timeout 值
- useInnerText boolean (可选) 添加于: v1.18#
  
  获取 DOM 节点文本时是否使用 element.innerText 而非 element.textContent

返回值

Promise<void>#

详细说明

当 expected 参数是字符串时，Playwright 会在匹配前对实际文本和期望字符串进行空白字符和换行符的标准化处理。当使用正则表达式时，实际文本将按原样匹配。

toHaveValue

添加于: v1.20

locatorAssertions.toHaveValue

确保 Locator 指向具有给定输入值的元素。你也可以使用正则表达式来匹配值。

用法

const locator = page.locator('input[type=number]');
await expect(locator).toHaveValue(/[0-9]/);

参数

value string | RegExp 添加于: v1.18#

期望的值。
options Object (可选)
- timeout number (可选) 添加于: v1.18#
  
  重试断言的超时时间（毫秒）。默认为 TestConfig.expect 中的 timeout 值。

返回值

Promise<void>#

toHaveValues

添加于: v1.23

locatorAssertions.toHaveValues

确保 Locator 指向多选/组合框（即带有 multiple 属性的 select 元素）且指定的值已被选中。

用法

例如，给定以下元素：

<select id="favorite-colors" multiple>
  <option value="R">Red</option>
  <option value="G">Green</option>
  <option value="B">Blue</option>
</select>

const locator = page.locator('id=favorite-colors');
await locator.selectOption(['R', 'G']);
await expect(locator).toHaveValues([/R/, /G/]);

参数

values Array<string | RegExp>#

预期当前选中的选项值。
options Object (可选)
- timeout number (可选)#
  
  重试断言的时间（毫秒）。默认为 TestConfig.expect 中的 timeout 值。

Promise<void>#

toMatchAriaSnapshot(expected)

新增于: v1.49

locatorAssertions.toMatchAriaSnapshot(expected)

断言目标元素与给定的无障碍快照匹配。

用法

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

参数

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

Promise<void>#

toMatchAriaSnapshot(options)

新增于: v1.50

locatorAssertions.toMatchAriaSnapshot(options)

断言目标元素与给定的无障碍快照匹配。

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

用法

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

参数

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

返回值

Promise<void>#

属性

not

发布于: v1.20

locatorAssertions.not

使断言检查相反的条件。例如，以下代码测试定位器是否不包含文本 "error"：

await expect(locator).not.toContainText('error');

用法

expect(locator).not

类型

LocatorAssertions

方法​

toBeAttached​

toBeChecked​

toBeDisabled​

toBeEditable​

toBeEmpty​

toBeEnabled​

toBeFocused​

toBeHidden​

toBeInViewport​

toBeVisible​

toContainClass​

toContainText​

toHaveAccessibleDescription​

toHaveAccessibleErrorMessage​

toHaveAccessibleName​

toHaveAttribute(name, value)​

toHaveAttribute(name)​

toHaveClass​

toHaveCount​

toHaveCSS​

toHaveId​

toHaveJSProperty​

toHaveRole​

toHaveScreenshot(name)​

toHaveScreenshot(options)​

toHaveText​

toHaveValue​

toHaveValues​

toMatchAriaSnapshot(expected)​

toMatchAriaSnapshot(options)​

属性​

not​

方法

toBeAttached

toBeChecked

toBeDisabled

toBeEditable

toBeEmpty

toBeEnabled

toBeFocused

toBeHidden

toBeInViewport

toBeVisible

toContainClass

toContainText

toHaveAccessibleDescription

toHaveAccessibleErrorMessage

toHaveAccessibleName

toHaveAttribute(name, value)

toHaveAttribute(name)

toHaveClass

toHaveCount

toHaveCSS

toHaveId

toHaveJSProperty

toHaveRole

toHaveScreenshot(name)

toHaveScreenshot(options)

toHaveText

toHaveValue

toHaveValues

toMatchAriaSnapshot(expected)

toMatchAriaSnapshot(options)

属性

not