openspec-playwright 0.3.52 → 0.3.53

package/README.md

@@ -50,7 +50,7 @@ openspec-pw audit         # Audit tests for orphaned specs and issues
 openspec-pw coverage      # Analyze spec–test coverage for changes
 openspec-pw flake         # Detect static flake patterns in test files
 openspec-pw migrate       # Migrate old test files to new structure
-openspec-pw explore       # Explore routes in parallel with Playwright
+openspec-pw explore       # Explore app routes with Playwright
 openspec-pw run <name>    # Execute E2E tests for a change
 openspec-pw uninstall     # Remove integration from the project
 ```
@@ -87,7 +87,7 @@ openspec-pw uninstall     # Remove integration from the project
   │
   ├── 10. Healer (if needed) → auto-heals failures via MCP
   │
-  └── 11. Report → openspec/reports/playwright-e2e-<name>.md
+  └── 11. Report → openspec/reports/playwright-e2e-<name>-<timestamp>.md
 ```
 
 ## Prerequisites
@@ -115,7 +115,7 @@ Browser exploration is provided out of the box by Playwright MCP and `openspec-p
 
 1. Detects supported editors in the project (Claude Code and/or OpenCode)
 2. Installs the E2E command for each detected editor (`/opsx:e2e` for Claude Code, `/opsx-e2e` for OpenCode)
-3. Generates `tests/playwright/seed.spec.ts`, `auth.setup.ts`, `credentials.yaml`, `app-knowledge.md`
+3. Generates `tests/playwright/seed.spec.ts`, `auth.setup.ts`, `credentials.yaml`, `app-knowledge.md`, `pages/BasePage.ts`
 4. Generates `playwright.config.ts` with automatic dev script and port detection (Vite/Next/Nuxt/Astro, `.env`, and `--port`)
 
 > **Note**: After running `openspec-pw init`, manually install Playwright browsers: `npx playwright install --with-deps`
@@ -144,14 +144,16 @@ Run through these steps in order when using the E2E workflow for the first time:
 
 ## App Server Detection
 
-Generated `playwright.config.ts` automatically detects the app URL in this order:
+Generated `playwright.config.ts` automatically detects the app URL in this priority order:
 
 1. `BASE_URL` environment variable
-2. port flags in `package.json` scripts, e.g. `vite --port 5125`
-3. `vite.config.*` `server.port`
-4. `.env.local`, `.env.development`, `.env` (`PLAYWRIGHT_PORT`, `E2E_PORT`, `VITE_PORT`, `PORT`)
-5. framework defaults: Vite `5173`, Astro `4321`, Next/Nuxt `3000`
-6. fallback: `http://localhost:3000`
+2. environment variables: `PLAYWRIGHT_PORT`, `E2E_PORT`, `VITE_PORT`, `PORT`
+3. port flags in `package.json` scripts, e.g. `vite --port 5125`
+4. `vite.config.*` `server.port`
+5. `.env.local`, `.env.development`, `.env` (same env var names)
+6. framework defaults: Vite `5173`, Astro `4321`, Next/Nuxt `3000`
+7. `seed.spec.ts` `BASE_URL` constant
+8. fallback: `http://localhost:3000`
 
 Run `openspec-pw doctor` to see the detected dev script and base URL:
 
@@ -215,27 +217,33 @@ CLI (openspec-pw)
   ├── run        → Executes E2E tests with server lifecycle
   ├── migrate    → Migrates old test files to new structure
   ├── audit      → Audits tests for orphaned specs and issues
+  ├── coverage   → Analyzes spec–test coverage for changes
   ├── flake      → Detects static flake patterns in test files
   ├── doctor     → Checks prerequisites
-  ├── explore    → Explores routes in parallel with Playwright
+  ├── explore    → Explores app routes with Playwright
   └── uninstall  → Removes integration from the project
 
 Editors (auto-detected by openspec-pw init)
   ├── Claude Code (/opsx:e2e)
   │   ├── .claude/commands/opsx/e2e.md   → Command file
   │   ├── @playwright/mcp                → Healer Agent tools (via `claude mcp add playwright …`)
-  │   └── CLAUDE.md                      → Employee-grade standards
+  │   └── CLAUDE.md                      → Imports AGENTS.md via `@AGENTS.md`
   └── OpenCode (/opsx-e2e)
       ├── .opencode/commands/opsx-e2e.md → Command file (body rewritten from /opsx: → /opsx-)
       ├── opencode.jsonc                 → Playwright MCP (mcp.playwright) + instructions routing
-      └── CLAUDE.md or AGENTS.md         → Employee-grade standards (routed by detected editors)
+      └── AGENTS.md                      → Employee-grade standards (SSOT)
+
+Employee-grade standards live in **AGENTS.md** as the single source of truth. Claude Code
+loads them via a thin CLAUDE.md with `@AGENTS.md` import. OpenCode registers AGENTS.md in
+`opencode.jsonc` under `instructions`.
 
 Test Assets (tests/playwright/)
   ├── seed.spec.ts         → Env validation
   ├── auth.setup.ts        → Session recording
   ├── global.teardown.ts   → Post-test cleanup (optional)
   ├── credentials.yaml     → Test users
-  └── app-knowledge.md     → Project-level selector patterns (cross-change)
+  ├── app-knowledge.md     → Project-level selector patterns (cross-change)
+  └── pages/BasePage.ts    → Shared page object class
 
 Exploration (openspec/changes/<name>/specs/playwright/)
   ├── app-exploration.md → This change's routes + verified selectors

package/README.zh-CN.md

@@ -68,10 +68,12 @@ openspec-pw init          # 安装 Playwright E2E 集成
 ```bash
 openspec-pw init          # 初始化集成（一次性设置；加 --seed 覆盖已有 seed.spec.ts）
 openspec-pw update        # 更新 CLI 和命令到最新版本
-openspec-pw doctor        # 检查前置条件
+openspec-pw doctor        # 检查前置条件 + 应用服务器诊断
 openspec-pw audit         # 检查测试文件是否有孤儿文件和配置问题
+openspec-pw coverage      # 分析 spec 与测试之间的覆盖率
+openspec-pw flake         # 检测测试文件中的静态不稳定模式
 openspec-pw migrate       # 迁移旧测试文件到新目录结构
-openspec-pw explore       # 并行探索路由
+openspec-pw explore       # 探索应用路由
 openspec-pw run <name>    # 执行指定 change 的 E2E 测试
 openspec-pw uninstall     # 移除项目中的集成
 ```
@@ -108,14 +110,14 @@ openspec-pw uninstall     # 移除项目中的集成
   │
   ├── 10. Healer（如需要）→ 通过 MCP 自动修复失败
   │
-  └── 11. 报告 → openspec/reports/playwright-e2e-<name>.md
+  └── 11. 报告 → openspec/reports/playwright-e2e-<name>-<timestamp>.md
 ```
 
 ## `openspec-pw init` 做了什么
 
 1. 检测项目中的受支持编辑器（Claude Code 和/或 OpenCode）
 2. 为每个检测到的编辑器安装 E2E 命令（Claude Code 用 `/opsx:e2e`，OpenCode 用 `/opsx-e2e`）
-3. 生成 `tests/playwright/seed.spec.ts`、`auth.setup.ts`、`credentials.yaml`、`app-knowledge.md`
+3. 生成 `tests/playwright/seed.spec.ts`、`auth.setup.ts`、`credentials.yaml`、`app-knowledge.md`、`pages/BasePage.ts`
 
 ## 首次配置清单
 
@@ -188,23 +190,32 @@ CLI (openspec-pw)
   ├── run        → 执行 E2E 测试并管理服务器生命周期
   ├── migrate    → 迁移旧测试文件到新目录结构
   ├── audit      → 检查测试文件是否有孤儿文件和配置问题
+  ├── coverage   → 分析 spec 与测试之间的覆盖率
+  ├── flake      → 检测测试文件中的静态不稳定模式
   ├── doctor     → 检查前置条件
-  ├── explore    → 并行探索路由
+  ├── explore    → 探索应用路由
   └── uninstall  → 移除项目中的集成
 
 编辑器（由 openspec-pw init 自动检测）
   ├── Claude Code (/opsx:e2e)
   │   ├── .claude/commands/opsx/e2e.md    → 命令文件（从 templates/e2e-command.md 安装）
-  │   └── @playwright/mcp                 → Healer Agent 工具（通过 `claude mcp add playwright …`）
+  │   ├── @playwright/mcp                 → Healer Agent 工具（通过 `claude mcp add playwright …`）
+  │   └── CLAUDE.md                       → 通过 `@AGENTS.md` 引入 AGENTS.md
   └── OpenCode (/opsx-e2e)
       ├── .opencode/commands/opsx-e2e.md  → 命令文件（正文由 /opsx: 改写为 /opsx-）
-      └── opencode.jsonc                  → Playwright MCP (mcp.playwright) + 指令路由
+      ├── opencode.jsonc                  → Playwright MCP (mcp.playwright) + 指令路由
+      └── AGENTS.md                       → 员工级规范（单一数据源）
+
+员工级规范统一存放在 **AGENTS.md** 中。Claude Code 通过薄层 CLAUDE.md
+（包含 `@AGENTS.md` 导入）加载；OpenCode 在 `opencode.jsonc` 的 `instructions` 中注册 AGENTS.md。
 
 测试资产 (tests/playwright/)
-  ├── seed.spec.ts       → 环境验证
-  ├── auth.setup.ts      → 会话录制
-  ├── credentials.yaml   → 测试用户
-  └── app-knowledge.md   → 项目级选择器模式（跨 change 复用）
+  ├── seed.spec.ts        → 环境验证
+  ├── auth.setup.ts       → 会话录制
+  ├── global.teardown.ts  → 测试后清理（可选）
+  ├── credentials.yaml    → 测试用户
+  ├── app-knowledge.md    → 项目级选择器模式（跨 change 复用）
+  └── pages/BasePage.ts   → 共享页面对象基类
 
 探索结果 (openspec/changes/<name>/specs/playwright/)
   ├── app-exploration.md → 本次 change 的路由 + 已验证选择器

package/employee-standards.md

@@ -20,6 +20,8 @@
 
 **精准改动**：只改必要的，改完清理自己造成的垃圾。匹配现有风格，不改进无关代码。
 
+**代码文件行数上限 1500**：超过 1500 行即视为过长。需要扩展时按职责拆分为多个文件，而不是堆叠。
+
 **lint + typecheck 通过（项目标准工具链）才算成功**。动手前扫描项目根目录源码文件扩展名检测主语言——`.py`→Python（ruff + mypy）、`.ts`/`.tsx`→TypeScript（ESLint + tsc）、`.go`→Go（gofmt + vet），工具不存在时告知用户。
 
 **禁止非通用性改动**：

package/package.json

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