Assertions

In outcome they are the same. Both retry until the element is hidden or absent from the DOM, and both pass when it never existed at all. The difference is readability and the failure message, not semantics.

Playwright captures the page, writes that capture to the snapshots folder as the new reference image, and still fails the test. A later run, or an automatic retry, compares against the file just written and passes.

A soft assertion records its failure and lets the test keep running, while a plain expect throws and stops the test at that line. Both end with the test reported as failed.

Playwright's web-first matchers return a promise. Without await, the test body runs on and the test finishes before the matcher decides anything, so the assertion can never fail it — the error is dropped or blamed on a later test.

A negated web-first assertion stops retrying the moment its condition is true, and it is already true on a page that never rendered the spinner. The check passes at time zero and proves nothing.

Use expect.poll when the check reduces to one value and one matcher. Use toPass when a whole block must be retried together: several assertions, or code that can throw. Poll retries a value, toPass retries statements.

By default the reference lands beside the test in a folder named after the spec file, with the project name and platform in the file name. The snapshotPathTemplate config option, built from tokens, changes that layout.

Each attempt re-runs the locator query from scratch, reads the element's text, normalizes whitespace and compares it. Playwright repeats until the condition holds or the expect timeout (5 seconds by default in 1.63) expires, then reports the last value seen.

It rewrites reference images only for the tests that command actually executed, and only for the projects and the platform that ran. Everything filtered out, every other project, and every orphaned file stays exactly as it was.

Hand expect.poll the function, not the value: await expect.poll(() => readRowCount()).toBe(42). Playwright re-invokes the callback and re-applies the matcher until it passes or the timeout expires.

Read the YAML diff in the failure, confirm every changed line is intended, then re-run that spec with --update-snapshots so the stored template is regenerated. Commit the regenerated template with the code change and review it as a normal text diff.

Each node is one YAML list item: the role, then the accessible name in double quotes, then state in square brackets, as in a heading line reading role heading, name October statement, level=1. Indentation nests children.

It does not pass. Playwright only treats a missing element as success for visibility and attachment checks, so the content negation keeps retrying and fails at the timeout with a log showing no element was ever found.

Both probe on intervals of 100, 250, 500 then 1000 milliseconds, with the last value repeating. In Playwright 1.63 expect.poll uses the expect timeout, five seconds by default, while toPass defaults to timeout 0 and has none of its own.

It accepts an array of locators. Each matched element is painted over with a solid box covering its bounding box, bright pink by default, changeable with maskColor. The box is applied while capturing, so both the reference and the actual carry it.

The matcher defaults to animations disabled and scale css, where a plain page screenshot allows animations and captures at device resolution. Both hide the text caret. The matcher also re-captures until the image matches or the assertion times out.

Read test.info().errors, the array of errors the runner has recorded for the running test. Soft failures land there as they happen, so asserting the array is empty stops the test at the point you choose.

Both retry and normalize whitespace, but toHaveText requires the element's entire text to match while toContainText only requires a substring. Use the exact form on tightly-scoped elements and the containment form when surrounding text is volatile.

Relax the volatile nodes instead of regenerating the template: write their text or name as a regular expression between slashes, or drop the value entirely, and scope the assertion to the region the test is about rather than the whole page body.

Bracket the delete with positive assertions. Assert the table and the target row are visible and the row count is known, delete, then assert the count dropped by one and the row is no longer attached.

Everything inside a toPass block re-runs on each probe, so the Refresh click keeps firing and restarting the load being awaited. With toPass defaulting to no timeout, the test timeout ends the run instead of the assertion.

Assert on a locator rather than the page: expect(page.getByTestId('balance-widget')).toHaveScreenshot() scrolls that element into view and captures only its box. Full page and clip are the alternatives when a region cannot be located.

Import expect as baseExpect from @playwright/test, call baseExpect.extend with your matcher functions, and export the result as expect. Each matcher returns an object with a boolean pass and a message function that builds the failure text.

Make a check soft when nothing later in the test depends on it, such as the balance format or the export button's label. Keep it hard when the following steps are meaningless or misleading if it fails.

Reading with textContent() takes one snapshot of the text, and comparing it with a generic matcher happens once. Nothing retries, so a value that arrives moments later fails. toHaveText re-reads the element until it matches or the timeout expires.

It returns a new expect instance carrying preset options - timeout, soft and message - and leaves the imported expect untouched. You call the returned instance exactly like expect, and its matchers inherit those defaults.

Put snapshots on high-value, stable surfaces whose structure is a contract, scope each one to the region the test is about, and set an update policy: regeneration scoped to the changed spec, templates reviewed as code, shrink any template that churns.

Only when the styling itself is the requirement, such as an overdraft that must be visually marked, or when the class is a documented state contract. Otherwise assert user-visible meaning or a stable state attribute instead.