openspec-playwright 0.1.16

package/src/commands/init.ts

@@ -0,0 +1,209 @@
+import { execSync } from 'child_process';
+import {
+  existsSync,
+  readFileSync,
+  writeFileSync,
+  mkdirSync,
+} from 'fs';
+import { join } from 'path';
+import chalk from 'chalk';
+import { readFile } from 'fs/promises';
+
+const TEMPLATE_DIR = new URL('../../templates', import.meta.url).pathname;
+const SCHEMA_DIR = new URL('../../schemas', import.meta.url).pathname;
+const SKILL_SRC = new URL('../../.claude/skills/openspec-e2e', import.meta.url).pathname;
+const CMD_SRC = new URL('../../.claude/commands/opsx/e2e.md', import.meta.url).pathname;
+
+export interface InitOptions {
+  change?: string;
+  mcp?: boolean;
+  seed?: boolean;
+}
+
+export async function init(options: InitOptions) {
+  console.log(chalk.blue('\n🔧 OpenSpec + Playwright E2E Setup\n'));
+
+  const projectRoot = process.cwd();
+
+  // 1. Check prerequisites
+  console.log(chalk.blue('─── Prerequisites ───'));
+
+  const hasNode = execCmd('node --version', 'Node.js', true);
+  const hasNpm = execCmd('npm --version', 'npm', true);
+  const hasOpenspec = execCmd('npx openspec --version 2>/dev/null || echo "not found"', 'OpenSpec', true);
+
+  if (!hasNode || !hasNpm) {
+    console.log(chalk.red('  ✗ Node.js/npm is required'));
+    process.exit(1);
+  }
+  console.log(chalk.green('  ✓ Node.js and npm found'));
+
+  // 2. Check OpenSpec
+  if (!existsSync(join(projectRoot, 'openspec'))) {
+    console.log(chalk.yellow('\n⚠ OpenSpec not initialized. Run these commands first:'));
+    console.log(chalk.gray('  npm install -g @fission-ai/openspec'));
+    console.log(chalk.gray('  openspec init'));
+    console.log(chalk.gray('  openspec config profile core'));
+    console.log(chalk.gray('  openspec update\n'));
+    console.log(chalk.gray('  Then run openspec-pw init again.\n'));
+    return;
+  }
+  console.log(chalk.green('  ✓ OpenSpec initialized'));
+
+  // 3. Install Playwright MCP (global)
+  if (options.mcp !== false) {
+    console.log(chalk.blue('\n─── Installing Playwright MCP ───'));
+
+    // Check if playwright MCP already exists in global config
+    const claudeJsonPath = join(process.env.HOME ?? '', '.claude.json');
+    const claudeJson = existsSync(claudeJsonPath) ? JSON.parse(readFileSync(claudeJsonPath, 'utf-8')) : {};
+    const globalMcp = claudeJson?.mcpServers ?? {};
+    const localMcp = claudeJson?.projects?.[projectRoot]?.mcpServers ?? {};
+
+    if (globalMcp['playwright'] || localMcp['playwright']) {
+      console.log(chalk.green('  ✓ Playwright MCP already installed'));
+    } else {
+      try {
+        execSync('claude mcp add playwright npx @playwright/mcp@latest', {
+          cwd: projectRoot,
+          stdio: 'inherit',
+        });
+        console.log(chalk.green('  ✓ Playwright MCP installed globally'));
+        console.log(chalk.gray('  (Restart Claude Code to activate)'));
+      } catch {
+        console.log(chalk.yellow('  ⚠ Failed to run claude mcp add'));
+        console.log(chalk.gray('  Run manually: claude mcp add playwright npx @playwright/mcp@latest'));
+        console.log(chalk.gray('  (Restart Claude Code to activate the MCP server)'));
+      }
+    }
+  }
+
+  // 4. Copy skill files
+  console.log(chalk.blue('\n─── Installing Claude Code Skill ───'));
+  await installSkill(projectRoot);
+
+  // 5. Install OpenSpec schema
+  console.log(chalk.blue('\n─── Installing OpenSpec Schema ───'));
+  await installSchema(projectRoot);
+
+  // 6. Generate seed test
+  if (options.seed !== false) {
+    console.log(chalk.blue('\n─── Generating Seed Test ───'));
+    await generateSeedTest(projectRoot);
+  }
+
+  // 7. Summary
+  console.log(chalk.blue('\n─── Summary ───'));
+  console.log(chalk.green('  ✓ Setup complete!\n'));
+
+  console.log(chalk.bold('Next steps:'));
+  console.log(chalk.gray('  1. Install Playwright browsers: npx playwright install --with-deps'));
+  console.log(chalk.gray('  2. Customize tests/playwright/credentials.yaml with your test user'));
+  console.log(chalk.gray('  3. Set credentials: export E2E_USERNAME=xxx E2E_PASSWORD=yyy'));
+  console.log(chalk.gray('  4. Run auth setup: npx playwright test --project=setup'));
+  console.log(chalk.gray('  5. In Claude Code, run: /opsx:e2e <change-name>'));
+  console.log(chalk.gray('  6. Or: openspec-pw doctor to verify setup\n'));
+
+  console.log(chalk.bold('How it works:'));
+  console.log(chalk.gray('  /opsx:e2e reads your OpenSpec specs and runs Playwright'));
+  console.log(chalk.gray('  E2E tests through a three-agent pipeline:'));
+  console.log(chalk.gray('  Planner → Generator → Healer\n'));
+}
+
+async function installSkill(projectRoot: string) {
+  const skillsDir = join(projectRoot, '.claude', 'skills');
+  const skillDir = join(skillsDir, 'openspec-e2e');
+  const cmdDir = join(projectRoot, '.claude', 'commands');
+
+  // Copy skill
+  mkdirSync(skillDir, { recursive: true });
+  const skillContent = await readFile(SKILL_SRC + '/SKILL.md', 'utf-8');
+  writeFileSync(join(skillDir, 'SKILL.md'), skillContent);
+  console.log(chalk.green(`  ✓ Skill installed: /openspec-e2e`));
+
+  // Copy command
+  mkdirSync(join(cmdDir, 'opsx'), { recursive: true });
+  const cmdContent = await readFile(CMD_SRC, 'utf-8');
+  writeFileSync(join(cmdDir, 'opsx', 'e2e.md'), cmdContent);
+  console.log(chalk.green(`  ✓ Command installed: /opsx:e2e`));
+}
+
+async function generateSeedTest(projectRoot: string) {
+  const testsDir = join(projectRoot, 'tests', 'playwright');
+  mkdirSync(testsDir, { recursive: true });
+
+  const seedPath = join(testsDir, 'seed.spec.ts');
+  if (existsSync(seedPath)) {
+    console.log(chalk.gray('  - seed.spec.ts already exists, skipping'));
+  } else {
+    const seedContent = await readFile(TEMPLATE_DIR + '/seed.spec.ts', 'utf-8');
+    writeFileSync(seedPath, seedContent);
+    console.log(chalk.green('  ✓ Generated: tests/playwright/seed.spec.ts'));
+  }
+
+  // Generate auth.setup.ts
+  const authSetupPath = join(testsDir, 'auth.setup.ts');
+  if (existsSync(authSetupPath)) {
+    console.log(chalk.gray('  - auth.setup.ts already exists, skipping'));
+  } else {
+    const authContent = await readFile(TEMPLATE_DIR + '/auth.setup.ts', 'utf-8');
+    writeFileSync(authSetupPath, authContent);
+    console.log(chalk.green('  ✓ Generated: tests/playwright/auth.setup.ts'));
+  }
+
+  // Generate credentials.yaml
+  const credsPath = join(testsDir, 'credentials.yaml');
+  if (existsSync(credsPath)) {
+    console.log(chalk.gray('  - credentials.yaml already exists, skipping'));
+  } else {
+    const credsContent = await readFile(TEMPLATE_DIR + '/credentials.yaml', 'utf-8');
+    writeFileSync(credsPath, credsContent);
+    console.log(chalk.green('  ✓ Generated: tests/playwright/credentials.yaml'));
+  }
+
+  console.log(chalk.gray('  (Customize BASE_URL and credentials for your app)'));
+}
+
+async function installSchema(projectRoot: string) {
+  const schemaSrc = SCHEMA_DIR + '/playwright-e2e';
+  const schemaDest = join(projectRoot, 'openspec', 'schemas', 'playwright-e2e');
+  const schemaFiles = ['schema.yaml'];
+
+  for (const file of schemaFiles) {
+    const src = join(schemaSrc, file);
+    const dest = join(schemaDest, file);
+    if (existsSync(src)) {
+      writeFileSync(dest, readFileSync(src));
+    }
+  }
+
+  // Copy templates
+  const templatesSrc = join(schemaSrc, 'templates');
+  const templatesDest = join(schemaDest, 'templates');
+  mkdirSync(templatesDest, { recursive: true });
+  const templateFiles = ['test-plan.md', 'report.md', 'e2e-test.ts', 'playwright.config.ts'];
+  for (const file of templateFiles) {
+    const src = join(templatesSrc, file);
+    const dest = join(templatesDest, file);
+    if (existsSync(src)) {
+      writeFileSync(dest, readFileSync(src));
+    }
+  }
+
+  console.log(chalk.green('  ✓ Schema installed: openspec/schemas/playwright-e2e/'));
+}
+
+function execCmd(
+  cmd: string,
+  name: string,
+  silent = false
+): boolean {
+  try {
+    execSync(cmd, { stdio: 'pipe' });
+    if (!silent) console.log(chalk.green(`  ✓ ${name} found`));
+    return true;
+  } catch {
+    if (!silent) console.log(chalk.yellow(`  ⚠ ${name} not found`));
+    return false;
+  }
+}

package/src/commands/run.ts

@@ -0,0 +1,172 @@
+import { execSync } from 'child_process';
+import { existsSync, mkdirSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import chalk from 'chalk';
+
+export interface RunOptions {
+  project?: string;
+  timeout?: number;
+}
+
+const REPORTS_DIR = 'openspec/reports';
+
+export async function run(changeName: string, options: RunOptions) {
+  console.log(chalk.blue(`\n🔍 OpenSpec Playwright E2E: ${changeName}\n`));
+
+  const projectRoot = process.cwd();
+
+  // 1. Verify test file exists
+  const testFile = join(projectRoot, 'tests', 'playwright', `${changeName}.spec.ts`);
+  if (!existsSync(testFile)) {
+    console.log(chalk.red(`  ✗ Test file not found: tests/playwright/${changeName}.spec.ts`));
+    console.log(chalk.gray('  Run /opsx:e2e first to generate tests.\n'));
+    process.exit(1);
+  }
+
+  // 2. Setup reports dir
+  mkdirSync(join(projectRoot, REPORTS_DIR), { recursive: true });
+
+  // 3. Detect auth credentials
+  const credsPath = join(projectRoot, 'tests', 'playwright', 'credentials.yaml');
+  const hasCredentials = existsSync(credsPath);
+  if (!hasCredentials) {
+    console.log(chalk.yellow('  ⚠ No credentials.yaml found — tests may fail if auth required'));
+  }
+
+  // 4. Run Playwright tests with output capture
+  console.log(chalk.blue('─── Running Tests ───'));
+
+  const args = ['npx', 'playwright', 'test', testFile, '--reporter=list'];
+  if (options.project) {
+    args.push('--project=' + options.project);
+  }
+
+  let testOutput = '';
+  let exitCode = 0;
+
+  try {
+    // Capture stdout to detect port mismatch
+    const result = execSync(args.join(' '), {
+      cwd: projectRoot,
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+      timeout: (options.timeout ?? 300) * 1000,
+    });
+    testOutput = result;
+  } catch (err: unknown) {
+    exitCode = 1;
+    const error = err as { stdout?: string; stderr?: string; status?: number };
+    testOutput = (error.stdout ?? '') + (error.stderr ?? '');
+  }
+
+  // 5. Parse results from Playwright output
+  const results = parsePlaywrightOutput(testOutput);
+
+  // 6. Detect port mismatch
+  if (testOutput.includes('net::ERR_CONNECTION_REFUSED') ||
+      testOutput.includes('listen EADDRINUSE') ||
+      testOutput.includes('0.0.0.0:')) {
+    console.log(chalk.yellow('  ⚠ Port mismatch detected. Check BASE_URL and webServer port.'));
+  }
+
+  // 7. Generate markdown report
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+  const reportPath = join(projectRoot, REPORTS_DIR, `playwright-e2e-${changeName}-${timestamp}.md`);
+
+  const reportContent = generateReport(changeName, timestamp, results);
+  writeFileSync(reportPath, reportContent);
+
+  // 8. Summary
+  console.log(chalk.blue('\n─── Results ───'));
+  console.log(`  Tests: ${results.total}  ` +
+    chalk.green(`✓ ${results.passed}`) + '  ' +
+    (results.failed > 0 ? chalk.red(`✗ ${results.failed}`) : chalk.gray(`✗ ${results.failed}`)) +
+    `  Duration: ${results.duration}`);
+
+  console.log(chalk.blue('\n─── Report ───'));
+  console.log(chalk.green(`  ✓ ${reportPath}\n`));
+
+  if (results.failed > 0) {
+    console.log(chalk.red(`✗ E2E verification FAILED (${results.failed} tests)`));
+    process.exit(1);
+  } else {
+    console.log(chalk.green('✓ E2E verification PASSED'));
+  }
+}
+
+interface TestResults {
+  total: number;
+  passed: number;
+  failed: number;
+  duration: string;
+  tests: Array<{ name: string; status: 'passed' | 'failed' }>;
+}
+
+function parsePlaywrightOutput(output: string): TestResults {
+  const results: TestResults = { total: 0, passed: 0, failed: 0, duration: '0s', tests: [] };
+
+  // Parse: "✓ my-test (1.2s)" or "✗ my-test (0.5s)"
+  const testLineRegex = /([✓✗x]) (.+?) \((\d+(?:\.\d+)?[a-z]+)\)/g;
+  let match;
+  while ((match = testLineRegex.exec(output)) !== null) {
+    const status = match[1] === '✓' ? 'passed' : 'failed';
+    results.tests.push({ name: match[2], status });
+    results.total++;
+    if (status === 'passed') results.passed++;
+    else results.failed++;
+  }
+
+  // Parse duration: "N tests ran (1m 30s)" or "1 test ran (5s)"
+  const durationMatch = output.match(/\d+ tests? ran \((\d+(?:m\s*\d+)?s?)\)/);
+  if (durationMatch) results.duration = durationMatch[1];
+
+  return results;
+}
+
+function generateReport(changeName: string, timestamp: string, results: TestResults): string {
+  const lines: string[] = [
+    `# E2E Verify Report: ${changeName}`,
+    '',
+    `**Change**: \`${changeName}\``,
+    `**Generated**: ${timestamp.replace('T', ' ').slice(0, 16)} UTC`,
+    '',
+    '## Summary',
+    '',
+    '| Check | Status |',
+    '|-------|--------|',
+    `| Tests Run | ${results.total} |`,
+    `| Passed | ${results.passed} |`,
+    `| Failed | ${results.failed} |`,
+    `| Duration | ${results.duration} |`,
+    `| Final Status | ${results.failed === 0 ? '✅ PASS' : '❌ FAIL'} |`,
+    '',
+    '## Test Results',
+    '',
+  ];
+
+  if (results.tests.length === 0) {
+    lines.push('_(No test output captured — check Playwright configuration)_', '');
+  } else {
+    for (const test of results.tests) {
+      const icon = test.status === 'passed' ? '✅' : '❌';
+      lines.push(`- ${test.name}: ${icon} ${test.status}`);
+    }
+    lines.push('');
+  }
+
+  lines.push('## Recommendations', '');
+  if (results.failed > 0) {
+    lines.push(
+      'Review failed tests above. Common fixes:',
+      '- Update selectors if UI changed (use `data-testid` attributes)',
+      '- Adjust BASE_URL in seed.spec.ts if port differs',
+      '- Set E2E_USERNAME/E2E_PASSWORD if auth is required',
+      '- Check `npx playwright show-report` for screenshots',
+      ''
+    );
+  } else {
+    lines.push('All tests passed. No action needed.', '');
+  }
+
+  return lines.join('\n');
+}

package/src/commands/update.ts

@@ -0,0 +1,130 @@
+import { execSync } from 'child_process';
+import {
+  existsSync,
+  readFileSync,
+  writeFileSync,
+  mkdirSync,
+} from 'fs';
+import { join } from 'path';
+import chalk from 'chalk';
+
+const SKILL_SRC = new URL('../../.claude/skills/openspec-e2e', import.meta.url).pathname;
+const CMD_SRC = new URL('../../.claude/commands/opsx/e2e.md', import.meta.url).pathname;
+const SCHEMA_DIR = new URL('../../schemas', import.meta.url).pathname;
+
+export interface UpdateOptions {
+  cli?: boolean;
+  skill?: boolean;
+}
+
+export async function update(options: UpdateOptions) {
+  console.log(chalk.blue('\n🔄 Updating OpenSpec + Playwright E2E\n'));
+
+  const projectRoot = process.cwd();
+
+  // 1. Update CLI tool (from git latest, not npm)
+  if (options.cli !== false) {
+    console.log(chalk.blue('─── Updating CLI ───'));
+    try {
+      execSync(
+        'npm install -g https://github.com/wxhou/openspec-playwright/archive/refs/heads/main.tar.gz',
+        { stdio: 'inherit' }
+      );
+      console.log(chalk.green('  ✓ CLI updated to latest commit'));
+    } catch {
+      console.log(chalk.yellow('  ⚠ Failed to update CLI'));
+      console.log(
+        chalk.gray('  Run manually: npm install -g https://github.com/wxhou/openspec-playwright/archive/refs/heads/main.tar.gz')
+      );
+    }
+  }
+
+  // 2. Update skill and command from git tarball (latest commit, not npm package)
+  if (options.skill !== false) {
+    console.log(chalk.blue('\n─── Updating Skill & Command ───'));
+    try {
+      // Download tarball to temp file and extract
+      const tmpSkill = '/tmp/openspec-e2e-skill.tar.gz';
+      const tmpDir = '/tmp/openspec-e2e-update';
+
+      execSync(
+        `curl -sL https://github.com/wxhou/openspec-playwright/archive/refs/heads/main.tar.gz -o ${tmpSkill}`,
+        { stdio: 'pipe' }
+      );
+      // Clean and re-extract to avoid stale files from previous runs
+      execSync(`rm -rf ${tmpDir} && mkdir -p ${tmpDir} && tar -xzf ${tmpSkill} -C ${tmpDir} --strip-components=1`, { stdio: 'pipe' });
+
+      const skillSrc = `${tmpDir}/.claude/skills/openspec-e2e/SKILL.md`;
+      const cmdSrc = `${tmpDir}/.claude/commands/opsx/e2e.md`;
+      const schemaSrc = `${tmpDir}/schemas/playwright-e2e`;
+
+      installSkillFrom(skillSrc, cmdSrc, schemaSrc, projectRoot);
+      console.log(chalk.green('  ✓ Skill & command updated to latest'));
+    } catch {
+      console.log(chalk.yellow('  ⚠ Failed to update skill/command from git'));
+      console.log(chalk.gray('  Running from npm package instead...'));
+      installSkill(projectRoot);
+    }
+  }
+
+  // Summary
+  console.log(chalk.blue('\n─── Summary ───'));
+  console.log(chalk.green('  ✓ Update complete!\n'));
+
+  console.log(chalk.bold('Restart Claude Code to use the updated skill.'));
+  console.log(chalk.gray('  Then run /opsx:e2e <change-name> to verify.\n'));
+}
+
+function installSkill(projectRoot: string) {
+  installSkillFrom(
+    SKILL_SRC,
+    CMD_SRC,
+    SCHEMA_DIR + '/playwright-e2e',
+    projectRoot
+  );
+}
+
+function installSkillFrom(skillSrc: string, cmdSrc: string, schemaSrc: string, projectRoot: string) {
+  const skillDir = join(projectRoot, '.claude', 'skills', 'openspec-e2e');
+  const cmdDir = join(projectRoot, '.claude', 'commands');
+
+  mkdirSync(skillDir, { recursive: true });
+  const skillContent = readFileSync(skillSrc, 'utf-8');
+  writeFileSync(join(skillDir, 'SKILL.md'), skillContent);
+  console.log(chalk.green(`  ✓ Skill updated: /openspec-e2e`));
+
+  mkdirSync(join(cmdDir, 'opsx'), { recursive: true });
+  const cmdContent = readFileSync(cmdSrc, 'utf-8');
+  writeFileSync(join(cmdDir, 'opsx', 'e2e.md'), cmdContent);
+  console.log(chalk.green(`  ✓ Command updated: /opsx:e2e`));
+
+  installSchemaFrom(schemaSrc, projectRoot);
+}
+
+function installSchemaFrom(schemaSrc: string, projectRoot: string) {
+  const schemaDest = join(projectRoot, 'openspec', 'schemas', 'playwright-e2e');
+
+  mkdirSync(schemaDest, { recursive: true });
+  // Copy schema.yaml
+  const schemaYamlSrc = join(schemaSrc, 'schema.yaml');
+  if (existsSync(schemaYamlSrc)) {
+    writeFileSync(join(schemaDest, 'schema.yaml'), readFileSync(schemaYamlSrc));
+  }
+
+  // Copy templates
+  const templatesSrc = join(schemaSrc, 'templates');
+  const templatesDest = join(schemaDest, 'templates');
+  if (existsSync(templatesSrc)) {
+    mkdirSync(templatesDest, { recursive: true });
+    const templateFiles = ['test-plan.md', 'report.md', 'e2e-test.ts', 'playwright.config.ts'];
+    for (const file of templateFiles) {
+      const src = join(templatesSrc, file);
+      const dest = join(templatesDest, file);
+      if (existsSync(src)) {
+        writeFileSync(dest, readFileSync(src));
+      }
+    }
+  }
+
+  console.log(chalk.green('  ✓ Schema updated: openspec/schemas/playwright-e2e/'));
+}

package/src/index.ts

@@ -0,0 +1,47 @@
+import { readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { Command } from 'commander';
+import { init } from './commands/init.js';
+import { update } from './commands/update.js';
+import { doctor } from './commands/doctor.js';
+import { run } from './commands/run.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, '../package.json'), 'utf-8'));
+
+const program = new Command();
+
+program
+  .name('openspec-pw')
+  .description('OpenSpec + Playwright E2E verification setup tool')
+  .version(pkg.version);
+
+program
+  .command('init')
+  .description('Initialize OpenSpec + Playwright E2E integration in the current project')
+  .option('-c, --change <name>', 'default change name', 'default')
+  .option('--no-mcp', 'skip Playwright MCP configuration')
+  .option('--no-seed', 'skip seed test generation')
+  .action(init);
+
+program
+  .command('doctor')
+  .description('Check if all prerequisites are installed')
+  .action(doctor);
+
+program
+  .command('update')
+  .description('Update the CLI tool and skill to the latest version')
+  .option('--no-cli', 'skip CLI update')
+  .option('--no-skill', 'skip skill/command update')
+  .action(update);
+
+program
+  .command('run <change-name>')
+  .description('Run Playwright E2E tests for an OpenSpec change')
+  .option('-p, --project <name>', 'Playwright project to run (e.g., user, admin)')
+  .option('-t, --timeout <seconds>', 'Test timeout in seconds', '300')
+  .action(run);
+
+program.parse();

package/templates/auth.setup.ts

@@ -0,0 +1,77 @@
+// Auth setup for Playwright Test Agents
+// This file authenticates once and saves the session state to .auth/user.json
+// All subsequent tests reuse this state — no repeated logins needed.
+//
+// Setup:
+//   1. Set credentials: export E2E_USERNAME=xxx E2E_PASSWORD=yyy
+//   2. Run: npx playwright test --project=setup
+//      (if UI login: browser opens — log in manually once)
+//   3. Credentials are saved — tests auto-use the saved session
+//
+// To switch users, update credentials and re-run step 2.
+//
+// For multi-user testing, add more setup blocks with different storageState paths.
+
+import { test as setup, expect } from '@playwright/test';
+
+// ─── API Login (preferred) ───────────────────────────────────────────────────
+// If your app has a login API, configure it in tests/playwright/credentials.yaml:
+//   api: /api/auth/login
+// Then this block runs automatically.
+
+setup('authenticate via API', async ({ page }) => {
+  const baseUrl = process.env.BASE_URL || 'http://localhost:3000';
+  const username = process.env.E2E_USERNAME;
+  const password = process.env.E2E_PASSWORD;
+
+  if (!username || !password) {
+    console.warn('⚠ E2E_USERNAME or E2E_PASSWORD not set — skipping API auth');
+    return;
+  }
+
+  const res = await page.request.post(`${baseUrl}/api/auth/login`, {
+    data: { username, password },
+  });
+
+  if (!res.ok()) {
+    throw new Error(`API login failed (${res.status()}). Check credentials.`);
+  }
+
+  await page.context().storageState({ path: './playwright/.auth/user.json' });
+});
+
+// ─── UI Login (fallback) ─────────────────────────────────────────────────────
+// If no login API, use UI login. Update selectors to match your login page.
+
+setup('authenticate via UI', async ({ page }) => {
+  const baseUrl = process.env.BASE_URL || 'http://localhost:3000';
+  const username = process.env.E2E_USERNAME;
+  const password = process.env.E2E_PASSWORD;
+
+  if (!username || !password) {
+    console.warn('⚠ E2E_USERNAME or E2E_PASSWORD not set — skipping UI auth');
+    return;
+  }
+
+  // TODO: Update these selectors to match your login page
+  // Preferred: add data-testid attributes to your login form fields
+  await page.goto(`${baseUrl}/login`);
+
+  // Common selector patterns (uncomment the one that matches):
+  await page.fill('[data-testid="username"]', username);
+  // await page.fill('input[name="email"]', username);
+  // await page.fill('input[type="email"]', username);
+
+  await page.fill('[data-testid="password"]', password);
+  // await page.fill('input[name="password"]', password);
+
+  await page.click('[data-testid="login-button"]');
+  // await page.click('button[type="submit"]');
+  // await page.click('text=Sign In');
+
+  // Wait for redirect after login (adjust pattern to your app)
+  await page.waitForURL(/\/(dashboard|home|profile)/);
+  await expect(page).not.toHaveURL(/.*login.*|.*signin.*/);
+
+  await page.context().storageState({ path: './playwright/.auth/user.json' });
+});

package/templates/credentials.yaml

@@ -0,0 +1,33 @@
+# Playwright E2E Test Credentials
+# Customize these for your application.
+#
+# Setup:
+#   1. Fill in your test user credentials below
+#   2. Export credentials as environment variables:
+#        export E2E_USERNAME=your-email@example.com
+#        export E2E_PASSWORD=your-password
+#   3. For multi-user tests, add more users with unique names
+#   4. Run: npx playwright test --project=setup
+#
+# API login (preferred): Set `api` to your login endpoint
+#   The auth.setup.ts will call POST {api} with username + password
+#   Example: api: /api/auth/login
+#
+# UI login (fallback): Leave `api` empty
+#   The auth.setup.ts will open the browser and fill the login form
+#   Make sure selectors in auth.setup.ts match your login page
+
+api: /api/auth/login  # Leave empty for UI login
+
+users:
+  - name: user
+    username: test@example.com
+    password: testpassword123
+
+  # Multi-user example (uncomment and configure for role-based tests):
+  # - name: admin
+  #   username: admin@example.com
+  #   password: adminpassword123
+  # - name: premium
+  #   username: premium@example.com
+  #   password: premiumpassword123