openspec-playwright 0.3.6 → 0.3.8

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

@@ -3,9 +3,21 @@
 
 <!-- This section is auto-generated by claude-mem. Edit content outside the tags. -->
 
-### Apr 7, 2026
+### Mar 27, 2026
 
 | ID | Time | T | Title | Read |
 |----|------|---|-------|------|
-| #5762 | 11:14 AM | 🔵 | SKILL.md Already Documents fillAndVerify Pattern | ~214 |
+| #5635 | 3:00 PM | ✅ | Simplified skill input instructions | ~201 |
+| #5634 | " | 🟣 | Improved change selection logic in openspec-e2e skill | ~200 |
+| #5633 | " | 🔵 | openspec-e2e SKILL.md implements three-agent Playwright pipeline | ~252 |
+| #5511 | 11:22 AM | ✅ | Extended guardrails to protect auth files from overwriting | ~181 |
+| #5510 | 11:21 AM | 🟣 | Enhanced SKILL.md with Playwright auth project configuration | ~228 |
+| #5427 | 10:05 AM | ✅ | Committed style fixes aligning SKILL.md with OpenSpec template standard | ~281 |
+
+### Apr 16, 2026
+
+| ID | Time | T | Title | Read |
+|----|------|---|-------|------|
+| #5997 | 9:59 AM | 🔵 | openspec-e2e skill uses openspec-pw CLI for parallel exploration | ~279 |
+| #5996 | " | 🔵 | openspec-e2e skill handles missing auth gracefully | ~172 |
 </claude-mem-context>

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

@@ -1,6 +1,6 @@
 ---
 name: openspec-e2e
-description: Run Playwright E2E verification for an OpenSpec change. Use when the user wants to validate that the implementation works end-to-end by running Playwright tests generated from the specs.
+description: "Run Playwright E2E verification. ONLY invoke when user explicitly says '/opsx:e2e' or 'run E2E tests'. Do NOT auto-trigger from explore/propose/apply/verify/continue stages — E2E is a separate workflow requiring explicit user request."
 license: MIT
 compatibility: Requires openspec CLI, Playwright (with browsers installed), /browse (gstack, for exploration), and @playwright/mcp (globally installed via `claude mcp add playwright npx @playwright/mcp@latest`, for test execution + Healer).
 metadata:
@@ -32,10 +32,64 @@ Two modes, same pipeline:
 | Change | `/opsx:e2e <name>` | OpenSpec specs           | `changes/<name>/<name>.spec.ts` |
 | All    | `/opsx:e2e all`    | sitemap + homepage crawl | `pages/*.ts` (Page Objects)     |
 
-Both modes update `app-knowledge.md` and `app-exploration.md`. All `.spec.ts` files run together as regression suite.
+Both modes update `app-knowledge.md` and `app-exploration.md`. Spec files are independent per change — `openspec-pw run <name>` runs only `changes/<name>/<name>.spec.ts`.
+
+> **⚠️ Full regression is opt-in only.** Default: `openspec-pw run <name>` → one spec file. Do NOT run `npx playwright test` (no file), `--only-changed`, or any command that executes multiple `.spec.ts` files unless the user explicitly requests it. This includes running the same command twice across different changes to simulate regression.
 
 > **Role mapping**: Planner (Step 4–5) → test-plan.md; Generator (Step 6) → `.spec.ts` + Page Objects; Healer (Step 9) → repairs failures via MCP.
 
+## Setup / Teardown
+
+Playwright supports two approaches for global lifecycle hooks. **openspec-playwright uses project dependencies** (the recommended approach) for full feature support.
+
+### Comparison
+
+| Feature | Project Dependencies | globalSetup/globalTeardown |
+|---------|---------------------|---------------------------|
+| HTML report visibility | ✅ Shown as project | ❌ Not shown |
+| Trace recording | ✅ Full support | ❌ Not supported |
+| Playwright fixtures | ✅ Fully supported | ❌ Not supported |
+| Browser via fixture | ✅ Automatic | ❌ Manual launch |
+
+### Current Implementation
+
+**Setup project** (enabled by default):
+- `tests/playwright/auth.setup.ts` — authenticates once, saves session to `./playwright/.auth/user.json`
+- All test projects depend on setup via `dependencies: ['setup']`
+
+**Teardown project** (optional, disabled by default):
+- `tests/playwright/global.teardown.ts` — runs AFTER all tests complete
+- Use for: database cleanup, uploaded file removal, cache invalidation
+- Enable by uncommenting in `playwright.config.ts`
+
+### When to Enable Teardown
+
+Enable teardown when your tests create persistent data that should be cleaned up:
+
+| Scenario | Action |
+|----------|--------|
+| Tests create database records | ✅ Enable teardown, add DB cleanup |
+| Tests upload files | ✅ Enable teardown, add file cleanup |
+| Tests only read data | ❌ No teardown needed |
+| Tests use ephemeral/isolated environments | ❌ No teardown needed |
+
+### Enabling Teardown
+
+1. Copy template: `cp templates/global.teardown.ts tests/playwright/global.teardown.ts`
+2. Customize cleanup logic in the file
+3. Uncomment in `playwright.config.ts`:
+   ```typescript
+   projects: [
+     { name: 'setup', testMatch: /.*\.setup\.ts/ },
+     { name: 'teardown', testMatch: /global\.teardown\.ts/ }, // Uncomment
+     {
+       name: 'chromium',
+       // ...
+       teardown: 'teardown', // Uncomment
+     },
+   ],
+   ```
+
 ## 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.

package/README.md

@@ -149,7 +149,7 @@ Edit `tests/playwright/credentials.yaml`:
 
 ```
 Templates (in npm package, installed to .claude/skills/openspec-e2e/templates/)
-  └── test-plan.md, report.md, playwright.config.ts, e2e-test.ts, app-exploration.md
+  └── test-plan.md, report.md, playwright.config.ts, e2e-test.ts, global.teardown.ts, app-exploration.md
 
 CLI (openspec-pw)
   ├── init       → Installs commands, skill & templates to .claude/
@@ -166,10 +166,11 @@ Claude Code (/opsx:e2e)
   └── @playwright/mcp                 → Healer Agent tools
 
 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)
+  ├── 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)
 
 Exploration (openspec/changes/<name>/specs/playwright/)
   ├── app-exploration.md → This change's routes + verified selectors

package/employee-standards.md

@@ -8,6 +8,8 @@
 
 本规范适用于 OpenSpec + openspec-playwright 项目（Claude Code 作为开发工具）。
 
+**项目规范**：动手前读 `openspec/config.yaml`（技术栈、结构、约定、约束等），无内容则忽略。
+
 E2E 工作流前提（由用户确保，非 AI 操作）：
 - gstack：`git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack && cd ~/.claude/skills/gstack && ./setup`（提供 `/browse` 探索 + `/qa` 浏览器验证）
 - OpenSpec CLI：`npm install -g @fission-ai/openspec && openspec init`（提供变更管理能力）
@@ -28,7 +30,7 @@ E2E 工作流前提（由用户确保，非 AI 操作）：
 ## 3. 上下文管理
 **文件读取完整**：超过 500 行的文件，不要假设单次读取覆盖完整内容——根据需要分次读取或编辑前重新读取完整文件。超过 10 条消息后，编辑任何文件前强制重新读取。
 
-**OpenSpec 阶段隔离**：`specs/playwright/`、`tests/playwright/`（seed 除外）和 `test-plan.md` 由 `/opsx:e2e` 显式触发，不由 explore/propose/continue/apply/verify 等阶段自动推断。E2E 工作流是独立的。
+**OpenSpec 阶段隔离**：所有阶段均由用户手动触发，不自动进入下一阶段。`/opsx:explore`、`/opsx:propose`、`/opsx:apply`、`/opsx:verify`、`/opsx:e2e` 均需用户明确调用。禁止在同一阶段内触发其他阶段（如 explore 阶段不能调用 apply，verify 阶段不能调用 e2e）。
 
 **重构前清死代码**：未使用的 import/export/prop/console.log 先删掉，单独提交，再做重构。
 
@@ -51,11 +53,11 @@ E2E 工作流前提（由用户确保，非 AI 操作）：
 ```
  1. 探索与提案
  2. 产品与架构评审（按需触发）
- 3. 设计审查
+ 3. 设计审查 → /plan-design-review
  4. 实现 → /opsx:apply
  5. 自审 → /opsx:verify
  6. E2E 测试 → /opsx:e2e <change-name> → /browse 探索 + /qa 验证
- 7. 发布 → /ship 或 /land-and-deploy
+ 7. 发布 → 用户手动 /ship 或 /land-and-deploy
  8. 迭代回顾 → /retro
 ```
 
@@ -68,13 +70,14 @@ E2E 工作流前提（由用户确保，非 AI 操作）：
 - `/plan-eng-review`：架构影响（新增服务、API 契约变更、数据模型重构）时
 
 **3. 设计审查**：在实现前进行设计评审，确保方案合理。评审通过后开始实现。
+- `/plan-design-review`：UI/UX 方案审查，评分各设计维度，确保用户体验达标
 
 **4. 实现**：执行 `/opsx:apply` 进行实现 → `lint + typecheck` 通过才算成功。
 
 **5. 自审**：`/opsx:verify` 自审实现代码，确保质量。
 
-**6. E2E 测试**：`/opsx:e2e <change-name>` 生成 Playwright 测试 → `/browse` 探索真实 DOM → Healer 自动修复 → `/qa` 真实浏览器验证。E2E 通过后进入发布环节。
+**6. E2E 测试**：`/opsx:e2e <change-name>` 生成 Playwright 测试 → `/browse` 探索真实 DOM → Healer 自动修复 → `/qa` 真实浏览器验证。E2E 通过后，由用户决定发布时机。
 
-**7. 发布**：`/ship`、`/land-and-deploy` 或 `/canary`。内部项目可能直接部署，无需走 PR 机制。
+**7. 发布**：由用户手动触发 `/ship`、`/land-and-deploy` 或 `/canary`。内部项目可能直接部署，无需走 PR 机制。
 
 **8. 迭代回顾**：`/retro`

package/package.json

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

package/templates/CLAUDE.md

@@ -3,5 +3,20 @@
 
 <!-- This section is auto-generated by claude-mem. Edit content outside the tags. -->
 
-*No recent activity*
+### Mar 27, 2026
+
+| ID | Time | T | Title | Read |
+|----|------|---|-------|------|
+| #5522 | 11:25 AM | 🔵 | Playwright auth setup template supports API and UI login | ~261 |
+| #5514 | 11:22 AM | 🟣 | Created credentials.yaml template for E2E test authentication | ~227 |
+| #5513 | " | 🟣 | Created auth.setup.ts template for Playwright Test Agents | ~276 |
+| #5390 | 9:48 AM | 🔄 | Refactored openspec-playwright from CLI to setup tool + Claude Code skill | ~209 |
+| #5375 | 9:44 AM | 🟣 | Created Playwright seed test template | ~224 |
+
+### Apr 16, 2026
+
+| ID | Time | T | Title | Read |
+|----|------|---|-------|------|
+| #6002 | 10:06 AM | 🔵 | openspec-e2e provides seed test template with anti-patterns documented | ~299 |
+| #5998 | 9:59 AM | 🔵 | OpenSpec Playwright auth.setup.ts uses session reuse pattern | ~202 |
 </claude-mem-context>

package/templates/global.teardown.ts

@@ -0,0 +1,74 @@
+// Global Teardown for Playwright Test Agents
+// This file runs AFTER all tests complete — use it to clean up test data.
+//
+// Setup:
+//   1. Uncomment the teardown project in playwright.config.ts
+//   2. Customize the cleanup logic below for your project
+//   3. Run: npx playwright test (teardown runs automatically after all tests)
+//
+// Common use cases:
+//   - Database cleanup: DELETE test records created during E2E runs
+//   - API cleanup: Call /api/test/cleanup endpoint
+//   - File cleanup: Remove uploaded test files or artifacts
+//   - Cache invalidation: Clear Redis/Memcached test keys
+
+import { test as teardown } from '@playwright/test';
+
+teardown('cleanup test data', async ({ request }) => {
+  const baseUrl = process.env.BASE_URL || 'http://localhost:3000';
+
+  // ─── Option 1: API-based cleanup (recommended) ───────────────────────────
+  // If your app has a test cleanup endpoint, call it here.
+  // Example: POST /api/test/cleanup with a secret token
+  //
+  // const cleanupToken = process.env.E2E_CLEANUP_TOKEN;
+  // if (cleanupToken) {
+  //   const res = await request.post(`${baseUrl}/api/test/cleanup`, {
+  //     headers: { 'X-Cleanup-Token': cleanupToken },
+  //   });
+  //   if (!res.ok()) {
+  //     console.warn(`Cleanup API returned ${res.status()}`);
+  //   }
+  // }
+
+  // ─── Option 2: Database cleanup (direct connection) ──────────────────────
+  // If you have direct DB access, clean up test records.
+  // Example using pg (PostgreSQL):
+  //
+  // import { Pool } from 'pg';
+  // const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+  // await pool.query(`
+  //   DELETE FROM orders WHERE email LIKE '%@test.example.com';
+  //   DELETE FROM users WHERE email LIKE '%@test.example.com';
+  // `);
+  // await pool.end();
+
+  // ─── Option 3: File cleanup ──────────────────────────────────────────────
+  // Remove test-generated files or uploads.
+  //
+  // import { rm } from 'fs/promises';
+  // await rm('./uploads/test-*', { recursive: true, force: true });
+
+  // ─── Option 4: Session/cache cleanup ─────────────────────────────────────
+  // Invalidate test sessions or cache entries.
+  //
+  // import Redis from 'ioredis';
+  // const redis = new Redis(process.env.REDIS_URL);
+  // const keys = await redis.keys('session:test-*');
+  // if (keys.length) await redis.del(...keys);
+  // await redis.quit();
+
+  console.log('✓ Global teardown completed');
+});
+
+// ─── Additional teardown tasks (optional) ──────────────────────────────────
+// Add more teardown blocks if you need to clean up different resources
+// in a specific order.
+
+// teardown('cleanup uploaded files', async ({ }) => {
+//   // File cleanup logic
+// });
+
+// teardown('invalidate cache', async ({ }) => {
+//   // Cache cleanup logic
+// });

package/templates/playwright.config.ts

@@ -90,9 +90,11 @@ export default defineConfig({
     reuseExistingServer: true,
   },
 
-  // Setup project for authentication (configured by openspec-pw run)
+  // Setup project (configured by openspec-pw run)
+  // Teardown project (optional): uncomment the two lines below + create tests/playwright/global.teardown.ts
   projects: [
     { name: 'setup', testMatch: /.*\.setup\.ts/ },
+    // { name: 'teardown', testMatch: /global\.teardown\.ts/ }, // Uncomment + create file
     {
       name: 'chromium',
       use: {
@@ -100,6 +102,7 @@ export default defineConfig({
         storageState: './playwright/.auth/user.json',
       },
       dependencies: ['setup'],
+      // teardown: 'teardown', // Uncomment when teardown project is enabled
     },
   ],
 });