---
name: playwright-101
description: Basic Playwright setup, running, debugging, and troubleshooting. Use when Codex needs to run Playwright tests, write or fix Playwright tests, diagnose common Playwright failures (missing fixtures, auth, server not running), or explain Playwright usage at a 101 level.
---
# Playwright 101
## Overview
Run and debug Playwright tests reliably, with a minimal checklist for setup and a short troubleshooting playbook for common failures.
## Quick Start (Local)
1. Ensure the app server is running in another terminal (per repo instructions).
2. Install browsers once if needed:
```bash
cd frontend
npx playwright install
```
3. Run the full suite:
```bash
cd frontend
npx playwright test
```
## Common Tasks
Run a single file:
```bash
cd frontend
npx playwright test tests/budget/budget-end-user.spec.ts
```
Run a single test by name:
```bash
cd frontend
npx playwright test -g "Project manager views empty budget state"
```
Debug interactively:
```bash
cd frontend
npx playwright test --debug
```
Open the report:
```bash
cd frontend
npx playwright show-report
```
## Troubleshooting Checklist
- **Server not running**: Start the app server first; verify `baseURL` in `playwright.config.ts` matches.
- **Missing fixtures**: Confirm test imports use the project fixtures entrypoint (e.g., `../fixtures/index`), not an unintended file with a similar name.
- **Auth failures**: Ensure auth setup test passes and storage state path matches config.
- **Empty data**: Many tests assume seeded data; verify the seed script or local DB is populated.
- **Flaky selectors**: Prefer `getByRole` and stable data attributes; avoid text-only selectors when UI is dynamic.
## References
See `references/playwright-101.md` for more commands and patterns.
