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确保 Locator 指向的元素 连接 到 Document 或 ShadowRoot。
用法
await Expect(Page.GetByText("Hidden text")).ToBeAttachedAsync();
参数
options
LocatorAssertionsToBeAttachedOptions?
(可选)
返回
ToBeCheckedAsync
新增于: v1.20确保 Locator 指向一个已选中的输入框。
用法
var locator = Page.GetByLabel("Subscribe to newsletter");
await Expect(locator).ToBeCheckedAsync();
参数
options
LocatorAssertionsToBeCheckedOptions?
(可选)
返回
ToBeDisabledAsync
新增于: v1.20确保 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
。
-
返回
ToBeEditableAsync
新增于: v1.20确保 Locator 指向一个可编辑的元素。
用法
var locator = Page.GetByRole(AriaRole.Textbox);
await Expect(locator).ToBeEditableAsync();
参数
options
LocatorAssertionsToBeEditableOptions?
(可选)
返回
ToBeEmptyAsync
新增于: v1.20确保 Locator 指向一个空的、可编辑的元素,或一个没有文本的 DOM 节点。
用法
var locator = Page.Locator("div.warning");
await Expect(locator).ToBeEmptyAsync();
参数
options
LocatorAssertionsToBeEmptyOptions?
(可选)-
Timeout
[float]? (可选)新增于: v1.18#重试断言的时间,单位为毫秒。默认为
5000
。
-
返回
ToBeEnabledAsync
新增于: v1.20确保 Locator 指向一个已启用的元素。
用法
var locator = Page.Locator("button.submit");
await Expect(locator).ToBeEnabledAsync();
参数
options
LocatorAssertionsToBeEnabledOptions?
(可选)
返回
ToBeFocusedAsync
新增于: v1.20确保 Locator 指向一个获得焦点的 DOM 节点。
用法
var locator = Page.GetByRole(AriaRole.Textbox);
await Expect(locator).ToBeFocusedAsync();
参数
options
LocatorAssertionsToBeFocusedOptions?
(可选)-
Timeout
[float]? (可选)新增于: v1.18#重试断言的时间,单位为毫秒。默认为
5000
。
-
返回
ToBeHiddenAsync
新增于: v1.20确保 Locator 要么不解析为任何 DOM 节点,要么解析为 不可见 的节点。
用法
var locator = Page.Locator(".my-element");
await Expect(locator).ToBeHiddenAsync();
参数
options
LocatorAssertionsToBeHiddenOptions?
(可选)-
Timeout
[float]? (可选)新增于: v1.18#重试断言的时间,单位为毫秒。默认为
5000
。
-
返回
ToBeInViewportAsync
添加于:v1.31确保 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?
(可选)
返回
ToBeVisibleAsync
新增于: v1.20确保 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?
(可选)
返回
ToContainClassAsync
添加于: v1.52确保 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");
当传入数组时,该方法断言定位的元素列表与相应的预期类列表匹配。每个元素的 class 属性都与数组中相应的类进行匹配。
<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确保 Locator 指向的元素包含给定文本。计算元素的文本内容时将考虑所有嵌套元素。您也可以使用正则表达式作为值。
用法
var locator = Page.Locator(".title");
await Expect(locator).ToContainTextAsync("substring");
await Expect(locator).ToContainTextAsync(new Regex("\\d messages"));
如果您将数组作为预期值传入,则预期结果是
- 定位器解析为元素列表。
- 此列表的**子集**中的元素分别包含预期数组中的文本。
- 匹配的元素子集与预期数组具有相同的顺序。
- 预期数组中的每个文本值都由列表中的某个元素匹配。
例如,考虑以下列表
<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?
(可选)
返回
详情
当 expected
参数是一个字符串时,Playwright 会在匹配之前将实际文本和预期字符串中的空格和换行符规范化。当使用正则表达式时,实际文本按原样匹配。
ToHaveAccessibleDescriptionAsync
新增于:v1.44确保 Locator 指向一个具有给定 可访问描述 的元素。
用法
var locator = Page.GetByTestId("save-button");
await Expect(locator).ToHaveAccessibleDescriptionAsync("Save results to disk");
参数
-
预期的可访问描述。
-
options
LocatorAssertionsToHaveAccessibleDescriptionOptions?
(可选)-
是否执行不区分大小写的匹配。IgnoreCase 选项优先于相应的正则表达式标志(如果指定)。
-
Timeout
[float]? (可选)#重试断言的时间,单位为毫秒。默认为
5000
。
-
返回
ToHaveAccessibleErrorMessageAsync
新增于: v1.50确保 Locator 指向一个具有给定 aria 错误消息 的元素。
用法
var locator = Page.GetByTestId("username-input");
await Expect(locator).ToHaveAccessibleErrorMessageAsync("Username is required.");
参数
-
预期的可访问错误消息。
-
options
LocatorAssertionsToHaveAccessibleErrorMessageOptions?
(可选)-
是否执行不区分大小写的匹配。IgnoreCase 选项优先于相应的正则表达式标志(如果指定)。
-
Timeout
[float]? (可选)#重试断言的时间,单位为毫秒。默认为
5000
。
-
返回
ToHaveAccessibleNameAsync
新增于:v1.44确保 Locator 指向一个具有给定 可访问名称 的元素。
用法
var locator = Page.GetByTestId("save-button");
await Expect(locator).ToHaveAccessibleNameAsync("Save to disk");
参数
-
预期的可访问名称。
-
options
LocatorAssertionsToHaveAccessibleNameOptions?
(可选)-
是否执行不区分大小写的匹配。IgnoreCase 选项优先于相应的正则表达式标志(如果指定)。
-
Timeout
[float]? (可选)#重试断言的时间,单位为毫秒。默认为
5000
。
-
返回
ToHaveAttributeAsync
新增于: v1.20确保 Locator 指向一个具有给定属性的元素。
用法
var locator = Page.Locator("input");
await Expect(locator).ToHaveAttributeAsync("type", "text");
参数
-
属性名。
-
value
string | Regex新增于: v1.18#预期属性值。
-
options
LocatorAssertionsToHaveAttributeOptions?
(可选)-
IgnoreCase
bool? (可选)添加于:v1.40#是否执行不区分大小写的匹配。IgnoreCase 选项优先于相应的正则表达式标志(如果指定)。
-
Timeout
[float]? (可选)新增于: v1.18#重试断言的时间,单位为毫秒。默认为
5000
。
-
返回
ToHaveClassAsync
新增于: v1.20确保 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确保 Locator 解析为精确数量的 DOM 节点。
用法
var locator = Page.Locator("list > .component");
await Expect(locator).ToHaveCountAsync(3);
参数
-
预期计数。
-
options
LocatorAssertionsToHaveCountOptions?
(可选)-
Timeout
[float]? (可选)新增于: v1.18#重试断言的时间,单位为毫秒。默认为
5000
。
-
返回
ToHaveCSSAsync
新增于: v1.20确保 Locator 解析为具有给定计算 CSS 样式的元素。
用法
var locator = Page.GetByRole(AriaRole.Button);
await Expect(locator).ToHaveCSSAsync("display", "flex");
参数
-
CSS 属性名称。
-
value
string | Regex新增于: v1.18#CSS 属性值。
-
options
LocatorAssertionsToHaveCSSOptions?
(可选)-
Timeout
[float]? (可选)新增于: v1.18#重试断言的时间,单位为毫秒。默认为
5000
。
-
返回
ToHaveIdAsync
新增于: v1.20确保 Locator 指向一个具有给定 DOM 节点 ID 的元素。
用法
var locator = Page.GetByRole(AriaRole.Textbox);
await Expect(locator).ToHaveIdAsync("lastname");
参数
-
元素 ID。
-
options
LocatorAssertionsToHaveIdOptions?
(可选)-
Timeout
[float]? (可选)新增于: v1.18#重试断言的时间,单位为毫秒。默认为
5000
。
-
返回
ToHaveJSPropertyAsync
新增于: v1.20确保 Locator 指向一个具有给定 JavaScript 属性的元素。请注意,此属性可以是原始类型,也可以是普通的、可序列化的 JavaScript 对象。
用法
var locator = Page.Locator(".component");
await Expect(locator).ToHaveJSPropertyAsync("loaded", true);
参数
-
属性名称。
-
value
[object]新增于: v1.18#属性值。
-
options
LocatorAssertionsToHaveJSPropertyOptions?
(可选)-
Timeout
[float]? (可选)新增于: v1.18#重试断言的时间,单位为毫秒。默认为
5000
。
-
返回
ToHaveRoleAsync
新增于:v1.44确保 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确保 Locator 指向一个具有给定文本的元素。计算元素的文本内容时将考虑所有嵌套元素。您也可以使用正则表达式作为值。
用法
var locator = Page.Locator(".title");
await Expect(locator).ToHaveTextAsync(new Regex("Welcome, Test User"));
await Expect(locator).ToHaveTextAsync(new Regex("Welcome, .*"));
如果您将数组作为预期值传入,则预期结果是
- 定位器解析为元素列表。
- 元素的数量等于数组中预期值的数量。
- 列表中的元素依次匹配预期数组中的文本值。
例如,考虑以下列表
<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?
(可选)
返回
详情
当 expected
参数是一个字符串时,Playwright 会在匹配之前将实际文本和预期字符串中的空格和换行符规范化。当使用正则表达式时,实际文本按原样匹配。
ToHaveValueAsync
新增于: v1.20确保 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确保 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
。
-
返回
ToMatchAriaSnapshotAsync
新增于: v1.49断言目标元素匹配给定的 可访问性快照。
用法
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
。
-
返回
属性
Not
新增于: v1.20使断言检查相反的条件。例如,此代码测试定位器不包含文本 "error"
。
await Expect(locator).Not.ToContainTextAsync("error");
用法
Expect(Locator).Not
类型