openspec-playwright 0.1.62 → 0.1.63

package/docs/plans/2026-03-26-openspec-playwright-design.md

@@ -1,180 +0,0 @@
-# OpenSpec + Playwright E2E Integration Design
-
-**Date:** 2026-03-26
-**Updated:** 2026-03-27
-**Status:** Implemented (MVP)
-
-## Overview
-
-Integrate OpenSpec's spec-driven development workflow with Playwright Test Agents' three-agent harness (Planner / Generator / Healer) for automated E2E verification.
-
-**Design decision:** Add a new independent command `/openspec-e2e` rather than hooking into `/opsx:verify`. This keeps concerns separated and allows each verification to be run independently.
-
-## Architecture
-
-```
-openspec-pw (CLI - setup only)
-  openspec-pw init    → installs Playwright + configures MCP + installs skill
-  openspec-pw doctor  → checks prerequisites
-
-/openspec-e2e (Claude Code skill - runs in Claude)
-  │
-  ├── 1. Read OpenSpec specs from openspec/changes/<name>/specs/
-  ├── 2. Planner Agent → specs/playwright/test-plan.md
-  ├── 3. Generator Agent → tests/playwright/<name>.spec.ts
-  └── 4. Healer Agent → run tests + auto-heal
-          │
-          └── Report: openspec/reports/playwright-e2e-<name>-<ts>.md
-```
-
-### Two Verification Layers
-
-| Layer | Command | Runs in | What it checks |
-|-------|---------|---------|----------------|
-| Static | `/opsx:verify` | Claude Code (OpenSpec skill) | Implementation matches artifacts |
-| E2E | `/openspec-e2e` | Claude Code (this skill) | App works when running |
-
-## Key Design Decisions
-
-- **Separate command, not hook**: `/openspec-e2e` is independent from `/opsx:verify`. Users run them separately or together.
-- **CLI as setup only**: The CLI does not run agents. It only installs/configures. Agents run in Claude Code.
-- **Playwright MCP**: Playwright agents use the MCP protocol, configured in `.claude/settings.local.json`.
-- **Seed test**: A `tests/playwright/seed.spec.ts` template guides the Generator agent.
-- **No re-exploration**: Planner uses OpenSpec specs directly as the source of truth, no app exploration needed.
-
-## CLI Commands
-
-```bash
-npm install -g wxhou/openspec-playwright
-
-openspec-pw init          # Setup: Playwright + MCP + skill + seed
-openspec-pw doctor        # Check prerequisites
-```
-
-## What `openspec-pw init` Does
-
-1. `npx playwright init-agents --loop=claude` — installs Playwright agents
-2. Configure Playwright MCP in `.claude/settings.local.json`
-3. Install skill: `.claude/skills/openspec-e2e/SKILL.md`
-4. Install command: `.claude/commands/opsx-e2e.md`
-5. Generate `tests/playwright/seed.spec.ts` template
-
-## SKILL.md Format
-
-Follows the OpenSpec standard format:
-- YAML frontmatter: `name`, `description`, `license`, `compatibility`, `metadata`
-- Bold step names: `**Step 1: Name**`
-- Output fenced code blocks: `**Output During Implementation**`, `**Output On Completion**`
-- Guardrails section
-- Fluid Workflow Integration section
-
-## Directory Structure
-
-```
-project/
-├── .claude/
-│   ├── skills/
-│   │   └── openspec-e2e/
-│   │       └── SKILL.md           # The /openspec-e2e skill
-│   ├── commands/
-│   │   └── opsx-e2e.md           # The /openspec-e2e command
-│   └── settings.local.json        # Playwright MCP config
-├── .github/                       # Playwright agent definitions
-│   └── ...
-├── openspec/
-│   ├── changes/<name>/
-│   │   ├── specs/
-│   │   │   ├── *.md              # OpenSpec propose output
-│   │   │   └── playwright/
-│   │   │       └── test-plan.md  # Planner output
-│   │   ├── design.md
-│   │   └── tasks.md
-│   └── reports/
-│       └── playwright-e2e-<name>-<ts>.md  # Healer report
-└── tests/playwright/
-    ├── seed.spec.ts               # Seed test template
-    └── <name>.spec.ts             # Generated tests
-```
-
-## SKILL.md Sections (OpenSpec Standard)
-
-```yaml
----
-name: openspec-e2e
-description: Run Playwright E2E verification for an OpenSpec change...
-license: MIT
-compatibility: Requires openspec CLI and Playwright Test Agents...
-metadata:
-  author: openspec-playwright
-  version: "0.1.0"
-  generatedBy: "openspec-playwright"
----
-
-Run Playwright E2E verification for an OpenSpec change...
-
-## Step 1: Identify the Change
-...
-
-## Step 2: Verify Prerequisites
-...
-
-**Output During Implementation**
-```markdown
-## E2E Verification: <name>
-Status: 🔄 In Progress
-```
-```
-
-**Output On Completion**
-```markdown
-## E2E Verify Report: <name>
-| Check | Status |
-|-------|--------|
-...
-```
-```
-
-**Guardrails**
-- Always read specs from `openspec/changes/<name>/specs/` as source of truth
-- Do not generate tests that contradict the specs
-- Cap auto-heal attempts at 3
-...
-
-**Fluid Workflow Integration**
-- Before: /opsx:propose → /opsx:apply
-- This skill: /openspec-e2e
-- After: /opsx:archive
-```
-
-## Error Handling
-
-| Scenario | Action |
-|----------|--------|
-| No specs found | Prompt to run `/opsx:propose` first |
-| Prerequisites missing | Prompt to run `openspec-pw init` |
-| Dev server not running | Prompt to start before proceeding |
-| Planner fails | Log error, mark FAILED |
-| Generator fails | Log error, mark FAILED |
-| Healer guardrails trigger | Report failures, mark PARTIAL |
-
-## Project Structure
-
-```
-openspec-playwright/
-├── src/
-│   ├── index.ts           # CLI entry
-│   └── commands/
-│       ├── init.ts        # openspec-pw init
-│       └── doctor.ts      # openspec-pw doctor
-├── .claude/
-│   ├── skills/
-│   │   └── openspec-e2e/
-│   │       └── SKILL.md  # The Claude Code skill
-│   └── commands/
-│       └── opsx-e2e.md    # The command file
-├── templates/
-│   └── seed.spec.ts       # Playwright seed test template
-├── README.md
-├── package.json
-└── tsconfig.json
-```

package/employee-standards.md

@@ -1,44 +0,0 @@
-# Claude Code Employee-Grade Configuration
-
-> 员工级行为规范，适用于 OpenSpec 项目。
-> 遵循 OpenSpec 规范驱动开发流程（详见 /openspec/）。
-
----
-
-## 一、代码质量
-
-**验证后才能报告成功**。运行项目的 linter 和 type checker：查看 `package.json`/`pyproject.toml`/`go.mod`/`Cargo.toml` 中的 scripts，使用对应的 `lint`/`typecheck` 命令。不存在时，明确告知用户，不得假装成功。
-
-**拒绝'够用就行'**。架构缺陷、状态重复、模式不一致——说出来并修复。高级工程师在 code review 中会拒绝什么？全部修掉。
-
-**安全防护**：防范 XSS、SQL 注入、命令注入（OWASP Top 10）。
-
----
-
-## 二、上下文管理
-
-**文件读取完整**：超过 500 行的文件，不要假设单次读取覆盖了完整文件——根据需要分次读取相关段落，或编辑前重新读取完整文件。超过 10 条消息后，编辑任何文件前强制重新读取。
-
-**重构前清死代码**：未使用的 import/export/prop/console.log 先删掉，单独提交，再做重构。
-
----
-
-## 三，大规模任务
-
-**子 Agent 并行化**：任务涉及超过 5 个独立文件时，启动并行子 agent（每个 5-8 个文件），每个拥有独立 token budget。
-
-**分阶段执行**：每个阶段不超过 5 个文件，完成后验证，等待用户批准再继续。
-
----
-
-## 四、工具限制
-
-**搜索维度完整**：重命名函数/类型/变量时，必须覆盖：直接调用、类型级引用、字符串字面量、`require()`/`import`、barrel file、测试 mock。不得假设一次 grep 覆盖所有情况。
-
----
-
-## 五、编辑安全
-
-**验证后才算完成**：编辑后再次读取确认变更正确应用。同一文件连续编辑不超过 3 次，中间必须验证。变更完成后，明确告知用户可能遗漏的区域（动态引用、测试 mock 等），提示人工复查。
-
-**不主动推送**：除非用户明确要求，否则不推送代码。

package/openspec/schemas/playwright-e2e/schema.yaml

@@ -1,56 +0,0 @@
-name: playwright-e2e
-version: 1
-description: Playwright E2E verification for an OpenSpec change
-
-artifacts:
-  - id: test-plan
-    generates: specs/playwright/test-plan.md
-    description: Test plan derived from change specs
-    template: test-plan.md
-    instruction: |
-      Generate a test plan from the change specs. Each functional requirement becomes
-      one or more test cases.
-
-      For each test case, specify:
-      - **Test name** (kebab-case): what it verifies
-      - **Route/Page**: which URL or UI component it targets
-      - **Prerequisites**: auth role needed (user/admin/guest/none)
-      - **Happy path**: main user flow to verify
-      - **Error paths**: key error conditions to verify
-
-      Mark tests with role tags: `@role(user)`, `@role(admin)`, `@role(guest)`, `@role(none)`.
-      Mark auth requirement: `@auth(required)` or `@auth(none)`.
-
-  - id: e2e-test
-    generates: tests/playwright/<change>.spec.ts
-    description: Playwright E2E test suite
-    template: e2e-test.ts
-    instruction: |
-      Generate Playwright tests from the test-plan.
-
-      Rules:
-      - Follow the page object pattern from seed.spec.ts
-      - Prefer `data-testid` selectors, fall back to semantic selectors
-      - Each test maps to one test case from the test-plan
-      - Use `@project(user)` / `@project(admin)` for role-specific tests
-      - Cover happy path AND key error paths
-      - Name tests descriptively: `test('shows error on invalid input')`
-
-  - id: playwright-config
-    generates: playwright.config.ts
-    description: Playwright config with webServer and auth projects
-    template: playwright.config.ts
-    instruction: |
-      Configure Playwright for E2E testing.
-
-      - Set webServer command and url from BASE_URL
-      - Set baseURL for all tests
-      - Add auth setup project if credentials are configured
-      - Preserve any existing config fields (browsers, retries, etc.)
-      - Do NOT overwrite existing projects unless they conflict
-
-apply:
-  requires: [test-plan, e2e-test]
-  instruction: |
-    Run tests via: openspec-pw run <change-name>
-    Analyze results and generate report at openspec/reports/playwright-e2e-<change>-<timestamp>.md

package/openspec/schemas/playwright-e2e/templates/e2e-test.ts

@@ -1,55 +0,0 @@
-import { test, expect, Page } from '@playwright/test';
-
-// ──────────────────────────────────────────────
-// Test plan: <change-name>
-// Generated from: openspec/changes/<change-name>/specs/playwright/test-plan.md
-// ──────────────────────────────────────────────
-
-const BASE_URL = process.env.BASE_URL || 'http://localhost:3000';
-
-/**
- * Page Object Pattern - add selectors for your app's pages
- */
-class AppPage {
-  constructor(private page: Page) {}
-
-  async goto(path: string = '/') {
-    await this.page.goto(`${BASE_URL}${path}`);
-  }
-
-  async getByTestId(id: string) {
-    return this.page.locator(`[data-testid="${id}"]`);
-  }
-
-  async waitForToast(message?: string) {
-    if (message) {
-      await this.page.getByText(message, { state: 'visible' }).waitFor();
-    }
-  }
-}
-
-function createPage(page: Page): AppPage {
-  return new AppPage(page);
-}
-
-// ──────────────────────────────────────────────
-// Tests - generated from test-plan.md
-// Customize selectors and assertions to match your app
-// ──────────────────────────────────────────────
-
-test.describe('<change-name>: E2E verification', () => {
-
-  test.beforeEach(async ({ page }) => {
-    const app = createPage(page);
-    await app.goto('/');
-  });
-
-  // TODO: Add test cases from specs/playwright/test-plan.md
-  // Example:
-  // test('shows expected content on page load', async ({ page }) => {
-  //   const app = createPage(page);
-  //   await app.goto('/');
-  //   await expect(app.getByTestId('main-heading')).toBeVisible();
-  // });
-
-});

package/openspec/schemas/playwright-e2e/templates/playwright.config.ts

@@ -1,52 +0,0 @@
-import { defineConfig, devices } from '@playwright/test';
-import { readFileSync, existsSync } from 'fs';
-import { join } from 'path';
-
-// ─── BASE_URL: prefer env, then seed.spec.ts, then default ───
-const seedSpec = join(__dirname, '../tests/playwright/seed.spec.ts');
-let baseUrl = process.env.BASE_URL || 'http://localhost:3000';
-if (existsSync(seedSpec)) {
-  const content = readFileSync(seedSpec, 'utf-8');
-  const m = content.match(/BASE_URL\s*=\s*process\.env\.BASE_URL\s*\|\|\s*['"]([^'"]+)['"]/);
-  if (m) baseUrl = m[1];
-}
-
-// ─── Dev command: detect from package.json scripts ───
-const pkgPath = join(__dirname, '../package.json');
-let devCmd = 'npm run dev';
-if (existsSync(pkgPath)) {
-  const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
-  const scripts = pkg.scripts ?? {};
-  // Prefer in order: dev, start, serve, preview
-  devCmd = scripts.dev ?? scripts.start ?? scripts.serve ?? scripts.preview ?? devCmd;
-}
-
-export default defineConfig({
-  testDir: '../tests/playwright',
-  // Keep test artifacts inside tests/playwright/ instead of project root
-  outputDir: '../tests/playwright/test-results',
-  fullyParallel: true,
-  forbidOnly: !!process.env.CI,
-  retries: process.env.CI ? 2 : 0,
-  workers: process.env.CI ? 1 : undefined,
-  reporter: 'list',
-
-  use: {
-    baseURL: baseUrl,
-    trace: 'on-first-retry',
-  },
-
-  // Dev server lifecycle - Playwright starts/stops automatically
-  webServer: {
-    command: devCmd,
-    url: baseUrl,
-    timeout: 120000,
-    reuseExistingServer: true,
-  },
-
-  // Setup project for authentication (configured by openspec-pw run)
-  projects: [
-    { name: 'setup', testMatch: /.*\.setup\.ts/ },
-    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
-  ],
-});

package/openspec/schemas/playwright-e2e/templates/report.md

@@ -1,27 +0,0 @@
-# E2E Verify Report: <change-name>
-
-**Change**: `<change-name>`
-**Generated**: `<timestamp>`
-**Auth**: `<required|none>`
-
-## Summary
-
-| Check | Status |
-|-------|--------|
-| Tests Run | <N> |
-| Passed | <X> |
-| Failed | <Y> |
-| Auto-heals | <Z> |
-| Final Status | <PASS|FAIL> |
-
-## Test Results
-
-<!-- List each test with pass/fail status -->
-
-## Auto-Heal Log
-
-<!-- If heals were performed, document each attempt -->
-
-## Recommendations
-
-<!-- For failed tests, specific file:line references and fixes -->

package/openspec/schemas/playwright-e2e/templates/test-plan.md

@@ -1,24 +0,0 @@
-# Test Plan: <change-name>
-
-Generated from: `openspec/changes/<change-name>/specs/`
-
-## Auth Requirements
-
-<!-- Mark auth requirements based on specs analysis: -->
-- Auth required: **yes / no**
-- Roles needed: none / user / admin / user+admin
-
-## Test Cases
-
-### <test-name>
-
-- **Route**: `/<page>`
-- **Role**: `@role(<role>)`
-- **Auth**: `@auth(required|none)`
-
-**Happy path:**
-- Step 1: ...
-- Step 2: ...
-
-**Error paths:**
-- ...

package/release-notes.md

@@ -1,5 +0,0 @@
-## What's Changed
-
-- chore: bump version to 0.1.62
-
-**Full Changelog**: https://github.com/wxhou/openspec-playwright/releases/tag/v0.1.62

package/src/commands/doctor.ts

@@ -1,115 +0,0 @@
-import { existsSync, readFileSync } from 'fs';
-import { join } from 'path';
-import { homedir } from 'os';
-import { execSync } from 'child_process';
-import chalk from 'chalk';
-
-export async function doctor() {
-  console.log(chalk.blue('\n🔍 OpenSpec + Playwright E2E Prerequisites Check\n'));
-
-  const projectRoot = process.cwd();
-  let allOk = true;
-
-  // Node.js
-  console.log(chalk.blue('─── Node.js ───'));
-  try {
-    const node = execSync('node --version', { encoding: 'utf-8' }).trim();
-    console.log(chalk.green(`  ✓ Node.js ${node}`));
-  } catch {
-    console.log(chalk.red('  ✗ Node.js not found'));
-    allOk = false;
-  }
-
-  // npm
-  console.log(chalk.blue('\n─── npm ───'));
-  try {
-    const npm = execSync('npm --version', { encoding: 'utf-8' }).trim();
-    console.log(chalk.green(`  ✓ npm ${npm}`));
-  } catch {
-    console.log(chalk.red('  ✗ npm not found'));
-    allOk = false;
-  }
-
-  // OpenSpec
-  console.log(chalk.blue('\n─── OpenSpec ───'));
-  const hasOpenSpec = existsSync(join(projectRoot, 'openspec'));
-  if (hasOpenSpec) {
-    console.log(chalk.green('  ✓ OpenSpec initialized'));
-  } else {
-    console.log(chalk.red('  ✗ OpenSpec not initialized'));
-    console.log(chalk.gray('    Run: openspec init'));
-    allOk = false;
-  }
-
-  // Playwright browsers
-  console.log(chalk.blue('\n─── Playwright Browsers ───'));
-  try {
-    const pw = execSync('npx playwright --version', { encoding: 'utf-8' }).trim();
-    console.log(chalk.green(`  ✓ Playwright ${pw}`));
-  } catch {
-    console.log(chalk.red('  ✗ Playwright browsers not installed'));
-    console.log(chalk.gray('    Run: npx playwright install --with-deps'));
-    allOk = false;
-  }
-
-  // Playwright MCP (global)
-  console.log(chalk.blue('\n─── Playwright MCP ───'));
-  const homeDir = homedir();
-  const claudeJsonPath = join(homeDir, '.claude.json');
-  let mcpInstalled = false;
-  if (existsSync(claudeJsonPath)) {
-    try {
-      const claudeJson = JSON.parse(readFileSync(claudeJsonPath, 'utf-8'));
-      const globalMcp = claudeJson?.mcpServers ?? {};
-      const localMcp = claudeJson?.projects?.[projectRoot]?.mcpServers ?? {};
-      if (globalMcp['playwright'] || localMcp['playwright']) {
-        mcpInstalled = true;
-      }
-    } catch {
-      // ignore
-    }
-  }
-  if (mcpInstalled) {
-    console.log(chalk.green('  ✓ Playwright MCP installed globally'));
-  } else {
-    console.log(chalk.red('  ✗ Playwright MCP not configured'));
-    console.log(chalk.gray('    Run: openspec-pw init'));
-    allOk = false;
-  }
-
-  // Skill
-  console.log(chalk.blue('\n─── Claude Code Skill ───'));
-  const hasSkill = existsSync(
-    join(projectRoot, '.claude', 'skills', 'openspec-e2e', 'SKILL.md')
-  );
-  if (hasSkill) {
-    console.log(chalk.green('  ✓ /openspec-e2e skill installed'));
-  } else {
-    console.log(chalk.red('  ✗ Skill not installed'));
-    console.log(chalk.gray('    Run: openspec-pw init'));
-    allOk = false;
-  }
-
-  // Seed test
-  console.log(chalk.blue('\n─── Seed Test ───'));
-  const hasSeed = existsSync(
-    join(projectRoot, 'tests', 'playwright', 'seed.spec.ts')
-  );
-  if (hasSeed) {
-    console.log(chalk.green('  ✓ seed.spec.ts found'));
-  } else {
-    console.log(chalk.yellow('  ⚠ seed.spec.ts not found (optional)'));
-    console.log(chalk.gray('    Run: openspec-pw init'));
-  }
-
-  // Summary
-  console.log(chalk.blue('\n─── Summary ───'));
-  if (allOk) {
-    console.log(chalk.green('  ✅ All prerequisites met!\n'));
-    console.log(chalk.gray('  Run: /opsx:e2e <change-name> in Claude Code\n'));
-  } else {
-    console.log(chalk.red('  ❌ Some prerequisites are missing\n'));
-    console.log(chalk.gray('  Run: openspec-pw init to fix\n'));
-    process.exit(1);
-  }
-}