openspec-playwright 0.3.6 → 0.3.7

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

@@ -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

@@ -51,7 +51,7 @@ E2E 工作流前提（由用户确保，非 AI 操作）：
 ```
  1. 探索与提案
  2. 产品与架构评审（按需触发）
- 3. 设计审查
+ 3. 设计审查 → /plan-design-review + /frontend-design
  4. 实现 → /opsx:apply
  5. 自审 → /opsx:verify
  6. E2E 测试 → /opsx:e2e <change-name> → /browse 探索 + /qa 验证
@@ -68,6 +68,7 @@ E2E 工作流前提（由用户确保，非 AI 操作）：
 - `/plan-eng-review`：架构影响（新增服务、API 契约变更、数据模型重构）时
 
 **3. 设计审查**：在实现前进行设计评审，确保方案合理。评审通过后开始实现。
+- `/plan-design-review`：UI/UX 方案审查，评分各设计维度，确保用户体验达标
 
 **4. 实现**：执行 `/opsx:apply` 进行实现 → `lint + typecheck` 通过才算成功。
 

package/package.json

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

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
     },
   ],
 });