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 字串 | Pattern | 字串[] | Pattern[]新增於：v1.18#

預期的子字串或 RegExp 或其列表。
options LocatorAssertions.ContainsTextOptions (選用)
- setIgnoreCase 布林值 (選用)新增於：v1.23#
  
  是否執行不區分大小寫的匹配。setIgnoreCase 選項優先於對應的正規表示式旗標（如果指定）。
- setTimeout 雙精度浮點數 (選用)新增於：v1.18#
  
  重試斷言的時間（以毫秒為單位）。預設為 5000。
- setUseInnerText 布林值 (選用)新增於：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 字串 | Pattern #

預期的無障礙描述。
options LocatorAssertions.HasAccessibleDescriptionOptions (選用)
- setIgnoreCase 布林值 (選用)#
  
  是否執行不區分大小寫的匹配。setIgnoreCase 選項優先於對應的正規表示式旗標（如果指定）。
- setTimeout 雙精度浮點數 (選用)#
  
  重試斷言的時間（以毫秒為單位）。預設為 5000。

傳回

void #

hasAccessibleErrorMessage

新增於：v1.50

locatorAssertions.hasAccessibleErrorMessage

確保 Locator 指向的元素具有指定的 aria 錯誤訊息。

用法

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

引數

errorMessage 字串 | Pattern #

預期的無障礙錯誤訊息。
options LocatorAssertions.HasAccessibleErrorMessageOptions (選用)
- setIgnoreCase 布林值 (選用)#
  
  是否執行不區分大小寫的匹配。setIgnoreCase 選項優先於對應的正規表示式旗標（如果指定）。
- setTimeout 雙精度浮點數 (選用)#
  
  重試斷言的時間（以毫秒為單位）。預設為 5000。

傳回

void #

hasAccessibleName

新增於：v1.44

locatorAssertions.hasAccessibleName

確保 Locator 指向的元素具有指定的無障礙名稱。

用法

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

引數

name 字串 | Pattern #

預期的無障礙名稱。
options LocatorAssertions.HasAccessibleNameOptions (選用)
- setIgnoreCase 布林值 (選用)#
  
  是否執行不區分大小寫的匹配。setIgnoreCase 選項優先於對應的正規表示式旗標（如果指定）。
- setTimeout 雙精度浮點數 (選用)#
  
  重試斷言的時間（以毫秒為單位）。預設為 5000。

傳回

void #

hasAttribute

新增於：v1.20

locatorAssertions.hasAttribute

確保 Locator 指向的元素具有指定的屬性。

用法

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

引數

name 字串新增於：v1.18#

屬性名稱。
value 字串 | Pattern新增於：v1.18#

預期的屬性值。
options LocatorAssertions.HasAttributeOptions (選用)
- setIgnoreCase 布林值 (選用)新增於：v1.40#
  
  是否執行不區分大小寫的匹配。setIgnoreCase 選項優先於對應的正規表示式旗標（如果指定）。
- setTimeout 雙精度浮點數 (選用)新增於：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 字串 | Pattern | 字串[] | Pattern[]新增於：v1.18#

預期的類別或 RegExp 或其列表。
options LocatorAssertions.HasClassOptions (選用)
- setTimeout 雙精度浮點數 (選用)新增於：v1.18#
  
  重試斷言的時間（以毫秒為單位）。預設為 5000。

傳回

void #

hasCount

新增於：v1.20

locatorAssertions.hasCount

確保 Locator 解析為精確數量的 DOM 節點。

用法

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

引數

count 整數新增於：v1.18#

預期的計數。
options LocatorAssertions.HasCountOptions (選用)
- setTimeout 雙精度浮點數 (選用)新增於：v1.18#
  
  重試斷言的時間（以毫秒為單位）。預設為 5000。

傳回

void #

hasCSS

新增於：v1.20

locatorAssertions.hasCSS

確保 Locator 解析為具有指定計算 CSS 樣式的元素。

用法

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

引數

name 字串新增於：v1.18#

CSS 屬性名稱。
value 字串 | Pattern新增於：v1.18#

CSS 屬性值。
options LocatorAssertions.HasCSSOptions (選用)
- setTimeout 雙精度浮點數 (選用)新增於：v1.18#
  
  重試斷言的時間（以毫秒為單位）。預設為 5000。

傳回

void #

hasId

新增於：v1.20

locatorAssertions.hasId

確保 Locator 指向的元素具有指定的 DOM 節點 ID。

用法

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

引數

id 字串 | Pattern新增於：v1.18#

元素 ID。
options LocatorAssertions.HasIdOptions (選用)
- setTimeout 雙精度浮點數 (選用)新增於：v1.18#
  
  重試斷言的時間（以毫秒為單位）。預設為 5000。

傳回

void #

hasJSProperty

新增於：v1.20

locatorAssertions.hasJSProperty

確保 Locator 指向的元素具有指定的 JavaScript 屬性。請注意，此屬性可以是基本類型，也可以是純粹可序列化的 JavaScript 物件。

用法

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

引數

name 字串新增於：v1.18#

屬性名稱。
value 物件新增於：v1.18#

屬性值。
options LocatorAssertions.HasJSPropertyOptions (選用)
- setTimeout 雙精度浮點數 (選用)新增於：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 雙精度浮點數 (選用)#
  
  重試斷言的時間（以毫秒為單位）。預設為 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 字串 | Pattern | 字串[] | Pattern[]新增於：v1.18#

預期的字串或 RegExp 或其列表。
options LocatorAssertions.HasTextOptions (選用)
- setIgnoreCase 布林值 (選用)新增於：v1.23#
  
  是否執行不區分大小寫的匹配。setIgnoreCase 選項優先於對應的正規表示式旗標（如果指定）。
- setTimeout 雙精度浮點數 (選用)新增於：v1.18#
  
  重試斷言的時間（以毫秒為單位）。預設為 5000。
- setUseInnerText 布林值 (選用)新增於：v1.18#
  
  在檢索 DOM 節點文字時，是否使用 element.innerText 而不是 element.textContent。

傳回

void #

詳細資訊

hasValue

新增於：v1.20

locatorAssertions.hasValue

確保 Locator 指向的元素具有指定的輸入值。您也可以對值使用正規表示式。

用法

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

引數

value 字串 | Pattern新增於：v1.18#

預期的值。
options LocatorAssertions.HasValueOptions (選用)
- setTimeout 雙精度浮點數 (選用)新增於：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 字串[] | Pattern[]#

目前選取的預期選項。
options LocatorAssertions.HasValuesOptions (選用)
- setTimeout 雙精度浮點數 (選用)#
  
  重試斷言的時間（以毫秒為單位）。預設為 5000。

傳回

void #

isAttached

新增於：v1.33

locatorAssertions.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 布林值 (選用)新增於：v1.18#
  
  提供要斷言的狀態。預設會斷言輸入是否已勾選。當 setIndeterminate 設定為 true 時，無法使用此選項。
- setIndeterminate 布林值 (選用)新增於：v1.50#
  
  斷言元素是否處於不確定（混合）狀態。僅支援核取方塊和單選按鈕。當提供 setChecked 時，此選項不能為 true。
- setTimeout 雙精度浮點數 (選用)新增於：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 雙精度浮點數 (選用)新增於：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 布林值 (選用)新增於：v1.26#
- setTimeout 雙精度浮點數 (選用)新增於：v1.18#
  
  重試斷言的時間（以毫秒為單位）。預設為 5000。

傳回

void #

isFocused

新增於：v1.20

locatorAssertions.isFocused

確保 Locator 指向已聚焦的 DOM 節點。

用法

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

引數

options LocatorAssertions.IsFocusedOptions (選用)
- setTimeout 雙精度浮點數 (選用)新增於：v1.18#
  
  重試斷言的時間（以毫秒為單位）。預設為 5000。

傳回

void #

isHidden

新增於：v1.20

locatorAssertions.isHidden

確保 Locator 要么不解析為任何 DOM 節點，要么解析為非可見的節點。

用法

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

引數

options LocatorAssertions.IsHiddenOptions (選用)
- setTimeout 雙精度浮點數 (選用)新增於：v1.18#
  
  重試斷言的時間（以毫秒為單位）。預設為 5000。

傳回

void #

isInViewport

新增於：v1.31

locatorAssertions.isInViewport

確保 Locator 指向的元素根據 intersection observer API 與可視viewport相交。

用法

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 雙精度浮點數 (選用)#
  
  元素與 viewport 相交的最小比率。如果等於 0，則元素應以任何正比率與 viewport 相交。預設為 0。
- setTimeout 雙精度浮點數 (選用)#
  
  重試斷言的時間（以毫秒為單位）。預設為 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 雙精度浮點數 (選用)新增於：v1.18#
  
  重試斷言的時間（以毫秒為單位）。預設為 5000。
- setVisible 布林值 (選用)新增於：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 字串 #
options LocatorAssertions.MatchesAriaSnapshotOptions (選用)
- setTimeout 雙精度浮點數 (選用)#
  
  重試斷言的時間（以毫秒為單位）。預設為 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()