LocatorAssertions

LocatorAssertions 類別提供可被用於對測試中的 Locator 狀態進行斷言的斷言方法。

using Microsoft.Playwright;
using Microsoft.Playwright.MSTest;

namespace PlaywrightTests;

[TestClass]
public class ExampleTests : PageTest
{
    [TestMethod]
    public async Task StatusBecomesSubmitted()
    {
        // ...
        await Page.GetByRole(AriaRole.Button, new() { Name = "Sign In" }).ClickAsync();
        await Expect(Page.Locator(".status")).ToHaveTextAsync("Submitted");
    }
}

方法

ToBeAttachedAsync

新增於: v1.33

locatorAssertions.ToBeAttachedAsync

確保 Locator 指向一個連接到 Document 或 ShadowRoot 的元素。

用法

await Expect(Page.GetByText("Hidden text")).ToBeAttachedAsync();

引數

options LocatorAssertionsToBeAttachedOptions? (選用)
- Attached bool? (選用)#
- Timeout [float]? (選用)#
  
  重試斷言的時間，以毫秒為單位。預設為 5000。

回傳

void #

ToBeCheckedAsync

新增於: v1.20

locatorAssertions.ToBeCheckedAsync

確保 Locator 指向一個已勾選的輸入。

用法

var locator = Page.GetByLabel("Subscribe to newsletter");
await Expect(locator).ToBeCheckedAsync();

引數

options LocatorAssertionsToBeCheckedOptions? (選用)
- Checked bool? (選用)新增於: v1.18#
  
  提供要斷言的狀態。預設斷言輸入為已勾選。當 Indeterminate 設定為 true 時，不能使用此選項。
- Indeterminate bool? (選用)新增於: v1.50#
  
  斷言元素處於不確定（混合）狀態。僅支援核取方塊和單選按鈕。當提供 Checked 時，此選項不能為 true。
- Timeout [float]? (選用)新增於: v1.18#
  
  重試斷言的時間，以毫秒為單位。預設為 5000。

回傳

void #

ToBeDisabledAsync

新增於: v1.20

locatorAssertions.ToBeDisabledAsync

確保 Locator 指向一個已停用的元素。如果元素具有 "disabled" 屬性或通過 'aria-disabled' 停用，則該元素被停用。請注意，只有原生控制元素（例如 HTML button、input、select、textarea、option、optgroup）可以通過設定 "disabled" 屬性來停用。"disabled" 屬性在其他元素上會被瀏覽器忽略。

用法

var locator = Page.Locator("button.submit");
await Expect(locator).ToBeDisabledAsync();

引數

options LocatorAssertionsToBeDisabledOptions? (選用)
- Timeout [float]? (選用)新增於: v1.18#
  
  重試斷言的時間，以毫秒為單位。預設為 5000。

回傳

void #

ToBeEditableAsync

新增於: v1.20

locatorAssertions.ToBeEditableAsync

確保 Locator 指向一個可編輯的元素。

用法

var locator = Page.GetByRole(AriaRole.Textbox);
await Expect(locator).ToBeEditableAsync();

引數

options LocatorAssertionsToBeEditableOptions? (選用)
- Editable bool? (選用)新增於: v1.26#
- Timeout [float]? (選用)新增於: v1.18#
  
  重試斷言的時間，以毫秒為單位。預設為 5000。

回傳

void #

ToBeEmptyAsync

新增於: v1.20

locatorAssertions.ToBeEmptyAsync

確保 Locator 指向一個空的、可編輯的元素，或指向一個沒有文字的 DOM 節點。

用法

var locator = Page.Locator("div.warning");
await Expect(locator).ToBeEmptyAsync();

引數

options LocatorAssertionsToBeEmptyOptions? (選用)
- Timeout [float]? (選用)新增於: v1.18#
  
  重試斷言的時間，以毫秒為單位。預設為 5000。

回傳

void #

ToBeEnabledAsync

新增於: v1.20

locatorAssertions.ToBeEnabledAsync

確保 Locator 指向一個已啟用的元素。

用法

var locator = Page.Locator("button.submit");
await Expect(locator).ToBeEnabledAsync();

引數

options LocatorAssertionsToBeEnabledOptions? (選用)
- Enabled bool? (選用)新增於: v1.26#
- Timeout [float]? (選用)新增於: v1.18#
  
  重試斷言的時間，以毫秒為單位。預設為 5000。

回傳

void #

ToBeFocusedAsync

新增於: v1.20

locatorAssertions.ToBeFocusedAsync

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

用法

var locator = Page.GetByRole(AriaRole.Textbox);
await Expect(locator).ToBeFocusedAsync();

引數

options LocatorAssertionsToBeFocusedOptions? (選用)
- Timeout [float]? (選用)新增於: v1.18#
  
  重試斷言的時間，以毫秒為單位。預設為 5000。

回傳

void #

ToBeHiddenAsync

新增於: v1.20

locatorAssertions.ToBeHiddenAsync

確保 Locator 要麼不解析為任何 DOM 節點，要麼解析為一個不可見的節點。

用法

var locator = Page.Locator(".my-element");
await Expect(locator).ToBeHiddenAsync();

引數

options LocatorAssertionsToBeHiddenOptions? (選用)
- Timeout [float]? (選用)新增於: v1.18#
  
  重試斷言的時間，以毫秒為單位。預設為 5000。

回傳

void #

ToBeInViewportAsync

新增於: v1.31

locatorAssertions.ToBeInViewportAsync

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

用法

var locator = Page.GetByRole(AriaRole.Button);
// Make sure at least some part of element intersects viewport.
await Expect(locator).ToBeInViewportAsync();
// Make sure element is fully outside of viewport.
await Expect(locator).Not.ToBeInViewportAsync();
// Make sure that at least half of the element intersects viewport.
await Expect(locator).ToBeInViewportAsync(new() { Ratio = 0.5 });

引數

options LocatorAssertionsToBeInViewportOptions? (選用)
- Ratio [float]? (選用)#
  
  元素與 viewport 相交的最小比例。如果等於 0，則元素應以任何正比例與 viewport 相交。預設為 0。
- Timeout [float]? (選用)#
  
  重試斷言的時間，以毫秒為單位。預設為 5000。

回傳

void #

ToBeVisibleAsync

新增於: v1.20

locatorAssertions.ToBeVisibleAsync

確保 Locator 指向一個已附加且可見的 DOM 節點。

要檢查列表中的至少一個元素是否可見，請使用 Locator.First。

用法

// A specific element is visible.
await Expect(Page.GetByText("Welcome")).ToBeVisibleAsync();

// At least one item in the list is visible.
await Expect(Page.GetByTestId("todo-item").First).ToBeVisibleAsync();

// At least one of the two elements is visible, possibly both.
await Expect(
  Page.GetByRole(AriaRole.Button, new() { Name = "Sign in" })
    .Or(Page.GetByRole(AriaRole.Button, new() { Name = "Sign up" }))
    .First
).ToBeVisibleAsync();

引數

options LocatorAssertionsToBeVisibleOptions? (選用)
- Timeout [float]? (選用)新增於: v1.18#
  
  重試斷言的時間，以毫秒為單位。預設為 5000。
- Visible bool? (選用)新增於: v1.26#

回傳

void #

ToContainTextAsync

新增於: v1.20

locatorAssertions.ToContainTextAsync

確保 Locator 指向一個包含給定文字的元素。在計算元素的文字內容時，將考慮所有巢狀元素。您也可以使用正則表達式作為值。

用法

var locator = Page.Locator(".title");
await Expect(locator).ToContainTextAsync("substring");
await Expect(locator).ToContainTextAsync(new Regex("\\d messages"));

如果您傳遞一個陣列作為預期值，則期望是

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
await Expect(Page.Locator("ul > li")).ToContainTextAsync(new string[] {"Text 1", "Text 3", "Text 4"});

// ✖ Wrong order
await Expect(Page.Locator("ul > li")).ToContainTextAsync(new string[] {"Text 3", "Text 2"});

// ✖ No item contains this text
await Expect(Page.Locator("ul > li")).ToContainTextAsync(new string[] {"Some 33"});

// ✖ Locator points to the outer list element, not to the list items
await Expect(Page.Locator("ul")).ToContainTextAsync(new string[] {"Text 3"});

引數

expected string | Regex | IEnumerable<string> | IEnumerable<Regex>新增於: v1.18#

預期的子字串或 RegExp 或它們的列表。
options LocatorAssertionsToContainTextOptions? (選用)
- IgnoreCase bool? (選用)新增於: v1.23#
  
  是否執行不區分大小寫的匹配。IgnoreCase 選項優先於對應的正則表達式標誌（如果指定）。
- Timeout [float]? (選用)新增於: v1.18#
  
  重試斷言的時間，以毫秒為單位。預設為 5000。
- UseInnerText bool? (選用)新增於: v1.18#
  
  在檢索 DOM 節點文字時，是否使用 element.innerText 而不是 element.textContent。

回傳

void #

詳細資訊

當 expected 參數是字串時，Playwright 將在匹配之前正規化實際文字和預期字串中的空格和換行符。當使用正則表達式時，實際文字將按原樣匹配。

ToHaveAccessibleDescriptionAsync

新增於: v1.44

locatorAssertions.ToHaveAccessibleDescriptionAsync

確保 Locator 指向一個具有給定的可存取描述的元素。

用法

var locator = Page.GetByTestId("save-button");
await Expect(locator).ToHaveAccessibleDescriptionAsync("Save results to disk");

引數

description string | Regex #

預期的可存取描述。
options LocatorAssertionsToHaveAccessibleDescriptionOptions? (選用)
- IgnoreCase bool? (選用)#
  
  是否執行不區分大小寫的匹配。IgnoreCase 選項優先於對應的正則表達式標誌（如果指定）。
- Timeout [float]? (選用)#
  
  重試斷言的時間，以毫秒為單位。預設為 5000。

回傳

void #

ToHaveAccessibleErrorMessageAsync

新增於: v1.50

locatorAssertions.ToHaveAccessibleErrorMessageAsync

確保 Locator 指向一個具有給定的 aria errormessage 的元素。

用法

var locator = Page.GetByTestId("username-input");
await Expect(locator).ToHaveAccessibleErrorMessageAsync("Username is required.");

引數

errorMessage string | Regex #

預期的可存取錯誤訊息。
options LocatorAssertionsToHaveAccessibleErrorMessageOptions? (選用)
- IgnoreCase bool? (選用)#
  
  是否執行不區分大小寫的匹配。IgnoreCase 選項優先於對應的正則表達式標誌（如果指定）。
- Timeout [float]? (選用)#
  
  重試斷言的時間，以毫秒為單位。預設為 5000。

回傳

void #

ToHaveAccessibleNameAsync

新增於: v1.44

locatorAssertions.ToHaveAccessibleNameAsync

確保 Locator 指向一個具有給定的可存取名稱的元素。

用法

var locator = Page.GetByTestId("save-button");
await Expect(locator).ToHaveAccessibleNameAsync("Save to disk");

引數

name string | Regex #

預期的可存取名稱。
options LocatorAssertionsToHaveAccessibleNameOptions? (選用)
- IgnoreCase bool? (選用)#
  
  是否執行不區分大小寫的匹配。IgnoreCase 選項優先於對應的正則表達式標誌（如果指定）。
- Timeout [float]? (選用)#
  
  重試斷言的時間，以毫秒為單位。預設為 5000。

回傳

void #

ToHaveAttributeAsync

新增於: v1.20

locatorAssertions.ToHaveAttributeAsync

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

用法

var locator = Page.Locator("input");
await Expect(locator).ToHaveAttributeAsync("type", "text");

引數

name string新增於: v1.18#

屬性名稱。
value string | Regex新增於: v1.18#

預期的屬性值。
options LocatorAssertionsToHaveAttributeOptions? (選用)
- IgnoreCase bool? (選用)新增於: v1.40#
  
  是否執行不區分大小寫的匹配。IgnoreCase 選項優先於對應的正則表達式標誌（如果指定）。
- Timeout [float]? (選用)新增於: v1.18#
  
  重試斷言的時間，以毫秒為單位。預設為 5000。

回傳

void #

ToHaveClassAsync

新增於: v1.20

locatorAssertions.ToHaveClassAsync

確保 Locator 指向一個具有給定 CSS 類別的元素。當提供字串時，它必須完全匹配元素的 class 屬性。要匹配個別類別或執行部分匹配，請使用正則表達式

用法

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

var locator = Page.Locator("#component");
await Expect(locator).ToHaveClassAsync(new Regex("(^|\\s)selected(\\s|$)"));
await Expect(locator).ToHaveClassAsync("middle selected row");

當傳遞陣列時，此方法會斷言找到的元素列表與預期的類別值列表相符。每個元素的 class 屬性都與陣列中對應的字串或正則表達式匹配

var locator = Page.Locator("list > .component");
await Expect(locator).ToHaveClassAsync(new string[]{"component", "component selected", "component"});

引數

expected string | Regex | IEnumerable<string> | IEnumerable<Regex>新增於: v1.18#

預期的類別或 RegExp 或它們的列表。
options LocatorAssertionsToHaveClassOptions? (選用)
- Timeout [float]? (選用)新增於: v1.18#
  
  重試斷言的時間，以毫秒為單位。預設為 5000。

回傳

void #

ToHaveCountAsync

新增於: v1.20

locatorAssertions.ToHaveCountAsync

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

用法

var locator = Page.Locator("list > .component");
await Expect(locator).ToHaveCountAsync(3);

引數

count int新增於: v1.18#

預期的計數。
options LocatorAssertionsToHaveCountOptions? (選用)
- Timeout [float]? (選用)新增於: v1.18#
  
  重試斷言的時間，以毫秒為單位。預設為 5000。

回傳

void #

ToHaveCSSAsync

新增於: v1.20

locatorAssertions.ToHaveCSSAsync

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

用法

var locator = Page.GetByRole(AriaRole.Button);
await Expect(locator).ToHaveCSSAsync("display", "flex");

引數

name string新增於: v1.18#

CSS 屬性名稱。
value string | Regex新增於: v1.18#

CSS 屬性值。
options LocatorAssertionsToHaveCSSOptions? (選用)
- Timeout [float]? (選用)新增於: v1.18#
  
  重試斷言的時間，以毫秒為單位。預設為 5000。

回傳

void #

ToHaveIdAsync

新增於: v1.20

locatorAssertions.ToHaveIdAsync

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

用法

var locator = Page.GetByRole(AriaRole.Textbox);
await Expect(locator).ToHaveIdAsync("lastname");

引數

id string | Regex新增於: v1.18#

元素 ID。
options LocatorAssertionsToHaveIdOptions? (選用)
- Timeout [float]? (選用)新增於: v1.18#
  
  重試斷言的時間，以毫秒為單位。預設為 5000。

回傳

void #

ToHaveJSPropertyAsync

新增於: v1.20

locatorAssertions.ToHaveJSPropertyAsync

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

用法

var locator = Page.Locator(".component");
await Expect(locator).ToHaveJSPropertyAsync("loaded", true);

引數

name string新增於: v1.18#

屬性名稱。
value [object]新增於: v1.18#

屬性值。
options LocatorAssertionsToHaveJSPropertyOptions? (選用)
- Timeout [float]? (選用)新增於: v1.18#
  
  重試斷言的時間，以毫秒為單位。預設為 5000。

回傳

void #

ToHaveRoleAsync

新增於: v1.44

locatorAssertions.ToHaveRoleAsync

確保 Locator 指向一個具有給定的 ARIA 角色的元素。

請注意，角色是作為字串匹配的，忽略了 ARIA 角色層次結構。例如，在具有子類別角色 "switch" 的元素上斷言超類別角色 "checkbox" 將會失敗。

用法

var locator = Page.GetByTestId("save-button");
await Expect(locator).ToHaveRoleAsync(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 LocatorAssertionsToHaveRoleOptions? (選用)
- Timeout [float]? (選用)#
  
  重試斷言的時間，以毫秒為單位。預設為 5000。

回傳

void #

ToHaveTextAsync

新增於: v1.20

locatorAssertions.ToHaveTextAsync

確保 Locator 指向一個具有給定文字的元素。在計算元素的文字內容時，將考慮所有巢狀元素。您也可以使用正則表達式作為值。

用法

var locator = Page.Locator(".title");
await Expect(locator).ToHaveTextAsync(new Regex("Welcome, Test User"));
await Expect(locator).ToHaveTextAsync(new Regex("Welcome, .*"));

如果您傳遞一個陣列作為預期值，則期望是

Locator 解析為元素列表。
元素的數量等於陣列中預期值的數量。
列表中的元素具有與預期陣列值匹配的文字，一個接一個，依序排列。

例如，考慮以下列表

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

讓我們看看如何使用斷言

// ✓ Has the right items in the right order
await Expect(Page.Locator("ul > li")).ToHaveTextAsync(new string[] {"Text 1", "Text 2", "Text 3"});

// ✖ Wrong order
await Expect(Page.Locator("ul > li")).ToHaveTextAsync(new string[] {"Text 3", "Text 2", "Text 1"});

// ✖ Last item does not match
await Expect(Page.Locator("ul > li")).ToHaveTextAsync(new string[] {"Text 1", "Text 2", "Text"});

// ✖ Locator points to the outer list element, not to the list items
await Expect(Page.Locator("ul")).ToHaveTextAsync(new string[] {"Text 1", "Text 2", "Text 3"});

引數

expected string | Regex | IEnumerable<string> | IEnumerable<Regex>新增於: v1.18#

預期的字串或 RegExp 或它們的列表。
options LocatorAssertionsToHaveTextOptions? (選用)
- IgnoreCase bool? (選用)新增於: v1.23#
  
  是否執行不區分大小寫的匹配。IgnoreCase 選項優先於對應的正則表達式標誌（如果指定）。
- Timeout [float]? (選用)新增於: v1.18#
  
  重試斷言的時間，以毫秒為單位。預設為 5000。
- UseInnerText bool? (選用)新增於: v1.18#
  
  在檢索 DOM 節點文字時，是否使用 element.innerText 而不是 element.textContent。

回傳

void #

詳細資訊

當 expected 參數是字串時，Playwright 將在匹配之前正規化實際文字和預期字串中的空格和換行符。當使用正則表達式時，實際文字將按原樣匹配。

ToHaveValueAsync

新增於: v1.20

locatorAssertions.ToHaveValueAsync

確保 Locator 指向一個具有給定輸入值的元素。您也可以使用正則表達式作為值。

用法

var locator = Page.Locator("input[type=number]");
await Expect(locator).ToHaveValueAsync(new Regex("[0-9]"));

引數

value string | Regex新增於: v1.18#

預期的值。
options LocatorAssertionsToHaveValueOptions? (選用)
- Timeout [float]? (選用)新增於: v1.18#
  
  重試斷言的時間，以毫秒為單位。預設為 5000。

回傳

void #

ToHaveValuesAsync

新增於: v1.23

locatorAssertions.ToHaveValuesAsync

確保 Locator 指向多選/組合方塊（即具有 multiple 屬性的 select），並且已選取指定的 values。

用法

例如，給定以下元素

<select id="favorite-colors" multiple>
  <option value="R">Red</option>
  <option value="G">Green</option>
  <option value="B">Blue</option>
</select>

var locator = Page.Locator("id=favorite-colors");
await locator.SelectOptionAsync(new string[] { "R", "G" });
await Expect(locator).ToHaveValuesAsync(new Regex[] { new Regex("R"), new Regex("G") });

引數

values IEnumerable<string> | IEnumerable<Regex>#

預期的當前選定選項。
options LocatorAssertionsToHaveValuesOptions? (選用)
- Timeout [float]? (選用)#
  
  重試斷言的時間，以毫秒為單位。預設為 5000。

回傳

void #

ToMatchAriaSnapshotAsync

新增於: v1.49

locatorAssertions.ToMatchAriaSnapshotAsync

斷言目標元素與給定的無障礙快照相符。

用法

await page.GotoAsync("https://demo.playwright.dev/todomvc/");
await Expect(page.Locator("body")).ToMatchAriaSnapshotAsync(@"
  - heading ""todos""
  - textbox ""What needs to be done?""
");

引數

expected string #
options LocatorAssertionsToMatchAriaSnapshotOptions? (選用)
- Timeout [float]? (選用)#
  
  重試斷言的時間，以毫秒為單位。預設為 5000。

回傳

void #

屬性

Not

新增於: v1.20

locatorAssertions.Not

使斷言檢查相反的條件。例如，此程式碼測試 Locator 不包含文字 "error"

await Expect(locator).Not.ToContainTextAsync("error");

用法

Expect(Locator).Not

類型

LocatorAssertions

方法​

ToBeAttachedAsync​

ToBeCheckedAsync​

ToBeDisabledAsync​

ToBeEditableAsync​

ToBeEmptyAsync​

ToBeEnabledAsync​

ToBeFocusedAsync​

ToBeHiddenAsync​

ToBeInViewportAsync​

ToBeVisibleAsync​

ToContainTextAsync​

ToHaveAccessibleDescriptionAsync​

ToHaveAccessibleErrorMessageAsync​

ToHaveAccessibleNameAsync​

ToHaveAttributeAsync​

ToHaveClassAsync​

ToHaveCountAsync​

ToHaveCSSAsync​

ToHaveIdAsync​

ToHaveJSPropertyAsync​

ToHaveRoleAsync​

ToHaveTextAsync​

ToHaveValueAsync​

ToHaveValuesAsync​

ToMatchAriaSnapshotAsync​

屬性​

Not​

方法

ToBeAttachedAsync

ToBeCheckedAsync

ToBeDisabledAsync

ToBeEditableAsync

ToBeEmptyAsync

ToBeEnabledAsync

ToBeFocusedAsync

ToBeHiddenAsync

ToBeInViewportAsync

ToBeVisibleAsync

ToContainTextAsync

ToHaveAccessibleDescriptionAsync

ToHaveAccessibleErrorMessageAsync

ToHaveAccessibleNameAsync

ToHaveAttributeAsync

ToHaveClassAsync

ToHaveCountAsync

ToHaveCSSAsync

ToHaveIdAsync

ToHaveJSPropertyAsync

ToHaveRoleAsync

ToHaveTextAsync

ToHaveValueAsync

ToHaveValuesAsync

ToMatchAriaSnapshotAsync

屬性

Not