Principle:Microsoft Playwright Assertion and Verification
| Knowledge Sources | |
|---|---|
| Domains | Testing, Browser_Automation |
| Last Updated | 2026-02-11 00:00 GMT |
Overview
Assertion and verification is the practice of confirming that an application's observable state matches expected values, using auto-retrying mechanisms that account for the asynchronous nature of modern web interfaces.
Description
Assertions are the verification layer of any test. They answer the fundamental question: "Is the application behaving correctly?" In the context of browser automation, assertions face a unique challenge that does not exist in unit testing: the state being verified is inherently asynchronous and may not be immediately available when the assertion runs.
Consider a test that clicks a "Submit" button and then verifies that a success message appears. In a traditional synchronous assertion model, the test would fail if the success message has not yet rendered at the exact moment the assertion executes. This leads to flaky tests -- tests that pass or fail depending on timing rather than correctness.
Web-first assertions solve this problem by incorporating a retry mechanism. Instead of checking the state once and immediately failing, a web-first assertion repeatedly polls the DOM until the condition is satisfied or a timeout is reached. This approach is fundamentally different from inserting arbitrary sleep() or waitFor() calls, because it waits for exactly the right condition rather than an arbitrary duration.
The retry mechanism must be carefully designed. It should poll at a frequency that balances responsiveness (detecting the condition quickly) against resource usage (not overwhelming the browser process with queries). It should also provide clear error messages when the timeout is reached, showing the actual state versus the expected state at the time of failure.
Usage
Assertions should be used after every significant action in a test to verify that the application responded correctly. They are used to check element visibility, text content, attribute values, element counts, CSS properties, page URLs, page titles, and screenshot comparisons. Auto-retrying assertions should be preferred over manual waits whenever verifying DOM state.
Theoretical Basis
The assertion and verification process follows a poll-until-satisfied model:
Step 1 -- Assertion Construction: The assertion is constructed by combining a subject (typically a Locator representing a DOM element) with a matcher (a named condition like "is visible" or "has text"). The assertion may include options such as a custom timeout or matching flags.
Step 2 -- Initial Evaluation: The assertion evaluates the current state of the subject against the matcher. If the condition is satisfied, the assertion passes immediately.
Step 3 -- Retry Loop: If the condition is not satisfied, the assertion enters a retry loop:
deadline = now() + timeout
while now() < deadline:
state = querySubjectState()
if matcher.matches(state):
return PASS
wait(pollInterval)
return FAIL with (expected, actual)
The poll interval is typically short (on the order of 100ms) to provide fast feedback. The timeout defaults to a framework-configured value (commonly 5000ms) but can be overridden per assertion.
Step 4 -- Negation: Negated assertions (e.g., "expect element NOT to be visible") follow the same retry model but invert the condition. The assertion passes if the condition remains false for the duration of the retry period, and fails if the condition becomes true.
Step 5 -- Soft Assertions: Some frameworks support soft assertions that do not immediately terminate the test on failure. Instead, they collect all failures and report them at the end of the test. This allows a single test run to identify multiple issues.
Categories of Assertions:
- Element State: Visible, hidden, attached, detached, enabled, disabled, focused, checked, unchecked.
- Element Content: Text content, inner text, input value, attribute values.
- Element Appearance: CSS properties, bounding box, screenshot comparison.
- Collection: Element count.
- Page State: URL, title.
- Generic: Arbitrary conditions via "to pass" retry wrappers.
- Accessibility: ARIA snapshot matching for accessibility tree verification.