openspec-playwright 0.2.0 → 0.2.1

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

@@ -49,12 +49,14 @@ Both modes update `app-knowledge.md` and `app-exploration.md`. All `.spec.ts` fi
 - Edge cases requiring pre-condition data that UI cannot set up
 - Cases where Step 4 exploration confirmed no UI element exists
 
-**Decision rule**:
+**Setup vs Assertion**: API is acceptable for **setup/precondition** (preparing test data). Every **final assertion** about visible UI state must use UI selectors — never use `page.request` to assert something the user can see on screen.
+
+**Decision rule (per assertion)**:
 
 ```
-Can this be tested through the UI?
-  → Yes → page.getByRole/ByLabel/ByText + click/fill/type + assert UI
-  → No  → record reason → use page.request
+Can the user SEE this on screen?
+  → Yes → MUST use: page.getByRole/ByLabel/ByText + expect()
+  → No  → Record reason → page.request acceptable
 ```
 
 **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.
@@ -192,8 +194,9 @@ await browser_navigate(`${BASE_URL}/<route>`);
 
 Wait for page stability:
 
-- Prefer `browser_wait_for` with text or selector
-- Avoid `networkidle` / `load` — too slow or unreliable
+- **React 19 / Next.js App Router**: use `page.waitForLoadState('networkidle')` — React 19 concurrent mode batches events asynchronously; 200-500ms timeouts are unreliable under resource contention
+- **Vue 2/3 / Angular / React 18 / Plain JS / jQuery**: `waitForSelector(targetElement)` is sufficient and faster — DOM updates are synchronous; Playwright's actionability checks auto-wait correctly
+- Prefer specific element waits (`waitForSelector`) over generic load states
 - Ready signal: heading, spinner disappears, or URL change
 
 #### 4.3. Parse the snapshot
@@ -472,6 +475,16 @@ For each discovered route:
 - Read: test-plan.md, app-exploration.md, app-knowledge.md, seed.spec.ts
 - For each test case: verify selectors in real browser, then write Playwright code
 
+**Per-assertion UI check** (before writing each assertion):
+```
+Is this assertion about a visible UI result?
+  → Yes → MUST use: expect(locator) with page selector
+  → No  → Is this a precondition or unreachable HTTP error?
+    → Yes → page.request is acceptable (record reason)
+    → No → This is a bug — rewrite with UI selector
+```
+**Never use page.request for assertions the user can see on screen.** If you wrote page.request.get() for a visible result → rewrite with expect(locator) from the browser snapshot.
+
 **Selector verification (change mode)**:
 
 1. Navigate to route with correct auth state
@@ -809,7 +822,7 @@ When a test fails, classify before attempting repair:
 | **Auth Expired** | Redirected to login mid-test | **Flaky** | Re-run auth.setup → re-run |
 | **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 (1×, not counted in heal attempts) |
+| **Timeout** | waitFor/evaluate timeout | **Flaky** | Retry isolated (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. |
 | **Same test fails in suite, passes isolated** | — | **RAFT** | `test.skip()` in suite, note RAFT in report |
 
 - **App Bug** → skip immediately (no healing needed)
@@ -866,6 +879,17 @@ Please decide:
 
 Wait for user input before proceeding.
 
+**Decision tree — follow the path based on user's choice:**
+
+| Choice | What to do | After fix, do this |
+|--------|-----------|-------------------|
+| **(a)** Fix the app to match the spec | Fix the app code | Re-run: `npx playwright test tests/playwright/<name>.spec.ts` to verify fix, then re-run `/opsx:e2e <change-name>` to confirm full suite passes |
+| **(b)** Update the spec to match the app | Edit the spec file | Then update the test assertion (→ option c), or regenerate the affected part of the test |
+| **(c)** Update the test assertion | Fix the assertion in `tests/playwright/<name>.spec.ts` | Re-run: `npx playwright test tests/playwright/<name>.spec.ts` to verify, then re-run `/opsx:e2e <change-name>` for full suite |
+| **(d)** Skip with `test.skip()` | Add `test.skip()` to the test | Note in `app-knowledge.md` → `Selector Fixes` table with reason "human escalation — skipped pending resolution" |
+
+**Same choice ≥ 2 times without progress**: If user picks the same option twice but the test still doesn't pass, STOP and ask: "This was tried before without success. Are you sure the root cause is still the same, or has something changed?"
+
 After the issue is resolved, re-run:
 ```
 /opsx:e2e <change-name>

package/README.md

@@ -92,6 +92,22 @@ claude mcp add playwright npx @playwright/mcp@latest
 
 > **Note**: After running `openspec-pw init`, manually install Playwright browsers: `npx playwright install --with-deps`
 
+## First-Time Setup Checklist
+
+Run through these steps in order when using the E2E workflow for the first time:
+
+| Step | Command | If it fails |
+|------|---------|-------------|
+| 1. Install CLI | `npm install -g openspec-playwright` | Check Node.js version `node -v` (needs >= 20) |
+| 2. Install OpenSpec | `npm install -g @fission-ai/openspec && openspec init` | `npm cache clean -f && npm install -g @fission-ai/openspec` |
+| 3. Initialize E2E | `openspec-pw init` | Run `openspec-pw doctor` to see what's missing |
+| 4. Install Playwright MCP | `claude mcp add playwright npx @playwright/mcp@latest` | `claude mcp list` to confirm installation |
+| 5. Install browsers | `npx playwright install --with-deps` | macOS may need `xcode-select --install` first |
+| 6. Start dev server | `npm run dev` (in a separate terminal) | Confirm port, set `BASE_URL` if non-standard |
+| 7. Validate env | `npx playwright test tests/playwright/seed.spec.ts` | Check `webServer` in `playwright.config.ts` |
+| 8. Configure auth (if needed) | See "Authentication" below | Debug with `npx playwright test --project=setup` |
+| 9. Run first E2E | `/opsx:e2e <change-name>` | Check `openspec/reports/` for the report |
+
 ## Authentication
 
 If your app requires login, set up credentials once, then all tests run authenticated automatically.

package/README.zh-CN.md

@@ -10,6 +10,17 @@
 npm install -g openspec-playwright
 ```
 
+## 前置条件
+
+1. **Node.js >= 20**
+2. **OpenSpec** 已初始化: `npm install -g @fission-ai/openspec && openspec init`
+3. **Claude Code** 且项目中有 `.claude/` 目录
+
+安装 Playwright MCP：
+```bash
+claude mcp add playwright npx @playwright/mcp@latest
+```
+
 ## 初始化
 
 ```bash
@@ -18,6 +29,8 @@ openspec init              # 初始化 OpenSpec
 openspec-pw init          # 安装 Playwright E2E 集成
 ```
 
+> **注意**：运行 `openspec-pw init` 后，手动安装 Playwright 浏览器：`npx playwright install --with-deps`
+
 ## 支持的 AI 编码助手
 
 Claude Code — E2E 工作流由 SKILL.md 驱动，使用 Playwright MCP 工具（`/opsx:e2e <change-name>`）。
@@ -73,17 +86,6 @@ openspec-pw uninstall     # 移除项目中的集成
   └── 11. 报告 → openspec/reports/playwright-e2e-<name>.md
 ```
 
-## 前置条件
-
-1. **Node.js >= 20**
-2. **OpenSpec** 已初始化: `npm install -g @fission-ai/openspec && openspec init`
-3. **Claude Code** 且项目中有 `.claude/` 目录
-
-安装 Playwright MCP：
-```bash
-claude mcp add playwright npx @playwright/mcp@latest
-```
-
 ## `openspec-pw init` 做了什么
 
 1. 检测项目中的 Claude Code
@@ -91,9 +93,23 @@ claude mcp add playwright npx @playwright/mcp@latest
 3. 从最新 `@playwright/mcp` 同步 Healer 工具
 4. 生成 `tests/playwright/seed.spec.ts`、`auth.setup.ts`、`credentials.yaml`、`app-knowledge.md`
 
-> **注意**：运行 `openspec-pw init` 后，手动安装 Playwright 浏览器：`npx playwright install --with-deps`
+## 首次配置清单
+
+首次使用 E2E 工作流，按顺序执行以下步骤：
+
+| 步骤 | 命令 | 失败时快速修复 |
+|------|------|----------------|
+| 1. 安装 CLI | `npm install -g openspec-playwright` | 检查 Node.js 版本 `node -v`（需 >= 20） |
+| 2. 安装 OpenSpec | `npm install -g @fission-ai/openspec && openspec init` | `npm cache clean -f && npm install -g @fission-ai/openspec` |
+| 3. 初始化 E2E | `openspec-pw init` | 运行 `openspec-pw doctor` 查看具体缺失项 |
+| 4. 安装 Playwright MCP | `claude mcp add playwright npx @playwright/mcp@latest` | `claude mcp list` 确认安装成功 |
+| 5. 安装浏览器 | `npx playwright install --with-deps` | macOS 可能需先运行 `xcode-select --install` |
+| 6. 启动开发服务器 | `npm run dev`（在另一个终端） | 确认端口，配置 `BASE_URL` |
+| 7. 验证环境 | `npx playwright test tests/playwright/seed.spec.ts` | 检查 `playwright.config.ts` 中的 `webServer` 配置 |
+| 8. 配置认证（如需要） | 见下方"认证配置" | `npx playwright test --project=setup` 调试 |
+| 9. 运行第一个 E2E | `/opsx:e2e <change-name>` | 查看 `openspec/reports/` 中的报告 |
 
-## 认证
+## 认证配置
 
 如果你的应用需要登录，配置一次凭证后，所有测试自动以已登录状态运行。
 

package/employee-standards.md

@@ -31,6 +31,8 @@
 
 **分阶段执行**：每个阶段不超过 5 个文件，完成后验证，等待用户批准再继续。
 
+**200 行以上修改必须走 OpenSpec**：代码改动超过 200 行时，禁止直接修改，必须通过 OpenSpec 工作流。
+
 ---
 
 ## 四、工具限制

package/package.json

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