LocatorAssertions

The LocatorAssertions class provides assertion methods that can be used to make assertions about the Locator state in the tests.

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");
    }
}

Methods

ToBeAttachedAsync

Added in: v1.33

locatorAssertions.ToBeAttachedAsync

Ensures that Locator points to an element that is connected to a Document or a ShadowRoot.

Usage

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

Arguments

options LocatorAssertionsToBeAttachedOptions? (optional)
- Attached bool? (optional)#
- Timeout [float]? (optional)#
  
  Time to retry the assertion for in milliseconds. Defaults to 5000.

Returns

void #

ToBeCheckedAsync

Added in: v1.20

locatorAssertions.ToBeCheckedAsync

Ensures the Locator points to a checked input.

Usage

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

Arguments

options LocatorAssertionsToBeCheckedOptions? (optional)
- Checked bool? (optional) Added in: v1.18#
- Timeout [float]? (optional) Added in: v1.18#
  
  Time to retry the assertion for in milliseconds. Defaults to 5000.

Returns

void #

ToBeDisabledAsync

Added in: v1.20

locatorAssertions.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.

Usage

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

Arguments

options LocatorAssertionsToBeDisabledOptions? (optional)
- Timeout [float]? (optional) Added in: v1.18#
  
  Time to retry the assertion for in milliseconds. Defaults to 5000.

Returns

void #

ToBeEditableAsync

Added in: v1.20

locatorAssertions.ToBeEditableAsync

Ensures the Locator points to an editable element.

Usage

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

Arguments

options LocatorAssertionsToBeEditableOptions? (optional)
- Editable bool? (optional) Added in: v1.26#
- Timeout [float]? (optional) Added in: v1.18#
  
  Time to retry the assertion for in milliseconds. Defaults to 5000.

Returns

void #

ToBeEmptyAsync

Added in: v1.20

locatorAssertions.ToBeEmptyAsync

Ensures the Locator points to an empty editable element or to a DOM node that has no text.

Usage

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

Arguments

options LocatorAssertionsToBeEmptyOptions? (optional)
- Timeout [float]? (optional) Added in: v1.18#
  
  Time to retry the assertion for in milliseconds. Defaults to 5000.

Returns

void #

ToBeEnabledAsync

Added in: v1.20

locatorAssertions.ToBeEnabledAsync

Ensures the Locator points to an enabled element.

Usage

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

Arguments

options LocatorAssertionsToBeEnabledOptions? (optional)
- Enabled bool? (optional) Added in: v1.26#
- Timeout [float]? (optional) Added in: v1.18#
  
  Time to retry the assertion for in milliseconds. Defaults to 5000.

Returns

void #

ToBeFocusedAsync

Added in: v1.20

locatorAssertions.ToBeFocusedAsync

Ensures the Locator points to a focused DOM node.

Usage

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

Arguments

options LocatorAssertionsToBeFocusedOptions? (optional)
- Timeout [float]? (optional) Added in: v1.18#
  
  Time to retry the assertion for in milliseconds. Defaults to 5000.

Returns

void #

ToBeHiddenAsync

Added in: v1.20

locatorAssertions.ToBeHiddenAsync

Ensures that Locator either does not resolve to any DOM node, or resolves to a non-visible one.

Usage

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

Arguments

options LocatorAssertionsToBeHiddenOptions? (optional)
- Timeout [float]? (optional) Added in: v1.18#
  
  Time to retry the assertion for in milliseconds. Defaults to 5000.

Returns

void #

ToBeInViewportAsync

Added in: v1.31

locatorAssertions.ToBeInViewportAsync

Ensures the Locator points to an element that intersects viewport, according to the intersection observer API.

Usage

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 });

Arguments

options LocatorAssertionsToBeInViewportOptions? (optional)
- Ratio [float]? (optional)#
  
  The minimal ratio of the element to intersect viewport. If equals to 0, then element should intersect viewport at any positive ratio. Defaults to 0.
- Timeout [float]? (optional)#
  
  Time to retry the assertion for in milliseconds. Defaults to 5000.

Returns

void #

ToBeVisibleAsync

Added in: v1.20

locatorAssertions.ToBeVisibleAsync

Ensures that Locator points to an attached and visible DOM node.

To check that at least one element from the list is visible, use Locator.First.

Usage

// 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();

Arguments

options LocatorAssertionsToBeVisibleOptions? (optional)
- Timeout [float]? (optional) Added in: v1.18#
  
  Time to retry the assertion for in milliseconds. Defaults to 5000.
- Visible bool? (optional) Added in: v1.26#

Returns

void #

ToContainTextAsync

Added in: v1.20

locatorAssertions.ToContainTextAsync

Ensures the Locator points to an element that contains the given text. All nested elements will be considered when computing the text content of the element. You can use regular expressions for the value as well.

Usage

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

If you pass an array as an expected value, the expectations are:

Locator resolves to a list of elements.
Elements from a subset of this list contain text from the expected array, respectively.
The matching subset of elements has the same order as the expected array.
Each text value from the expected array is matched by some element from the list.

For example, consider the following list:

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

Let's see how we can use the assertion:

// ✓ 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"});

Arguments

expected string | Regex | IEnumerable<string> | IEnumerable<Regex> Added in: v1.18#

Expected substring or RegExp or a list of those.
options LocatorAssertionsToContainTextOptions? (optional)
- IgnoreCase bool? (optional) Added in: v1.23#
  
  Whether to perform case-insensitive match. IgnoreCase option takes precedence over the corresponding regular expression flag if specified.
- Timeout [float]? (optional) Added in: v1.18#
  
  Time to retry the assertion for in milliseconds. Defaults to 5000.
- UseInnerText bool? (optional) Added in: v1.18#
  
  Whether to use element.innerText instead of element.textContent when retrieving DOM node text.

Returns

void #

Details

When expected parameter is a string, Playwright will normalize whitespaces and line breaks both in the actual text and in the expected string before matching. When regular expression is used, the actual text is matched as is.

ToHaveAccessibleDescriptionAsync

Added in: v1.44

locatorAssertions.ToHaveAccessibleDescriptionAsync

Ensures the Locator points to an element with a given accessible description.

Usage

var locator = Page.GetByTestId("save-button");
await Expect(locator).toHaveAccessibleDescriptionAsync("Save results to disk");

Arguments

description string | Regex #

Expected accessible description.
options LocatorAssertionsToHaveAccessibleDescriptionOptions? (optional)
- IgnoreCase bool? (optional)#
  
  Whether to perform case-insensitive match. IgnoreCase option takes precedence over the corresponding regular expression flag if specified.
- Timeout [float]? (optional)#
  
  Time to retry the assertion for in milliseconds. Defaults to 5000.

Returns

void #

ToHaveAccessibleNameAsync

Added in: v1.44

locatorAssertions.ToHaveAccessibleNameAsync

Ensures the Locator points to an element with a given accessible name.

Usage

var locator = Page.GetByTestId("save-button");
await Expect(locator).toHaveAccessibleNameAsync("Save to disk");

Arguments

name string | Regex #

Expected accessible name.
options LocatorAssertionsToHaveAccessibleNameOptions? (optional)
- IgnoreCase bool? (optional)#
  
  Whether to perform case-insensitive match. IgnoreCase option takes precedence over the corresponding regular expression flag if specified.
- Timeout [float]? (optional)#
  
  Time to retry the assertion for in milliseconds. Defaults to 5000.

Returns

void #

ToHaveAttributeAsync

Added in: v1.20

locatorAssertions.ToHaveAttributeAsync

Ensures the Locator points to an element with given attribute.

Usage

var locator = Page.Locator("input");
await Expect(locator).ToHaveAttributeAsync("type", "text");

Arguments

name string Added in: v1.18#

Attribute name.
value string | Regex Added in: v1.18#

Expected attribute value.
options LocatorAssertionsToHaveAttributeOptions? (optional)
- IgnoreCase bool? (optional) Added in: v1.40#
  
  Whether to perform case-insensitive match. IgnoreCase option takes precedence over the corresponding regular expression flag if specified.
- Timeout [float]? (optional) Added in: v1.18#
  
  Time to retry the assertion for in milliseconds. Defaults to 5000.

Returns

void #

ToHaveClassAsync

Added in: v1.20

locatorAssertions.ToHaveClassAsync

Ensures the Locator points to an element with given CSS classes. This needs to be a full match or using a relaxed regular expression.

Usage

<div class='selected row' id='component'></div>

var locator = Page.Locator("#component");
await Expect(locator).ToHaveClassAsync(new Regex("selected"));
await Expect(locator).ToHaveClassAsync("selected row");

Note that if array is passed as an expected value, entire lists of elements can be asserted:

var locator = Page.Locator("list > .component");
await Expect(locator).ToHaveClassAsync(new string[]{"component", "component selected", "component"});

Arguments

expected string | Regex | IEnumerable<string> | IEnumerable<Regex> Added in: v1.18#

Expected class or RegExp or a list of those.
options LocatorAssertionsToHaveClassOptions? (optional)
- Timeout [float]? (optional) Added in: v1.18#
  
  Time to retry the assertion for in milliseconds. Defaults to 5000.

Returns

void #

ToHaveCountAsync

Added in: v1.20

locatorAssertions.ToHaveCountAsync

Ensures the Locator resolves to an exact number of DOM nodes.

Usage

var locator = Page.Locator("list > .component");
await Expect(locator).ToHaveCountAsync(3);

Arguments

count int Added in: v1.18#

Expected count.
options LocatorAssertionsToHaveCountOptions? (optional)
- Timeout [float]? (optional) Added in: v1.18#
  
  Time to retry the assertion for in milliseconds. Defaults to 5000.

Returns

void #

ToHaveCSSAsync

Added in: v1.20

locatorAssertions.ToHaveCSSAsync

Ensures the Locator resolves to an element with the given computed CSS style.

Usage

var locator = Page.GetByRole(AriaRole.Button);
await Expect(locator).ToHaveCSSAsync("display", "flex");

Arguments

name string Added in: v1.18#

CSS property name.
value string | Regex Added in: v1.18#

CSS property value.
options LocatorAssertionsToHaveCSSOptions? (optional)
- Timeout [float]? (optional) Added in: v1.18#
  
  Time to retry the assertion for in milliseconds. Defaults to 5000.

Returns

void #

ToHaveIdAsync

Added in: v1.20

locatorAssertions.ToHaveIdAsync

Ensures the Locator points to an element with the given DOM Node ID.

Usage

var locator = Page.GetByRole(AriaRole.Textbox);
await Expect(locator).ToHaveIdAsync("lastname");

Arguments

id string | Regex Added in: v1.18#

Element id.
options LocatorAssertionsToHaveIdOptions? (optional)
- Timeout [float]? (optional) Added in: v1.18#
  
  Time to retry the assertion for in milliseconds. Defaults to 5000.

Returns

void #

ToHaveJSPropertyAsync

Added in: v1.20

locatorAssertions.ToHaveJSPropertyAsync

Ensures the Locator points to an element with given JavaScript property. Note that this property can be of a primitive type as well as a plain serializable JavaScript object.

Usage

var locator = Page.Locator(".component");
await Expect(locator).ToHaveJSPropertyAsync("loaded", true);

Arguments

name string Added in: v1.18#

Property name.
value [object] Added in: v1.18#

Property value.
options LocatorAssertionsToHaveJSPropertyOptions? (optional)
- Timeout [float]? (optional) Added in: v1.18#
  
  Time to retry the assertion for in milliseconds. Defaults to 5000.

Returns

void #

ToHaveRoleAsync

Added in: v1.44

locatorAssertions.ToHaveRoleAsync

Ensures the Locator points to an element with a given ARIA role.

Note that role is matched as a string, disregarding the ARIA role hierarchy. For example, asserting a superclass role "checkbox" on an element with a subclass role "switch" will fail.

Usage

var locator = Page.GetByTestId("save-button");
await Expect(locator).ToHaveRoleAsync(AriaRole.Button);

Arguments

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

Required aria role.
options LocatorAssertionsToHaveRoleOptions? (optional)
- Timeout [float]? (optional)#
  
  Time to retry the assertion for in milliseconds. Defaults to 5000.

Returns

void #

ToHaveTextAsync

Added in: v1.20

locatorAssertions.ToHaveTextAsync

Ensures the Locator points to an element with the given text. All nested elements will be considered when computing the text content of the element. You can use regular expressions for the value as well.

Usage

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

If you pass an array as an expected value, the expectations are:

Locator resolves to a list of elements.
The number of elements equals the number of expected values in the array.
Elements from the list have text matching expected array values, one by one, in order.

For example, consider the following list:

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

Let's see how we can use the assertion:

// ✓ 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"});

Arguments

expected string | Regex | IEnumerable<string> | IEnumerable<Regex> Added in: v1.18#

Expected string or RegExp or a list of those.
options LocatorAssertionsToHaveTextOptions? (optional)
- IgnoreCase bool? (optional) Added in: v1.23#
  
  Whether to perform case-insensitive match. IgnoreCase option takes precedence over the corresponding regular expression flag if specified.
- Timeout [float]? (optional) Added in: v1.18#
  
  Time to retry the assertion for in milliseconds. Defaults to 5000.
- UseInnerText bool? (optional) Added in: v1.18#
  
  Whether to use element.innerText instead of element.textContent when retrieving DOM node text.

Returns

void #

Details

ToHaveValueAsync

Added in: v1.20

locatorAssertions.ToHaveValueAsync

Ensures the Locator points to an element with the given input value. You can use regular expressions for the value as well.

Usage

var locator = Page.Locator("input[type=number]");
await Expect(locator).ToHaveValueAsync(new Regex("[0-9]"));

Arguments

value string | Regex Added in: v1.18#

Expected value.
options LocatorAssertionsToHaveValueOptions? (optional)
- Timeout [float]? (optional) Added in: v1.18#
  
  Time to retry the assertion for in milliseconds. Defaults to 5000.

Returns

void #

ToHaveValuesAsync

Added in: v1.23

locatorAssertions.ToHaveValuesAsync

Ensures the Locator points to multi-select/combobox (i.e. a select with the multiple attribute) and the specified values are selected.

Usage

For example, given the following element:

<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") });

Arguments

values IEnumerable<string> | IEnumerable<Regex>#

Expected options currently selected.
options LocatorAssertionsToHaveValuesOptions? (optional)
- Timeout [float]? (optional)#
  
  Time to retry the assertion for in milliseconds. Defaults to 5000.

Returns

void #

ToMatchAriaSnapshotAsync

Added in: v1.49

locatorAssertions.ToMatchAriaSnapshotAsync

Asserts that the target element matches the given accessibility snapshot.

Usage

await page.GotoAsync("https://demo.playwright.dev/todomvc/");
await Expect(page.Locator("body")).ToMatchAriaSnapshotAsync(@"
  - heading ""todos""
  - textbox ""What needs to be done?""
");

Arguments

expected string #
options LocatorAssertionsToMatchAriaSnapshotOptions? (optional)
- Timeout [float]? (optional)#
  
  Time to retry the assertion for in milliseconds. Defaults to 5000.

Returns

void #

Properties

Not

Added in: v1.20

locatorAssertions.Not

Makes the assertion check for the opposite condition. For example, this code tests that the Locator doesn't contain text "error":

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

Usage

Expect(Locator).Not

Type

LocatorAssertions

Methods​

ToBeAttachedAsync​

ToBeCheckedAsync​

ToBeDisabledAsync​

ToBeEditableAsync​

ToBeEmptyAsync​

ToBeEnabledAsync​

ToBeFocusedAsync​

ToBeHiddenAsync​

ToBeInViewportAsync​

ToBeVisibleAsync​

ToContainTextAsync​

ToHaveAccessibleDescriptionAsync​

ToHaveAccessibleNameAsync​

ToHaveAttributeAsync​

ToHaveClassAsync​

ToHaveCountAsync​

ToHaveCSSAsync​

ToHaveIdAsync​

ToHaveJSPropertyAsync​

ToHaveRoleAsync​

ToHaveTextAsync​

ToHaveValueAsync​

ToHaveValuesAsync​

ToMatchAriaSnapshotAsync​

Properties​

Not​

Methods

ToBeAttachedAsync

ToBeCheckedAsync

ToBeDisabledAsync

ToBeEditableAsync

ToBeEmptyAsync

ToBeEnabledAsync

ToBeFocusedAsync

ToBeHiddenAsync

ToBeInViewportAsync

ToBeVisibleAsync

ToContainTextAsync

ToHaveAccessibleDescriptionAsync

ToHaveAccessibleNameAsync

ToHaveAttributeAsync

ToHaveClassAsync

ToHaveCountAsync

ToHaveCSSAsync

ToHaveIdAsync

ToHaveJSPropertyAsync

ToHaveRoleAsync

ToHaveTextAsync

ToHaveValueAsync

ToHaveValuesAsync

ToMatchAriaSnapshotAsync

Properties

Not