跳到主要内容

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 指向的元素已 连接 到文档或 ShadowRoot。

用法

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

参数

  • options LocatorAssertionsToBeAttachedOptions? (可选)
    • Attached bool? (可选)#

    • Timeout [float]? (可选)#

      重试断言的时间(毫秒)。默认为 5000

返回


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

返回值


ToBeDisabledAsync

新增于:v1.20 locatorAssertions.ToBeDisabledAsync

确保 Locator 指向一个禁用的元素。如果元素有 "disabled" 属性,或者通过 'aria-disabled' 被禁用,则该元素为禁用状态。请注意,只有原生控件元素,如 HTML buttoninputselecttextareaoptionoptgroup,可以通过设置 "disabled" 属性来禁用。浏览器会忽略其他元素上的 "disabled" 属性。

用法

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

参数

  • options LocatorAssertionsToBeDisabledOptions? (可选)
    • Timeout [float]? (可选) 新增于:v1.18#

      重试断言的时间(毫秒)。默认为 5000

返回值


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

返回值


ToBeEmptyAsync

添加于:v1.20 locatorAssertions.ToBeEmptyAsync

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

使用方法

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

参数

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

      重试断言的时间(毫秒)。默认为 5000

返回值


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

返回值


ToBeFocusedAsync

新增于:v1.20 locatorAssertions.ToBeFocusedAsync

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

用法

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

参数

  • options LocatorAssertionsToBeFocusedOptions?可选
    • Timeout [float]?(可选新增于:v1.18#

      重试断言的时间(毫秒)。默认为 5000

返回值


ToBeHiddenAsync

新增于:v1.20 locatorAssertions.ToBeHiddenAsync

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

用法

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

参数

  • options LocatorAssertionsToBeHiddenOptions?可选
    • Timeout [float]?(可选新增于:v1.18#

      重试断言的时间(毫秒)。默认为 5000

返回值


ToBeInViewportAsync

新增于:v1.31 locatorAssertions.ToBeInViewportAsync

根据 交集观察器 API,确保 Locator 指向与视口相交的元素。

用法

var locator = Page.GetByRole(AriaRole.Button);
// 确保元素至少有一部分与视口相交。
await Expect(locator).ToBeInViewportAsync();
// 确保元素完全在视口之外。
await Expect(locator).Not.ToBeInViewportAsync();
// 确保元素至少有一半与视口相交。
await Expect(locator).ToBeInViewportAsync(new() { Ratio = 0.5 });

参数

  • options LocatorAssertionsToBeInViewportOptions?(可选)
    • Ratio [float]?(可选)#

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

    • Timeout [float]?(可选)#

      重试断言的时间(毫秒)。默认为 5000

返回


ToBeVisibleAsync

新增于:v1.20 locatorAssertions.ToBeVisibleAsync

确保 Locator 指向一个已附加且 可见 的 DOM 节点。

要检查列表中至少有一个元素可见,请使用 Locator.First

用法

// 特定元素可见。
await Expect(Page.GetByText("Welcome")).ToBeVisibleAsync();

// 列表中至少有一个项目可见。
await Expect(Page.GetByTestId("todo-item").First).ToBeVisibleAsync();

// 两个元素中至少有一个可见,也可能两个都可见。
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#

返回


ToContainClassAsync

添加于:v1.52 locatorAssertions.ToContainClassAsync

确保 Locator 指向具有给定 CSS 类的元素。断言值中以空格分隔的所有类,必须以任意顺序存在于 Element.classList 中。

用法

<div class='middle selected row' id='component'></div>
var locator = Page.Locator("#component");
await Expect(locator).ToContainClassAsync("middle selected row");
await Expect(locator).ToContainClassAsync("selected");
await Expect(locator).ToContainClassAsync("row middle");

当传入一个数组时,该方法断言定位到的元素列表与对应的预期类列表相匹配。每个元素的类属性会与数组中对应的类进行匹配:

<div class='list'>
<div class='component inactive'></div>
<div class='component active'></div>
<div class='component inactive'></div>
</div>
var locator = Page.Locator(".list > .component");
await Expect(locator).ToContainClassAsync(new string[]{"inactive", "active", "inactive"});

参数

  • expected string | IEnumerable<string>#

    包含预期类名的字符串,类名之间用空格分隔,或者是这样的字符串列表,用于断言多个元素。

  • options LocatorAssertionsToContainClassOptions? (可选)

    • Timeout [float]? (可选)#

      重试断言的时间(毫秒)。默认为 5000

返回值


ToContainTextAsync

新增于:v1.20 locatorAssertions.ToContainTextAsync

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

用法

var locator = Page.Locator(".title");
await Expect(locator).ToContainTextAsync("子字符串");
await Expect(locator).ToContainTextAsync(new Regex("\\d messages"));

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

  1. 定位器解析为元素列表。
  2. 此列表的 子集 中的元素分别包含预期数组中的文本。
  3. 匹配的元素子集与预期数组的顺序相同。
  4. 预期数组中的每个文本值都与列表中的某个元素匹配。

例如,考虑以下列表:

<ul>
<li>项目文本 1</li>
<li>项目文本 2</li>
<li>项目文本 3</li>
</ul>

让我们看看如何使用断言:

// ✓ 按正确顺序包含正确的项目
await Expect(Page.Locator("ul > li")).ToContainTextAsync(new string[] {"文本 1", "文本 3", "文本 4"});

// ✖ 顺序错误
await Expect(Page.Locator("ul > li")).ToContainTextAsync(new string[] {"文本 3", "文本 2"});

// ✖ 没有项目包含此文本
await Expect(Page.Locator("ul > li")).ToContainTextAsync(new string[] {"Some 33"});

// ✖ 定位器指向外部列表元素,而不是列表项
await Expect(Page.Locator("ul")).ToContainTextAsync(new string[] {"文本 3"});

参数

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

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

  • options LocatorAssertionsToContainTextOptions?可选

    • IgnoreCase bool?(可选新增于:v1.23#

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

    • Timeout [float]?(可选新增于:v1.18#

      重试断言的时间(毫秒)。默认为 5000

    • UseInnerText bool?(可选新增于:v1.18#

      在检索 DOM 节点文本时,是否使用 element.innerText 而不是 element.textContent

返回值

详细信息

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

返回值


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 选项(IgnoreCase),则它优先于相应的正则表达式标志。

    • Timeout [float]?(可选)#

      重试断言的时间(毫秒)。默认为 5000

返回值


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 选项(IgnoreCase),则它优先于相应的正则表达式标志。

    • Timeout [float]? (可选)#

      重试断言的时间(毫秒)。默认为 5000

返回


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

返回值


ToHaveClassAsync

添加于:v1.20 locatorAssertions.ToHaveClassAsync

确保 Locator 指向具有给定 CSS 类的元素。当提供一个字符串时,它必须与元素的 class 属性完全匹配。要匹配单个类,请使用 Expect(Locator).ToContainClassAsync()

用法

<div class='middle selected row' id='component'></div>
var locator = Page.Locator("#component");
await Expect(locator).ToHaveClassAsync("middle selected row");
await Expect(locator).ToHaveClassAsync(new Regex("(^|\\s)selected(\\s|$)"));

当传递一个数组时,该方法断言定位到的元素列表与相应的预期类值列表相匹配。每个元素的 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

返回值


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

返回值


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

返回值


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

返回值


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

返回值


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

返回值


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, .*"));

如果传递一个数组作为预期值,期望如下:

  1. 定位器解析为元素列表。
  2. 元素数量与数组中的预期值数量相等。
  3. 列表中的元素文本按顺序逐个匹配预期数组值。

例如,考虑以下列表:

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

让我们看看如何使用断言:

// ✓ 顺序正确且项目正确
await Expect(Page.Locator("ul > li")).ToHaveTextAsync(new string[] {"Text 1", "Text 2", "Text 3"});

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

// ✖ 最后一项不匹配
await Expect(Page.Locator("ul > li")).ToHaveTextAsync(new string[] {"Text 1", "Text 2", "Text"});

// ✖ 定位器指向外部列表元素,而非列表项
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 选项(IgnoreCase),则它优先于相应的正则表达式标志。

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

      重试断言的时间(毫秒)。默认为 5000

    • UseInnerText bool?(可选) 新增于:v1.18#

      在检索 DOM 节点文本时,是否使用 element.innerText 而不是 element.textContent

返回值

详细信息

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

返回值


ToHaveValuesAsync

添加于:v1.23 locatorAssertions.ToHaveValuesAsync

确保 Locator 指向多选框/组合框(即带有 multiple 属性的 select 元素),并且指定的值已被选中。

用法

例如,对于以下元素:

<select id="favorite-colors" multiple>
<option value="R">红色</option>
<option value="G">绿色</option>
<option value="B">蓝色</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

返回值

ToMatchAriaSnapshotAsync

新增于:v1.49locatorAssertions.ToMatchAriaSnapshotAsync 断言目标元素与给定的 可访问性快照 匹配。

用法

await page.GotoAsync("https://demo.playwright.dev/todomvc/");
await Expect(page.Locator("body")).ToMatchAriaSnapshotAsync(@"
- 标题 ""待办事项""
- 文本框 ""需要做什么?""
");

参数

  • expected string#
  • options LocatorAssertionsToMatchAriaSnapshotOptions?可选
    • Timeout [float]?(可选#

      重试断言的时间(毫秒)。默认为 5000

返回值


属性

Not

新增于:v1.20 locatorAssertions.Not

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

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

用法

Expect(Locator).Not

类型