openspec-playwright 0.1.48 → 0.1.49

package/README.md

@@ -59,18 +59,35 @@ openspec-pw doctor        # Check prerequisites
 ## How It Works
 
 ```
-/openspec-e2e <change-name>
+/opsx:e2e <change-name>
   │
-  ├── 1. Read OpenSpec specs from openspec/changes/<name>/specs/
+  ├── 1. Select change → read openspec/changes/<name>/specs/
   │
-  ├── 2. Planner Agent → generates test-plan.md
+  ├── 2. Detect auth → check specs for login/auth markers
   │
-  ├── 3. Generator Agent → creates tests/playwright/<name>.spec.ts
+  ├── 3. Validate env → run seed.spec.ts
   │
-  └── 4. Healer Agent → runs tests + auto-heals failures
-          │
-          └── Report: openspec/reports/playwright-e2e-<name>.md
-```
+  ├── 4. Explore app → Playwright MCP explores real DOM
+  │       ├─ Read app-knowledge.md (project-level knowledge)
+  │       ├─ Extract routes from specs
+  │       ├─ Navigate each route → snapshot → screenshot
+  │       └─ Write app-exploration.md (change-level findings)
+  │           └─ Extract patterns → update app-knowledge.md
+  │
+  ├── 5. Planner → generates test-plan.md
+  │
+  ├── 6. Generator → creates tests/playwright/<name>.spec.ts
+  │       └─ Verifies selectors in real browser before writing
+  │
+  ├── 7. Configure auth → auth.setup.ts (if required)
+  │
+  ├── 8. Configure playwright → playwright.config.ts
+  │
+  ├── 9. Execute tests → openspec-pw run <name>
+  │
+  ├── 10. Healer (if needed) → auto-heals failures via MCP
+  │
+  └── 11. Report → openspec/reports/playwright-e2e-<name>.md
 
 ### Two Verification Layers
 
@@ -92,7 +109,7 @@ openspec-pw doctor        # Check prerequisites
 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`
+5. Generates `tests/playwright/seed.spec.ts`, `auth.setup.ts`, `credentials.yaml`, `app-knowledge.md`
 
 > **Note**: After running `openspec-pw init`, manually install Playwright browsers: `npx playwright install --with-deps`
 
@@ -141,20 +158,32 @@ Playwright MCP is installed globally via `claude mcp add` and enables the Healer
 
 ```
 Schema (openspec/schemas/playwright-e2e/)
-  └── Templates: test-plan.md, report.md, playwright.config.ts
+  └── Templates: test-plan.md, report.md, playwright.config.ts, app-knowledge.md
 
 CLI (openspec-pw)
   ├── init       → Installs commands for detected editors
   ├── update     → Syncs commands + schema from npm
+  ├── run        → Executes E2E tests with server lifecycle
+  ├── verify     → Checks implementation against artifacts
   └── doctor     → Checks prerequisites
 
 Skill/Commands (per editor)
-  ├── Claude Code → /openspec-e2e (skill) + /opsx:e2e (command) + MCP
+  ├── Claude Code → /opsx:e2e (skill) + /opsx:e2e (command) + MCP
   ├── Cursor      → /opsx-e2e (command)
   ├── Windsurf    → /opsx-e2e (workflow)
   ├── Cline       → /opsx-e2e (workflow)
   └── Continue    → /opsx-e2e (prompt)
 
+Test Assets (tests/playwright/)
+  ├── seed.spec.ts       → Env validation
+  ├── auth.setup.ts      → Session recording
+  ├── credentials.yaml   → Test users
+  └── app-knowledge.md   → Project-level selector patterns (cross-change)
+
+Exploration (openspec/changes/<name>/specs/playwright/)
+  ├── app-exploration.md → This change's routes + verified selectors
+  └── test-plan.md       → This change's test cases
+
 Healer Agent (Claude Code + MCP only)
   └── browser_snapshot, browser_navigate, browser_run_code, etc.
 ```

package/README.zh-CN.md

@@ -61,15 +61,33 @@ openspec-pw doctor        # 检查前置条件
 ```
 /opsx:e2e <change-name>
   │
-  ├── 1. 从 openspec/changes/<name>/specs/ 读取 OpenSpec specs
+  ├── 1. 选择 change → 读取 openspec/changes/<name>/specs/
   │
-  ├── 2. Planner Agent → 生成 test-plan.md
+  ├── 2. 检测 auth → 从 specs 识别登录/认证标记
   │
-  ├── 3. Generator Agent → 创建 tests/playwright/<name>.spec.ts
+  ├── 3. 验证环境 → 运行 seed.spec.ts
   │
-  └── 4. Healer Agent → 运行测试 + 自动修复失败（Claude Code + MCP）
-          │
-          └── 报告: openspec/reports/playwright-e2e-<name>.md
+  ├── 4. 探索应用 → Playwright MCP 探索真实 DOM
+  │       ├─ 读取 app-knowledge.md（项目级知识）
+  │       ├─ 从 specs 提取路由
+  │       ├─ 遍历每个路由 → snapshot → screenshot
+  │       └─ 写入 app-exploration.md（change 级发现）
+  │           └─ 提取模式 → 更新 app-knowledge.md
+  │
+  ├── 5. Planner → 生成 test-plan.md
+  │
+  ├── 6. Generator → 创建 tests/playwright/<name>.spec.ts
+  │       └─ 写测试前先在真实浏览器验证选择器
+  │
+  ├── 7. 配置 auth → auth.setup.ts（如需要）
+  │
+  ├── 8. 配置 playwright → playwright.config.ts
+  │
+  ├── 9. 执行测试 → openspec-pw run <name>
+  │
+  ├── 10. Healer（如需要）→ 通过 MCP 自动修复失败
+  │
+  └── 11. 报告 → openspec/reports/playwright-e2e-<name>.md
 ```
 
 ### 两层验证
@@ -83,16 +101,16 @@ openspec-pw doctor        # 检查前置条件
 
 1. **Node.js >= 20**
 2. **OpenSpec** 已初始化: `npm install -g @fission-ai/openspec && openspec init`
-3. **任一**: Claude Code、Cursor、Windsurf、Cline 或 Continue（自动检测）
+3. **任一 24 编辑器**: Claude Code、Cursor、Windsurf、Cline、Continue 等（自动检测）
 4. **仅 Claude Code**: Playwright MCP — `claude mcp add playwright npx @playwright/mcp@latest`
 
 ## `openspec-pw init` 做了什么
 
-1. 检测已安装的 AI 编码助手（Claude Code、Cursor、Windsurf、Cline、Continue）
+1. 检测已安装的 AI 编码助手（支持全部 24 个编辑器）
 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`
+5. 生成 `tests/playwright/seed.spec.ts`、`auth.setup.ts`、`credentials.yaml`、`app-knowledge.md`
 
 > **注意**：运行 `openspec-pw init` 后，手动安装 Playwright 浏览器：`npx playwright install --with-deps`
 
@@ -137,6 +155,40 @@ npx playwright test --project=setup
 
 Playwright MCP 通过 `claude mcp add` 全局安装，启用 Healer Agent（通过 UI 检查自动修复测试失败）。设置后需重启 Claude Code 生效。
 
+## 架构
+
+```
+Schema (openspec/schemas/playwright-e2e/)
+  └── 模板: test-plan.md, report.md, playwright.config.ts, app-knowledge.md
+
+CLI (openspec-pw)
+  ├── init       → 为检测到的编辑器安装命令
+  ├── update     → 从 npm 同步命令和 schema
+  ├── run        → 执行 E2E 测试并管理服务器生命周期
+  ├── verify     → 检查实现是否符合 artifacts
+  └── doctor     → 检查前置条件
+
+Skill/命令（按编辑器）
+  ├── Claude Code → /opsx:e2e (skill) + /opsx:e2e (command) + MCP
+  ├── Cursor      → /opsx-e2e (command)
+  ├── Windsurf    → /opsx-e2e (workflow)
+  ├── Cline       → /opsx-e2e (workflow)
+  └── Continue    → /opsx-e2e (prompt)
+
+测试资产 (tests/playwright/)
+  ├── seed.spec.ts       → 环境验证
+  ├── auth.setup.ts      → 会话录制
+  ├── credentials.yaml   → 测试用户
+  └── app-knowledge.md   → 项目级选择器模式（跨 change 复用）
+
+探索结果 (openspec/changes/<name>/specs/playwright/)
+  ├── app-exploration.md → 本次 change 的路由 + 已验证选择器
+  └── test-plan.md       → 本次 change 的测试用例
+
+Healer Agent（仅 Claude Code + MCP）
+  └── browser_snapshot, browser_navigate, browser_run_code 等
+```
+
 ## 许可
 
 MIT

package/package.json

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

package/release-notes.md

@@ -1,5 +1,5 @@
 ## What's Changed
 
-- fix(SKILL): merge Step 4.0 into 4.1 — read app-knowledge + extract routes as one step
+- docs: update README and Chinese README with app-knowledge and new pipeline
 
-**Full Changelog**: https://github.com/wxhou/openspec-playwright/releases/tag/v0.1.48
+**Full Changelog**: https://github.com/wxhou/openspec-playwright/releases/tag/v0.1.49