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');
// Make sure at least some part of element intersects viewport.
await expect(locator).toBeInViewport();
// Make sure element is fully outside of viewport.
await expect(locator).not.toBeInViewport();
// Make sure that at least half of the element intersects viewport.
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()。

用法

// A specific element is visible.
await expect(page.getByText('Welcome')).toBeVisible();

// At least one item in the list is visible.
await expect(page.getByTestId('todo-item').first()).toBeVisible();

// At least one of the two elements is visible, possibly both.
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>
  <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>

让我们看看如何使用该断言

// ✓ Contains the right items in the right order
await expect(page.locator('ul > li')).toContainText(['Text 1', 'Text 3']);

// ✖ Wrong order
await expect(page.locator('ul > li')).toContainText(['Text 3', 'Text 2']);

// ✖ No item contains this text
await expect(page.locator('ul > li')).toContainText(['Some 33']);

// ✖ Locator points to the outer list element, not to the list items
await expect(page.locator('ul')).toContainText(['Text 3']);

参数

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

预期的子字符串或 RegExp，或它们的列表。
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('Save to disk');

参数

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');
// Assert attribute existence.
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#

预期的类或 RegExp，或它们的列表。
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)

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

用法

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 Animations。动画根据其持续时间受到不同处理
  - 有限动画被快进到完成，因此它们会触发 transitionend 事件。
  - 无限动画被取消到初始状态，然后在截图后重新播放。
  默认为 "disabled"，该值禁用动画。
- caret "hide" | "initial" （可选）#
  
  设置为 "hide" 时，截图将隐藏文本插入符号（caret）。设置为 "initial" 时，文本插入符号的行为不会改变。默认为 "hide"。
- mask Array<Locator> （可选）#
  
  指定截图时应被遮罩的 locator。被遮罩的元素将叠加一个粉色框 #FF00FF（由 maskColor 定制），该框完全覆盖其边界框。遮罩也应用于不可见元素，请参阅 Matching only visible elements 以禁用此行为。
- 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

locatorAssertions.toHaveScreenshot(options)

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

用法

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

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

参数

options Object (可选)
- animations "disabled" | "allow" （可选）#
  
  设置为 "disabled" 时，停止 CSS 动画、CSS 过渡和 Web Animations。动画根据其持续时间受到不同处理
  - 有限动画被快进到完成，因此它们会触发 transitionend 事件。
  - 无限动画被取消到初始状态，然后在截图后重新播放。
  默认为 "disabled"，该值禁用动画。
- caret "hide" | "initial" （可选）#
  
  设置为 "hide" 时，截图将隐藏文本插入符号（caret）。设置为 "initial" 时，文本插入符号的行为不会改变。默认为 "hide"。
- mask Array<Locator> （可选）#
  
  指定截图时应被遮罩的 locator。被遮罩的元素将叠加一个粉色框 #FF00FF（由 maskColor 定制），该框完全覆盖其边界框。遮罩也应用于不可见元素，请参阅 Matching only visible elements 以禁用此行为。
- 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>#

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>

让我们看看如何使用该断言

// ✓ Has the right items in the right order
await expect(page.locator('ul > li')).toHaveText(['Text 1', 'Text 2', 'Text 3']);

// ✖ Wrong order
await expect(page.locator('ul > li')).toHaveText(['Text 3', 'Text 2', 'Text 1']);

// ✖ Last item does not match
await expect(page.locator('ul > li')).toHaveText(['Text 1', 'Text 2', 'Text']);

// ✖ Locator points to the outer list element, not to the list items
await expect(page.locator('ul')).toHaveText(['Text 1', 'Text 2', 'Text 3']);

参数

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

预期的字符串或 RegExp 或其列表。
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)

断言目标元素与给定 accessibility snapshot 匹配。

用法

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)

断言目标元素与给定 accessibility snapshot 匹配。

快照存储在单独的 .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

使断言检查相反的条件。例如，此代码测试 Locator 不包含文本 "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