SKILL.md

v1.0.0 · 2035 B · text/markdown

---
name: playwright-webapp-testing
description: Use to verify a running web app actually works - drives a real Playwright browser against the live app instead of relying on unit tests alone
---

# Playwright Webapp Testing

Unit and integration tests verify functions and API routes; they don't
prove the rendered app actually works for a real browser session. This
skill drives a real (optionally headless) browser against the running app.

## Core loop

1. Start the app locally if it isn't already running.
2. Navigate to the flow under test with a real Playwright session.
3. Interact the way a user would — click, type, wait for real navigation
and network responses, not artificial sleeps.
4. Assert on what's actually rendered (visible text, element state), not
on internal implementation details.
5. Capture a screenshot (and a trace/video on failure) so a failure is
diagnosable without re-running interactively.

## What to prioritize testing this way

- The golden path of any new or changed feature, end to end.
- Cross-page flows unit tests can't see (navigate → submit → confirm state
persisted → reload → confirm it's still there).
- Anything unit tests mock away that could still be broken in reality:
actual network calls, actual auth redirects, actual responsive layout.

## Practical notes

- Prefer real interactions over mocked network responses when testing the
golden path; reserve request interception for deliberately testing error
states (a 500, a timeout) that are hard to trigger for real.
- Use device-emulation presets to check that critical flows aren't broken
on mobile viewports, not just desktop.
- A screenshot alone doesn't prove correctness — pair visual capture with
an explicit assertion on the specific thing being verified.

## When not to reach for this

Don't replace fast unit tests with slow browser tests for logic that
doesn't need a real DOM — use this for what only a real browser session can
verify, and keep the rest at the unit/integration level.