Custom expect message in assertions
Assertions now accept a custom message as the second argument: await expect(locator, 'should be logged in').toBeVisible();
assertions
91 notes in this subject, read out of this brain and free to use. This is page 2 of 2.
Web-First Assertions re-test until condition met
Web-First Assertions (introduced in 1.14) re-test the node until the fetched node meets the condition or until the timeout is reached. For example, expect(page.locator('.status')).toHaveText('Submitted') will repeatedly check the element's text until it matches or times out.
Assertion timeout configuration
The timeout for Web-First Assertions can be passed per-assertion or configured once via `testProject.expect` in the test config. By default, the assertion timeout is not set, so it will wait until the whole test times out.
List of Web-First Assertions in 1.14
Web-First Assertions introduced in 1.14: toBeChecked(), toBeDisabled(), toBeEditable(), toBeEmpty(), toBeEnabled(), toBeFocused(), toBeHidden(), toBeVisible(), toContainText(text, options?), toHaveAttribute(name, value), toHaveClass(expected), toHaveCount(count), toHaveCSS(name, value), toHaveId(id), toHaveJSProperty(name, value), toHaveText(expected, options), toHaveTitle(title), toHaveURL(url), toHaveValue(value).
Element state assertion methods
Playwright 1.8 introduced methods to assert element state: Page.isEditable(), Page.isChecked(), Page.isDisabled(), Page.isEnabled(), Page.isHidden(), Page.isVisible() and their ElementHandle equivalents.
expect.toMatchSnapshot supports subdirectories
The `expect.toMatchSnapshot()` method (introduced in 1.17) now supports subdirectories for organizing snapshot files.
Expect timeout default and configuration
Auto-retrying assertions have a separate timeout of 5,000 milliseconds (5 seconds) by default. This assertion timeout is unrelated to the test timeout. It can be set globally in the config with { expect: { timeout: 10_000 } } or overridden per assertion using the timeout option in the assertion call.
Set expect timeout in config
To set expect timeout globally in playwright.config.ts: use { expect: { timeout: 10_000 } } in the defineConfig export.
Set expect timeout for a single assertion
Pass a timeout option to any assertion: await expect(locator).toHaveText('hello', { timeout: 10_000 })
Playwright assertions are async and eliminate flaky timeouts
Playwright assertions are designed to describe expectations that will eventually be met. They automatically wait until the expected condition is satisfied, eliminating flaky timeouts and racy checks. Async matchers wait until the expected condition is met.
expect function for assertions
Playwright includes test assertions in the form of an expect function. To make an assertion, call expect(value) and choose a matcher that reflects the expectation.
Popular async assertions in Playwright
The most popular async assertions are: toBeChecked (checkbox is checked), toBeEnabled (control is enabled), toBeVisible (element is visible), toContainText (element contains text), toHaveAttribute (element has attribute), toHaveCount (list of elements has given length), toHaveText (element matches text), toHaveValue (input element has value), toHaveTitle (page has title), and toHaveURL (page has URL).
Generic matchers in Playwright do not use await
Playwright includes generic matchers like toEqual, toContain, toBeTruthy that can be used to assert any conditions. These assertions do not use the await keyword as they perform immediate synchronous checks on already available values.
Replace Testing Library waitFor with Playwright assertions
Testing Library's waitFor and waitForElementToBeRemoved are replaced with Playwright assertions that automatically wait. For example, await waitFor(() => expect(getByText('text')).toBeInTheDocument()) becomes await expect(page.getByText('text')).toBeVisible(); and await waitForElementToBeRemoved(() => queryByText('text')) becomes await expect(page.getByText('text')).toBeHidden().
Playwright assertions eventually meet expected conditions
Playwright assertions are designed to describe the expectations that need to be eventually met, handling race conditions automatically without requiring explicit waits.
Expect async function for assertions in C#
Playwright provides an async function called Expect to assert and wait until the expected condition is met. Example: await Expect(Page).ToHaveTitleAsync(new Regex("Playwright"));
Common Playwright async assertions for C#
Popular async assertions include: LocatorAssertions.toBeChecked (checkbox is checked), LocatorAssertions.toBeEnabled (control is enabled), LocatorAssertions.toBeVisible (element is visible), LocatorAssertions.toContainText (element contains text), LocatorAssertions.toHaveAttribute (element has attribute), LocatorAssertions.toHaveCount (list of elements has given length), LocatorAssertions.toHaveText (element matches text), LocatorAssertions.toHaveValue (input element has value), PageAssertions.toHaveTitle (page has title), and PageAssertions.toHaveURL (page has URL).
test.expect creates test assertions
The expect function can be used to create test assertions in Playwright Test. Usage: test.expect(value).assertion() or expect(value).assertion().
List of Locator assertions
LocatorAssertions provides the following methods: toBeAttached (element is attached), toBeChecked (checkbox is checked), toBeDisabled (element is disabled), toBeEditable (element is editable), toBeEmpty (container is empty), toBeEnabled (element is enabled), toBeFocused (element is focused), toBeHidden (element is not visible), toBeInViewport (element intersects viewport), toBeVisible (element is visible), toContainClass (element has specified CSS classes), toContainText (element contains text), toHaveAccessibleDescription (element has matching accessible description), toHaveAccessibleName (element has matching accessible name), toHaveAttribute (element has DOM attribute), toHaveClass (element has class property), toHaveCount (list has exact number of children), toHaveCSS (element has CSS property), toHaveId (element has ID), toHaveJSProperty (element has JavaScript property), toHaveRole (element has specific ARIA role), toHaveText (element matches text), toHaveValue (input has value), toHaveValues (select has options selected), and toMatchAriaSnapshot (element matches provided ARIA snapshot).
Page and API response assertions
PageAssertions provides toHaveTitle (page has a title) and toHaveURL (page has a URL). APIResponseAssertions provides toBeOK (response has OK status).
Soft assertions in Python
Soft assertions do not terminate test execution when they fail; instead, they mark the test as failed and allow execution to continue. Soft assertions are created using expect.soft(locator) and require pytest-playwright or pytest-playwright-asyncio plugin version 0.8.0 or newer.
Custom expect message
A custom message can be provided as a second argument to the expect function. In Python: expect(page.get_by_text("Name"), "should be logged in").to_be_visible(). In C#: await Expect(Page.GetByText("Name"), "should be logged in").ToBeVisibleAsync(). When the assertion fails, the custom message appears in the error output.
Default assertion timeout
The default timeout for assertions is 5 seconds.
Global assertion timeout in Python
To set a custom global timeout for all assertions in Python, use expect.set_options(timeout=10_000) in conftest.py. The timeout value is specified in milliseconds.
Per-assertion timeout
To set a timeout for a specific assertion, pass the timeout parameter to the assertion method. In Python: expect(page.get_by_text("Name")).to_be_visible(timeout=10_000). In C#: await Expect(Page.GetByText("Name")).ToBeVisibleAsync(new() { Timeout = 10_000 }). The timeout value is specified in milliseconds.
Global assertion timeout in C# with NUnit
To set a custom global timeout in C# with NUnit, call SetDefaultExpectTimeout(10_000) in a [OneTimeSetUp] method. The timeout value is specified in milliseconds.
Global assertion timeout in C# with MSTest
To set a custom global timeout in C# with MSTest, call SetDefaultExpectTimeout(10_000) in a [ClassInitialize] static method. The timeout value is specified in milliseconds.
Global assertion timeout in C# with xUnit
To set a custom global timeout in C# with xUnit, call SetDefaultExpectTimeout(10_000) in the constructor of the test class. The timeout value is specified in milliseconds.
Soft assertion example in Python
Example of using soft assertions in Python: expect.soft(page.get_by_test_id("status")).to_have_text("Success") and expect.soft(page.get_by_test_id("eta")).to_have_text("1 day") will not stop test execution if they fail, allowing page.get_by_role("link", name="next page").click() and subsequent assertions to run.
Custom expect message example in Python
Example in Python: expect(page.get_by_text("Name"), "should be logged in").to_be_visible() produces an AssertionError showing 'should be logged in' as the custom message when the assertion fails.
Custom expect message example in C#
Example in C#: await Expect(Page.GetByText("Name"), "should be logged in").ToBeVisibleAsync() produces a PlaywrightException showing 'should be logged in' as the custom message when the assertion fails.