Use readable Playwright page fixtures

[mmkal]

Summary

Make Middlewright's checked-in Playwright examples read like normal Playwright tests:

• call the plugin-enhanced page page, with the original fixture aliased to basePage
• rely on locator actions and waits for UI state instead of redundant expect calls
• keep value assertions for metadata, timings, paths, and other non-UI results
• update demo snippets so new users copy the preferred style

No public API or runtime behavior changes.

Review notes

The first commit records scope and assumptions. The FFmpeg boundary check now samples the first stable decoded frame because removing a redundant locator matcher also removes its incidental startup delay.

Verification

• pnpm typecheck
• pnpm build
• CI=1 pnpm test — 101 passed, 4 skipped, 1 flaky test passed on retry
• GitHub Actions — 101 passed, 4 skipped
• pnpm exec playwright test spec/todo-app.spec.ts
• focused FFmpeg boundary test passed 3/3 concurrently

Visual baseline

Rendered spec/todo-app.spec.ts:

video-rendered.webm

Codex session: 019fcc8a-c39a-7940-8df7-85cb34080ca3

---

Note

Low Risk
Test and documentation-only changes with no runtime or API modifications; risk is limited to spec behavior if observation waits were mis-scoped.

Overview
Aligns checked-in specs, README snippets, and demo code with the documented Playwright style: the Playwright fixture is basePage, the plugin-wrapped handle is page (replacing plugged), and UI outcomes use locator actions and waitFor() instead of redundant expect matchers.

expect remains for metadata, timings, paths, and other non-UI values. Some video-mode specs use basePage for observation-only waits so checks do not become recorded middleware actions on the enhanced page. writing-middlewright-tests.md and the completed task note mirror the same conventions; no public addPlugins API changes.

^{Reviewed by Cursor Bugbot for commit f90e921. Bugbot is set up for automated code reviews on this repo. Configure here.}

[pkg-pr-new]

Open in StackBlitz

pnpm add https://pkg.pr.new/middlewright@21

commit: f90e921

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 7ab36b7. Configure here.}