跳至主要内容

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

如果将数组作为预期值传递,则预期将

  1. Locator 解析为元素列表。
  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#

    预期的子字符串或 RegExp 或它们的列表。

  • options LocatorAssertions.ContainsTextOptions (可选)

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

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

    • setTimeout double (可选)添加于:v1.18#

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

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

      是否使用 element.innerText 而不是 element.textContent 来检索 DOM 节点文本。

返回

详情

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

返回


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

返回


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

返回


hasClass

添加于:v1.20 locatorAssertions.hasClass

确保 Locator 指向具有给定 CSS 类的元素。这需要是完全匹配或使用宽松的正则表达式。

用法

<div class='selected row' id='component'></div>
assertThat(page.locator("#component")).hasClass(Pattern.compile("selected"));
assertThat(page.locator("#component")).hasClass("selected row");

请注意,如果数组作为预期值传递,则可以断言整个元素列表

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

返回


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

返回


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

返回


hasId

添加于:v1.20 locatorAssertions.hasId

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

用法

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

参数

  • id 字符串 | 模式添加于:v1.18#

    元素 ID。

  • options LocatorAssertions.HasIdOptions (可选)

    • setTimeout double (可选)添加于:v1.18#

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

返回


hasJSProperty

添加于:v1.20 locatorAssertions.hasJSProperty

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

用法

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

参数

  • name String添加于:v1.18#

    属性名称。

  • value 对象添加于:v1.18#

    属性值。

  • options LocatorAssertions.HasJSPropertyOptions (可选)

    • setTimeout double (可选)添加于:v1.18#

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

返回


hasRole

添加于:v1.44 locatorAssertions.hasRole

确保 定位器 指向具有给定 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 双精度浮点数 (可选)#

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

返回


hasText

添加于:v1.20 locatorAssertions.hasText

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

用法

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

如果将数组作为预期值传递,则预期将

  1. Locator 解析为元素列表。
  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#

    预期字符串或 RegExp 或它们的列表。

  • options LocatorAssertions.HasTextOptions (可选)

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

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

    • setTimeout double (可选)添加于:v1.18#

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

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

      是否使用 element.innerText 而不是 element.textContent 来检索 DOM 节点文本。

返回

详情

expected 参数是字符串时,Playwright 将在匹配之前对实际文本和预期字符串中的空格和换行符进行规范化。当使用正则表达式时,实际文本将按原样匹配。


hasValue

添加于:v1.20 locatorAssertions.hasValue

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

用法

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

参数

  • value String | Pattern添加于:v1.18#

    预期值。

  • options LocatorAssertions.HasValueOptions (可选)

    • setTimeout double (可选)添加于:v1.18#

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

返回


hasValues

添加于:v1.23 locatorAssertions.hasValues

确保 定位器 指向多选/组合框(即具有 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(["R", "G"]);
assertThat(page.locator("id=favorite-colors")).hasValues(new Pattern[] { Pattern.compile("R"), Pattern.compile("G") });

参数

  • values 字符串[] | 模式[]#

    预期当前选中的选项。

  • options LocatorAssertions.HasValuesOptions (可选)

    • setTimeout 双精度浮点数 (可选)#

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

返回


isAttached

添加到:v1.33 locatorAssertions.isAttached

确保 定位器 指向与文档或 ShadowRoot 连接 的元素。

用法

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

参数

  • options LocatorAssertions.IsAttachedOptions (可选)

返回


isChecked

添加于:v1.20 locatorAssertions.isChecked

确保 定位器 指向选中的输入。

用法

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

参数

  • options LocatorAssertions.IsCheckedOptions (可选)
    • setChecked 布尔值 (可选)添加于:v1.18#

    • setTimeout double (可选)添加于:v1.18#

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

返回


isDisabled

添加于:v1.20 locatorAssertions.isDisabled

确保 定位器 指向禁用的元素。如果元素具有 "disabled" 属性或通过 'aria-disabled' 禁用,则该元素被禁用。请注意,只有本机控件元素(如 HTML buttoninputselecttextareaoptionoptgroup)可以通过设置 "disabled" 属性禁用。浏览器会忽略其他元素上的 "disabled" 属性。

用法

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

参数

  • options LocatorAssertions.IsDisabledOptions (可选)
    • setTimeout double (可选)添加于:v1.18#

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

返回


isEditable

添加于:v1.20 locatorAssertions.isEditable

确保 定位器 指向可编辑的元素。

用法

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

参数

  • options LocatorAssertions.IsEditableOptions (可选)
    • setEditable 布尔值 (可选)添加到:v1.26#

    • setTimeout double (可选)添加于:v1.18#

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

返回


isEmpty

添加于:v1.20 locatorAssertions.isEmpty

确保 定位器 指向空的 可编辑 元素,或指向没有文本的 DOM 节点。

用法

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

参数

  • options LocatorAssertions.IsEmptyOptions (可选)
    • setTimeout double (可选)添加于:v1.18#

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

返回


isEnabled

添加于:v1.20 locatorAssertions.isEnabled

确保 定位器 指向启用的元素。

用法

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

参数

  • options LocatorAssertions.IsEnabledOptions (可选)
    • setEnabled 布尔值 (可选)添加到:v1.26#

    • setTimeout double (可选)添加于:v1.18#

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

返回


isFocused

添加于:v1.20 locatorAssertions.isFocused

确保 定位器 指向已获得焦点的 DOM 节点。

用法

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

参数

  • options LocatorAssertions.IsFocusedOptions (可选)
    • setTimeout double (可选)添加于:v1.18#

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

返回


isHidden

添加于:v1.20 locatorAssertions.isHidden

确保 定位器 既不解析为任何 DOM 节点,也不解析为 不可见 的节点。

用法

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

参数

  • options LocatorAssertions.IsHiddenOptions (可选)
    • setTimeout double (可选)添加于:v1.18#

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

返回


isInViewport

添加到:v1.31 locatorAssertions.isInViewport

确保 Locator 指向与视窗相交的元素,根据 交集观察者 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

返回


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#

返回


属性

not()

添加于:v1.20 locatorAssertions.not()

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

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

用法

assertThat(locator).not()

返回