openspec-playwright 0.1.29 → 0.1.31

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

@@ -7,7 +7,7 @@ compatibility: Requires openspec CLI, Playwright (with browsers installed), and
 **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.4"
+  version: "2.6"
 ---
 
 ## Input
@@ -194,16 +194,31 @@ If tests fail → analyze failures, use **Playwright MCP tools** to inspect UI s
 | `browser_run_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 `browser_navigate`
-3. Take a `browser_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.
+1. Read the failing test → identify failure type by checking error message and console output
+2. Classify the failure:
+
+| Failure type | Signal | Action |
+|-------------|--------|--------|
+| **Network/backend** | `fetch failed`, `net::ERR`, 5xx, timeout | `browser_console_messages` → add `test.skip()` + report "backend error" |
+| **Selector changed** | Element not found, page loaded | `browser_snapshot` → fix selector → re-run |
+| **Assertion mismatch** | Element exists, wrong content/value | `browser_snapshot` → compare → fix assertion → re-run |
+| **Timing issue** | `waitFor` timeout, race condition | Adjust wait strategy → re-run |
+
+3. **Attempt heal** (up to 3 times):
+   - Apply fix using `browser_snapshot` (prefer `getByRole`, `getByLabel`, `getByText`)
+   - Re-run: `openspec-pw run <name> --project=<role>`
+4. **After 3 failed attempts**, collect evidence:
+
+   **Evidence checklist** (in order, stop at first match):
+   | Check | Signal | Decision |
+   |-------|--------|----------|
+   | `browser_console_messages` | ERROR-level messages present | App bug → `test.skip()` + report "console error" |
+   | `browser_snapshot` | Target element missing from DOM | App bug → `test.skip()` + report "element missing" |
+   | `browser_snapshot` | Element exists, no errors | Test bug → report recommendation |
+
+   - **App bug**: `test.skip('app bug — reason: <signal>')` + detailed report entry
+   - **Test bug**: report with "likely selector change, verify manually at file:line"
+   - Do NOT retry after evidence checklist — evidence is conclusive
 
 ### 9. Report results
 
@@ -267,8 +282,10 @@ Read the report at `openspec/reports/playwright-e2e-<name>-<timestamp>.md`.
 | 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 |
+| Test fails (network/backend) | Skip with `test.skip()` — backend/app error, not test fragility |
+| Test fails (selector) | Healer: snapshot → fix selector → re-run (≤3 attempts) |
+| Test fails (assertion) | Healer: snapshot → fix assertion → re-run (≤3 attempts) |
+| 3 heal attempts failed | Confirm root cause → if app bug: `test.skip()` + report; if unclear: report with recommendation |
 
 ## Verification Heuristics
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openspec-playwright",
-  "version": "0.1.29",
+  "version": "0.1.31",
   "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: add MCP version sync for Healer tools (init + update)
+- feat(skill): add evidence checklist for Healer skip decision (v2.6)
 
-**Full Changelog**: https://github.com/wxhou/openspec-playwright/releases/tag/v0.1.29
+**Full Changelog**: https://github.com/wxhou/openspec-playwright/releases/tag/v0.1.31