Assertions
Playwright gives you Web-First Assertions with convenience methods for creating assertions that will wait and retry until the expected condition is met.
Consider the following example:
using System.Threading.Tasks;
using Microsoft.Playwright.NUnit;
using NUnit.Framework;
namespace Playwright.TestingHarnessTest.NUnit;
public class ExampleTests : PageTest
{
[Test]
public async Task StatusBecomesSubmitted()
{
await Expect(Page.Locator(".status")).ToHaveTextAsync("Submitted");
}
}
Playwright will be re-testing the node with the selector .status
until fetched Node has the "Submitted"
text. It will be re-fetching the node and checking it over and over, until the condition is met or until the timeout is reached. You can pass this timeout as an option.
By default, the timeout for assertions is set to 5 seconds.
- Expect(Locator).ToBeCheckedAsync(options)
- Expect(Locator).ToBeDisabledAsync(options)
- Expect(Locator).ToBeEditableAsync(options)
- Expect(Locator).ToBeEmptyAsync(options)
- Expect(Locator).ToBeEnabledAsync(options)
- Expect(Locator).ToBeFocusedAsync(options)
- Expect(Locator).ToBeHiddenAsync(options)
- Expect(Locator).ToBeVisibleAsync(options)
- Expect(Locator).ToContainTextAsync(expected, options)
- Expect(Locator).ToHaveAttributeAsync(name, value, options)
- Expect(Locator).ToHaveClassAsync(expected, options)
- Expect(Locator).ToHaveCountAsync(count, options)
- Expect(Locator).ToHaveCSSAsync(name, value, options)
- Expect(Locator).ToHaveIdAsync(id, options)
- Expect(Locator).ToHaveJSPropertyAsync(name, value, options)
- Expect(Locator).ToHaveTextAsync(expected, options)
- Expect(Locator).ToHaveValueAsync(value, options)
- Expect(Locator).ToHaveValuesAsync(values, options)
- Expect(Locator).Not
- Expect(Page).ToHaveTitleAsync(titleOrRegExp, options)
- Expect(Page).ToHaveURLAsync(urlOrRegExp, options)
- Expect(Page).Not
- Expect(ApiResponse).NotToBeOKAsync()
- Expect(ApiResponse).ToBeOKAsync()
- Expect(ApiResponse).Not
Expect(Locator).Not
- type: <LocatorAssertions>
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");
Expect(Locator).ToBeCheckedAsync(options)
Ensures the Locator points to a checked input.
var locator = Page.Locator(".subscribe");
await Expect(locator).ToBeCheckedAsync();
Expect(Locator).ToBeDisabledAsync(options)
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.
var locator = Page.Locator("button.submit");
await Expect(locator).ToBeDisabledAsync();
Expect(Locator).ToBeEditableAsync(options)
Ensures the Locator points to an editable element.
var locator = Page.Locator("input");
await Expect(locator).ToBeEditableAsync();
Expect(Locator).ToBeEmptyAsync(options)
Ensures the Locator points to an empty editable element or to a DOM node that has no text.
var locator = Page.Locator("div.warning");
await Expect(locator).ToBeEmptyAsync();
Expect(Locator).ToBeEnabledAsync(options)
Ensures the Locator points to an enabled element.
var locator = Page.Locator("button.submit");
await Expect(locator).toBeEnabledAsync();
Expect(Locator).ToBeFocusedAsync(options)
Ensures the Locator points to a focused DOM node.
var locator = Page.Locator("input");
await Expect(locator).ToBeFocusedAsync();
Expect(Locator).ToBeHiddenAsync(options)
Ensures the Locator points to a hidden DOM node, which is the opposite of visible.
var locator = Page.Locator(".my-element");
await Expect(locator).ToBeHiddenAsync();
Expect(Locator).ToBeVisibleAsync(options)
Ensures the Locator points to a visible DOM node.
var locator = Page.Locator(".my-element");
await Expect(locator).ToBeVisibleAsync();
Expect(Locator).ToContainTextAsync(expected, options)
expected
<string|Regex|IEnumerable<string>|IEnumerable<Regex>> Expected substring or RegExp or a list of those.#options
<LocatorAssertionsToContainTextOptions?
>IgnoreCase
<bool?> Whether to perform case-insensitive match.ignoreCase
option takes precedence over the corresponding regular expression flag if specified.#Timeout
<double?> Time to retry the assertion for.#UseInnerText
<bool?> Whether to useelement.innerText
instead ofelement.textContent
when retrieving DOM node text.#
- returns:void># <
Ensures the Locator points to an element that contains the given text. You can use regular expressions for the value as well.
var locator = Page.Locator(".title");
await Expect(locator).ToContainTextAsync("substring");
await Expect(locator).ToContainTextAsync(new Regex("\\d messages"));
Note that if array is passed as an expected value, entire lists of elements can be asserted:
var locator = Page.Locator("list > .list-item");
await Expect(locator).ToContainTextAsync(new string[] { "Text 1", "Text 4", "Text 5" });
Expect(Locator).ToHaveAttributeAsync(name, value, options)
name
<string> Attribute name.#value
<string|Regex> Expected attribute value.#options
<LocatorAssertionsToHaveAttributeOptions?
>- returns:void># <
Ensures the Locator points to an element with given attribute.
var locator = Page.Locator("input");
await Expect(locator).ToHaveAttributeAsync("type", "text");
Expect(Locator).ToHaveClassAsync(expected, options)
expected
<string|Regex|IEnumerable<string>|IEnumerable<Regex>> Expected class or RegExp or a list of those.#options
<LocatorAssertionsToHaveClassOptions?
>- returns:void># <
Ensures the Locator points to an element with given CSS class.
var locator = Page.Locator("#component");
await Expect(locator).ToHaveClassAsync(new Regex("selected"));
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"});
Expect(Locator).ToHaveCountAsync(count, options)
Ensures the Locator resolves to an exact number of DOM nodes.
var locator = Page.Locator("list > .component");
await Expect(locator).ToHaveCountAsync(3);
Expect(Locator).ToHaveCSSAsync(name, value, options)
name
<string> CSS property name.#value
<string|Regex> CSS property value.#options
<LocatorAssertionsToHaveCSSOptions?
>- returns:void># <
Ensures the Locator resolves to an element with the given computed CSS style.
var locator = Page.Locator("button");
await Expect(locator).ToHaveCSSAsync("display", "flex");
Expect(Locator).ToHaveIdAsync(id, options)
Ensures the Locator points to an element with the given DOM Node ID.
var locator = Page.Locator("input");
await Expect(locator).ToHaveIdAsync("lastname");
Expect(Locator).ToHaveJSPropertyAsync(name, value, options)
name
<string> Property name.#value
<[object]> Property value.#options
<LocatorAssertionsToHaveJSPropertyOptions?
>- returns:void># <
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.
var locator = Page.Locator(".component");
await Expect(locator).ToHaveJSPropertyAsync("loaded", true);
Expect(Locator).ToHaveTextAsync(expected, options)
expected
<string|Regex|IEnumerable<string>|IEnumerable<Regex>> Expected substring or RegExp or a list of those.#options
<LocatorAssertionsToHaveTextOptions?
>IgnoreCase
<bool?> Whether to perform case-insensitive match.ignoreCase
option takes precedence over the corresponding regular expression flag if specified.#Timeout
<double?> Time to retry the assertion for.#UseInnerText
<bool?> Whether to useelement.innerText
instead ofelement.textContent
when retrieving DOM node text.#
- returns:void># <
Ensures the Locator points to an element with the given text. You can use regular expressions for the value as well.
var locator = Page.Locator(".title");
await Expect(locator).ToHaveTextAsync(new Regex("Welcome, Test User"));
await Expect(locator).ToHaveTextAsync(new Regex("Welcome, .*"));
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).toHaveTextAsync(new string[]{ "Text 1", "Text 2", "Text 3" });
Expect(Locator).ToHaveValueAsync(value, options)
Ensures the Locator points to an element with the given input value. You can use regular expressions for the value as well.
var locator = Page.Locator("input[type=number]");
await Expect(locator).ToHaveValueAsync(new Regex("[0-9]"));
Expect(Locator).ToHaveValuesAsync(values, options)
values
<IEnumerable<string>|IEnumerable<Regex>> Expected options currently selected.#options
<LocatorAssertionsToHaveValuesOptions?
>- returns:void># <
Ensures the Locator points to multi-select/combobox (i.e. a select
with the multiple
attribute) and the specified values are selected.
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") });
Expect(Page).Not
- type: <PageAssertions>
Makes the assertion check for the opposite condition. For example, this code tests that the page URL doesn't contain "error"
:
await Expect(page).Not.ToHaveURL("error");
Expect(Page).ToHaveTitleAsync(titleOrRegExp, options)
titleOrRegExp
<string|Regex> Expected title or RegExp.#options
<PageAssertionsToHaveTitleOptions?
>- returns:void># <
Ensures the page has the given title.
await Expect(page).ToHaveTitle("Playwright");
Expect(Page).ToHaveURLAsync(urlOrRegExp, options)
urlOrRegExp
<string|Regex> Expected substring or RegExp.#options
<PageAssertionsToHaveURLOptions?
>- returns:void># <
Ensures the page is navigated to the given URL.
await Expect(page).ToHaveURL(new Regex(".*checkout"));
Expect(ApiResponse).Not
- type: <[APIResponseAssertions]>
Makes the assertion check for the opposite condition. For example, this code tests that the response status is not successful:
Expect(ApiResponse).NotToBeOKAsync()
The opposite of [method: APIResponseAssertions.toBeOK
].
Expect(ApiResponse).ToBeOKAsync()
Ensures the response status code is within [200..299] range.