Playwright Assertions

expect is imported from @playwright/test. Calling expect(value) returns an object of matchers; what you pass in decides which matchers exist:

A retrying matcher runs a loop. It resolves the locator again on every iteration (so a re-rendered element is found afresh), evaluates the condition inside the page and, when the condition is false, waits and tries again until the assertion timeout passes. Because the loop is asynchronous, a retrying assertion must be awaited; a missing await is the most common reason a check silently never runs. This is the property that removes the need for fixed sleeps, as discussed in Test Design & Page Objects.

Source: Playwright: Assertions

The test above does not wait for the search to finish before it asserts. After the click, the page navigates and the catalogue is re-rendered; toHaveURL and toContainText keep polling until the new state appears. The example’s imports come from a small fixtures.ts that re-exports test and a customised expect (shown later under custom matchers); the built-in @playwright/test import behaves identically for everything except the custom matcher.

All of these are asynchronous and retry. Every one accepts the timeout and signal options; the extra options are listed in the last column. A version in parentheses is the release that introduced the matcher or the option, when it is later than the first web-first assertions of 1.8.

expect(value) with any plain value gives the Jest-compatible matchers: toBe, toEqual, toStrictEqual, toMatchObject, toContain, toContainEqual, toHaveLength, toHaveProperty, toMatch, toBeCloseTo, toBeGreaterThan and toBeLessThan (and their OrEqual forms), toBeDefined, toBeUndefined, toBeNull, toBeNaN, toBeTruthy, toBeFalsy, toBeInstanceOf and toThrow. They evaluate once and never retry. They are the right tool for data that is already settled, such as an API response body or a value computed in the test, and the wrong tool for anything the page produces asynchronously: expect(await locator.textContent()).toBe('x') reads the text once and is the classic cause of flaky tests. Use expect(locator).toHaveText('x') instead.

The asymmetric matchers can be nested inside toEqual and toMatchObject to relax a comparison: expect.any(Class), expect.anything(), expect.arrayContaining(), expect.arrayOf(), expect.closeTo(), expect.objectContaining(), expect.stringContaining() and expect.stringMatching().

Source: Playwright: GenericAssertions

Playwright’s expect is not the expect library that Jest uses, although the generic matchers have the same names. The official documentation warns that the library is not fully integrated with the Playwright test runner, so always import expect from @playwright/test.

expect(response).toBeOK() asserts that an APIResponse, from request.get() or page.request, has a status in the range 200 to 299. It does not retry, because the response is complete. not.toBeOK() asserts the opposite. The failure message includes the request line, the response headers and the response body, which is usually enough to diagnose the problem without re-running:

Source: Playwright: APIResponseAssertions

Captured from a test asserting toBeOK() on the missing book:

Source: Playwright: API testing

(Some header lines were removed for brevity.) Assert on the exact status with expect(response.status()).toBe(404) when the code matters, and on the body with generic matchers. The APIRequestContext itself, including failOnStatusCode, is covered in Network Mocking, Clock & API Testing.

A failed assertion normally throws and ends the test. A soft assertion records the failure, marks the test as failed and lets the test keep going, so one run reports every problem on a page. Use expect.soft(...) in place of expect(...); it takes the same matchers, messages and options. Soft assertions are a feature of the Playwright test runner and do not work outside it.

Source: Playwright: Soft assertions

test.info().errors lists every failure recorded so far, so asserting it is empty turns the next step into a gate: when earlier soft checks failed, the test stops before doing anything that depends on them. This failing test, with shortened timeouts, shows that both soft failures are reported and the following hard assertion still runs:

Source: Playwright: Soft assertions

Soft assertions are a good fit for checking many independent facts on one page, such as a summary panel. They are a poor fit for steps where later actions assume the earlier check passed: each failed soft assertion still waits for its full timeout, so a page that is entirely broken costs one timeout per soft check unless a gate stops the test. expect.soft.poll(...) combines soft behaviour with polling (1.61), and expect.configure({ soft: true }) makes a whole expect instance soft.

expect.configure(options) returns a new expect with its own defaults. The options are timeout, soft and message. Use it to create a "slow" or "soft" variant once and share it:

Source: Playwright: expect.configure

expect.configure({ soft: true }) also chains with expect.poll, so softExpect.poll(...) is a soft polling assertion.

Not every condition is a locator. expect.poll(fn, options) calls an async function repeatedly and applies a generic matcher to the returned value until it passes. It is the right tool for a value that changes outside the page, such as an API that eventually reports a state, a counter, or a file on disk.

Source: Playwright: expect.poll

The poller supports the generic matchers (toBe, toContain, toEqual, …​) but not the locator matchers, which already retry. A poll failure shows the last value:

Source: Playwright: expect.poll

expect(async () => { ... }).toPass() re-runs a whole block until every assertion inside passes. Use it when the condition needs several steps or several assertions, or when the block must perform an action (such as a request) on each attempt. toPass retries on any thrown error, including from non-retrying assertions.

Source: Playwright: expect.toPass

Choose between the retry tools by the shape of the check:

Keep the block small and free of side effects that cannot be repeated: a retried block that clicks "Place order" can place several orders. Do not wrap clicks and fills in toPass to compensate for missing waits; locator actions already auto-wait.

expect.extend(matchers) returns a new expect with extra matchers, which TypeScript sees with correct types when the matchers are declared in the object literal. A matcher is an async function whose first argument is the received value and which returns { pass, message, name, expected, actual }. Inside it, this.isNot tells whether .not was used, this.utils offers formatting helpers (matcherHint, printExpected, printReceived) and the timeout option reflects the configured expect timeout (since 1.45). The simplest way to keep retry behaviour is to delegate to a built-in matcher and translate its result, as below.

Source: Playwright: Add custom matchers using expect.extend

Source: Playwright: Add custom matchers using expect.extend

The failure output of a custom matcher uses the hint the matcher builds:

Source: Playwright: Add custom matchers using expect.extend

A matcher that wraps a built-in one is still limited by the built-in’s timeout, so pass the options through, as the example does. Matchers declared in separate files or packages are combined with mergeExpects (and the matching fixtures with mergeTests):

Source: Playwright: Combine custom matchers from multiple modules

The merge example was not run: database-test-utils and a11y-test-utils are placeholder module names from the official documentation, not real packages. mergeExpects itself is declared in the installed 1.64.1 type definitions.

Locator assertions check one fact at a time. An aria snapshot checks the structure of a region at once: it compares the accessibility tree of a page or element with a YAML template, so a test can say "this region is a heading, a search form and a list of links" in a few lines and still fail if the structure regresses. Because the tree is built from roles and accessible names, the template also exercises accessibility: a button that lost its name, or a heading that became a div, no longer matches. Aria snapshots arrived in Playwright 1.49 (toMatchAriaSnapshot).

All examples live in one project with a configuration that reads BASE_URL. With Bookshelf running on a free port:

Source: Playwright: Running tests

The result was 36 passed (18 tests in Chromium and 18 in WebKit, headless). The configuration sets workers: 1 because every test calls /api/test/reset, which also clears all sessions; with several workers, one test’s reset can sign out another test that is half-way through a sign-in. That failure was observed once, in the toPass example under WebKit, before the setting was added, and it did not recur after it. Firefox was not run on this host: the local Firefox build did not launch. Shared state on one server is a property of the example application; in a real suite, give each worker its own data or user, as described in Authentication & Isolation.