LocatorAssertions

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

// ...
import static com.microsoft.playwright.assertions.PlaywrightAssertions.assertThat;

public class TestLocator {
  // ...
  @Test
  void statusBecomesSubmitted() {
    // ...
    page.getByRole(AriaRole.BUTTON).click();
    assertThat(page.locator(".status")).hasText("Submitted");
  }
}

方法

containsClass

添加于：v1.52

locatorAssertions.containsClass

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

用法

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

assertThat(page.locator("#component")).containsClass("middle selected row");
assertThat(page.locator("#component")).containsClass("selected");
assertThat(page.locator("#component")).containsClass("row middle");

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

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

assertThat(page.locator(".list > .component")).containsClass(new String[] {"inactive", "active", "inactive"});

参数

expected String | List<String>#

一个包含预期类名的字符串，类名之间用空格分隔，或者是这样的字符串列表，用于断言多个元素。
options LocatorAssertions.ContainsClassOptions（可选）
- setTimeout double（可选）#
  
  重试断言的时间（毫秒）。默认为 5000。

返回值

void #

containsText

新增于：v1.20

locatorAssertions.containsText

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

用法

assertThat(page.locator(".title")).containsText("子字符串");

如果传入一个数组作为预期值，期望如下：

定位器解析为元素列表。
此列表的子集中的元素分别包含预期数组中的文本。
匹配的元素子集与预期数组的顺序相同。
预期数组中的每个文本值都由列表中的某个元素匹配。

例如，考虑以下列表：

<ul>
  <li>项目文本 1</li>
  <li>项目文本 2</li>
  <li>项目文本 3</li>
</ul>

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

// ✓ 按正确顺序包含正确的项目
assertThat(page.locator("ul > li")).containsText(new String[] {"文本 1", "文本 3", "文本 4"});

// ✖ 顺序错误
assertThat(page.locator("ul > li")).containsText(new String[] {"文本 3", "文本 2"});

// ✖ 没有项目包含此文本
assertThat(page.locator("ul > li")).containsText(new String[] {"某些 33"});

// ✖ 定位器指向外部列表元素，而不是列表项
assertThat(page.locator("ul")).containsText(new String[] {"文本 3"});

参数

expected String | Pattern | String | Pattern 新增于：v1.18#

预期的子字符串、正则表达式或它们组成的列表。
options LocatorAssertions.ContainsTextOptions（可选）
- setIgnoreCase boolean（可选）新增于：v1.23#
  
  是否执行不区分大小写的匹配。如果指定了 setIgnoreCase 选项（setIgnoreCase），则它优先于相应的正则表达式标志。
- setTimeout double（可选）新增于：v1.18#
  
  重试断言的时间（毫秒）。默认为 5000。
- setUseInnerText boolean（可选）新增于：v1.18#
  
  在检索 DOM 节点文本时，是否使用 element.innerText 而不是 element.textContent。

返回值

void #

详细信息

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

hasAccessibleDescription

新增于：v1.44

locatorAssertions.hasAccessibleDescription

确保 Locator 指向具有给定可访问描述的元素。

用法

Locator locator = page.getByTestId("save-button");
assertThat(locator).hasAccessibleDescription("Save results to disk");

参数

description String | Pattern #

预期的无障碍描述。
options LocatorAssertions.HasAccessibleDescriptionOptions（可选）
- setIgnoreCase boolean（可选）#
  
  是否执行不区分大小写的匹配。如果指定了 setIgnoreCase 选项（setIgnoreCase），则它优先于相应的正则表达式标志。
- setTimeout double（可选）#
  
  重试断言的时间（毫秒）。默认为 5000。

返回值

void #

hasAccessibleErrorMessage

新增于：v1.50

locatorAssertions.hasAccessibleErrorMessage

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

用法

Locator locator = page.getByTestId("username-input");
assertThat(locator).hasAccessibleErrorMessage("Username is required.");

参数

errorMessage String | Pattern #

预期的无障碍错误信息。
options LocatorAssertions.HasAccessibleErrorMessageOptions（可选）
- setIgnoreCase boolean（可选）#
  
  是否执行不区分大小写的匹配。如果指定了 setIgnoreCase setIgnoreCase 选项，则该选项优先于相应的正则表达式标志。
- setTimeout double（可选）#
  
  重试断言的时间（毫秒）。默认为 5000。

返回值

void #

hasAccessibleName

新增于：v1.44

locatorAssertions.hasAccessibleName

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

用法

Locator locator = page.getByTestId("save-button");
assertThat(locator).hasAccessibleName("Save to disk");

参数

name String | Pattern #

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

void #

hasAttribute

新增于：v1.20

locatorAssertions.hasAttribute

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

用法

assertThat(page.locator("input")).hasAttribute("type", "text");

参数

name String 新增于：v1.18#

属性名。
value String | Pattern 新增于：v1.18#

预期的属性值。
options LocatorAssertions.HasAttributeOptions (可选)
- setIgnoreCase boolean (可选) 新增于：v1.40#
  
  是否执行不区分大小写的匹配。如果指定了 setIgnoreCase 选项（setIgnoreCase），则它优先于相应的正则表达式标志。
- setTimeout double (可选) 新增于：v1.18#
  
  重试断言的时间（毫秒）。默认为 5000。

返回值

void #

hasClass

添加于：v1.20

locatorAssertions.hasClass

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

用法

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

assertThat(page.locator("#component")).hasClass("middle selected row");
assertThat(page.locator("#component")).hasClass(Pattern.compile("(^|\\s)selected(\\s|$)"));

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

assertThat(page.locator(".list > .component")).hasClass(new String[] {"component", "component selected", "component"});

参数

expected String | Pattern | String | Pattern 新增于：v1.18#

预期的类名、正则表达式或它们组成的列表。
options LocatorAssertions.HasClassOptions (可选)
- setTimeout double (可选) 新增于：v1.18#
  
  重试断言的时间（毫秒）。默认为 5000。

返回值

void #

hasCount

新增于：v1.20

locatorAssertions.hasCount

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

用法

assertThat(page.locator("list > .component")).hasCount(3);

参数

count int 新增于：v1.18#

预期数量。
options LocatorAssertions.HasCountOptions (可选)
- setTimeout double (可选) 新增于：v1.18#
  
  重试断言的时间（毫秒）。默认为 5000。

返回值

void #

hasCSS

新增于：v1.20

locatorAssertions.hasCSS

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

用法

assertThat(page.getByRole(AriaRole.BUTTON)).hasCSS("display", "flex");

参数

name String 新增于：v1.18#

CSS 属性名。
value String | Pattern 新增于：v1.18#

CSS 属性值。
options LocatorAssertions.HasCSSOptions（可选）
- setTimeout double（可选）新增于：v1.18#
  
  重试断言的时间（毫秒）。默认为 5000。

返回值

void #

hasId

新增于：v1.20

locatorAssertions.hasId

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

用法

assertThat(page.getByRole(AriaRole.TEXTBOX)).hasId("lastname");

参数

id String | Pattern 新增于：v1.18#

元素 ID。
options LocatorAssertions.HasIdOptions（可选）
- setTimeout double（可选）新增于：v1.18#
  
  重试断言的时间（毫秒）。默认为 5000。

返回值

void #

hasJSProperty

新增于：v1.20

locatorAssertions.hasJSProperty

确保 Locator 指向具有给定 JavaScript 属性的元素。请注意，此属性可以是原始类型，也可以是普通的可序列化 JavaScript 对象。

用法

assertThat(page.locator("input")).hasJSProperty("loaded", true);

参数

name String 新增于：v1.18#

属性名称。
value Object 新增于：v1.18#

属性值。
options LocatorAssertions.HasJSPropertyOptions（可选）
- setTimeout double（可选）新增于：v1.18#
  
  重试断言的时间（毫秒）。默认为 5000。

返回值

void #

hasRole

新增于：v1.44

locatorAssertions.hasRole

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

请注意，角色是作为字符串进行匹配的，不考虑 ARIA 角色层次结构。例如，在具有子类角色 "switch" 的元素上断言超类角色 "checkbox" 将失败。

用法

Locator locator = page.getByTestId("save-button");
assertThat(locator).hasRole(AriaRole.BUTTON);

参数

role enum AriaRole { 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 LocatorAssertions.HasRoleOptions（可选）
- setTimeout double（可选）#
  
  重试断言的时间（毫秒）。默认为 5000。

返回值

void #

hasText

添加于：v1.20

locatorAssertions.hasText

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

用法

assertThat(page.locator(".title")).hasText("Welcome, Test User");
assertThat(page.locator(".title")).hasText(Pattern.compile("Welcome, .*"));

如果传入一个数组作为预期值，期望如下：

定位器解析为一个元素列表。
元素数量与数组中的预期值数量相等。
列表中的元素文本按顺序依次与预期数组值匹配。

例如，考虑以下列表：

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

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

// ✓ 顺序正确且项目正确
assertThat(page.locator("ul > li")).hasText(new String[] {"Text 1", "Text 2", "Text 3"});

// ✖ 顺序错误
assertThat(page.locator("ul > li")).hasText(new String[] {"Text 3", "Text 2", "Text 1"});

// ✖ 最后一项不匹配
assertThat(page.locator("ul > li")).hasText(new String[] {"Text 1", "Text 2", "Text"});

// ✖ 定位器指向外部列表元素，而非列表项
assertThat(page.locator("ul")).hasText(new String[] {"Text 1", "Text 2", "Text 3"});

参数

expected String | Pattern | String | Pattern 新增于：v1.18#

预期的字符串、正则表达式或它们组成的列表。
options LocatorAssertions.HasTextOptions（可选）
- setIgnoreCase boolean（可选）新增于：v1.23#
  
  是否执行不区分大小写的匹配。如果指定了 setIgnoreCase 选项（setIgnoreCase），它将优先于相应的正则表达式标志。
- setTimeout double（可选）新增于：v1.18#
  
  重试断言的时间（毫秒）。默认为 5000。
- setUseInnerText boolean（可选）新增于：v1.18#
  
  在检索 DOM 节点文本时，是否使用 element.innerText 而不是 element.textContent。

返回值

void #

详细信息

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

hasValue

添加于：v1.20

locatorAssertions.hasValue

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

用法

assertThat(page.locator("input[type=number]")).hasValue(Pattern.compile("[0-9]"));

参数

value String | Pattern 添加于：v1.18#

预期值。
options LocatorAssertions.HasValueOptions (可选)
- setTimeout double (可选) 添加于：v1.18#
  
  重试断言的时间（毫秒）。默认为 5000。

返回值

void #

hasValues

添加于：v1.23

locatorAssertions.hasValues

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

使用方法

例如，对于以下元素：

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

page.locator("id=favorite-colors").selectOption(new String[]{"R", "G"});
assertThat(page.locator("id=favorite-colors")).hasValues(new Pattern[] { Pattern.compile("R"), Pattern.compile("G") });

参数

values String | Pattern # 当前选中的预期选项。
options LocatorAssertions.HasValuesOptions（可选）
- setTimeout double（可选）# 重试断言的时间（毫秒）。默认为 5000。

返回值

void #

isAttached

新增于：v1.33locatorAssertions.isAttached 确保 Locator 指向的元素已连接到 Document 或 ShadowRoot。

使用方法

assertThat(page.getByText("Hidden text")).isAttached();

参数

options LocatorAssertions.IsAttachedOptions（可选）
- setAttached [布尔值]（可选）#
- setTimeout [双精度浮点数]（可选）#
  
  重试断言的时间（毫秒）。默认为 5000。

返回值

void #

isChecked

添加于：v1.20

locatorAssertions.isChecked

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

用法

assertThat(page.getByLabel("Subscribe to newsletter")).isChecked();

参数

options LocatorAssertions.IsCheckedOptions（可选）
- setChecked boolean（可选）自 v1.18 起可用#
  
  提供要断言的状态。默认情况下断言输入框被选中。当 setIndeterminate 设置为 true 时，不能使用此选项。
- setIndeterminate boolean（可选）自 v1.50 起可用#
  
  断言元素处于不确定（混合）状态。仅支持复选框和单选按钮。当提供 setChecked 时，此选项不能为 true。
- setTimeout double（可选）自 v1.18 起可用#
  
  重试断言的时间（毫秒）。默认为 5000。

返回值

void #

isDisabled

新增于：v1.20

locatorAssertions.isDisabled

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

用法

assertThat(page.locator("button.submit")).isDisabled();

参数

options LocatorAssertions.IsDisabledOptions （可选）
- setTimeout double （可选）新增于：v1.18#
  
  重试断言的时间（毫秒）。默认为 5000。

返回值

void #

isEditable

新增于：v1.20

locatorAssertions.isEditable

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

用法

assertThat(page.getByRole(AriaRole.TEXTBOX)).isEditable();

参数

options LocatorAssertions.IsEditableOptions（可选）
- setEditable [布尔值]（可选）添加于：v1.26#
- setTimeout [双精度浮点数]（可选）添加于：v1.18#
  
  重试断言的时间（毫秒）。默认为 5000。

返回值

void #

isEmpty

添加于：v1.20

locatorAssertions.isEmpty

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

用法

assertThat(page.locator("div.warning")).isEmpty();

参数

options LocatorAssertions.IsEmptyOptions（可选）
- setTimeout [双精度浮点数]（可选）添加于：v1.18#
  
  重试断言的时间（毫秒）。默认为 5000。

返回值

void #

isEnabled

新增于：v1.20

locatorAssertions.isEnabled

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

用法

assertThat(page.locator("button.submit")).isEnabled();

参数

options LocatorAssertions.IsEnabledOptions（可选）
- setEnabled boolean（可选）新增于：v1.26#
- setTimeout double（可选）新增于：v1.18#
  
  以毫秒为单位重试断言的时间。默认为 5000。

返回值

void #

isFocused

新增于：v1.20

locatorAssertions.isFocused

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

用法

assertThat(page.getByRole(AriaRole.TEXTBOX)).isFocused();

参数

options LocatorAssertions.IsFocusedOptions（可选）
- setTimeout double（可选）新增于：v1.18#
  
  以毫秒为单位重试断言的时间。默认为 5000。

返回值

void #

isHidden

新增于：v1.20

locatorAssertions.isHidden

确保 Locator 要么未解析到任何 DOM 节点，要么解析到一个不可见的节点。

用法

assertThat(page.locator(".my-element")).isHidden();

参数

options LocatorAssertions.IsHiddenOptions （可选）
- setTimeout double （可选）新增于：v1.18#
  
  重试断言的时间（毫秒）。默认为 5000。

返回值

void #

isInViewport

新增于：v1.31

locatorAssertions.isInViewport

根据交集观察器 API，确保 Locator 指向与视口相交的元素。

使用方法

Locator locator = page.getByRole(AriaRole.BUTTON);
// 确保元素的至少一部分与视口相交。
assertThat(locator).isInViewport();
// 确保元素完全在视口之外。
assertThat(locator).not().isInViewport();
// 确保元素至少有一半与视口相交。
assertThat(locator).isInViewport(new LocatorAssertions.IsInViewportOptions().setRatio(0.5));

参数

options LocatorAssertions.IsInViewportOptions（可选）
- setRatio double（可选）#
  
  元素与视口相交的最小比例。如果等于 0，则元素应以任何正比例与视口相交。默认为 0。
- setTimeout double（可选）#
  
  重试断言的时间（毫秒）。默认为 5000。

返回值

void #

isVisible

新增于：v1.20

locatorAssertions.isVisible

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

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

用法

// 特定元素可见。
assertThat(page.getByText("Welcome")).isVisible();

// 列表中至少有一个项目可见。
assertThat(page.getByTestId("todo-item").first()).isVisible();

// 两个元素中至少有一个可见，也可能两个都可见。
assertThat(
  page.getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("Sign in"))
    .or(page.getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("Sign up")))
    .first()
).isVisible();

参数

options LocatorAssertions.IsVisibleOptions（可选）
- setTimeout double（可选）新增于：v1.18#
  
  重试断言的时间（毫秒）。默认为 5000。
- setVisible boolean（可选）新增于：v1.26#

返回值

void #

matchesAriaSnapshot

新增于：v1.49

locatorAssertions.matchesAriaSnapshot

断言目标元素与给定的可访问性快照匹配。

用法

page.navigate("https://demo.playwright.dev/todomvc/");
assertThat(page.locator("body")).matchesAriaSnapshot("""
  - heading "todos"
  - textbox "What needs to be done?"
""");

参数

expected String #
options LocatorAssertions.MatchesAriaSnapshotOptions（可选）
- setTimeout double（可选）#
  
  重试断言的时间（毫秒）。默认为 5000。

返回值

void #

属性

not()

添加于：v1.20

locatorAssertions.not()

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

assertThat(locator).not().containsText("error");

用法

assertThat(locator).not()

返回值

LocatorAssertions

方法​

containsClass​

containsText​

用法​

参数​

返回值​

hasAccessibleDescription​

hasAccessibleErrorMessage​

用法​

参数​

返回值​

hasAccessibleName​

hasAttribute​

hasClass​

hasCount​

hasCSS​

hasId​

hasJSProperty​

hasRole​

hasText​

参数​

返回值​

详细信息​

hasValue​

用法​

参数​

返回值​

hasValues​

使用方法​

参数​

返回值​

isAttached​

使用方法​

isChecked​

参数​

返回值​

isDisabled​

isEditable​

参数​

返回值​

isEmpty​

用法​

参数​

返回值​

isEnabled​

isFocused​

isHidden​

isInViewport​

使用方法​

参数​

返回值​

isVisible​

matchesAriaSnapshot​

参数​

返回值​

属性​

not()​

用法​

返回值​

方法

containsClass

containsText

用法

参数

返回值

hasAccessibleDescription

hasAccessibleErrorMessage

用法

参数

返回值

hasAccessibleName

hasAttribute

hasClass

hasCount

hasCSS

hasId

hasJSProperty

hasRole

hasText

参数

返回值

详细信息

hasValue

用法

参数

返回值

hasValues

使用方法

参数

返回值

isAttached

使用方法

isChecked

参数

返回值

isDisabled

isEditable

参数

返回值

isEmpty

用法

参数

返回值

isEnabled

isFocused

isHidden

isInViewport

使用方法

参数

返回值

isVisible

matchesAriaSnapshot

参数

返回值

属性

not()

用法

返回值