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");
  }
}

方法​

containsText​

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

用法

assertThat(page.locator(".title")).containsText("substring");

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

1. 定位器解析为一组元素。
2. 该列表中的部分元素分别包含预期数组中的文本。
3. 匹配的元素子集与预期数组的顺序相同。
4. 预期数组中的每个文本值都与列表中的某个元素匹配。

例如，考虑以下列表：

<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
assertThat(page.locator("ul > li")).containsText(new String[] {"Text 1", "Text 3", "Text 4"});

// ✖ Wrong order
assertThat(page.locator("ul > li")).containsText(new String[] {"Text 3", "Text 2"});

// ✖ No item contains this text
assertThat(page.locator("ul > li")).containsText(new String[] {"Some 33"});

// ✖ Locator points to the outer list element, not to the list items
assertThat(page.locator("ul")).containsText(new String[] {"Text 3"});

参数

• expected String | Pattern | String[] | Pattern[] 添加于: v1.18#

  预期的子字符串或正则表达式或其列表。

• options LocatorAssertions.ContainsTextOptions (可选)

  • setIgnoreCase boolean (可选) 添加于: v1.23#

    是否执行不区分大小写的匹配。如果指定了setIgnoreCase选项，它将优先于相应的正则表达式标志。

  • setTimeout double (可选) 新增于: v1.18#

    重试断言的时间，以毫秒为单位。默认为 5000。

  • setUseInnerText boolean (可选) 添加于: v1.18#

    在获取DOM节点文本时，是否使用element.innerText而非element.textContent。

返回

• void#

详情

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

hasAccessibleDescription​

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

用法

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

参数

• description String | Pattern#

  预期的可访问描述。

• options LocatorAssertions.HasAccessibleDescriptionOptions (可选)

  • setIgnoreCase boolean (可选)#

    是否执行不区分大小写的匹配。如果指定了setIgnoreCase选项，它将优先于相应的正则表达式标志。

  • setTimeout double (可选)#

    重试断言的超时时间，单位为毫秒。默认为 5000。

返回

• void#

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选项，它将优先于相应的正则表达式标志。

  • setTimeout double (可选)#

    重试断言的时间，以毫秒为单位。默认为 5000。

返回

• void#

hasAccessibleName​

确保Locator指向具有给定accessible name的元素。

用法

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

参数

• name String | Pattern#

  预期的可访问名称。

• options LocatorAssertions.HasAccessibleNameOptions (可选)

  • setIgnoreCase boolean (可选)#

    是否执行不区分大小写的匹配。如果指定了setIgnoreCase选项，它将优先于相应的正则表达式标志。

  • setTimeout double (可选)#

    重试断言的超时时间，单位为毫秒。默认为 5000。

返回

• void#

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选项，它将优先于相应的正则表达式标志。

  • setTimeout double (可选) 新增于: v1.18#

    重试断言的时间，以毫秒为单位。默认为 5000。

返回

• void#

hasClass​

确保Locator指向具有给定CSS类的元素。当提供字符串时，它必须完全匹配元素的class属性。要匹配单个类或执行部分匹配，请使用正则表达式：

用法

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

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

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

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​

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

用法

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

参数

• count int 添加于: v1.18#

  预期数量。

• options LocatorAssertions.HasCountOptions (可选)

  • setTimeout double (可选) 新增于: v1.18#

    重试断言的时间，以毫秒为单位。默认为 5000。

返回

• void#

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​

确保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​

确保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​

确保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​

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

用法

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

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

1. 定位器解析为一组元素。
2. 元素数量等于数组中预期值的数量。
3. 列表中的元素依次按顺序匹配预期数组值的文本。

例如，考虑以下列表：

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

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

// ✓ Has the right items in the right order
assertThat(page.locator("ul > li")).hasText(new String[] {"Text 1", "Text 2", "Text 3"});

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

// ✖ Last item does not match
assertThat(page.locator("ul > li")).hasText(new String[] {"Text 1", "Text 2", "Text"});

// ✖ Locator points to the outer list element, not to the list items
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选项，它将优先于相应的正则表达式标志。

  • setTimeout double (可选) 新增于: v1.18#

    重试断言的时间，以毫秒为单位。默认为 5000。

  • setUseInnerText boolean (可选) 添加于: v1.18#

    在获取DOM节点文本时，是否使用element.innerText而非element.textContent。

返回

• void#

详情

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

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​

确保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​

确保Locator指向一个connected到Document或ShadowRoot的元素。

用法

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

参数

• options LocatorAssertions.IsAttachedOptions (optional)

  • setAttached boolean (可选)#

  • setTimeout double (可选)#

    重试断言的时间，以毫秒为单位。默认为 5000。

返回

• void#

isChecked​

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

用法

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

参数

• options LocatorAssertions.IsCheckedOptions (optional)

  • setChecked boolean (可选) 添加于: v1.18#

    提供要断言的状态。默认断言输入应被勾选。当setIndeterminate设为true时不能使用此选项。

  • setIndeterminate boolean (可选) 添加于: v1.50#

    断言元素处于不确定(混合)状态。仅支持复选框和单选按钮。当提供setChecked时，此选项不能为true。

  • setTimeout double (可选) 新增于: v1.18#

    重试断言的时间，以毫秒为单位。默认为 5000。

返回

• void#

isDisabled​

Ensures the Locator points to a disabled element. Element is disabled if it has "disabled" attribute or is disabled via 'aria-disabled'. Note that only native control elements such as HTML button, input, select, textarea, option, optgroup can be disabled by setting "disabled" attribute. "disabled" attribute on other elements is ignored by the browser.

用法

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

参数

• options LocatorAssertions.IsDisabledOptions (optional)

  • setTimeout double (可选) 新增于: v1.18#

    重试断言的时间，以毫秒为单位。默认为 5000。

返回

• void#

isEditable​

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

用法

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

参数

• options LocatorAssertions.IsEditableOptions (optional)

  • setEditable boolean (可选) 新增于: v1.26#

  • setTimeout double (可选) 新增于: v1.18#

    重试断言的时间，以毫秒为单位。默认为 5000。

返回

• void#

isEmpty​

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

用法

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

参数

• options LocatorAssertions.IsEmptyOptions (optional)

  • setTimeout double (可选) 新增于: v1.18#

    重试断言的时间，以毫秒为单位。默认为 5000。

返回

• void#

isEnabled​

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

用法

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

参数

• options LocatorAssertions.IsEnabledOptions (optional)

  • setEnabled boolean (可选) 添加于: v1.26#

  • setTimeout double (可选) 新增于: v1.18#

    重试断言的时间，以毫秒为单位。默认为 5000。

返回

• void#

isFocused​

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

用法

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

参数

• options LocatorAssertions.IsFocusedOptions (optional)

  • setTimeout double (可选) 新增于: v1.18#

    重试断言的时间，以毫秒为单位。默认为 5000。

返回

• void#

isHidden​

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

用法

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

参数

• options LocatorAssertions.IsHiddenOptions (optional)

  • setTimeout double (可选) 新增于: v1.18#

    重试断言的时间，以毫秒为单位。默认为 5000。

返回

• void#

isInViewport​

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

用法

Locator locator = page.getByRole(AriaRole.BUTTON);
// Make sure at least some part of element intersects viewport.
assertThat(locator).isInViewport();
// Make sure element is fully outside of viewport.
assertThat(locator).not().isInViewport();
// Make sure that at least half of the element intersects viewport.
assertThat(locator).isInViewport(new LocatorAssertions.IsInViewportOptions().setRatio(0.5));

参数

• options LocatorAssertions.IsInViewportOptions (optional)

  • setRatio double (可选)#

    元素与视口相交的最小比例。如果等于0，则元素应以任何正比例与视口相交。默认为0。

  • setTimeout double (可选)#

    重试断言的时间，以毫秒为单位。默认为 5000。

返回

• void#

isVisible​

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

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

用法

// A specific element is visible.
assertThat(page.getByText("Welcome")).isVisible();

// At least one item in the list is visible.
assertThat(page.getByTestId("todo-item").first()).isVisible();

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

  • setTimeout double (可选) 新增于: v1.18#

    重试断言的时间，以毫秒为单位。默认为 5000。

  • setVisible boolean (可选) 添加于: v1.26#

返回

• void#

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 (optional)

  • setTimeout double (可选)#

    重试断言的时间，以毫秒为单位。默认为 5000。

返回

• void#

属性​

not()​

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

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

用法

assertThat(locator).not()

返回

• LocatorAssertions