定位器断言

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

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

<div class='list'></div>
  <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("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 指向的元素具有给定的 accessible description。

用法

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

参数

description String | Pattern #

预期的 accessible description。
options LocatorAssertions.HasAccessibleDescriptionOptions (可选)
- setIgnoreCase boolean (可选)#
  
  是否执行不区分大小写的匹配。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 #

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

返回值

void #

hasAccessibleName

添加于: v1.44

locatorAssertions.hasAccessibleName

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

用法

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

参数

name String | Pattern #

预期的 accessible name。
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 属性完全匹配。要匹配单个类，请使用 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|$)"));

当传递数组时，该方法断言定位到的元素列表与对应的预期类值列表匹配。每个元素的 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 role 的元素。

请注意， role 是按字符串匹配的，不考虑 ARIA role 层次结构。例如，在一个具有子类角色 "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 role。
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

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

用法

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

返回值

定位器断言

方法​

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