Web-first Assertions

Assert the rendered result. Playwright retries against the page until the condition holds or the timeout is reached.

Retry, not sleep An assertion waits for the state it asserts
Web-first Assert what the user can perceive
On failure The timeout names the unmet condition

Retry, not sleep

An assertion waits for the state it asserts

Each assertion re-reads the page until it holds or the timeout expires. The expected outcome and the wait stay in one expression.

Timeouts and retries →

// retries until the text lands, then passes
expect($page->getByRole('alert'))
    ->toContainText('Saved');

Web-first

Assert what the user can perceive

Visibility, enabled state, value, count, attribute, accessible name. The vocabulary describes the rendered page rather than the shape of the DOM behind it.

Choosing assertions →

On failure

The timeout names the unmet condition

When the assertion times out, its error reports the expected condition and the observed state so you can start with the failed check.

Debugging and logging →

Next step

Move from the tour to working code.

Choose the explanation, recipe, or runnable example that matches what you need next.

Understand Assertions Choose web-first assertions and let them retry against real page state. Compare Timeouts and retries Place assertions next to waiting, timeout budgets, and retry policy. Run Expectation example Copy a small script that asserts browser-visible state.

Common questions

Before you wire it into a suite.

Are Playwright assertions just PHPUnit assertions?

No. Web-first assertions retry against the browser until the expected condition is true or the timeout expires. PHPUnit assertions are still useful for plain PHP values.

Should I add sleeps before assertions?

No. Prefer an assertion that describes the final state. The retry loop belongs inside the assertion, not in the test body.

What should I assert on?

Prefer visible user outcomes: text, role, accessible name, enabled state, value, count, URL, or title.