docs: clarify locator read waiting in Playwright migration

Closed
MA
14d ago
+13-2

What and why

  • Mark value, attribute, box and enabled-state reads as by design: e2e reads once and reports LOCATOR_NOT_FOUND when nothing matches, while Playwright waits for a match. Show an assertion before reading an element that appears later.
  • Keep isVisible() and isHidden() together as immediate reads in both frameworks. Addresses only item 7 of #1020; the other items remain open. No runtime change.

Verified

Ran it locally: yes

  • Built CLI on the local testbed, real Chromium 153: all five reads report LOCATOR_NOT_FOUND for a missing element, visibility reads return false/true, and the guide's assert-before-read example succeeds for an input inserted later. The pinned Playwright 1.63.0 waits for that input in all five reads.
✓ reads return the current absence and assertions wait before a read
Tests 1 passed
  • Rendered the main and changed guide with Mintlify on Node 24.21.0 and inspected both screenshots. Screenshots remain local because the installed gh 2.87.2 lacks --attach.
mainthis branch
Waiting and immediate reads share a same rowWaiting differences are by design, visibility reads remain same, and an assertion precedes the example read
  • pnpm check passed. pnpm test: 4,245 passed, 2 existing skips, plus 17 script tests passed. Full built testbed: 77 passed, 1 existing skip. Independent fresh-context review found no blocking issues. No live model calls; web/mobile benchmarks and Firefox/WebKit were not run for this docs-only change.

Upstream CI has not run: the spec, docs, benchmark and mobile workflows require maintainer approval for this fork.

Checklist

  • Docs-only change; no changeset required.
  • No breaking change.
  • Migration guide updated; existing consumer instructions are unchanged.
  • No public type or wire contract change.
  • No engine contract change.