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。

用法

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]? (可选)#
  
  元素与视口相交的最小比例。如果等于 0，则元素应以任何正比例与视口相交。默认为 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），并且已选择指定的值。

用法

例如，给定以下元素

<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