openspec-playwright 0.1.16

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

@@ -0,0 +1,180 @@
+# 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/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "openspec-playwright",
+  "version": "0.1.16",
+  "description": "OpenSpec + Playwright E2E verification setup tool for Claude Code",
+  "type": "module",
+  "bin": {
+    "openspec-pw": "./bin/openspec-pw.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "release": "npm version patch && npm run build && git push && git push --tags"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "openspec",
+    "playwright",
+    "e2e",
+    "testing",
+    "claude-code",
+    "spec-driven",
+    "claude-code-skill"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/wxhou/openspec-playwright"
+  }
+}

package/schemas/playwright-e2e/schema.yaml

@@ -0,0 +1,56 @@
+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/schemas/playwright-e2e/templates/e2e-test.ts

@@ -0,0 +1,55 @@
+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/schemas/playwright-e2e/templates/playwright.config.ts

@@ -0,0 +1,52 @@
+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/schemas/playwright-e2e/templates/report.md

@@ -0,0 +1,27 @@
+# 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/schemas/playwright-e2e/templates/test-plan.md

@@ -0,0 +1,24 @@
+# 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/src/commands/doctor.ts

@@ -0,0 +1,114 @@
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+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 = process.env.HOME ?? '';
+  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);
+  }
+}