Locators and assertions
editA Locator works like a Playwright locator. It is a query that runs again each time you use it, so it still finds the element after a component renders it again. The actions wait until the element can receive the input, and the assertions of Expectations.Expect retry until they pass. Together they remove the waits and the timing issues from the tests.
Find elements
Create locators from a page, from a rendered component (it searches only the elements of the component), or from another locator (it searches the descendants of its elements):
await using var host = new ComponentTestHost();
var page = await host.RenderAsync(builder => builder.AddMarkupContent(0, """
<h1>Users</h1>
<label for="search">Search users</label>
<input id="search" placeholder="Name or email">
<label>Subscribe <input type="checkbox" checked></label>
<button aria-pressed="true">Bold</button>
<img alt="Portrait of Ada">
<p data-testid="user">Ada Lovelace <button>Delete</button></p>
"""));
// A text matches a substring, ignoring the case, unless it is exact
Assert.Equal("Users", page.GetByRole("heading", "users").TextContent);
Assert.Equal(0, page.GetByRole("heading", "users", new() { Exact = true }).Count);
// The states of the accessibility tree
Assert.Equal("Users", page.GetByRole("heading", options: new() { Level = 1 }).TextContent);
Assert.Equal("Bold", page.GetByRole("button", options: new() { Pressed = true }).TextContent);
Assert.True(page.GetByLabel("subscribe").IsChecked);
// The labels, the attributes and the texts
Assert.Equal("search", page.GetByLabel("Search users").GetAttribute("id"));
Assert.Equal("search", page.GetByPlaceholder("email").GetAttribute("id"));
Assert.Equal("img", page.GetByAltText("Portrait").GetElement().LocalName);
Assert.Equal("p", page.GetByText("Ada Lovelace").GetElement().LocalName);
await page.GetByTestId("user").GetByRole("button", "Delete").ClickAsync();| Method | Finds the elements |
|---|---|
| GetByRole | With an ARIA role, an accessible name and the states of GetByRoleOptions (Checked, Disabled, Expanded, Pressed, Selected, Level) |
| GetByText | The smallest elements that contain a text: an element is found when none of its children contains the text |
| GetByLabel | Labelled by aria-labelledby, aria-label or a label element |
| GetByPlaceholder, GetByAltText, GetByTitle | With a placeholder, alt or title attribute |
| GetByTestId | With a test identifier: data-testid, or the attribute of TestPageSettings.TestIdAttribute |
| Locator | That match a CSS selector |
Prefer the queries that a user sees, the role and the text, to the CSS selectors: they don't break when the markup changes, and they check that the page is accessible.
- A text matches a substring, ignoring the case and collapsing the white space. Pass
exact: true(or GetByRoleOptions.Exact) to match the whole text, with the case, or aRegex. The test identifier is always compared as is. - GetByRole ignores the elements hidden from the accessibility tree (
aria-hidden="true",visibility: hidden), unless IncludeHidden is true. The role of an element that is not rendered (display: none) isnone: find it with a CSS selector. The other queries find the hidden elements too. - The queries search the open shadow roots of the page, so the internals of web components can be found.
Narrow, filter and combine
await using var host = new ComponentTestHost();
var page = await host.RenderAsync(builder => builder.AddMarkupContent(0, """
<ul>
<li>Ada Lovelace <button>Delete</button></li>
<li>Grace Hopper <button>Delete</button></li>
<li>Alan Turing</li>
</ul>
"""));
var users = page.GetByRole("listitem");
Assert.Equal(3, users.Count);
// Search inside the elements of a locator, filter them by text or by descendant, or pick one
await users.Filter(new() { HasText = "grace" }).GetByRole("button", "Delete").ClickAsync();
Assert.Equal(2, users.Filter(new() { Has = page.GetByRole("button", "Delete") }).Count);
Assert.Equal("Alan Turing", users.Filter(new() { HasNot = page.GetByRole("button") }).TextContent);
Assert.Equal("Alan Turing", users.Last.TextContent);
Assert.Equal("Ada Lovelace Delete", users.First.TextContent);
// Combine locators
Assert.Equal(2, page.GetByRole("button").And(page.GetByText("Delete")).Count);
Assert.Equal(5, users.Or(page.GetByRole("button")).Count);- Filter keeps the elements that contain a text (
HasText,HasNotText), that contain an element of another locator (Has,HasNot, evaluated from each element), or that are visible (Visible). - First, Last and Nth pick one element; a negative index counts from the end.
- And keeps the elements that both locators find, and Or the elements that either finds, in document order.
- GetAll returns a locator per element, to iterate the rows of a list.
Act on the elements
An action finds the element again before each attempt, and waits until it is actionable:
await using var host = new ComponentTestHost();
// Render without waiting: the controls are disabled, or not rendered, for a while
var form = host.Render<DelayedForm>();
// The click waits until the button is enabled, the fill until the field is rendered,
// and the selection until the select element has the option (by value or by label)
await form.GetByRole("button", "Save").ClickAsync();
await form.GetByLabel("Name").FillAsync("Ada");
await form.GetByLabel("Color").SelectOptionAsync("Red");
await Expect(form.GetByRole("status")).ToHaveTextAsync("Saved 1 times");
await Expect(form.Locator("#name")).ToHaveTextAsync("Ada");
await Expect(form.Locator("#color")).ToHaveTextAsync("r");| Check | Actions |
|---|---|
| The locator finds exactly one element | All |
Visible: a non-empty box, not visibility: hidden | Click, double click, hover, tap, fill, clear, select an option, check, uncheck, drag |
| Stable: its box is the same in consecutive animation frames | Click, double click, hover, tap, check, uncheck, drag |
| Receives the input: no other element covers it (hit testing) | Click, double click, hover, tap, check, uncheck, drag |
Enabled: not a disabled form control, no aria-disabled="true" | Click, double click, tap, fill, clear, select an option, check, uncheck |
Editable: not readonly | Fill, clear |
- An element out of the viewport is scrolled into it first.
- FillAsync, CheckAsync and SelectOptionAsync act on the control of a
labelwhen the element is inside the label:page.GetByText("Accept the terms").CheckAsync()checks the check box of the label. - SelectOptionAsync selects the options by value or by label, and waits until the
selectelement has them. - CheckAsync clicks only when the element is not checked yet, then checks that the click checked it.
The action fails after DefaultTimeout (10 seconds): with an ElementNotFoundException when the locator finds no element, and with an ElementNotInteractableException that gives the reason (it is disabled, <div id="overlay"> receives the input...) otherwise. Set ClickOptions.Timeout for one click, or ClickOptions.Force to skip the checks.
A locator that finds more than one element fails at once with a StrictModeViolationException, which lists the elements: make the locator more specific, or pick one with First, Last or Nth.
Assert the state of the page
Import the assertions with using static Meziantou.AspNetCore.Testing.Expectations;. Each assertion runs the event loop of the page until it passes, and fails with an ExpectationFailedException after the timeout:
await using var host = new ComponentTestHost();
var counter = await host.RenderAsync<Counter>();
await counter.GetByRole("button", "Click me").ClickAsync();
// The assertions run the event loop until they pass, and fail after the timeout of the page
await Expect(counter.GetByRole("status")).ToHaveTextAsync("Current count: 1");
await Expect(counter.GetByRole("button", "Click me")).ToBeEnabledAsync();
await Expect(counter.GetByRole("button")).ToHaveCountAsync(1);
await Expect(counter.GetByText("Current count: 2")).Not.ToBeVisibleAsync();| Assertions of LocatorAssertions | Pass when |
|---|---|
ToBeAttachedAsync, ToBeVisibleAsync, ToBeHiddenAsync | The locator finds an element, a visible element, no element or a hidden element |
ToBeEnabledAsync, ToBeDisabledAsync, ToBeCheckedAsync, ToBeEditableAsync, ToBeFocusedAsync, ToBeEmptyAsync | The element has the state |
ToHaveTextAsync, ToContainTextAsync | The text of the element is, or contains, a text (with collapsed white space) or matches a Regex |
ToHaveValueAsync, ToHaveAttributeAsync, ToHaveClassAsync, ToHaveCssAsync | A field, an attribute, the classes or a computed style have a value |
ToHaveRoleAsync, ToHaveAccessibleNameAsync, ToHaveAccessibilitySnapshotAsync | The accessibility tree of the element is the expected one |
ToHaveCountAsync | The locator finds a number of elements |
Not negates an assertion: Expect(locator).Not.ToBeVisibleAsync(). The assertions on an element fail, negated or not, while the locator finds no element. PageAssertions checks the URL and the title of a page: await Expect(page).ToHaveUrlAsync("/profile").
Read the elements now
A locator also reads the page without waiting: GetElement returns its element (the DOM element of WebPlatform), GetElements and Count its elements, and TextContent, InputValue, IsVisible or IsChecked the state of its element. Find, FindAll and FindOrDefault of the pages and of the components return the elements that match a CSS selector now. Since every action waits until the page is idle, these reads are reliable after an action. Use the assertions for a result that comes later (a timer, a message from the server).