openspec-playwright 0.1.26 → 0.1.28

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

@@ -2,15 +2,32 @@
 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.1"
+  version: "2.3"
 ---
 
-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.
+## Input
+
+- **Change name**: `/opsx:e2e <name>` or auto-detected from context
+- **Specs**: `openspec/changes/<name>/specs/*.md`
+- **Credentials**: `E2E_USERNAME` + `E2E_PASSWORD` env vars
+
+## Output
+
+- **Test file**: `tests/playwright/<name>.spec.ts`
+- **Auth setup**: `tests/playwright/auth.setup.ts` (if auth required)
+- **Report**: `openspec/reports/playwright-e2e-<name>-<timestamp>.md`
+- **Test plan**: `openspec/changes/<name>/specs/playwright/test-plan.md`
+
+## 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).
 
-**Architecture**: Schema owns templates. CLI handles execution. Skill handles cognitive work.
+**Schema owns templates. CLI handles execution. Skill handles cognitive work.**
 
 ## Steps
 
@@ -140,7 +157,27 @@ 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.
 
@@ -159,9 +196,54 @@ Read the report at `openspec/reports/playwright-e2e-<name>-<timestamp>.md`.
 - 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.
+## Output Format
 
----
+### Report Structure (`openspec/reports/playwright-e2e-<name>-<timestamp>.md`)
+
+```
+# Playwright E2E Report — <name>
+
+## Summary
+| Tests | Passed | Failed | Duration | Status |
+|-------|--------|--------|----------|--------|
+| N     | N      | N      | Xm Xs    | ✅/❌   |
+
+## Results
+
+### Passed
+| Test | Duration | Notes |
+|------|----------|-------|
+| ...  | ...      | ...   |
+
+### Failed
+| Test | Error | Recommendation |
+|------|-------|----------------|
+| ...  | ...   | file:line — fix |
+
+## Auto-Heal Log
+- Attempt N: selector fix → result
+
+## Coverage
+- [x] Requirement 1
+- [ ] Requirement 2 (unverified)
+```
+
+### Updated tasks.md
+```
+- [x] Implement feature X ✅ Verified via Playwright E2E (2026-03-28)
+```
+
+## Graceful Degradation
+
+| Scenario | Behavior |
+|----------|----------|
+| No specs found | Stop with info message — E2E requires specs |
+| No auth required | Skip auth setup entirely |
+| test-plan.md exists | Read and use it — never regenerate |
+| auth.setup.ts exists | Verify format — update only if stale |
+| playwright.config.ts exists | Read and preserve all fields — add only missing |
+| Test fails (selector) | Healer: snapshot → fix → re-run, cap at 3 attempts |
+| Test fails (app bug) | Report as failed with recommendation |
 
 ## Verification Heuristics
 

package/package.json

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

package/release-notes.md

@@ -1,5 +1,5 @@
 ## What's Changed
 
-- feat(skill): LLM-driven test generation and tasks.md integration
+- feat(skill): align SKILL.md with OpenSpec format (v2.3)
 
-**Full Changelog**: https://github.com/wxhou/openspec-playwright/releases/tag/v0.1.26
+**Full Changelog**: https://github.com/wxhou/openspec-playwright/releases/tag/v0.1.28