openspec-playwright 0.1.58 → 0.1.60

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.9"
+  version: "2.10"
 ---
 
 ## Input
@@ -32,6 +32,28 @@ Two modes, same pipeline:
 
 Both modes update `app-knowledge.md` and `app-exploration.md`. All `.spec.ts` files run together as regression suite.
 
+## Testing principles
+
+**UI first** — Test every user flow through the browser UI. E2E validates that users can accomplish tasks in the real interface, not just that the backend responds correctly.
+
+```
+用户操作 → 浏览器 UI → 后端 → 数据库 → UI 反馈
+```
+
+**API only as fallback** — Use `page.request` only when UI genuinely cannot cover the scenario:
+- Triggering HTTP 5xx/4xx error responses (hard to reach via UI)
+- Edge cases requiring pre-condition data that UI cannot set up
+- Cases where Step 4 exploration confirmed no UI element exists
+
+**Decision rule**:
+```
+Can this be tested through the UI?
+  → Yes → page.getByRole/ByLabel/ByText + click/fill/type + assert UI
+  → No  → record reason → use page.request
+```
+
+**Never use API calls to replace routine UI flows.** If a test completes in < 200ms, it is almost certainly using `page.request` instead of real UI interactions.
+
 ## Steps
 
 ### 1. Select the change or mode
@@ -181,6 +203,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 |
 
 Append only new/changed items — preserve existing content.
 
@@ -230,44 +253,58 @@ Template: `openspec/schemas/playwright-e2e/templates/test-plan.md`
 - Each test: `test('描述性名称', async ({ page }) => { ... })`
 - Prefer `data-testid` selectors (see 4.3 table)
 
-**Code examples — same for both modes:**
+**Code examples — UI first:**
 
 ```typescript
-// 🚫 False Pass — never silently skip when element is missing
+// ✅ UI 测试 — 用户在界面上的真实操作
+await page.goto(`${BASE_URL}/orders`);
+await page.getByRole('button', { name: '新建订单' }).click();
+await page.getByLabel('订单名称').fill('Test Order');
+await page.getByRole('button', { name: '提交' }).click();
+await expect(page.getByText('订单创建成功')).toBeVisible();
+
+// ✅ Error path — 通过 UI 触发错误
+await page.goto(`${BASE_URL}/orders`);
+await page.getByRole('button', { name: '新建订单' }).click();
+await page.getByRole('button', { name: '提交' }).click();
+await expect(page.getByRole('alert')).toContainText('名称不能为空');
+
+// ✅ API fallback — 仅在 UI 无法触发时使用
+const res = await page.request.get(`${BASE_URL}/api/orders/99999`);
+expect(res.status()).toBe(404);
+```
+
+```typescript
+// 🚫 False Pass — 元素不存在时静默跳过
 if (await btn.isVisible().catch(() => false)) { ... }
+
 // ✅ CORRECT
 await expect(page.getByRole('button', { name: '取消' })).toBeVisible();
 
-// 🚫 Auth guard — test with FRESH browser context
-test('redirects unauthenticated user to login', async ({ browser }) => {
-  const freshPage = await browser.newContext().newPage();
-  await freshPage.goto(`${BASE_URL}/dashboard`);
-  await expect(freshPage).toHaveURL(/login|auth/);
-});
+// 🚫 用 API 替代 UI — 失去了端到端的意义
+const res = await page.request.post(`${BASE_URL}/api/login`, { data: credentials });
 
-// ✅ API calls — use page.request directly
-const res = await page.request.get(`${BASE_URL}/api/data`);
-expect(res.status()).toBe(200);
+// ✅ CORRECT — 通过 UI 登录
+await page.goto(`${BASE_URL}/login`);
+await page.getByLabel('邮箱').fill(process.env.E2E_USERNAME);
+await page.getByLabel('密码').fill(process.env.E2E_PASSWORD);
+await page.getByRole('button', { name: '登录' }).click();
+await expect(page).toHaveURL(/dashboard/);
 ```
 
 ```typescript
-// ✅ BrowserContext — close when done
-const context = await browser.newContext();
-await context.close();
-
-// ✅ APIRequestContext — page.request is already one, no cleanup needed
-const res = await page.request.get(`${BASE_URL}/api/data`);
-```
+// ✅ Fresh browser context for auth guard
+test('unauthenticated user redirected to login', async ({ browser }) => {
+  const freshPage = await browser.newContext().newPage();
+  await freshPage.goto(`${BASE_URL}/dashboard`);
+  await expect(freshPage).toHaveURL(/login|auth/);
+});
 
-```typescript
-// ✅ File uploads — use setInputFiles()
+// ✅ File uploads — UI 操作
 await page.locator('input[type="file"]').setInputFiles('/path/to/file.pdf');
-
-// ✅ Form submissions — prefer Playwright locators
-await page.getByRole('button', { name: 'Submit' }).click();
 ```
 
-Always include error path tests: API 500, 404, network timeout, invalid input.
+Always include error path tests: UI validation messages, network failure, invalid input. Use `page.request` only for scenarios confirmed unreachable via UI.
 
 If the file exists → diff against test-plan, add only missing test cases.
 
@@ -321,8 +358,6 @@ The CLI handles: server lifecycle, port mismatch, report generation.
 If tests fail → use Playwright MCP tools to inspect UI, fix selectors, re-run.
 
 **Healer MCP tools** (in order of use):
-<!-- MCP_VERSION: 0.0.68 -->
-
 <!-- MCP_VERSION: 0.0.70 -->
 
 | Tool | Purpose |
@@ -345,7 +380,7 @@ If tests fail → use Playwright MCP tools to inspect UI, fix selectors, re-run.
 | **Timing issue** | `waitFor`/`page.evaluate` timeout | Switch to `request` API or add `waitFor` → re-run |
 | **page.evaluate with fetch** | `fetch` in browser context, CORS errors | Switch to `page.request` API → re-run |
 
-3. **Heal** (≤3 attempts): snapshot → fix → re-run
+3. **Heal** (≤3 attempts): snapshot → fix → re-run. If healed successfully → append to `app-knowledge.md` → **Selector Fixes** table: route, old selector → new selector, reason.
 4. **After 3 failures**: collect evidence checklist → `test.skip()` if app bug, report recommendation if test bug
 
 ### 10. False Pass Detection

package/dist/commands/mcpSync.js

@@ -21,6 +21,13 @@ export function getStoredMcpVersion(skillContent) {
     const end = skillContent.indexOf(' -->', idx);
     return skillContent.slice(idx + MCP_VERSION_MARKER.length, end).trim();
 }
+/** Remove all existing MCP_VERSION comment lines from content */
+function removeMcpVersionMarkers(content) {
+    return content
+        .split('\n')
+        .filter(line => !line.trim().startsWith(MCP_VERSION_MARKER))
+        .join('\n');
+}
 /** Build the Healer tools table markdown */
 function buildHealerTable(version, tools) {
     const rows = tools.map(t => `| \`${t.name}\` | ${t.purpose} |`).join('\n');
@@ -28,14 +35,15 @@ function buildHealerTable(version, tools) {
 }
 /** Replace the Healer tools table in SKILL.md */
 export function updateHealerTable(skillContent, version, tools) {
-    const start = skillContent.indexOf('| Tool | Purpose |');
+    const noMarkers = removeMcpVersionMarkers(skillContent);
+    const start = noMarkers.indexOf('| Tool | Purpose |');
     if (start === -1)
         return skillContent;
-    let end = skillContent.indexOf('\n\n', start);
+    let end = noMarkers.indexOf('\n\n', start);
     if (end === -1)
-        end = skillContent.length;
-    const before = skillContent.slice(0, start);
-    const after = skillContent.slice(end);
+        end = noMarkers.length;
+    const before = noMarkers.slice(0, start);
+    const after = noMarkers.slice(end);
     return before + buildHealerTable(version, tools) + after;
 }
 /** Fetch latest @playwright/mcp version from npm registry */

package/dist/commands/mcpSync.js.map

@@ -1 +1 @@
-{"version":3,"file":"mcpSync.js","sourceRoot":"","sources":["../../src/commands/mcpSync.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AACrC,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,YAAY,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,IAAI,CAAC;AAC7F,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAC5B,OAAO,EAAE,MAAM,EAAE,MAAM,IAAI,CAAC;AAC5B,OAAO,EAAE,SAAS,EAAE,MAAM,MAAM,CAAC;AACjC,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,KAAK,GAAG,MAAM,KAAK,CAAC;AAE3B,MAAM,CAAC,MAAM,kBAAkB,GAAG,mBAAmB,CAAC;AAEtD,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,EAAE,IAAI,EAAE,kBAAkB,EAAE,OAAO,EAAE,+BAA+B,EAAE;IACtE,EAAE,IAAI,EAAE,kBAAkB,EAAE,OAAO,EAAE,iDAAiD,EAAE;IACxF,EAAE,IAAI,EAAE,0BAA0B,EAAE,OAAO,EAAE,4CAA4C,EAAE;IAC3F,EAAE,IAAI,EAAE,yBAAyB,EAAE,OAAO,EAAE,qCAAqC,EAAE;IACnF,EAAE,IAAI,EAAE,kBAAkB,EAAE,OAAO,EAAE,qCAAqC,EAAE;CAC7E,CAAC;AAEF,+CAA+C;AAC/C,MAAM,UAAU,mBAAmB,CAAC,YAAoB;IACtD,MAAM,GAAG,GAAG,YAAY,CAAC,OAAO,CAAC,kBAAkB,CAAC,CAAC;IACrD,IAAI,GAAG,KAAK,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IAC5B,MAAM,GAAG,GAAG,YAAY,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC9C,OAAO,YAAY,CAAC,KAAK,CAAC,GAAG,GAAG,kBAAkB,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;AACzE,CAAC;AAED,4CAA4C;AAC5C,SAAS,gBAAgB,CAAC,OAAe,EAAE,KAA+C;IACxF,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC,IAAI,QAAQ,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC3E,OAAO,GAAG,kBAAkB,IAAI,OAAO,mDAAmD,IAAI,EAAE,CAAC;AACnG,CAAC;AAED,iDAAiD;AACjD,MAAM,UAAU,iBAAiB,CAC/B,YAAoB,EACpB,OAAe,EACf,KAA+C;IAE/C,MAAM,KAAK,GAAG,YAAY,CAAC,OAAO,CAAC,oBAAoB,CAAC,CAAC;IACzD,IAAI,KAAK,KAAK,CAAC,CAAC;QAAE,OAAO,YAAY,CAAC;IACtC,IAAI,GAAG,GAAG,YAAY,CAAC,OAAO,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAC9C,IAAI,GAAG,KAAK,CAAC,CAAC;QAAE,GAAG,GAAG,YAAY,CAAC,MAAM,CAAC;IAE1C,MAAM,MAAM,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;IAC5C,MAAM,KAAK,GAAG,YAAY,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACtC,OAAO,MAAM,GAAG,gBAAgB,CAAC,OAAO,EAAE,KAAK,CAAC,GAAG,KAAK,CAAC;AAC3D,CAAC;AAED,6DAA6D;AAC7D,MAAM,UAAU,mBAAmB;IACjC,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,IAAI,CAAC,yCAAyC,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE;YAClF,IAAI,GAAG,EAAE,CAAC;gBAAC,OAAO,CAAC,IAAI,CAAC,CAAC;gBAAC,OAAO;YAAC,CAAC;YACnC,IAAI,CAAC;gBAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;YAAC,CAAC;YAAC,MAAM,CAAC;gBAAC,OAAO,CAAC,IAAI,CAAC,CAAC;YAAC,CAAC;QACtE,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,SAAS,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;AAElC,yEAAyE;AACzE,KAAK,UAAU,cAAc,CAAC,WAAmB,EAAE,OAAe;IAChE,MAAM,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAClD,SAAS,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACxC,MAAM,GAAG,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC;AACnE,CAAC;AAED,8DAA8D;AAC9D,SAAS,cAAc,CAAC,OAAe;IACrC,MAAM,KAAK,GAA6C,EAAE,CAAC;IAC3D,MAAM,EAAE,GAAG,qDAAqD,CAAC;IACjE,IAAI,CAAC,CAAC;IACN,OAAO,CAAC,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;QACvC,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QACzB,IAAI,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;YAChC,MAAM,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;YAC/C,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;QAChC,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,OAAe;IACjD,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,EAAE,EAAE,mBAAmB,OAAO,EAAE,CAAC,CAAC;IAC5D,IAAI,CAAC;QACH,MAAM,SAAS,CACb,4BAA4B,OAAO,uBAAuB,MAAM,EAAE,EAClE,EAAE,OAAO,EAAE,KAAK,EAAE,CACnB,CAAC;QACF,MAAM,QAAQ,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;QACxG,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,EAAE,CAAC;QACrC,MAAM,WAAW,GAAG,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;QAC9C,MAAM,UAAU,GAAG,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QACvC,MAAM,cAAc,CAAC,WAAW,EAAE,UAAU,CAAC,CAAC;QAC9C,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,EAAE,WAAW,CAAC,CAAC;QACjD,MAAM,OAAO,GAAG,UAAU,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAChF,MAAM,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACjD,OAAO,cAAc,CAAC,OAAO,CAAC,CAAC;IACjC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,SAAiB,EACjB,OAAO,GAAG,KAAK;IAEf,MAAM,aAAa,GAAG,MAAM,mBAAmB,EAAE,CAAC;IAClD,IAAI,CAAC,aAAa,EAAE,CAAC;QACnB,IAAI,OAAO;YAAE,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,oDAAoD,CAAC,CAAC,CAAC;QAC7F,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QAC3B,IAAI,OAAO;YAAE,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,2CAA2C,CAAC,CAAC,CAAC;QAClF,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,YAAY,GAAG,YAAY,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IACtD,MAAM,aAAa,GAAG,mBAAmB,CAAC,YAAY,CAAC,CAAC;IAExD,IAAI,aAAa,KAAK,aAAa,EAAE,CAAC;QACpC,IAAI,OAAO;YAAE,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,6BAA6B,aAAa,GAAG,CAAC,CAAC,CAAC;QACpF,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,OAAO;QAAE,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,qBAAqB,aAAa,IAAI,SAAS,MAAM,aAAa,EAAE,CAAC,CAAC,CAAC;IAE3G,MAAM,KAAK,GAAG,MAAM,aAAa,CAAC,aAAa,CAAC,CAAC;IACjD,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,oBAAoB,CAAC;IAEhE,MAAM,OAAO,GAAG,iBAAiB,CAAC,YAAY,EAAE,aAAa,EAAE,OAAO,CAAC,CAAC;IACxE,aAAa,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IAElC,IAAI,OAAO,EAAE,CAAC;QACZ,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACrB,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,8BAA8B,aAAa,KAAK,KAAK,CAAC,MAAM,SAAS,CAAC,CAAC,CAAC;QAClG,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,8BAA8B,aAAa,gBAAgB,CAAC,CAAC,CAAC;QACxF,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}
+{"version":3,"file":"mcpSync.js","sourceRoot":"","sources":["../../src/commands/mcpSync.ts"],"names":[],"mappings":"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"}

package/dist/utils/mcp-tools.d.ts

@@ -0,0 +1,23 @@
+/** Record of tool name -> purpose description */
+export interface McpTool {
+    name: string;
+    title: string;
+    description: string;
+    purpose: string;
+}
+/**
+ * Download and parse the @playwright/mcp README to extract all browser_* tools.
+ */
+export declare function fetchMcpTools(): McpTool[];
+/**
+ * Update the Healer MCP tools table in SKILL.md.
+ * Only syncs the 5 core Healer tools; all other MCP tools are
+ * general-purpose automation not specific to healing.
+ * Deduplicates by tool name.
+ */
+export declare function updateSkillHealerTable(skillPath: string, tools: McpTool[]): void;
+/**
+ * Main entry point: fetch tools and update SKILL.md.
+ * Call this after installing the skill in init.ts and update.ts.
+ */
+export declare function syncMcpTools(skillPath: string): void;

package/dist/utils/mcp-tools.js

@@ -0,0 +1,130 @@
+/**
+ * Shared utilities for Playwright MCP tool synchronization.
+ * Parses @playwright/mcp README to extract browser_* tool names and
+ * updates the Healer MCP tools table in SKILL.md.
+ */
+import { execSync } from 'child_process';
+import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import chalk from 'chalk';
+/** Cached directory for npm temp files */
+const TMP_DIR = '/tmp/openspec-pw-mcp';
+/**
+ * Get the latest @playwright/mcp version from npm registry.
+ * Falls back to cached README if network fails.
+ */
+function getLatestVersion() {
+    try {
+        const json = execSync('npm show @playwright/mcp version --json', { stdio: 'pipe', encoding: 'utf-8' }).trim();
+        return JSON.parse(json);
+    }
+    catch {
+        return '0.0.68'; // fallback to known version
+    }
+}
+/**
+ * Download and parse the @playwright/mcp README to extract all browser_* tools.
+ */
+export function fetchMcpTools() {
+    const version = getLatestVersion();
+    const tmpPkg = join(TMP_DIR, 'package');
+    // Clean and prepare temp dir
+    execSync(`rm -rf ${TMP_DIR} && mkdir -p ${TMP_DIR}`, { stdio: 'pipe' });
+    // Download tarball
+    execSync(`cd ${TMP_DIR} && npm pack @playwright/mcp@${version} --pack-destination ${TMP_DIR}`, { stdio: 'pipe' });
+    const tarball = execSync(`ls -t ${TMP_DIR}/playwright-mcp-*.tgz | head -1`, { encoding: 'utf-8' }).trim();
+    execSync(`tar -xzf "${tarball}" -C ${TMP_DIR} --strip-components=1`, { stdio: 'pipe' });
+    const readme = readFileSync(join(TMP_DIR, 'README.md'), 'utf-8');
+    return parseToolsFromReadme(readme);
+}
+/**
+ * Parse browser_* tools from the MCP README markdown.
+ * Format:
+ * - **browser_navigate**
+ *   - Title: Navigate to a URL
+ *   - Description: Navigate to a URL
+ */
+function parseToolsFromReadme(readme) {
+    const tools = [];
+    // Match tool blocks: **browser_name** followed by Title and Description
+    const blockRegex = /- \*\*([a-z_]+)\*\*[\s\S]*?- Title: ([^\n]+)\n[\s\S]*?- Description: ([^\n]+)/g;
+    let match;
+    while ((match = blockRegex.exec(readme)) !== null) {
+        const name = match[1];
+        const title = match[2].trim();
+        const description = match[3].trim();
+        // Map tool name to Healer purpose
+        const purpose = mapToolToPurpose(name, title, description);
+        tools.push({ name, title, description, purpose });
+    }
+    return tools;
+}
+/** Map a browser_* tool to its Healer purpose in the SKILL */
+function mapToolToPurpose(name, title, description) {
+    const map = {
+        browser_navigate: 'Go to the failing test\'s page',
+        browser_snapshot: 'Get page structure to find equivalent selectors',
+        browser_console_messages: 'Diagnose JS errors that may cause failures',
+        browser_take_screenshot: 'Visually compare before/after fixes',
+        browser_run_code: 'Execute custom fix logic (optional)',
+    };
+    return map[name] || title;
+}
+/**
+ * Update the Healer MCP tools table in SKILL.md.
+ * Only syncs the 5 core Healer tools; all other MCP tools are
+ * general-purpose automation not specific to healing.
+ * Deduplicates by tool name.
+ */
+export function updateSkillHealerTable(skillPath, tools) {
+    if (!existsSync(skillPath))
+        return;
+    const content = readFileSync(skillPath, 'utf-8');
+    // Only the 5 core Healer tools
+    const healerToolNames = [
+        'browser_navigate',
+        'browser_snapshot',
+        'browser_console_messages',
+        'browser_take_screenshot',
+        'browser_run_code',
+    ];
+    // Filter to healer tools, deduplicate by name
+    const healerTools = tools.filter(t => healerToolNames.includes(t.name));
+    const seen = new Set();
+    const unique = healerTools.filter(t => {
+        if (seen.has(t.name))
+            return false;
+        seen.add(t.name);
+        return true;
+    });
+    // Build new table rows
+    const rows = unique.map(t => `| \`${t.name}\` | ${t.purpose} |`).join('\n');
+    // Replace the existing table
+    const tableHeader = '| Tool | Purpose |';
+    const tableSep = '|------|---------|';
+    const start = content.indexOf(tableHeader);
+    const end = content.indexOf(tableSep, start + 1);
+    if (start === -1 || end === -1)
+        return;
+    const newSection = tableHeader + '\n' + tableSep + '\n' + rows;
+    const newContent = content.substring(0, start) +
+        newSection +
+        content.substring(end + tableSep.length);
+    writeFileSync(skillPath, newContent, 'utf-8');
+}
+/**
+ * Main entry point: fetch tools and update SKILL.md.
+ * Call this after installing the skill in init.ts and update.ts.
+ */
+export function syncMcpTools(skillPath) {
+    try {
+        const tools = fetchMcpTools();
+        updateSkillHealerTable(skillPath, tools);
+        console.log(chalk.green(`  ✓ Healer tools synced from @playwright/mcp`));
+    }
+    catch (err) {
+        console.log(chalk.yellow(`  ⚠ Failed to sync MCP tools: ${err}`));
+        console.log(chalk.gray('  SKILL.md MCP tools table may be stale'));
+    }
+}
+//# sourceMappingURL=mcp-tools.js.map

package/dist/utils/mcp-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-tools.js","sourceRoot":"","sources":["../../src/utils/mcp-tools.ts"],"names":[],"mappings":"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"}

package/openspec/schemas/playwright-e2e/schema.yaml

@@ -0,0 +1,56 @@
+name: playwright-e2e
+version: 1
+description: Playwright E2E verification for an OpenSpec change
+
+artifacts:
+  - id: test-plan
+    generates: specs/playwright/test-plan.md
+    description: Test plan derived from change specs
+    template: test-plan.md
+    instruction: |
+      Generate a test plan from the change specs. Each functional requirement becomes
+      one or more test cases.
+
+      For each test case, specify:
+      - **Test name** (kebab-case): what it verifies
+      - **Route/Page**: which URL or UI component it targets
+      - **Prerequisites**: auth role needed (user/admin/guest/none)
+      - **Happy path**: main user flow to verify
+      - **Error paths**: key error conditions to verify
+
+      Mark tests with role tags: `@role(user)`, `@role(admin)`, `@role(guest)`, `@role(none)`.
+      Mark auth requirement: `@auth(required)` or `@auth(none)`.
+
+  - id: e2e-test
+    generates: tests/playwright/<change>.spec.ts
+    description: Playwright E2E test suite
+    template: e2e-test.ts
+    instruction: |
+      Generate Playwright tests from the test-plan.
+
+      Rules:
+      - Follow the page object pattern from 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(user)` / `@project(admin)` for role-specific tests
+      - Cover happy path AND key error paths
+      - Name tests descriptively: `test('shows error on invalid input')`
+
+  - id: playwright-config
+    generates: playwright.config.ts
+    description: Playwright config with webServer and auth projects
+    template: playwright.config.ts
+    instruction: |
+      Configure Playwright for E2E testing.
+
+      - Set webServer command and url from BASE_URL
+      - Set baseURL for all tests
+      - Add auth setup project if credentials are configured
+      - Preserve any existing config fields (browsers, retries, etc.)
+      - Do NOT overwrite existing projects unless they conflict
+
+apply:
+  requires: [test-plan, e2e-test]
+  instruction: |
+    Run tests via: openspec-pw run <change-name>
+    Analyze results and generate report at openspec/reports/playwright-e2e-<change>-<timestamp>.md

package/openspec/schemas/playwright-e2e/templates/e2e-test.ts

@@ -0,0 +1,55 @@
+import { test, expect, Page } from '@playwright/test';
+
+// ──────────────────────────────────────────────
+// Test plan: <change-name>
+// Generated from: openspec/changes/<change-name>/specs/playwright/test-plan.md
+// ──────────────────────────────────────────────
+
+const BASE_URL = process.env.BASE_URL || 'http://localhost:3000';
+
+/**
+ * Page Object Pattern - add selectors for your app's pages
+ */
+class AppPage {
+  constructor(private page: Page) {}
+
+  async goto(path: string = '/') {
+    await this.page.goto(`${BASE_URL}${path}`);
+  }
+
+  async getByTestId(id: string) {
+    return this.page.locator(`[data-testid="${id}"]`);
+  }
+
+  async waitForToast(message?: string) {
+    if (message) {
+      await this.page.getByText(message, { state: 'visible' }).waitFor();
+    }
+  }
+}
+
+function createPage(page: Page): AppPage {
+  return new AppPage(page);
+}
+
+// ──────────────────────────────────────────────
+// Tests - generated from test-plan.md
+// Customize selectors and assertions to match your app
+// ──────────────────────────────────────────────
+
+test.describe('<change-name>: E2E verification', () => {
+
+  test.beforeEach(async ({ page }) => {
+    const app = createPage(page);
+    await app.goto('/');
+  });
+
+  // TODO: Add test cases from specs/playwright/test-plan.md
+  // Example:
+  // test('shows expected content on page load', async ({ page }) => {
+  //   const app = createPage(page);
+  //   await app.goto('/');
+  //   await expect(app.getByTestId('main-heading')).toBeVisible();
+  // });
+
+});

package/openspec/schemas/playwright-e2e/templates/playwright.config.ts

@@ -0,0 +1,52 @@
+import { defineConfig, devices } from '@playwright/test';
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+
+// ─── BASE_URL: prefer env, then seed.spec.ts, then default ───
+const seedSpec = join(__dirname, '../tests/playwright/seed.spec.ts');
+let baseUrl = process.env.BASE_URL || 'http://localhost:3000';
+if (existsSync(seedSpec)) {
+  const content = readFileSync(seedSpec, 'utf-8');
+  const m = content.match(/BASE_URL\s*=\s*process\.env\.BASE_URL\s*\|\|\s*['"]([^'"]+)['"]/);
+  if (m) baseUrl = m[1];
+}
+
+// ─── Dev command: detect from package.json scripts ───
+const pkgPath = join(__dirname, '../package.json');
+let devCmd = 'npm run dev';
+if (existsSync(pkgPath)) {
+  const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+  const scripts = pkg.scripts ?? {};
+  // Prefer in order: dev, start, serve, preview
+  devCmd = scripts.dev ?? scripts.start ?? scripts.serve ?? scripts.preview ?? devCmd;
+}
+
+export default defineConfig({
+  testDir: '../tests/playwright',
+  // Keep test artifacts inside tests/playwright/ instead of project root
+  outputDir: '../tests/playwright/test-results',
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: process.env.CI ? 1 : undefined,
+  reporter: 'list',
+
+  use: {
+    baseURL: baseUrl,
+    trace: 'on-first-retry',
+  },
+
+  // Dev server lifecycle - Playwright starts/stops automatically
+  webServer: {
+    command: devCmd,
+    url: baseUrl,
+    timeout: 120000,
+    reuseExistingServer: true,
+  },
+
+  // Setup project for authentication (configured by openspec-pw run)
+  projects: [
+    { name: 'setup', testMatch: /.*\.setup\.ts/ },
+    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
+  ],
+});

package/openspec/schemas/playwright-e2e/templates/report.md

@@ -0,0 +1,27 @@
+# E2E Verify Report: <change-name>
+
+**Change**: `<change-name>`
+**Generated**: `<timestamp>`
+**Auth**: `<required|none>`
+
+## Summary
+
+| Check | Status |
+|-------|--------|
+| Tests Run | <N> |
+| Passed | <X> |
+| Failed | <Y> |
+| Auto-heals | <Z> |
+| Final Status | <PASS|FAIL> |
+
+## Test Results
+
+<!-- List each test with pass/fail status -->
+
+## Auto-Heal Log
+
+<!-- If heals were performed, document each attempt -->
+
+## Recommendations
+
+<!-- For failed tests, specific file:line references and fixes -->

package/openspec/schemas/playwright-e2e/templates/test-plan.md

@@ -0,0 +1,24 @@
+# Test Plan: <change-name>
+
+Generated from: `openspec/changes/<change-name>/specs/`
+
+## Auth Requirements
+
+<!-- Mark auth requirements based on specs analysis: -->
+- Auth required: **yes / no**
+- Roles needed: none / user / admin / user+admin
+
+## Test Cases
+
+### <test-name>
+
+- **Route**: `/<page>`
+- **Role**: `@role(<role>)`
+- **Auth**: `@auth(required|none)`
+
+**Happy path:**
+- Step 1: ...
+- Step 2: ...
+
+**Error paths:**
+- ...

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openspec-playwright",
-  "version": "0.1.58",
+  "version": "0.1.60",
   "description": "OpenSpec + Playwright E2E verification setup tool for Claude Code",
   "type": "module",
   "bin": {
@@ -14,9 +14,10 @@
     "release": "npm version patch && npm run build && git push && git push --tags && npm publish"
   },
   "dependencies": {
+    "@types/tar": "^6.1.13",
     "chalk": "^5.3.0",
     "commander": "^12.1.0",
-    "tar": "^7.0.0"
+    "tar": "^7.5.13"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/release-notes.md

@@ -1,5 +1,5 @@
 ## What's Changed
 
-- feat(SKILL): unify "all" and "change" modes — same pipeline, different scope
+- feat: fix MCP_VERSION dup, expand seed, add selector memory (v2.10)
 
-**Full Changelog**: https://github.com/wxhou/openspec-playwright/releases/tag/v0.1.58
+**Full Changelog**: https://github.com/wxhou/openspec-playwright/releases/tag/v0.1.60

package/schemas/playwright-e2e/templates/app-knowledge.md

@@ -70,6 +70,16 @@ Priority: `[data-testid]` > `getByRole` > `getByLabel` > `getByText` > CSS
 | auth method | API / UI | See auth.setup.ts |
 | multi-user roles | `<roles>` | e.g. admin, user, guest |
 
+## Selector Fixes (Healer memory)
+
+Persists selector repairs across sessions. Prevents the same selector from being healed repeatedly.
+
+| Date | Route | Old Selector | New Selector | Reason |
+|------|-------|-------------|-------------|--------|
+| | | | | |
+
+---
+
 ## Changelog
 
 | Date | Change | By |
@@ -78,4 +88,4 @@ Priority: `[data-testid]` > `getByRole` > `getByLabel` > `getByText` > CSS
 
 ---
 
-> **Updating this file**: After each E2E exploration (Step 4), extract new shared patterns and update this file. Generator (Step 6) reads this before writing tests.
+> **Updating this file**: After each E2E exploration (Step 4), extract new shared patterns and update this file. Generator (Step 6) reads this before writing tests. After Healer repairs (Step 9), append the fix here.

package/src/commands/mcpSync.ts

@@ -24,6 +24,14 @@ export function getStoredMcpVersion(skillContent: string): string | null {
   return skillContent.slice(idx + MCP_VERSION_MARKER.length, end).trim();
 }
 
+/** Remove all existing MCP_VERSION comment lines from content */
+function removeMcpVersionMarkers(content: string): string {
+  return content
+    .split('\n')
+    .filter(line => !line.trim().startsWith(MCP_VERSION_MARKER))
+    .join('\n');
+}
+
 /** Build the Healer tools table markdown */
 function buildHealerTable(version: string, tools: Array<{ name: string; purpose: string }>): string {
   const rows = tools.map(t => `| \`${t.name}\` | ${t.purpose} |`).join('\n');
@@ -36,13 +44,14 @@ export function updateHealerTable(
   version: string,
   tools: Array<{ name: string; purpose: string }>
 ): string {
-  const start = skillContent.indexOf('| Tool | Purpose |');
+  const noMarkers = removeMcpVersionMarkers(skillContent);
+  const start = noMarkers.indexOf('| Tool | Purpose |');
   if (start === -1) return skillContent;
-  let end = skillContent.indexOf('\n\n', start);
-  if (end === -1) end = skillContent.length;
+  let end = noMarkers.indexOf('\n\n', start);
+  if (end === -1) end = noMarkers.length;
 
-  const before = skillContent.slice(0, start);
-  const after = skillContent.slice(end);
+  const before = noMarkers.slice(0, start);
+  const after = noMarkers.slice(end);
   return before + buildHealerTable(version, tools) + after;
 }
 

package/templates/seed.spec.ts

@@ -3,6 +3,7 @@
 // Customize the page object and base URL for your application
 
 import { test, expect, Page } from '@playwright/test';
+import { existsSync } from 'fs';
 
 // Customize these for your application
 const BASE_URL = process.env.BASE_URL || 'http://localhost:3000';
@@ -63,6 +64,27 @@ test.describe('Application smoke tests', () => {
   });
 });
 
+// ──────────────────────────────────────────────
+// Environment validation (runs in Step 3)
+// ──────────────────────────────────────────────
+
+test.describe('Environment validation', () => {
+  test('BASE_URL responds 200', async ({ page }) => {
+    const res = await page.request.get(`${BASE_URL}/`);
+    expect(res.status(), `BASE_URL ${BASE_URL} returned ${res.status()}`).toBeLessThan(500);
+  });
+
+  test('auth storageState exists if credentials provided', async () => {
+    if (!process.env.E2E_USERNAME) return; // skip if no credentials configured
+    const authPath = 'playwright/.auth/user.json';
+    if (!existsSync(authPath)) {
+      throw new Error(
+        `Auth not configured. Run:\n  npx playwright test --project=setup\nThen re-run /opsx:e2e.`
+      );
+    }
+  });
+});
+
 // ──────────────────────────────────────────────
 // Example: Role-based tests with @tag
 // Use tags (@admin, @user) for permission filtering instead of