Skip to content

Assertions ​

Introduction ​

Playwright includes web-specific assertions that automatically retry until the expected condition is met. Consider the following example:

csharp
await Expect(Page.GetByTestId("status")).ToHaveTextAsync("Submitted");

Playwright will re-test the element with the test ID of status until it has the "Submitted" text. It will re-fetch the element and check it repeatedly until the condition is met or the timeout is reached.

By default, the timeout for assertions is 5 seconds.

Auto-retrying assertions ​

The following assertions will retry until the assertion passes or the assertion timeout is reached.

AssertionDescription
LocatorAssertions.ToBeAttachedAsync()Element is attached
LocatorAssertions.ToBeCheckedAsync()Checkbox is checked
LocatorAssertions.ToBeDisabledAsync()Element is disabled
LocatorAssertions.ToBeEditableAsync()Element is editable
LocatorAssertions.ToBeEmptyAsync()Container is empty
LocatorAssertions.ToBeEnabledAsync()Element is enabled
LocatorAssertions.ToBeFocusedAsync()Element is focused
LocatorAssertions.ToBeHiddenAsync()Element is not visible
LocatorAssertions.ToBeInViewportAsync()Element intersects viewport
LocatorAssertions.ToBeVisibleAsync()Element is visible
LocatorAssertions.ToContainClassAsync()Element has specified CSS classes
LocatorAssertions.ToContainTextAsync()Element contains text
LocatorAssertions.ToHaveAccessibleDescriptionAsync()Element has a matching accessible description
LocatorAssertions.ToHaveAccessibleNameAsync()Element has a matching accessible name
LocatorAssertions.ToHaveAttributeAsync()Element has a DOM attribute
LocatorAssertions.ToHaveClassAsync()Element has a class property
LocatorAssertions.ToHaveCountAsync()List has exact number of children
LocatorAssertions.ToHaveCSSAsync()Element has CSS property
LocatorAssertions.ToHaveIdAsync()Element has an ID
LocatorAssertions.ToHaveJSPropertyAsync()Element has a JavaScript property
LocatorAssertions.ToHaveRoleAsync()Element has a specific ARIA role
LocatorAssertions.ToHaveTextAsync()Element matches text
LocatorAssertions.ToHaveValueAsync()Input has a value
LocatorAssertions.ToHaveValuesAsync()Select has options selected
LocatorAssertions.ToMatchAriaSnapshotAsync()Element matches provided Aria snapshot
PageAssertions.ToHaveTitleAsync()Page has a title
PageAssertions.ToHaveURLAsync()Page has a URL
ApiResponseAssertions.ToBeOKAsync()Response has an OK status

Expect.ToPassAsync ​

Prefer auto-retrying assertions whenever possible. For more complex checks, retry a block of code until it passes with FunctionAssertions.ToPassAsync().

csharp
await Expect(async () =>
{
    var response = await Page.APIRequest.GetAsync("https://api.example.com");
    Assert.AreEqual(200, response.Status);
}).ToPassAsync();

You can also specify custom timeout and retry intervals:

csharp
await Expect(async () =>
{
    var response = await Page.APIRequest.GetAsync("https://api.example.com");
    Assert.AreEqual(200, response.Status);
}).ToPassAsync(new()
{
    // Probe, wait 1s, probe, wait 2s, probe, wait 10s, probe, wait 10s, probe
    // ... Defaults to [100, 250, 500, 1000].
    Intervals = [1_000, 2_000, 10_000],
    Timeout = 60_000,
});

By default, ToPassAsync retries for 30 seconds. SetDefaultExpectTimeout does not change this timeout, use SetDefaultExpectToPassTimeout instead:

csharp
SetDefaultExpectToPassTimeout(60_000);

Custom Expect Message ​

You can specify a custom expect message as a second argument to the expect function, for example:

csharp
await Expect(Page.GetByText("Name"), "should be logged in").ToBeVisibleAsync();

When expect fails, the error would look like this:

bash
Microsoft.Playwright.PlaywrightAssertionException : should be logged in

Locator expected to be visible
Call log:
- Expect "ToBeVisibleAsync" with timeout 5000ms
- waiting for GetByText("Name")

Setting a custom timeout ​

You can specify a custom timeout for assertions either globally or per assertion. The default timeout is 5 seconds.

Global timeout ​

csharp
using Microsoft.Playwright;
using Microsoft.Playwright.MSTest;
using Microsoft.VisualStudio.TestTools.UnitTesting;

namespace PlaywrightTests;

[TestClass]
public class UnitTest1 : PageTest
{
    [ClassInitialize]
    public static void GlobalSetup(TestContext context)
    {
        SetDefaultExpectTimeout(10_000);
    }
    // ...
}

Per assertion timeout ​

csharp
await Expect(Page.GetByText("Name")).ToBeVisibleAsync(new() { Timeout = 10_000 });

Released under the Apache 2.0 License.