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

添加于: v1.20

locatorAssertions.containsText

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

用法

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

如果您传递一个数组作为期望值，则期望是

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
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#

期望的子字符串或 RegExp 或它们的列表。
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

添加于: 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 选项优先于指定的相应正则表达式标志。
- setTimeout double (可选)#
  
  重试断言的时间，以毫秒为单位。默认为 5000。

void #

hasAccessibleErrorMessage

添加于: v1.50

locatorAssertions.hasAccessibleErrorMessage

确保 Locator 指向具有给定 aria 错误消息的元素。

用法

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

添加于: 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 选项优先于指定的相应正则表达式标志。
- 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 选项优先于指定的相应正则表达式标志。
- setTimeout double (可选)添加于: v1.18#
  
  重试断言的时间，以毫秒为单位。默认为 5000。

void #

hasClass

添加于: v1.20

locatorAssertions.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#

期望的类或 RegExp 或它们的列表。
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, .*"));

如果您传递一个数组作为期望值，则期望是

Locator 解析为元素列表。
元素的数量等于数组中期望值的数量。
列表中的元素具有与期望数组值匹配的文本，一个接一个，按顺序排列。

例如，考虑以下列表

<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#

期望的字符串或 RegExp 或它们的列表。
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

添加于: 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.33

locatorAssertions.isAttached

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

用法

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

参数

options LocatorAssertions.IsAttachedOptions (可选)
- setAttached boolean (可选)#
- setTimeout double (可选)#
  
  重试断言的时间，以毫秒为单位。默认为 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 boolean (可选)添加于: v1.26#
- setTimeout double (可选)添加于: v1.18#
  
  重试断言的时间，以毫秒为单位。默认为 5000。

void #

isEmpty

添加于: v1.20

locatorAssertions.isEmpty

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

用法

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

参数

options LocatorAssertions.IsEmptyOptions (可选)
- setTimeout double (可选)添加于: 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

确保 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 (可选)
- setRatio double (可选)#
  
  元素与视口相交的最小比例。如果等于 0，则元素应以任何正比例与视口相交。默认为 0。
- setTimeout double (可选)#
  
  重试断言的时间，以毫秒为单位。默认为 5000。

void #

isVisible

添加于: v1.20

locatorAssertions.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 (可选)
- 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()

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

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

用法

assertThat(locator).not()

LocatorAssertions

方法​

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

方法

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