docs: replace Playwright MCP workflow with Playwright Test Agents

Switch E2E testing to use Playwright Test Agents (planner, generator,
healer) instead of manual Playwright MCP workflow. Remove data-testid
requirements from coding standards — use semantic selectors instead.

Author: nshen

docs/coding-standards.md

@@ -27,26 +27,6 @@ try {
 }
 ```
 
-## Test Attributes
-
-All interactive elements must have `data-testid` for E2E testing. Non-interactive display elements do not need it.
-
-**What needs `data-testid`**: buttons, inputs, links, form controls, list containers, dialog triggers, dropdowns.
-
-**Naming convention**: `<context>-<element>`, lowercase with `-`:
-
-```tsx
-<Button data-testid="create-user-btn">Create</Button>
-<Input data-testid="user-name-input" />
-<ul data-testid="user-list">
-  <li data-testid={`user-item-${user.id}`}>...</li>
-</ul>
-<Dialog>
-  <DialogTrigger data-testid="edit-user-dialog-trigger" />
-  <DialogContent data-testid="edit-user-dialog">...</DialogContent>
-</Dialog>
-```
-
 ## Code Quality
 
 - Linting and formatting: Biome.

docs/testing.md

@@ -21,18 +21,30 @@ pnpm --filter <package> test          # Run tests for a specific package
 pnpm --filter <package> test --watch  # Watch mode
 ```
 
-## E2E Tests — AI-Assisted Playwright Workflow
+## E2E Tests — Playwright Test Agents
 
-E2E tests follow a two-phase AI-assisted workflow using [Playwright MCP](https://github.com/microsoft/playwright-mcp).
+E2E tests use [Playwright Test Agents](https://playwright.dev/docs/test-agents) for AI-assisted test creation, generation, and self-healing.
 
-### Prerequisites
+### Setup
 
-- All interactive elements must have `data-testid` attributes (see `docs/coding-standards.md`)
-- Playwright tests use `page.getByTestId()` for element selection — stable across UI refactors
+Initialize Playwright Test Agents in the project:
 
-### Phase 1: Write Test Specs as Natural Language
+```bash
+npx playwright init-agents --loop=claude
+```
+
+This sets up agent definitions under `.github/` with all necessary MCP tools and instructions — no separate skills installation required. Regenerate after Playwright updates to access new tools.
+
+### Workflow
+
+#### Step 1: Planner Agent — Create Test Specs
+
+Based on user descriptions or PRD documents, use the **Planner Agent** to explore the running app and produce markdown test plans:
 
-Create `.md` files describing user scenarios from the user's perspective:
+- Input: user scenario description or PRD document
+- Output: structured markdown spec file under `e2e/specs/`
+
+The planner navigates the app, discovers page structure, and writes human-readable test plans with steps and expected results.
 
 ```markdown
 <!-- e2e/specs/user-crud.md -->
@@ -49,50 +61,41 @@ Create `.md` files describing user scenarios from the user's perspective:
 9. Verify the user is removed from the list
 ```
 
-### Phase 2: Generate Playwright Tests via Playwright MCP
+#### Step 2: Generator Agent — Create Test Files
 
-1. AI reads the `.md` spec file
-2. AI uses **Playwright MCP** to navigate the running app, following the spec steps:
-   - Navigate to pages, click elements, fill forms, observe results
-   - Discover `data-testid` attributes and page structure via Playwright's built-in selectors (`getByTestId`, `getByRole`, etc.)
-3. AI generates a Playwright test file using the observed selectors:
+Use the **Generator Agent** to transform markdown specs into executable Playwright test files:
 
-```
-e2e/specs/user-crud.md        ← Human-written scenario
-e2e/tests/user-crud.spec.ts   ← AI-generated Playwright test
-```
+- Input: markdown spec from `e2e/specs/`
+- Output: Playwright test file under `e2e/tests/`
+- The generator verifies selectors and assertions live against the running app using semantic selectors (`getByRole`, `getByText`, `getByLabel`, `getByPlaceholder`)
 
-Example generated output:
-
-```ts
-test('user CRUD operations', async ({ page }) => {
-  await page.goto('/playground/components/users');
-  await page.getByTestId('user-name-input').fill('Test User');
-  await page.getByTestId('user-email-input').fill('test@example.com');
-  await page.getByTestId('create-user-btn').click();
-  await expect(page.getByText('Test User')).toBeVisible();
-  // ...
-});
-```
+#### Step 3: Healer Agent — Run & Fix Tests
+
+Use the **Healer Agent** to execute tests and automatically repair failures:
+
+- Replays failing steps and inspects the current UI
+- Suggests patches (locator updates, wait adjustments, data fixes)
+- Re-runs until passing or guardrails activate
 
 ### File Structure
 
 ```
 e2e/
-├── specs/                     ← Human-written natural language scenarios
+├── specs/                     ← Markdown test plans (planner output)
 │   ├── user-crud.md
 │   ├── file-upload.md
 │   └── ssr-demo.md
-└── tests/                     ← AI-generated Playwright tests
+└── tests/                     ← Playwright test files (generator output)
+    ├── seed.spec.ts           ← Bootstrap environment
     ├── user-crud.spec.ts
     ├── file-upload.spec.ts
     └── ssr-demo.spec.ts
 ```
 
 ### Key Principles
 
-- **Specs are the source of truth** — humans write and maintain the `.md` files
-- **`data-testid` is the contract** — UI can refactor freely as long as testids stay stable
+- **Specs are the source of truth** — review and maintain the markdown plans
+- **Use semantic selectors** — prefer `getByRole`, `getByText`, `getByLabel` over fragile CSS selectors or testids
 - **Generated tests run without AI** — standard Playwright in CI, no API keys needed
-- **Regenerate, don't hand-edit** — when UI changes, re-run Playwright MCP observation to update tests
+- **Use healer to fix flaky tests** — don't hand-edit generated tests, let the healer agent repair them
 - Keep specs focused: one user flow per file