openspec-playwright 0.1.24 → 0.1.26

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

@@ -5,7 +5,7 @@ license: MIT
 compatibility: Requires openspec CLI, Playwright (with browsers installed), and @playwright/mcp (globally installed via claude mcp add).
 metadata:
   author: openspec-playwright
-  version: "2.0"
+  version: "2.1"
 ---
 
 Run Playwright E2E verification for an OpenSpec change. This skill reads specs from `openspec/changes/<name>/specs/`, generates test files, detects auth requirements, and delegates test execution to the `openspec-pw run` CLI.
@@ -56,16 +56,47 @@ Create `openspec/changes/<name>/specs/playwright/test-plan.md` by:
 
 **Idempotency**: If test-plan.md already exists → read it, use it, do NOT regenerate unless user explicitly asks.
 
-### 4. Generate test file
+### 4. Generate test file (LLM-driven)
+
+Use your file writing capability to create `tests/playwright/<name>.spec.ts`.
+
+**Read inputs first**:
+- `openspec/changes/<name>/specs/playwright/test-plan.md` — test cases with `@role` and `@auth` tags
+- `tests/playwright/seed.spec.ts` — code pattern, BASE_URL, and page object structure
+
+**Generate Playwright code** for each test case from test-plan.md:
+- Follow the same structure as `seed.spec.ts`
+- Prefer `data-testid` selectors; fallback to `input[name="..."]` or semantic selectors
+- Include **happy path** AND **error/edge cases**
+- Use `test.describe(...)` for grouping related tests
+- Each test: `test('描述性名称', async ({ page }) => { ... })`
+- Add `@project(user)` / `@project(admin)` on role-specific tests
+
+**Example pattern** (from seed.spec.ts):
+```typescript
+import { test, expect } from '@playwright/test';
+
+const BASE_URL = process.env.BASE_URL || 'http://localhost:3000';
+
+test.describe('Feature Name', () => {
+  test('happy path - action succeeds', async ({ page }) => {
+    await page.goto(`${BASE_URL}/path`);
+    await page.getByTestId('element').click();
+    await expect(page.getByTestId('result')).toBeVisible();
+  });
+
+  test('error case - invalid input shows message', async ({ page }) => {
+    await page.goto(`${BASE_URL}/path`);
+    await page.getByTestId('input').fill('invalid');
+    await page.getByTestId('submit').click();
+    await expect(page.getByTestId('error')).toContainText('Error text');
+  });
+});
+```
 
-Create `tests/playwright/<name>.spec.ts`:
-- Follow the page object pattern from `tests/playwright/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(admin)` / `@project(user)` for role-specific tests
-- Cover happy path AND key error paths
+**Write the file** using the Write tool. If the file already exists → diff against test-plan, add only missing test cases, preserve existing implementations.
 
-**Idempotency**: If test file exists → diff against test-plan, add only missing test cases, preserve existing implementations.
+**Selector guidance**: If no `data-testid` exists in the app, prefer `getByRole`, `getByLabel`, `getByText` over fragile selectors like CSS paths.
 
 ### 5. Configure auth (if required)
 
@@ -115,10 +146,20 @@ If tests fail → analyze failures, use Playwright MCP tools to inspect UI state
 
 ### 8. Report results
 
-Read the report generated by `openspec-pw run` and present it to the user:
+Read the report at `openspec/reports/playwright-e2e-<name>-<timestamp>.md`.
+
+**Present results to user**:
 - Summary table (tests run, passed, failed, duration, final status)
 - Any auto-heal notes
-- Recommendations for failed tests (with specific file:line references)
+- Recommendations for failed tests (with specific `file:line` references)
+
+**Update tasks.md** (if all tests pass):
+- Read `openspec/changes/<name>/tasks.md`
+- Find tasks related to E2E testing (look for `[ ]` items mentioning "test", "e2e", "playwright", "verify")
+- Append a verification note: e.g. `✅ Verified via Playwright E2E (<timestamp>)`
+- Write the updated content back using the Edit tool
+
+**If tests fail**: Suggest which spec items remain unverified and what needs fixing.
 
 ---
 
@@ -133,6 +174,7 @@ Read the report generated by `openspec-pw run` and present it to the user:
 
 - Read specs from `openspec/changes/<name>/specs/` as source of truth
 - Do NOT generate tests that contradict the specs
+- **DO generate real, runnable Playwright test code** — not placeholders or TODO comments. Every test case in test-plan.md must produce an actual `test(...)` block.
 - Do NOT overwrite files outside: `specs/playwright/`, `tests/playwright/`, `openspec/reports/`, `playwright.config.ts`, `tests/auth.setup.ts`
 - Cap auto-heal at 3 attempts
 - If no change specified → always ask user to select

package/package.json

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

package/release-notes.md

@@ -1,5 +1,5 @@
 ## What's Changed
 
-- fix: playwright.config.ts detects package.json in subdirectories
+- feat(skill): LLM-driven test generation and tasks.md integration
 
-**Full Changelog**: https://github.com/wxhou/openspec-playwright/releases/tag/v0.1.24
+**Full Changelog**: https://github.com/wxhou/openspec-playwright/releases/tag/v0.1.26

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

@@ -1,8 +1,8 @@
 import { defineConfig, devices } from '@playwright/test';
-import { readFileSync, existsSync } from 'fs';
+import { readFileSync, existsSync, readdirSync } from 'fs';
 import { join } from 'path';
 
-// ─── Detect project root (find package.json walking up) ───
+// ─── Detect project root (where openspec/ lives) ───
 function findProjectRoot(start: string): string {
   let dir = start;
   for (let i = 0; i < 10; i++) {
@@ -14,7 +14,35 @@ function findProjectRoot(start: string): string {
   return start;
 }
 
+// ─── Find the npm project root (where package.json with scripts lives) ───
+// Checks project root first, then immediate subdirectories
+function findNpmRoot(projectRoot: string): string {
+  const pkgAtRoot = join(projectRoot, 'package.json');
+  if (existsSync(pkgAtRoot)) {
+    const pkg = JSON.parse(readFileSync(pkgAtRoot, 'utf-8'));
+    if (pkg.scripts?.dev || pkg.scripts?.start || pkg.scripts?.serve || pkg.scripts?.preview) {
+      return projectRoot;
+    }
+  }
+  // Check immediate subdirectories (e.g., openspec/ and imap/ are siblings)
+  try {
+    const entries = readdirSync(projectRoot, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory() || entry.name.startsWith('.') || entry.name === 'node_modules') continue;
+      const subPkg = join(projectRoot, entry.name, 'package.json');
+      if (existsSync(subPkg)) {
+        const sub = JSON.parse(readFileSync(subPkg, 'utf-8'));
+        if (sub.scripts?.dev || sub.scripts?.start) {
+          return join(projectRoot, entry.name);
+        }
+      }
+    }
+  } catch {}
+  return projectRoot;
+}
+
 const projectRoot = findProjectRoot(__dirname);
+const npmRoot = findNpmRoot(projectRoot);
 
 // ─── BASE_URL: prefer env, then seed.spec.ts, then default ───
 const seedSpec = join(projectRoot, 'tests', 'playwright', 'seed.spec.ts');
@@ -25,13 +53,17 @@ if (existsSync(seedSpec)) {
   if (m) baseUrl = m[1];
 }
 
-// ─── Dev command: detect from package.json scripts ───
-const pkgPath = join(projectRoot, 'package.json');
+// ─── Dev command: detect from the npm project ───
 let devCmd = 'npm run dev';
-if (existsSync(pkgPath)) {
-  const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+const npmPkg = join(npmRoot, 'package.json');
+if (existsSync(npmPkg)) {
+  const pkg = JSON.parse(readFileSync(npmPkg, 'utf-8'));
   const scripts = pkg.scripts ?? {};
   devCmd = scripts.dev ?? scripts.start ?? scripts.serve ?? scripts.preview ?? devCmd;
+  // Prefix with cd if npmRoot differs from projectRoot
+  if (npmRoot !== projectRoot) {
+    devCmd = `cd ${npmRoot} && ${devCmd}`;
+  }
 }
 
 export default defineConfig({