openspec-playwright 0.1.25 → 0.1.27

package/.claude/skills/openspec-e2e/SKILL.md

@@ -2,10 +2,12 @@
 name: openspec-e2e
 description: Run Playwright E2E verification for an OpenSpec change. Use when the user wants to validate that the implementation works end-to-end by running Playwright tests generated from the specs.
 license: MIT
-compatibility: Requires openspec CLI, Playwright (with browsers installed), and @playwright/mcp (globally installed via claude mcp add).
+compatibility: Requires openspec CLI, Playwright (with browsers installed), and @playwright/mcp (globally installed via `claude mcp add playwright npx @playwright/mcp@latest`).
+
+**Architecture**: Uses CLI + SKILLs (not `init-agents`). This follows Playwright's recommended approach for coding agents — CLI is more token-efficient than loading MCP tool schemas into context. MCP is used only for Healer (UI inspection on failure).
 metadata:
   author: openspec-playwright
-  version: "2.0"
+  version: "2.2"
 ---
 
 Run Playwright E2E verification for an OpenSpec change. This skill reads specs from `openspec/changes/<name>/specs/`, generates test files, detects auth requirements, and delegates test execution to the `openspec-pw run` CLI.
@@ -56,16 +58,47 @@ Create `openspec/changes/<name>/specs/playwright/test-plan.md` by:
 
 **Idempotency**: If test-plan.md already exists → read it, use it, do NOT regenerate unless user explicitly asks.
 
-### 4. Generate test file
+### 4. Generate test file (LLM-driven)
+
+Use your file writing capability to create `tests/playwright/<name>.spec.ts`.
+
+**Read inputs first**:
+- `openspec/changes/<name>/specs/playwright/test-plan.md` — test cases with `@role` and `@auth` tags
+- `tests/playwright/seed.spec.ts` — code pattern, BASE_URL, and page object structure
+
+**Generate Playwright code** for each test case from test-plan.md:
+- Follow the same structure as `seed.spec.ts`
+- Prefer `data-testid` selectors; fallback to `input[name="..."]` or semantic selectors
+- Include **happy path** AND **error/edge cases**
+- Use `test.describe(...)` for grouping related tests
+- Each test: `test('描述性名称', async ({ page }) => { ... })`
+- Add `@project(user)` / `@project(admin)` on role-specific tests
+
+**Example pattern** (from seed.spec.ts):
+```typescript
+import { test, expect } from '@playwright/test';
+
+const BASE_URL = process.env.BASE_URL || 'http://localhost:3000';
+
+test.describe('Feature Name', () => {
+  test('happy path - action succeeds', async ({ page }) => {
+    await page.goto(`${BASE_URL}/path`);
+    await page.getByTestId('element').click();
+    await expect(page.getByTestId('result')).toBeVisible();
+  });
+
+  test('error case - invalid input shows message', async ({ page }) => {
+    await page.goto(`${BASE_URL}/path`);
+    await page.getByTestId('input').fill('invalid');
+    await page.getByTestId('submit').click();
+    await expect(page.getByTestId('error')).toContainText('Error text');
+  });
+});
+```
 
-Create `tests/playwright/<name>.spec.ts`:
-- Follow the page object pattern from `tests/playwright/seed.spec.ts`
-- Prefer `data-testid` selectors, fall back to semantic selectors
-- Each test maps to one test case from the test-plan
-- Use `@project(admin)` / `@project(user)` for role-specific tests
-- Cover happy path AND key error paths
+**Write the file** using the Write tool. If the file already exists → diff against test-plan, add only missing test cases, preserve existing implementations.
 
-**Idempotency**: If test file exists → diff against test-plan, add only missing test cases, preserve existing implementations.
+**Selector guidance**: If no `data-testid` exists in the app, prefer `getByRole`, `getByLabel`, `getByText` over fragile selectors like CSS paths.
 
 ### 5. Configure auth (if required)
 
@@ -109,16 +142,46 @@ The CLI handles:
 - Port mismatch detection
 - Report generation at `openspec/reports/playwright-e2e-<name>-<timestamp>.md`
 
-If tests fail → analyze failures, use Playwright MCP tools to inspect UI state, fix selectors in the test file, and re-run.
+If tests fail → analyze failures, use **Playwright MCP tools** to inspect UI state, fix selectors in the test file, and re-run.
+
+**Healer MCP tools** (in order of use):
+
+| Tool | Purpose |
+|------|---------|
+| `Navigate to a URL` | Go to the failing test's page |
+| `Page snapshot` | Get page structure to find equivalent selectors |
+| `Get console messages` | Diagnose JS errors that may cause failures |
+| `Take a screenshot` | Visually compare before/after fixes |
+| `Run Playwright code` | Execute custom fix logic (optional) |
+
+**Healer workflow**:
+1. Read the failing test file — identify the broken selector or assertion
+2. Navigate to the target page with `Navigate to a URL`
+3. Take a `Page snapshot` — find an equivalent stable selector
+4. Fix the selector in the test file using the Edit tool
+5. Re-run: `openspec-pw run <name>`
+6. Repeat until pass or 3 attempts reached
+
+**Note**: For selector fixes, prefer `getByRole`, `getByLabel`, `getByText` over CSS paths. For structural issues (wrong page content), update the assertion in the test file.
 
 **Cap auto-heal attempts at 3** to prevent infinite loops.
 
 ### 8. Report results
 
-Read the report generated by `openspec-pw run` and present it to the user:
+Read the report at `openspec/reports/playwright-e2e-<name>-<timestamp>.md`.
+
+**Present results to user**:
 - Summary table (tests run, passed, failed, duration, final status)
 - Any auto-heal notes
-- Recommendations for failed tests (with specific file:line references)
+- Recommendations for failed tests (with specific `file:line` references)
+
+**Update tasks.md** (if all tests pass):
+- Read `openspec/changes/<name>/tasks.md`
+- Find tasks related to E2E testing (look for `[ ]` items mentioning "test", "e2e", "playwright", "verify")
+- Append a verification note: e.g. `✅ Verified via Playwright E2E (<timestamp>)`
+- Write the updated content back using the Edit tool
+
+**If tests fail**: Suggest which spec items remain unverified and what needs fixing.
 
 ---
 
@@ -133,6 +196,7 @@ Read the report generated by `openspec-pw run` and present it to the user:
 
 - Read specs from `openspec/changes/<name>/specs/` as source of truth
 - Do NOT generate tests that contradict the specs
+- **DO generate real, runnable Playwright test code** — not placeholders or TODO comments. Every test case in test-plan.md must produce an actual `test(...)` block.
 - Do NOT overwrite files outside: `specs/playwright/`, `tests/playwright/`, `openspec/reports/`, `playwright.config.ts`, `tests/auth.setup.ts`
 - Cap auto-heal at 3 attempts
 - If no change specified → always ask user to select

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openspec-playwright",
-  "version": "0.1.25",
+  "version": "0.1.27",
   "description": "OpenSpec + Playwright E2E verification setup tool for Claude Code",
   "type": "module",
   "bin": {

package/release-notes.md

@@ -1,5 +1,5 @@
 ## What's Changed
 
-- fix: playwright.config.ts searches subdirs for package.json
+- feat(skill): document Healer MCP tools and architecture rationale
 
-**Full Changelog**: https://github.com/wxhou/openspec-playwright/releases/tag/v0.1.25
+**Full Changelog**: https://github.com/wxhou/openspec-playwright/releases/tag/v0.1.27