LocatorAssertions
The LocatorAssertions class provides assertion methods that can be used to make assertions about the Locator state in the tests.
using System.Text.RegularExpressions;
using System.Threading.Tasks;
using Microsoft.Playwright.NUnit;
using NUnit.Framework;
namespace PlaywrightTests;
[TestFixture]
public class ExampleTests : PageTest
{
[Test]
public async Task StatusBecomesSubmitted()
{
// ..
await Page.GetByRole(AriaRole.Button).ClickAsync();
await Expect(Page.Locator(".status")).ToHaveTextAsync("Submitted");
}
}
Methods
ToBeAttachedAsync
Added in: v1.33Ensures that Locator points to an attached DOM node.
Usage
await Expect(Page.GetByText("Hidden text")).ToBeAttachedAsync();
Arguments
options
LocatorAssertionsToBeAttachedOptions?
(optional)
ToBeCheckedAsync
Added in: v1.20Ensures the Locator points to a checked input.
Usage
var locator = Page.GetByLabel("Subscribe to newsletter");
await Expect(locator).ToBeCheckedAsync();
Arguments
options
LocatorAssertionsToBeCheckedOptions?
(optional)
ToBeDisabledAsync
Added in: v1.20Ensures 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
.
ToBeEditableAsync
Added in: v1.20Ensures the Locator points to an editable element.
Usage
var locator = Page.GetByRole(AriaRole.Textbox);
await Expect(locator).ToBeEditableAsync();
Arguments
options
LocatorAssertionsToBeEditableOptions?
(optional)
ToBeEmptyAsync
Added in: v1.20Ensures 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
.
ToBeEnabledAsync
Added in: v1.20Ensures the Locator points to an enabled element.
Usage
var locator = Page.Locator("button.submit");
await Expect(locator).toBeEnabledAsync();
Arguments
options
LocatorAssertionsToBeEnabledOptions?
(optional)
ToBeFocusedAsync
Added in: v1.20Ensures 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
.
ToBeHiddenAsync
Added in: v1.20Ensures 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
.
ToBeInViewportAsync
Added in: v1.31Ensures 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)
ToBeVisibleAsync
Added in: v1.20Ensures that Locator points to an attached and visible DOM node.
Usage
await Expect(Page.GetByText("Welcome")).ToBeVisibleAsync();
Arguments
options
LocatorAssertionsToBeVisibleOptions?
(optional)
ToContainTextAsync
Added in: v1.20Ensures the Locator points to an element that contains the given text. 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 ofelement.textContent
when retrieving DOM node text.
ToHaveAttributeAsync
Added in: v1.20Ensures the Locator points to an element with given attribute.
Usage
var locator = Page.Locator("input");
await Expect(locator).ToHaveAttributeAsync("type", "text");
Arguments
Attribute name.
value
string|Regex Added in: v1.18#Expected attribute value.
options
LocatorAssertionsToHaveAttributeOptions?
(optional)Timeout
[float]? (optional) Added in: v1.18#Time to retry the assertion for in milliseconds. Defaults to
5000
.
ToHaveClassAsync
Added in: v1.20Ensures 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
.
ToHaveCountAsync
Added in: v1.20Ensures the Locator resolves to an exact number of DOM nodes.
Usage
var locator = Page.Locator("list > .component");
await Expect(locator).ToHaveCountAsync(3);
Arguments
Expected count.
options
LocatorAssertionsToHaveCountOptions?
(optional)Timeout
[float]? (optional) Added in: v1.18#Time to retry the assertion for in milliseconds. Defaults to
5000
.
ToHaveCSSAsync
Added in: v1.20Ensures 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
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
.
ToHaveIdAsync
Added in: v1.20Ensures 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
.
ToHaveJSPropertyAsync
Added in: v1.20Ensures 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
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
.
ToHaveTextAsync
Added in: v1.20Ensures the Locator points to an element with the given text. 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 ofelement.textContent
when retrieving DOM node text.
ToHaveValueAsync
Added in: v1.20Ensures 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
.
ToHaveValuesAsync
Added in: v1.23Ensures 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
.
Properties
Not
Added in: v1.20Makes 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