openspec-playwright 0.1.38 → 0.1.40

package/.claude/commands/opsx/e2e-body.md

@@ -0,0 +1,39 @@
+Run Playwright E2E verification for an OpenSpec change.
+
+## Workflow
+
+1. **Validate environment**: Run the seed test to confirm your app is reachable.
+   ```bash
+   npx playwright test tests/playwright/seed.spec.ts --project=chromium
+   ```
+   If it fails, fix your BASE_URL or start the dev server first.
+
+2. **Select the change**: If no change name is provided, run `openspec list --json` and pick one. Then announce: "Using change: `<name>`".
+
+3. **Read specs**: Read all files from `openspec/changes/<name>/specs/*.md`.
+
+4. **Detect auth**: Check if specs mention login, protected routes, or session handling. See `tests/playwright/auth.setup.ts` for auth setup.
+
+5. **Generate test plan**: Create `openspec/changes/<name>/specs/playwright/test-plan.md` listing each test case with `@auth(required|none)` and `@role(...)` tags. Skip if already exists.
+
+6. **Generate tests**: Write `tests/playwright/<name>.spec.ts` from the test plan. Follow the patterns in `seed.spec.ts`:
+   - Prefer `data-testid`, fallback to `getByRole`, `getByLabel`, `getByText`
+   - Include happy path AND error/edge cases
+   - Never use conditional `if (isVisible())` — always use `expect().toBeVisible()` (false-pass anti-pattern)
+   - Use `browser.newContext()` for auth guard tests (fresh session, no cookies)
+
+7. **Run tests**:
+   ```bash
+   openspec-pw run <change-name>
+   ```
+   Or with role filtering:
+   ```bash
+   npx playwright test tests/playwright/<name>.spec.ts --grep "@<role>"
+   ```
+
+8. **Fix failures**: If tests fail, analyze the error:
+   - Network/backend error → `test.skip()` + report
+   - Selector changed → use Playwright MCP tools to find equivalent selectors, fix, re-run
+   - Auto-heal up to 3 attempts
+
+9. **Report**: Results are saved to `openspec/reports/playwright-e2e-<name>-<timestamp>.md`. Present the summary table to the user.

package/README.md

@@ -18,21 +18,35 @@ openspec init              # Initialize OpenSpec
 openspec-pw init          # Install Playwright E2E integration
 ```
 
+## Supported AI Coding Assistants
+
+Auto-detects and installs commands for these editors:
+
+| Editor | Command | Format |
+|--------|---------|--------|
+| Claude Code | `/opsx:e2e` | Skill + command + MCP |
+| Cursor | `/opsx-e2e` | Command |
+| Windsurf | `/opsx-e2e` | Workflow |
+| Cline | `/opsx-e2e` | Workflow |
+| Continue | `/opsx-e2e` | Prompt |
+
+`openspec-pw init` detects which editors you have in your project and installs the appropriate files. Claude Code gets the full experience (skill + command + Playwright MCP). Other editors get command/workflow files with the complete E2E workflow.
+
 ## Usage
 
-### In Claude Code
+### In Your AI Coding Assistant
 
 ```bash
-/opsx:e2e my-feature    # Primary command (OpenSpec convention)
-/openspec-e2e           # Alternative from skill
+/opsx:e2e my-feature    # Claude Code
+/opsx-e2e my-feature   # Cursor, Windsurf, Cline, Continue
 ```
 
 ### CLI Commands
 
 ```bash
 openspec-pw init          # Initialize integration (one-time setup)
-openspec-pw update       # Update CLI and skill to latest version
-openspec-pw doctor       # Check prerequisites
+openspec-pw update        # Update CLI and commands to latest version
+openspec-pw doctor        # Check prerequisites
 ```
 
 ## How It Works
@@ -62,13 +76,16 @@ openspec-pw doctor       # Check prerequisites
 
 1. **Node.js >= 20**
 2. **OpenSpec** initialized: `npm install -g @fission-ai/openspec && openspec init`
-3. **Claude Code** with Playwright MCP configured
+3. **One of**: Claude Code, Cursor, Windsurf, Cline, or Continue (auto-detected)
+4. **Claude Code only**: Playwright MCP — `claude mcp add playwright npx @playwright/mcp@latest`
 
 ## What `openspec-pw init` Does
 
-1. Installs Playwright MCP globally via `claude mcp add`
-2. Installs `/opsx:e2e` command and `/openspec-e2e` skill
-3. Generates `tests/playwright/seed.spec.ts`, `auth.setup.ts`, `credentials.yaml`
+1. Detects installed AI coding assistants (Claude Code, Cursor, Windsurf, Cline, Continue)
+2. Installs E2E command/workflow files for each detected editor
+3. Installs `/openspec-e2e` skill for Claude Code
+4. Installs Playwright MCP globally for Claude Code (via `claude mcp add`)
+5. Generates `tests/playwright/seed.spec.ts`, `auth.setup.ts`, `credentials.yaml`
 
 > **Note**: After running `openspec-pw init`, manually install Playwright browsers: `npx playwright install --with-deps`
 
@@ -109,23 +126,30 @@ Edit `tests/playwright/credentials.yaml`:
 - Configure test user credentials
 - Add multiple users for role-based tests
 
-### MCP server
+### MCP server (Claude Code only)
 
-Playwright MCP is installed globally via `claude mcp add`. Restart Claude Code after setup to activate.
+Playwright MCP is installed globally via `claude mcp add` and enables the Healer Agent (auto-heals test failures via UI inspection). Restart Claude Code after setup to activate.
 
 ## Architecture
 
 ```
-openspec-pw (CLI - setup only)
-  ├── Installs Playwright agents (.github/)
-  ├── Installs Playwright MCP globally via claude mcp add
-  ├── Installs Claude Code skill (/openspec-e2e)
-  └── Installs command (/opsx:e2e)
-
-/openspec-e2e (Claude Code skill - runs in Claude)
-  ├── Reads OpenSpec specs
-  ├── Triggers Playwright agents via MCP
-  └── Generates E2E verification report
+Schema (openspec/schemas/playwright-e2e/)
+  └── Templates: test-plan.md, report.md, playwright.config.ts
+
+CLI (openspec-pw)
+  ├── init       → Installs commands for detected editors
+  ├── update     → Syncs commands + schema from npm
+  └── doctor     → Checks prerequisites
+
+Skill/Commands (per editor)
+  ├── Claude Code → /openspec-e2e (skill) + /opsx:e2e (command) + MCP
+  ├── Cursor      → /opsx-e2e (command)
+  ├── Windsurf    → /opsx-e2e (workflow)
+  ├── Cline       → /opsx-e2e (workflow)
+  └── Continue    → /opsx-e2e (prompt)
+
+Healer Agent (Claude Code + MCP only)
+  └── browser_snapshot, browser_navigate, browser_run_code, etc.
 ```
 
 ## License

package/README.zh-CN.md

@@ -18,27 +18,41 @@ openspec init              # 初始化 OpenSpec
 openspec-pw init          # 安装 Playwright E2E 集成
 ```
 
+## 支持的 AI 编码助手
+
+自动检测并安装以下编辑器的命令文件：
+
+| 编辑器 | 命令 | 格式 |
+|--------|------|------|
+| Claude Code | `/opsx:e2e` | Skill + 命令 + MCP |
+| Cursor | `/opsx-e2e` | 命令 |
+| Windsurf | `/opsx-e2e` | 工作流 |
+| Cline | `/opsx-e2e` | 工作流 |
+| Continue | `/opsx-e2e` | Prompt |
+
+`openspec-pw init` 会检测项目中安装了哪些编辑器并安装对应文件。Claude Code 获得完整体验（skill + 命令 + Playwright MCP）。其他编辑器获得包含完整 E2E 工作流的命令/工作流文件。
+
 ## 使用
 
-### 在 Claude Code 中
+### 在 AI 编码助手中
 
 ```bash
-/opsx:e2e my-feature    # 主命令（遵循 OpenSpec 规范）
-/openspec-e2e            # 来自 skill 的别名
+/opsx:e2e my-feature    # Claude Code
+/opsx-e2e my-feature   # Cursor, Windsurf, Cline, Continue
 ```
 
 ### CLI 命令
 
 ```bash
 openspec-pw init          # 初始化集成（一次性设置）
-openspec-pw update        # 更新 CLI 和 skill 到最新版本
+openspec-pw update        # 更新 CLI 和命令到最新版本
 openspec-pw doctor        # 检查前置条件
 ```
 
 ## 工作原理
 
 ```
-/openspec-e2e <change-name>
+/opsx:e2e <change-name>
   │
   ├── 1. 从 openspec/changes/<name>/specs/ 读取 OpenSpec specs
   │
@@ -46,7 +60,7 @@ openspec-pw doctor        # 检查前置条件
   │
   ├── 3. Generator Agent → 创建 tests/playwright/<name>.spec.ts
   │
-  └── 4. Healer Agent → 运行测试 + 自动修复失败
+  └── 4. Healer Agent → 运行测试 + 自动修复失败（Claude Code + MCP）
           │
           └── 报告: openspec/reports/playwright-e2e-<name>.md
 ```
@@ -62,13 +76,16 @@ openspec-pw doctor        # 检查前置条件
 
 1. **Node.js >= 20**
 2. **OpenSpec** 已初始化: `npm install -g @fission-ai/openspec && openspec init`
-3. **Claude Code** 已配置 Playwright MCP
+3. **任一**: Claude Code、Cursor、Windsurf、Cline 或 Continue（自动检测）
+4. **仅 Claude Code**: Playwright MCP — `claude mcp add playwright npx @playwright/mcp@latest`
 
 ## `openspec-pw init` 做了什么
 
-1. 通过 `claude mcp add` 全局安装 Playwright MCP
-2. 安装 `/opsx:e2e` 命令和 `/openspec-e2e` skill
-3. 生成 `tests/playwright/seed.spec.ts`、`auth.setup.ts`、`credentials.yaml`
+1. 检测已安装的 AI 编码助手（Claude Code、Cursor、Windsurf、Cline、Continue）
+2. 为每个检测到的编辑器安装 E2E 命令/工作流文件
+3. 为 Claude Code 安装 `/openspec-e2e` skill
+4. 为 Claude Code 全局安装 Playwright MCP（通过 `claude mcp add`）
+5. 生成 `tests/playwright/seed.spec.ts`、`auth.setup.ts`、`credentials.yaml`
 
 > **注意**：运行 `openspec-pw init` 后，手动安装 Playwright 浏览器：`npx playwright install --with-deps`
 
@@ -109,9 +126,9 @@ npx playwright test --project=setup
 - 配置测试用户凭证
 - 为角色测试添加多用户
 
-### MCP 服务器
+### MCP 服务器（仅 Claude Code）
 
-Playwright MCP 通过 `claude mcp add` 全局安装。设置后需重启 Claude Code 生效。
+Playwright MCP 通过 `claude mcp add` 全局安装，启用 Healer Agent（通过 UI 检查自动修复测试失败）。设置后需重启 Claude Code 生效。
 
 ## 许可
 

package/dist/commands/editors.d.ts

@@ -0,0 +1,33 @@
+/** Shared YAML escape — matches OpenSpec's escape logic */
+export declare function escapeYamlValue(value: string): string;
+/** Format tags as YAML inline array (escaped) */
+export declare function formatTagsArray(tags: string[]): string;
+/** Command metadata shared across editors */
+export interface CommandMeta {
+    id: string;
+    name: string;
+    description: string;
+    category: string;
+    tags: string[];
+    body: string;
+}
+/** Editor adapter — Strategy Pattern */
+export interface EditorAdapter {
+    toolId: string;
+    hasSkill: boolean;
+    getCommandPath(commandId: string): string;
+    formatCommand(meta: CommandMeta): string;
+}
+/** Claude Code: .claude/commands/opsx/<id>.md + SKILL.md */
+declare const claudeAdapter: EditorAdapter;
+/** Detect which editors are installed by checking their config directories */
+export declare function detectEditors(projectRoot: string): EditorAdapter[];
+/** Detect Codex by checking if CODEX_HOME or ~/.codex exists */
+export declare function detectCodex(): EditorAdapter | null;
+/** Build the shared command metadata */
+export declare function buildCommandMeta(body: string): CommandMeta;
+/** Install command files for all detected editors */
+export declare function installForAllEditors(body: string, adapters: EditorAdapter[], projectRoot: string): void;
+/** Install SKILL.md only for Claude Code */
+export declare function installSkill(projectRoot: string, skillContent: string): void;
+export { claudeAdapter };