Auto-retrying assertions wait until condition is met
Playwright includes auto-retrying assertions that remove flakiness by waiting until the condition is met, similarly to auto-waiting before actions.
assertions
91 notes in this subject, read out of this brain and free to use. This is page 1 of 2.
toMatchAriaSnapshot assertion on page
The expect(page).toMatchAriaSnapshot() method compares the accessible structure of the page with a predefined aria snapshot template. When using @playwright/test in JavaScript/TypeScript, the syntax is await expect(page).toMatchAriaSnapshot(`template`). The comparison is case-sensitive, collapses whitespace (indentation and line breaks are ignored), and is order-sensitive (the order of elements in the snapshot template must match the order in the page's accessibility tree).
toMatchAriaSnapshot assertion on locator
The expect(locator).toMatchAriaSnapshot() method in Playwright matches a specific part of the page by comparing its accessible structure to a predefined aria snapshot template. This allows testing the accessibility tree of individual elements or components rather than the entire page.
Assertion types in Codegen
Assertions can be recorded by clicking a toolbar icon, then clicking a page element to assert against. Available assertion types are: 'assert visibility' to assert that an element is visible, 'assert text' to assert that an element contains specific text, and 'assert value' to assert that an element has a specific value.
Playwright Test provides built-in Web-First Assertions
Playwright Test includes built-in Web-First assertions such as PageAssertions.toHaveTitle() and PageAssertions.toHaveScreenshot(). These assertions automatically wait and retry until the condition is met, unlike plain assertions in Playwright Library.
Use soft assertions for non-blocking checks
Soft assertions do not immediately terminate test execution. Instead, they compile and display a list of failed assertions once the test ends. Use expect.soft() to make checks that will not stop the test when they fail, allowing the test to continue checking more things.
Soft assertion example
// Make a few checks that will not stop the test when failed... await expect.soft(page.getByTestId('status')).toHaveText('Success'); // ... and continue the test to check more things. await page.getByRole('link', { name: 'next page' }).click();
Web first assertion example with toBeVisible
// Correct: uses web first assertion await expect(page.getByText('welcome')).toBeVisible(); // Incorrect: manual assertion without awaiting expect(await page.getByText('welcome').isVisible()).toBe(true);
Use web first assertions instead of manual assertions
Assertions are a way to verify that expected and actual results match. Use web first assertions like toBeVisible() which wait until the expected condition is met. Web first assertions retry if needed. Do not use manual assertions that do not await the expect, such as expect(await page.getByText('welcome').isVisible()).toBe(true).
Web-first assertions replace page.$eval()
Instead of using page.$eval() to inspect an ElementHandle and extract text content, attribute, or class, use web-first assertions which offer several matchers. This approach is more reliable and readable.
Custom expect message as second argument
A custom message can be specified as the second argument to expect: await expect(page.getByText('Name'), 'should be logged in').toBeVisible(); This message is shown in reporters for both passing and failing expects.
Soft assertions support custom message
Soft assertions also support custom messages: expect.soft(value, 'my soft assertion').toBe(56);
expect.configure() creates pre-configured expect instance
You can create a pre-configured expect instance with custom defaults such as timeout and soft. Example: const slowExpect = expect.configure({ timeout: 10000 }); await slowExpect(locator).toHaveText('Submit');
expect.poll() for polling assertions
expect.poll() converts a synchronous expect to an asynchronous polling one. It accepts a callback function and options. Options include: message (custom expect message for reporting), timeout (poll duration in ms, defaults to 5 seconds, pass 0 to disable), and intervals (array of wait durations between polls, defaults to [100, 250, 500, 1000]).
expect.poll() example polling API status
Example using expect.poll() to poll an API: await expect.poll(async () => { const response = await page.request.get('https://api.example.com'); return response.status(); }, { message: 'make sure API eventually succeeds', timeout: 10000, }).toBe(200);
expect.poll() with custom intervals
expect.poll() supports custom polling intervals via the intervals option: intervals: [1_000, 2_000, 10_000] creates pattern: probe, wait 1s, probe, wait 2s, probe, wait 10s, probe, wait 10s, probe. Default is [100, 250, 500, 1000].
expect.soft.poll() for soft polling assertions
You can combine expect.soft with expect.poll to perform soft assertions in polling logic: await expect.soft.poll(async () => { const response = await page.request.get('https://api.example.com'); return response.status(); }).toBe(200); This allows the test to continue even if the assertion inside poll fails.
expect.configure soft true chains with poll
expect.configure({ soft: true }) chains with expect.poll: const softExpect = expect.configure({ soft: true }); await softExpect.poll(async () => { ... }).toBe(200); This is useful when reusing a configured instance.
expect.toPass() retries blocks of code
expect.toPass() retries blocks of code until they pass successfully. Example: await expect(async () => { const response = await page.request.get('https://api.example.com'); expect(response.status()).toBe(200); }).toPass();
expect.toPass() with custom timeout and intervals
expect.toPass() accepts options for custom timeout and retry intervals. Options include: intervals (array of wait durations, defaults to [100, 250, 500, 1000]) and timeout (in ms, defaults to 60_000 in the example). By default toPass has timeout 0 and does not respect custom expect timeout.
expect.toPass() example with custom options
Example using expect.toPass() with custom timeout and intervals: await expect(async () => { const response = await page.request.get('https://api.example.com'); expect(response.status()).toBe(200); }).toPass({ intervals: [1_000, 2_000, 10_000], timeout: 60_000 });
expect.extend() for custom matchers
You can extend Playwright assertions by providing custom matchers using expect.extend(). Custom matchers must return an object with a pass flag indicating whether the assertion passed, and a message callback used when the assertion fails.
Custom matcher example toHaveAmount
Example of a custom matcher toHaveAmount that checks if a locator has a data-amount attribute with an expected value. The matcher receives a Locator and expected number, with optional timeout option. It returns an object with message callback, pass flag, name, expected, and actual properties.
Custom matcher implementation structure
Custom matcher implementation must: (1) call baseExpect based on isNot flag, (2) use try-catch to capture matcherResult on failure, (3) handle this.isNot for negation, (4) return object with message callback, pass boolean, name string, expected and actual values.
mergeExpects() combines custom matchers from multiple modules
You can combine custom matchers from multiple files using mergeExpects(): export const expect = mergeExpects(dbExpect, a11yExpect); This allows using custom matchers from multiple test utility modules in a single test file.
Distinguish Playwright expect from jest expect library
Do not confuse Playwright's expect with the expect library used by Jest. The Jest expect library is not fully integrated with Playwright test runner, so always use Playwright's own expect.
mergeTests() combines test fixtures from multiple modules
You can combine test fixtures from multiple modules using mergeTests(): export const test = mergeTests(dbTest, a11yTest); This allows using test fixtures from multiple test utility modules.
Non-retrying assertions can cause flaky tests
Most web pages show information asynchronously, and using non-retrying assertions can lead to flaky tests. For more complex assertions that need to be retried, use expect.poll() or expect.toPass() instead of non-retrying assertions.
expect() function basic usage
Playwright assertions are made by calling expect(value) and choosing a matcher that reflects the expectation. Example: expect(success).toBeTruthy();
Web-specific async matchers auto-wait
Playwright includes async matchers that wait until the expected condition is met. For example, await expect(page.getByTestId('status')).toHaveText('Submitted'); will re-fetch the element and check it repeatedly until the condition is met or timeout is reached.
Auto-retrying assertions list
Auto-retrying assertions that retry until passing or timeout: toBeAttached(), toBeChecked(), toBeDisabled(), toBeEditable(), toBeEmpty(), toBeEnabled(), toBeFocused(), toBeHidden(), toBeInViewport(), toBeVisible(), toContainText(), toContainClass(), toHaveAccessibleDescription(), toHaveAccessibleName(), toHaveAttribute(), toHaveClass(), toHaveCount(), toHaveCSS(), toHaveId(), toHaveJSProperty(), toHaveRole(), toHaveScreenshot(), toHaveText(), toHaveValue(), toHaveValues(), toMatchAriaSnapshot() for locators, and toMatchAriaSnapshot(), toHaveScreenshot(), toHaveTitle(), toHaveURL() for pages, and toBeOK() for responses. All retrying assertions are async and must be awaited.
Non-retrying generic assertions list
Non-retrying assertions that do not auto-retry: toBe(), toBeCloseTo(), toBeDefined(), toBeFalsy(), toBeGreaterThan(), toBeGreaterThanOrEqual(), toBeInstanceOf(), toBeLessThan(), toBeLessThanOrEqual(), toBeNaN(), toBeNull(), toBeTruthy(), toBeUndefined(), toContain() (for strings and arrays), toContainEqual(), toEqual(), toHaveLength(), toHaveProperty(), toMatch(), toMatchObject(), toStrictEqual(), toThrow().
Asymmetric matchers for relaxed matching
Asymmetric matchers that can be nested in other assertions: expect.any() matches any instance of a class or primitive, expect.anything() matches anything, expect.arrayContaining() matches arrays with specific elements, expect.arrayOf() matches arrays with elements of specific type, expect.closeTo() matches approximately equal numbers, expect.objectContaining() matches objects with specific properties, expect.stringContaining() matches strings with a substring, expect.stringMatching() matches strings matching a regular expression.
Negating matchers with .not
Matchers can be negated by adding .not to the front: expect(value).not.toEqual(0); or await expect(locator).not.toContainText('some text');
Soft assertions do not terminate test
Soft assertions use expect.soft() and do not terminate test execution when they fail, but mark the test as failed. Example: await expect.soft(page.getByTestId('status')).toHaveText('Success');. Soft assertions only work with Playwright test runner.
Check soft assertion failures during test
During test execution, you can check whether there were any soft assertion failures using: expect(test.info().errors).toHaveLength(0);
expect.timeout configuration option
The expect.timeout option under the expect configuration sets the maximum time that expect() should wait for a condition to be met. The default is 5 seconds (5000 milliseconds). Web first assertions like expect(locator).toHaveText() have this separate timeout from the test timeout.
toMatchSnapshot configuration options
The expect.toMatchSnapshot configuration object contains options for the expect(locator).toMatchSnapshot() method. The maxDiffPixelRatio option specifies an acceptable ratio of pixels that are different to the total amount of pixels, as a value between 0 and 1.
toHaveScreenshot configuration options
The expect.toHaveScreenshot configuration object contains options for the expect(locator).toHaveScreenshot() method. The maxDiffPixels option specifies an acceptable amount of pixels that could be different, and is unset by default.
expect.poll waits for arbitrary condition
The expect.poll method polls a function repeatedly until the assertion passes, useful for waiting on async conditions.
toHaveRole assertion checks ARIA role
The LocatorAssertions.toHaveRole method checks if an element has the specified ARIA role. Example: await expect(locator).toHaveRole('button');
toHaveURL ignoreCase option
The expect(page).toHaveURL(url) assertion now supports an ignoreCase option to perform case-insensitive URL comparison.
expect.toPass timeout configuration
The expect(callback).toPass() timeout can be configured with expect.toPass.timeout option globally in TestConfig.expect or per project in TestProject.expect.
toHaveScreenshot stylePath option
The stylePath option for PageAssertions.toHaveScreenshot and LocatorAssertions.toHaveScreenshot applies a custom stylesheet while making the screenshot.
LocatorAssertions.toBeAttached checks DOM presence
The LocatorAssertions.toBeAttached method ensures that an element is present in the page's DOM. Unlike toBeVisible, it does not require the element to be visible.
LocatorAssertions.toHaveAttribute with empty value
The LocatorAssertions.toHaveAttribute assertion with an empty value now checks for an attribute with empty string value, not for missing attribute. For example, toHaveAttribute('disabled', '') succeeds when button does not have a disabled attribute.
LocatorAssertions.toHaveValues asserts multiple selected values
The LocatorAssertions.toHaveValues method asserts all selected values of a <select multiple> element.
toContainText and toHaveText ignoreCase option
The LocatorAssertions.toContainText and LocatorAssertions.toHaveText methods now accept an ignoreCase option for case-insensitive text matching.
expect().toPass retries block until assertions pass
The expect(callback).toPass() assertion retries a block of code until all assertions pass, useful for waiting on async operations.
LocatorAssertions.toBeInViewport checks viewport intersection
The LocatorAssertions.toBeInViewport method ensures that an element intersects the viewport according to the Intersection Observer API, with optional ratio parameter to check partial visibility.
toMatchSnapshot anonymous snapshots
The expect().toMatchSnapshot() method now supports anonymous snapshots where Playwright automatically generates the snapshot name when omitted.
maxDiffPixels controls screenshot comparison tolerance
The maxDiffPixels and maxDiffPixelRatio options in expect().toMatchSnapshot() allow fine-grained control over acceptable differences in screenshot assertions.
LocatorAssertions.toHaveScreenshot screenshot assertion
The LocatorAssertions.toHaveScreenshot method provides web-first assertion for screenshot expectations with automatic animation disabling and CSS scaling.
PageAssertions.toHaveScreenshot page screenshot assertion
The PageAssertions.toHaveScreenshot method provides web-first assertion for full page screenshot expectations with automatic animation disabling and CSS scaling.
expect.configure creates pre-configured expect instance
The expect.configure method creates a pre-configured expect instance with custom defaults like timeout and soft assertion behavior.
mergeExpects combines custom matchers from multiple sources
The mergeExpects function allows combining custom expect matchers from multiple files or modules.
expect(response).toBeOK assertion
The expect(response).toBeOK() assertion verifies that an API response has an OK status code (200-299).
LocatorAssertions.toHaveAttribute with values
The LocatorAssertions.toHaveAttribute assertion checks that an element has a specific attribute with an expected value.
expect.toBeChecked with checked option
The expect(locator).toBeChecked() assertion now accepts a checked option to verify checkbox or radio button state.
expect.soft performs soft assertions
The expect.soft method performs soft assertions that do not terminate test execution on failure but mark the test as failed.