Initial commit

skills/testing/playwright-e2e-automation/workflow/phase-1-discovery.md

@@ -0,0 +1,72 @@
+# Phase 1: Application Discovery & Version Detection
+
+**Purpose**: Understand the application architecture, detect framework versions, and determine optimal Playwright setup
+
+## Steps
+
+### 1. Detect application type and versions
+- Read package.json to identify frameworks (React, Vite, Next.js, Express, etc.)
+- Check for common files (vite.config.ts, next.config.js, app.js, index.html)
+- Identify build tools and dev server configuration
+- Extract installed package versions for version-aware configuration
+
+### 2. Consult version compatibility database
+- Load `data/framework-versions.yaml` compatibility rules
+- Match installed versions against version ranges using semver
+- Determine appropriate templates for each framework version
+- Identify potential breaking changes or incompatibilities
+- **Example**: Tailwind v4 detected → use `@import` syntax, not `@tailwind`
+
+### 3. Validate application access
+- Check if dev server is running (ports 3000, 5173, 8080, etc.)
+- If not running, determine how to start it (npm run dev, npm start, etc.)
+- Verify application loads successfully
+
+### 4. Map critical user journeys
+- Identify key pages/routes from routing configuration
+- Detect authentication flows
+- Find form submissions and interactive elements
+- Locate API integrations
+
+## Version Detection Logic
+
+```typescript
+// Load compatibility database
+const versionDb = parseYAML('data/framework-versions.yaml');
+
+// Detect versions
+const detectedVersions = {
+  tailwind: detectVersion(deps.tailwindcss, versionDb.tailwindcss),
+  react: detectVersion(deps.react, versionDb.react),
+  vite: detectVersion(deps.vite, versionDb.vite),
+};
+
+// Select appropriate templates
+const templates = {
+  css: detectedVersions.tailwind?.templates.css || 'templates/css/vanilla.css',
+  postcss: detectedVersions.tailwind?.templates.postcss_config,
+  playwright: 'templates/playwright.config.template.ts',
+};
+```
+
+## Output
+
+Application profile with:
+- Framework type and versions
+- URLs and ports
+- Test targets
+- Selected templates
+
+## Common Issues
+
+**Unrecognized framework**
+- Ask user to specify app type and dev server command manually
+- Use generic static site configuration as fallback
+
+**Missing package.json**
+- Check for other indicators (index.html, etc.)
+- Prompt user for application details
+
+## Transition
+
+Proceed to Phase 2 (Playwright Installation) with version-aware configuration

skills/testing/playwright-e2e-automation/workflow/phase-2-setup.md

@@ -0,0 +1,72 @@
+# Phase 2: Playwright Installation & Setup
+
+**Purpose**: Install Playwright and generate optimal configuration
+
+## Steps
+
+### 1. Install Playwright
+
+```bash
+npm init playwright@latest -- --yes
+# Installs Playwright, test runners, and browsers (Chromium, Firefox, WebKit)
+```
+
+### 2. Generate playwright.config.ts
+
+Configure based on app type:
+- Set base URL (http://localhost:5173 for Vite, etc.)
+- Configure viewport sizes:
+  - Desktop: 1280x720
+  - Tablet: 768x1024
+  - Mobile: 375x667
+- Set screenshot directory: `screenshots/{test-name}/{timestamp}/`
+- Enable trace on failure for debugging
+- Configure retries (2 attempts) and timeout (30s)
+
+### 3. Set up directory structure
+
+```
+tests/
+├── setup/
+│   └── global-setup.ts    # Start dev server
+├── pages/
+│   └── *.page.ts         # Page object models
+├── specs/
+│   └── *.spec.ts         # Test specifications
+└── utils/
+    └── screenshot-helper.ts
+
+screenshots/
+├── baselines/            # Reference images
+├── current/              # Latest test run
+└── diffs/                # Visual comparisons
+```
+
+### 4. Integrate with existing test setup
+
+- Add playwright scripts to package.json
+- Configure alongside Vitest/Jest (no conflicts)
+- Set up TypeScript types for Playwright
+
+## Output
+
+Fully configured Playwright environment with version-appropriate templates
+
+## Performance
+
+~2-3 minutes for installation and setup (one-time)
+
+## Common Issues
+
+**Installation fails**
+- Check Node version (>=16)
+- Retry with --force
+- Suggest manual installation if network issues
+
+**Browser download fails**
+- Check disk space (~500MB needed)
+- Try installing specific browser: `npx playwright install chromium`
+
+## Transition
+
+Proceed to Phase 2.5 (Pre-flight Health Check)

skills/testing/playwright-e2e-automation/workflow/phase-2.5-preflight.md

@@ -0,0 +1,113 @@
+# Phase 2.5: Pre-flight Health Check
+
+**Purpose**: Validate app loads correctly before running full test suite - catches configuration errors early
+
+## Steps
+
+### 1. Launch browser and attempt to load app
+
+```typescript
+const browser = await chromium.launch();
+const page = await browser.newPage();
+
+try {
+  const response = await page.goto(baseURL, { timeout: 30000 });
+
+  if (!response || !response.ok()) {
+    throw new Error(`App returned ${response?.status()}`);
+  }
+} catch (error) {
+  // Analyze error and provide guidance
+}
+```
+
+### 2. Monitor console for critical errors
+
+- Listen for console errors during page load
+- Collect all error messages for pattern analysis
+- Wait 2-3 seconds to let errors surface
+
+### 3. Analyze errors against known patterns
+
+Load `data/error-patterns.yaml` error database and match against known patterns:
+
+**Example patterns detected**:
+- Tailwind v4 syntax mismatch: "Cannot apply unknown utility class"
+- PostCSS plugin error: "Plugin tailwindcss not found"
+- Missing dependencies: "Module not found"
+
+### 4. Provide actionable diagnostics
+
+```
+❌ Pre-flight check failed: Critical errors detected
+
+Issue: Tailwind CSS v4 syntax mismatch
+Root cause: CSS file uses @tailwind directives but v4 requires @import
+
+Fix:
+1. Update src/index.css (or globals.css):
+   Change from: @tailwind base; @tailwind components; @tailwind utilities;
+   Change to: @import "tailwindcss";
+
+2. Update postcss.config.js:
+   Change from: plugins: { tailwindcss: {} }
+   Change to: plugins: { '@tailwindcss/postcss': {} }
+
+3. Restart dev server: npm run dev
+
+Documentation: https://tailwindcss.com/docs/upgrade-guide
+```
+
+### 5. Auto-fix if possible, otherwise halt with guidance
+
+- For known issues with clear fixes, offer to fix automatically
+- For ambiguous issues, halt and require user intervention
+- Prevent running 10+ tests that will all fail due to one config issue
+
+## Error Pattern Analysis
+
+```typescript
+function analyzeErrors(consoleErrors) {
+  const errorPatterns = parseYAML('data/error-patterns.yaml');
+  const issues = [];
+
+  for (const error of consoleErrors) {
+    for (const [name, pattern] of Object.entries(errorPatterns.css_errors)) {
+      if (pattern.pattern.test(error) ||
+          pattern.alternative_patterns?.some(alt => alt.test(error))) {
+        issues.push({
+          name,
+          severity: pattern.severity,
+          diagnosis: pattern.diagnosis,
+          recovery_steps: pattern.recovery_steps,
+          documentation: pattern.documentation,
+        });
+      }
+    }
+  }
+
+  return {
+    critical: issues.filter(i => i.severity === 'critical'),
+    allIssues: issues,
+  };
+}
+```
+
+## Benefits
+
+- **Fast feedback**: 2-3 seconds vs 30+ seconds for full test suite
+- **Clear guidance**: Specific fix steps, not generic "tests failed"
+- **Prevents cascade failures**: One config error won't fail all 10 tests
+- **Educational**: Explains what went wrong and why
+
+## Output
+
+Health check passed, or detailed error diagnostics with fix steps
+
+## Performance
+
+~2-5 seconds
+
+## Transition
+
+If health check passes, proceed to Phase 3 (Test Generation). If fails, provide fixes and halt.

skills/testing/playwright-e2e-automation/workflow/phase-3-generation.md

@@ -0,0 +1,68 @@
+# Phase 3: Test Generation
+
+**Purpose**: Create screenshot-enabled test suite covering critical workflows
+
+## Steps
+
+### 1. Generate page object models
+
+- Create POM classes for each major page/component
+- Define locators using best practices (getByRole, getByLabel, getByText)
+- Add screenshot capture methods to each POM
+
+### 2. Create test specifications
+
+Generate tests for each critical user journey with screenshot capture at key points:
+- Initial page load
+- Before interaction (button click, form fill)
+- After interaction
+- Error states
+- Success states
+
+### 3. Add accessibility checks
+
+- Integrate axe-core for automated a11y testing
+- Capture accessibility violations in screenshots
+- Generate accessibility reports
+
+### 4. Set up screenshot helpers
+
+```typescript
+// templates/screenshot-helper.ts
+export async function captureWithContext(
+  page: Page,
+  name: string,
+  context?: string
+) {
+  const timestamp = new Date().toISOString();
+  const path = `screenshots/current/${name}-${timestamp}.png`;
+  await page.screenshot({ path, fullPage: true });
+  return { path, context, timestamp };
+}
+```
+
+## Output
+
+Complete test suite with screenshot automation
+
+## Test Coverage
+
+Aim for critical user journeys (80/20 rule):
+- Core functionality tests
+- Authentication flows
+- Form submissions
+- Key interactions
+
+## Common Issues
+
+**Too many tests generated**
+- Focus on critical paths
+- Prioritize user journeys over edge cases
+
+**Locators not found**
+- Use semantic locators (getByRole, getByLabel)
+- Add test IDs as last resort
+
+## Transition
+
+Proceed to Phase 4 (Screenshot Capture & Execution)

skills/testing/playwright-e2e-automation/workflow/phase-4-capture.md

@@ -0,0 +1,65 @@
+# Phase 4: Screenshot Capture & Execution
+
+**Purpose**: Run tests and capture comprehensive visual data
+
+## Steps
+
+### 1. Execute test suite
+
+```bash
+npx playwright test --project=chromium --headed=false
+```
+
+### 2. Capture screenshots systematically
+
+- Full-page screenshots for layout analysis
+- Element-specific screenshots for component testing
+- Different viewports (desktop, tablet, mobile)
+- Different states (hover, focus, active, disabled)
+
+### 3. Organize screenshot artifacts
+
+- Group by test name
+- Add timestamp and viewport metadata
+- Generate index file for easy navigation
+
+### 4. Handle failures gracefully
+
+On test failure:
+- Capture additional debug screenshots
+- Save page HTML snapshot
+- Record network activity
+- Generate Playwright trace for replay
+
+## Output
+
+Organized screenshot directory with metadata:
+
+```
+screenshots/
+├── current/
+│   ├── home-page-load-2024-01-15T10-30-00.png
+│   ├── home-page-after-click-2024-01-15T10-30-05.png
+│   └── index.json (metadata)
+└── ...
+```
+
+## Performance
+
+~30-60 seconds for typical app (5-10 tests)
+
+## Common Issues
+
+**Screenshot capture fails**
+- Increase timeout
+- Add explicit waits
+- Capture partial screenshot on failure
+
+**Tests timeout**
+- Check dev server is running
+- Increase test timeout
+- Add explicit wait conditions
+
+## Transition
+
+Proceed to Phase 5 (Visual Analysis)

skills/testing/playwright-e2e-automation/workflow/phase-5-analysis.md

@@ -0,0 +1,67 @@
+# Phase 5: Visual Analysis
+
+**Purpose**: Use LLM vision capabilities to analyze screenshots and identify issues
+
+## Steps
+
+### 1. Batch screenshot analysis
+
+Read all captured screenshots and ask LLM to identify:
+- UI bugs (broken layouts, overlapping elements, cut-off text)
+- Accessibility issues (low contrast, missing labels, improper heading hierarchy)
+- Responsive problems (elements not scaling, overflow issues)
+- Missing or misaligned elements
+- Unexpected visual artifacts
+
+### 2. Categorize findings
+
+- **Critical**: App is broken/unusable (crashes, white screen, no content)
+- **High**: Major UI bugs affecting core functionality
+- **Medium**: Visual inconsistencies that impact UX
+- **Low**: Minor alignment or styling issues
+
+### 3. Generate issue descriptions
+
+For each issue:
+- Natural language description
+- Screenshot reference with highlighted problem area
+- Affected viewport/browser if relevant
+- User impact assessment
+
+## Output
+
+Structured list of visual issues with severity ratings:
+
+```markdown
+## Visual Issues Found
+
+### Critical (1)
+- White screen on mobile viewport - App fails to render
+
+### High (2)
+- Button text cut off at 375px width
+- Form labels overlap input fields
+
+### Medium (3)
+- Header alignment inconsistent
+- ...
+```
+
+## Performance
+
+~5-10 seconds per screenshot for LLM analysis
+
+## Common Issues
+
+**Analysis fails**
+- Retry analysis
+- Skip corrupted images
+- Validate PNG format
+
+**Too many false positives**
+- Adjust analysis prompts
+- Focus on critical issues first
+
+## Transition
+
+Proceed to Phase 6 (Regression Detection)

skills/testing/playwright-e2e-automation/workflow/phase-6-regression.md

@@ -0,0 +1,77 @@
+# Phase 6: Regression Detection
+
+**Purpose**: Compare current screenshots against baselines to detect changes
+
+## Steps
+
+### 1. Load baseline images
+
+- Check if baselines exist in screenshots/baselines/
+- If first run, current screenshots become baselines
+- If baselines exist, proceed to comparison
+
+### 2. Perform pixel-level comparison
+
+```typescript
+import { compareScreenshots } from 'playwright-core/lib/utils';
+
+const diff = await compareScreenshots(
+  baselinePath,
+  currentPath,
+  diffPath,
+  { threshold: 0.2 } // 20% difference threshold
+);
+```
+
+### 3. Generate visual diff reports
+
+- Create side-by-side comparison images
+- Highlight changed regions in red
+- Calculate difference percentage
+- Classify changes:
+  - **Expected**: Intentional changes (new features, fixes)
+  - **Suspicious**: Unintended changes requiring review
+  - **Critical**: Major regressions (broken features)
+
+### 4. Update baselines if approved
+
+Ask user: "Accept these changes as new baseline?"
+- If yes, copy current → baselines
+- If no, flag as regressions needing fixes
+
+## Output
+
+Visual regression report with diff images:
+
+```markdown
+## Regression Report
+
+### Changed Screenshots (3)
+
+| Screenshot | Diff % | Classification |
+|------------|--------|----------------|
+| home-page | 5% | Expected |
+| form-page | 25% | Suspicious |
+| mobile-nav | 45% | Critical |
+
+See screenshots/diffs/ for visual comparisons.
+```
+
+## Performance
+
+~1-2 seconds per image pair
+
+## Common Issues
+
+**No baselines exist**
+- Current screenshots become baselines automatically
+- Message: "No baselines found. Current screenshots saved as baselines."
+
+**False positive diffs**
+- Adjust threshold (default 20%)
+- Ignore dynamic content areas
+- Use stable test data
+
+## Transition
+
+Proceed to Phase 7 (Fix Recommendation Generation)

skills/testing/playwright-e2e-automation/workflow/phase-7-fixes.md

@@ -0,0 +1,72 @@
+# Phase 7: Fix Recommendation Generation
+
+**Purpose**: Map visual issues to source code and generate actionable fixes
+
+## Steps
+
+### 1. Correlate issues with source code
+
+- Use test file metadata to identify component under test
+- Search codebase for relevant files (component, styles, layout)
+- Match visual issues to likely code locations
+
+### 2. Generate fix recommendations
+
+For each issue, provide:
+- **Issue description**: Natural language explanation
+- **File location**: `src/components/Button.tsx:45`
+- **Current code**: Snippet showing problematic code
+- **Recommended fix**: Specific code change
+- **Reasoning**: Why this fix addresses the issue
+
+### 3. Prioritize fixes
+
+- Sort by severity (critical → low)
+- Group related fixes (same component, same file)
+- Estimate complexity (simple CSS tweak vs. complex refactor)
+
+### 4. Format as actionable report
+
+```markdown
+# Visual Bug Fix Recommendations
+
+## Critical Issues (2)
+
+### 1. Button text cut off on mobile viewport
+**Location**: `src/components/Button.tsx:45`
+**Screenshot**: `screenshots/current/button-mobile-1234.png`
+
+**Current Code**:
+```tsx
+<button className="px-4 py-2 text-lg">
+  {children}
+</button>
+```
+
+**Recommended Fix**:
+```tsx
+<button className="px-4 py-2 text-sm sm:text-lg truncate max-w-full">
+  {children}
+</button>
+```
+
+**Reasoning**: Fixed width and font size cause overflow on narrow viewports. Added responsive text sizing and truncation.
+```
+
+## Output
+
+fix-recommendations.md with prioritized, actionable fixes
+
+## Common Issues
+
+**Can't find source file**
+- Ask user for component location
+- Search by component name patterns
+
+**Multiple possible fixes**
+- Present options with trade-offs
+- Recommend simplest solution
+
+## Transition
+
+Proceed to Phase 8 (Test Suite Export)

skills/testing/playwright-e2e-automation/workflow/phase-8-export.md

@@ -0,0 +1,82 @@
+# Phase 8: Test Suite Export
+
+**Purpose**: Provide production-ready test suite for ongoing use
+
+## Steps
+
+### 1. Export test files
+
+- Copy generated tests to project's tests/ directory
+- Ensure proper TypeScript types and imports
+- Add comments explaining test purpose
+
+### 2. Create README documentation
+
+```markdown
+# Playwright E2E Test Suite
+
+## Running Tests
+```bash
+npm run test:e2e              # Run all e2e tests
+npm run test:e2e:headed       # Run with browser UI
+npm run test:e2e:debug        # Run with Playwright Inspector
+```
+
+## Screenshot Management
+- Baselines: `screenshots/baselines/`
+- Current: `screenshots/current/`
+- Diffs: `screenshots/diffs/`
+
+## Updating Baselines
+```bash
+npm run test:e2e:update-snapshots
+```
+```
+
+### 3. Add npm scripts
+
+```json
+{
+  "scripts": {
+    "test:e2e": "playwright test",
+    "test:e2e:headed": "playwright test --headed",
+    "test:e2e:debug": "playwright test --debug",
+    "test:e2e:update-snapshots": "playwright test --update-snapshots"
+  }
+}
+```
+
+### 4. Document CI/CD integration
+
+- Provide GitHub Actions workflow example
+- Explain screenshot artifact storage
+- Show how to update baselines in CI
+- Configure Playwright HTML reporter for CI
+
+See `reference/ci-cd-integration.md` for complete examples.
+
+## Output
+
+Complete, documented test suite ready for development workflow:
+- Tests in `tests/` directory
+- README with usage instructions
+- npm scripts configured
+- CI/CD documentation
+
+## Common Issues
+
+**Tests don't run after export**
+- Check TypeScript types
+- Verify imports are correct
+- Ensure Playwright is in dependencies
+
+**CI/CD integration issues**
+- See `reference/ci-cd-integration.md`
+- Check browser installation in CI
+
+## Success Criteria
+
+- [ ] Test suite exported to project
+- [ ] All tests executable via npm run test:e2e
+- [ ] README includes usage instructions
+- [ ] CI/CD guidance documented