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​

确保Locator指向一个connected到Document或ShadowRoot的元素。

用法

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

参数

• options LocatorAssertionsToBeAttachedOptions? (optional)

  • Attached bool? (可选)#

  • Timeout [float]? (可选)#

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

返回

• void#

待检查异步​

确保Locator指向一个已勾选的输入框。

用法

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

参数

• options LocatorAssertionsToBeCheckedOptions? (optional)

  • Checked bool? (可选) 添加于: v1.18#

    提供要断言的状态。默认情况下断言输入应被勾选。当Indeterminate设置为true时不能使用此选项。

  • Indeterminate bool? (可选) 添加于: v1.50#

    断言元素处于不确定(混合)状态。仅支持复选框和单选按钮。当提供Checked时，此选项不能为true。

  • Timeout [float]? (可选) 添加于: v1.18#

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

返回

• void#

ToBeDisabledAsync​

Ensures the Locator points to a disabled element. Element is disabled if it has "disabled" attribute or is disabled via 'aria-disabled'. Note that only native control elements such as HTML button, input, select, textarea, option, optgroup can be disabled by setting "disabled" attribute. "disabled" attribute on other elements is ignored by the browser.

用法

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

参数

• options LocatorAssertionsToBeDisabledOptions? (optional)

  • Timeout [float]? (可选) 添加于: v1.18#

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

返回

• void#

ToBeEditableAsync​

确保Locator指向一个可编辑的元素。

用法

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

参数

• options LocatorAssertionsToBeEditableOptions? (optional)

  • Editable bool? (可选) 添加于: v1.26#

  • Timeout [float]? (可选) 添加于: v1.18#

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

返回

• void#

ToBeEmptyAsync​

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

用法

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

参数

• options LocatorAssertionsToBeEmptyOptions? (optional)

  • Timeout [float]? (可选) 添加于: v1.18#

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

返回

• void#

ToBeEnabledAsync​

确保Locator指向一个已启用的元素。

用法

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

参数

• options LocatorAssertionsToBeEnabledOptions? (optional)

  • Enabled bool? (可选) 添加于: v1.26#

  • Timeout [float]? (可选) 添加于: v1.18#

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

返回

• void#

ToBeFocusedAsync​

确保 Locator 指向一个获得焦点的 DOM 节点。

用法

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

参数

• options LocatorAssertionsToBeFocusedOptions? (optional)

  • Timeout [float]? (可选) 添加于: v1.18#

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

返回

• void#

ToBeHiddenAsync​

确保Locator要么不解析为任何DOM节点，要么解析为一个不可见的节点。

用法

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

参数

• options LocatorAssertionsToBeHiddenOptions? (optional)

  • Timeout [float]? (可选) 添加于: v1.18#

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

返回

• void#

ToBeInViewportAsync​

确保Locator指向的元素与视口相交，依据intersection observer API。

用法

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

  • Ratio [float]? (可选)#

    元素与视口相交的最小比例。如果等于0，则元素应以任何正比例与视口相交。默认为0。

  • Timeout [float]? (可选)#

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

返回

• void#

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

  • Timeout [float]? (可选) 添加于: v1.18#

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

  • Visible bool? (可选) 添加于: v1.26#

返回

• void#

ToContainTextAsync​

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

用法

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

如果传递一个数组作为期望值，预期条件如下：

1. 定位器解析为一组元素。
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
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#

  预期的子字符串或正则表达式或其列表。

• 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​

确保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​

确保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​

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

用法

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​

确保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​

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

  预期的类或正则表达式或其列表。

• options LocatorAssertionsToHaveClassOptions? (可选)

  • Timeout [float]? (可选) 添加于: v1.18#

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

返回

• void#

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​

确保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​

确保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​

确保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​

确保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​

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

用法

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

如果传递一个数组作为期望值，预期条件如下：

1. 定位器解析为一组元素。
2. 元素数量等于数组中预期值的数量。
3. 列表中的元素依次按顺序匹配预期数组值的文本。

例如，考虑以下列表：

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

  预期的字符串或正则表达式或它们的列表。

• 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​

确保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​

确保Locator指向多选/组合框（即带有multiple属性的select元素）并选中指定的值。

用法

例如，给定以下元素：

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

断言目标元素与给定的无障碍快照匹配。

用法

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

  • Timeout [float]? (可选)#

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

返回

• void#

属性​

非​

使断言检查相反的条件。例如，以下代码测试定位器不包含文本"error"：

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

用法

Expect(Locator).Not

类型

• LocatorAssertions