openspec-playwright 0.2.7 → 0.2.9

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

@@ -5,7 +5,7 @@ license: MIT
 compatibility: Requires openspec CLI, Playwright (with browsers installed), and @playwright/mcp (globally installed via `claude mcp add playwright npx @playwright/mcp@latest`).
 metadata:
   author: openspec-playwright
-  version: "2.19"
+  version: "2.22"
 ---
 
 ## Input
@@ -210,6 +210,32 @@ browser_navigate → browser_console_messages → browser_snapshot → browser_t
 | Auth required, no credentials | Missing auth setup                | Continue — skip protected routes, explore login page                                          |
 | Suspicious network request     | API returned 4xx/5xx             | Continue — mark `⚠️ API error: <endpoint> returned <code>` in app-exploration.md               |
 
+**Redirect / Refresh loop detection** — run after initial navigate:
+
+```
+// 1. Initial capture
+await browser_navigate(`${BASE_URL}/<route>`);
+await new Promise(r => setTimeout(r, 1500)); // wait for SPA hydration
+const url1 = await browser_evaluate(() => window.location.href);
+
+// 2. Observe stability
+await new Promise(r => setTimeout(r, 2000));
+const url2 = await browser_evaluate(() => window.location.href);
+const msgs = await browser_console_messages();
+
+// 3. Detect
+if (url1 !== url2) {
+  → ❌ URL changed — redirect loop (ERR_TOO_MANY_REDIRECTS)
+  → Is this route protected without valid auth.storageState?
+    → Yes → auth.setup.ts is broken → fix auth first
+    → No → App middleware bug → mark route ❌ skip, record as App Bug
+}
+if (msgs.filter(m => m.type === 'warning' || m.type === 'error').length > 10) {
+  → ❌ Excessive console errors — page refresh / JS crash loop
+  → Mark route ❌ skip, record as App Bug
+}
+```
+
 **Network monitoring**: After navigating, use `browser_network_requests` to check for failed API calls. Failed requests (status ≥ 400) on a route indicate an API/backend issue — record in `app-exploration.md` for reference.
 
 **For guest routes** (no auth):
@@ -323,7 +349,7 @@ After writing `app-exploration.md`, extract **project-level shared knowledge** a
 | Common Selector Patterns | New patterns discovered that apply across routes                          |
 | SPA Routing              | SPA framework, routing behavior                                           |
 | Project Conventions      | BASE_URL, auth method, multi-user roles                                   |
-| Selector Fixes           | Healed selectors (see Step 9) — route, old selector, new selector, reason |
+| Selector Fixes           | Healed selectors (see Step 9) — route, old → new selector, reason, date |
 
 Append only new/changed items — preserve existing content.
 
@@ -634,6 +660,10 @@ If tests fail → use Playwright MCP tools to inspect UI, fix selectors, re-run.
 | `browser_take_screenshot`  | Visually compare before/after fixes             |
 | `browser_run_code`         | Execute custom fix logic (optional)             |
 
+**Before Phase 1 — check accumulated knowledge:**
+
+Read `tests/playwright/app-knowledge.md` → **Selector Fixes** table. If the failing test's selector or route matches a known fix, use it directly (skip Phase 2). If partial match → use as the top candidate in Phase 2 Step 5a. If file does not exist → skip.
+
 **Healer — Phase 1: Triage**
 
 When a test fails, classify before attempting repair.
@@ -665,6 +695,8 @@ Proceed with individual Triage only for tests NOT in a batch failure group.
 | **Network/Backend** | `net::ERR`, 4xx/5xx in console/network | **App Bug** | `test.skip()` + record in `app-bug-registry.md` |
 | **JS Runtime Error** | Console error (non-network) | **App Bug** | `test.skip()` + record in `app-bug-registry.md` |
 | **Auth Expired** | Redirected to login mid-test | **Flaky** | Re-run auth.setup → re-run |
+| **Redirect Loop** | `ERR_TOO_MANY_REDIRECTS`, URL keeps changing on each snapshot | **App Bug** | Check auth first (see Step 4.2 loop detection). If auth is the cause → re-run auth. Otherwise → `test.skip()` + App Bug Registry |
+| **Page Refresh Loop** | Excessive console errors (>10) after navigation, page unstable | **App Bug** | `test.skip()` + record in App Bug Registry |
 | **Selector Not Found** | Element not found | **Test Bug** | → Phase 2 Healer |
 | **Assertion Mismatch** | Wrong content/value | **Ambiguous** | → Phase 2 Healer |
 | **Timeout** | waitFor/evaluate timeout | **Flaky** | Retry isolated: `openspec-pw run <name> --grep "<test-name>"` (1×, not counted in heal attempts). If it passes isolated but fails in suite → **RAFT**. If it consistently times out → check framework: React 19 / Next.js App Router: add `page.waitForLoadState('networkidle')`. Vue/Angular/React 18 / Plain JS / jQuery: use `waitForSelector(targetElement)` instead of timeout tuning. |
@@ -733,9 +765,29 @@ After Triage classifies failure as "Test Bug" or "Ambiguous":
    - Data values differ (e.g., expected "¥1000" but got "¥999" → **Phase 3**, could be rounding, discount, or calculation bug)
    - Missing elements after interaction (e.g., "after creating order, success message should appear" → no message → **Phase 3**)
 
-5. If selector issue → find equivalent stable selector from snapshot
+5. If selector issue → generate candidate list, then select:
+
+   **5a. Extract candidates** — identify the target element from the failing test's assertion, then from the snapshot list all selectors for that element:
+
+   First check `app-knowledge.md` → **Common Selector Patterns** for project-specific conventions (e.g., if project uses Tailwind and `.btn-primary` is listed as preferred → treat it as Fair or higher, not Fragile).
+
+   ```
+   Target: <element from failing assertion, e.g. "button with text 'Submit'">
+   Candidates (stable → fragile):
+   - getByRole(button, { name: 'Submit' })   ← Stable (semantic)
+   - getByText('Submit')                       ← Fair (unique text)
+   - getByLabel('Email')                       ← Fair (form fields)
+   - locator('#submit')                         ← Fair (id attribute)
+   - locator('.btn-primary')                   ← Fragile (style class) — upgrade if listed in Common Selector Patterns
+   - locator('button:nth-child(3)')            ← Fragile (DOM order)
+   ```
+
+   Stability: `getByRole` > `getByText`/`getByLabel` > `locator('#id')` > `locator('.class')` > `locator('nth-child')`. Upgrade stability if `app-knowledge.md` → **Common Selector Patterns** explicitly lists the selector as preferred for this project.
+
+   **5b. Select top candidate** — pick the highest-stability candidate that matches the target. Output: `SELECTED: <selector> — reason: <why this one>`.
+
 6. Apply fix → re-run **only that test** (attempt 1/3)
-7. If healed → append to `app-knowledge.md` → **Selector Fixes** table (route, old → new selector, reason)
+7. If healed → append to `app-knowledge.md` → **Selector Fixes** table (route, old → new selector, reason, date)
 
 **Element Missing handling (when browser_snapshot shows element not found):**
 
@@ -844,7 +896,7 @@ Report template: `.claude/skills/openspec-e2e/templates/report.md`
 | ------- | ------- |
 | No specs / app-exploration.md missing (change mode) | **STOP** |
 | JS errors or HTTP 5xx during exploration | **STOP** → user fixes app → re-run `/opsx:e2e <name>` to re-explore from Step 4 |
-| Sitemap fails ("all" mode) | Continue with homepage links fallback |
+| Redirect loop / page refresh loop during exploration | **App Bug** — **STOP** → check auth.setup.ts first (common cause). If auth is valid → app middleware/cookie bug → mark route skipped, record in App Bug Registry. Re-run exploration after fix. |
 | File already exists (app-exploration, test-plan, app-all.spec.ts, Page Objects) | Read and use — never regenerate |
 | Test fails (network/backend) | **App Bug** — `test.skip()` + record in `app-bug-registry.md` |
 | Test fails (selector/assertion) | **Test Bug/Ambiguous** — Healer Phase 1→2 (≤3 attempts) |

package/package.json

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