Initial commit

2025-11-29 18:17:04 +08:00
commit e758c0ab84
56 changed files with 9997 additions and 0 deletions
--- a/skills/playwright-e2e-automation/README.md
+++ b/skills/playwright-e2e-automation/README.md
@@ -0,0 +1,387 @@
+# Playwright E2E Automation
+
+> Automated Playwright e2e testing framework with LLM-powered visual debugging, screenshot analysis, and regression testing
+
+## Quick Start
+
+### Trigger Phrases
+
+Simply ask Claude Code:
+
+```
+"set up playwright testing for my app"
+"help me debug UI issues with screenshots"
+"create e2e tests with visual regression"
+"analyze my app's UI with screenshots"
+```
+
+### What Happens
+
+This skill will automatically:
+
+1. **Detect your application** - Identifies React/Vite, Node.js, static sites, or full-stack apps
+2. **Detect framework versions** (NEW) - Determines Tailwind v3 vs v4, React version, etc.
+3. **Pre-flight validation** (NEW) - Checks app loads before running tests, catches config errors early
+4. **Install Playwright** - Runs `npm init playwright@latest` with optimal configuration
+5. **Generate test suite** - Creates screenshot-enabled tests with version-appropriate templates
+6. **Capture screenshots** - Takes full-page screenshots at key interaction points
+7. **Analyze visually** - Uses LLM vision to identify UI bugs, layout issues, accessibility problems
+8. **Detect regressions** - Compares against baselines to find unexpected visual changes
+9. **Generate fixes** - Produces actionable code recommendations with file:line references
+10. **Export test suite** - Provides production-ready tests you can run independently
+
+**Total time**: ~5-8 minutes (one-time setup)
+**New in v0.2.0**: Version detection and pre-flight validation prevent configuration errors
+
+## Features
+
+### Zero-Setup Automation
+
+No configuration required. The skill:
+
+- Detects your framework automatically (React, Vite, Next.js, Express, etc.)
+- Installs Playwright and browsers without prompts
+- Generates optimal configuration based on your app type
+- Creates tests following best practices
+- Runs everything end-to-end
+
+### Multi-Framework Support
+
+Works with:
+
+- **React/Vite** - Modern React apps with Vite dev server
+- **Next.js** - Server-side rendered React applications
+- **Node.js/Express** - Backend services with HTML responses
+- **Static HTML/CSS/JS** - Traditional web applications
+- **Full-stack** - Combined frontend + backend applications
+
+### Version-Aware Configuration (NEW in v0.2.0)
+
+The skill now detects installed framework versions and adapts automatically:
+
+**Tailwind CSS**:
+- **v3.x**: Uses `@tailwind base; @tailwind components; @tailwind utilities;` syntax
+- **v4.x**: Uses `@import "tailwindcss";` syntax and `@tailwindcss/postcss` plugin
+
+**React**:
+- **v17**: Classic JSX transform (requires React import)
+- **v18+**: Automatic JSX transform (no import needed)
+
+**Detection Process**:
+1. Reads `package.json` dependencies
+2. Matches versions against compatibility database
+3. Selects appropriate templates (CSS, PostCSS config, etc.)
+4. Warns about breaking changes or unknown versions
+
+**Pre-flight Validation**:
+- Loads app in browser before running tests
+- Monitors console for critical errors
+- Matches errors against known patterns (Tailwind v4 syntax, PostCSS plugin, etc.)
+- Provides specific fix steps with file:line references
+- **Prevents cascade failures**: One config error won't fail all 10 tests
+
+**Example Error Detection**:
+```
+❌ Pre-flight check failed: Tailwind CSS v4 syntax mismatch
+
+Root cause: CSS file uses @tailwind directives but v4 requires @import
+
+Fix:
+1. Update src/index.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
+```
+
+### LLM-Powered Visual Analysis
+
+Automatically identifies:
+
+- **UI Bugs** - Broken layouts, overlapping elements, cut-off text
+- **Accessibility Issues** - Color contrast, missing labels, improper heading hierarchy
+- **Responsive Problems** - Elements not scaling, overflow on mobile
+- **Visual Regressions** - Unexpected changes from baseline screenshots
+- **Missing Elements** - Expected UI components not rendered
+
+### Actionable Fix Recommendations
+
+Generates specific fixes with:
+
+- File paths and line numbers (`src/components/Button.tsx:45`)
+- Current code snippets showing the issue
+- Recommended code changes
+- Explanation of why the fix works
+- Priority level (critical, high, medium, low)
+
+### Production-Ready Test Suite
+
+Exports include:
+
+- Organized test files following best practices
+- Page object models for maintainability
+- Screenshot helpers and utilities
+- npm scripts for test execution
+- README with usage instructions
+- CI/CD integration examples
+
+## Usage Examples
+
+### Example 1: Initial Setup for React App
+
+```
+User: "Set up Playwright testing for my Vite React app"
+
+Claude (via skill):
+✅ Detected React + Vite application
+✅ Installing Playwright...
+✅ Generated playwright.config.ts with base URL http://localhost:5173
+✅ Created 5 test specs covering critical journeys
+✅ Captured 23 screenshots across desktop, tablet, mobile viewports
+✅ Visual analysis complete: Found 3 issues (1 high, 2 medium)
+✅ Generated fix recommendations in fix-recommendations.md
+✅ Test suite exported to tests/e2e/
+
+Next steps:
+- Review fix-recommendations.md
+- Run tests: npm run test:e2e
+- Update baselines after fixes: npm run test:e2e:update-snapshots
+```
+
+### Example 2: Visual Regression Detection
+
+```
+User: "Check for visual regressions after my recent changes"
+
+Claude (via skill):
+✅ Running existing Playwright test suite...
+✅ Captured 23 screenshots
+✅ Comparing against baselines...
+
+⚠️  Found 4 visual changes:
+  - Home page hero section: Layout shift detected (12% difference)
+  - Navigation menu: New dropdown added (expected change)
+  - Contact form: Button text color changed (2% difference)
+  - Footer: Logo size increased (5% difference)
+
+📊 Visual regression report: screenshots/diffs/report.html
+
+Would you like to:
+1. Accept these changes as new baseline
+2. Review specific diffs
+3. Get fix recommendations for unintended changes
+```
+
+### Example 3: Bug Investigation
+
+```
+User: "Users report the checkout button is cut off on mobile"
+
+Claude (via skill):
+✅ Generating mobile viewport test...
+✅ Captured screenshot: screenshots/current/checkout-mobile.png
+✅ Visual analysis complete
+
+🐛 Issue confirmed: Button text truncated on 375px viewport
+
+Location: src/components/CheckoutButton.tsx:28
+
+Current code:
+```tsx
+<button className="px-6 py-3 text-xl font-bold">
+  Complete Purchase
+</button>
+```
+
+Recommended fix:
+```tsx
+<button className="px-4 py-2 text-sm sm:text-base md:text-xl font-bold max-w-full">
+  Complete Purchase
+</button>
+```
+
+Reasoning: Fixed padding and font size cause overflow on narrow screens.
+Added responsive sizing and max-width constraint.
+
+Test added: tests/e2e/checkout-responsive.spec.ts
+```
+
+## What Gets Generated
+
+After running this skill, you'll have:
+
+```
+your-project/
+├── playwright.config.ts          # Playwright configuration
+├── tests/
+│   └── e2e/
+│       ├── setup/
+│       │   └── global-setup.ts   # Dev server startup
+│       ├── pages/
+│       │   └── *.page.ts         # Page object models
+│       ├── specs/
+│       │   └── *.spec.ts         # Test specifications
+│       └── utils/
+│           └── screenshot-helper.ts
+├── screenshots/
+│   ├── baselines/                # Reference images
+│   ├── current/                  # Latest run
+│   └── diffs/                    # Visual comparisons
+├── fix-recommendations.md        # Generated fix suggestions
+├── visual-analysis-report.md     # LLM analysis results
+└── package.json                  # Updated with test scripts
+```
+
+## Performance
+
+**Typical execution time** (React app with 5 critical journeys):
+
+- Application detection: ~5 seconds
+- Playwright installation: ~2-3 minutes (one-time)
+- Test generation: ~30 seconds
+- Test execution: ~30-60 seconds
+- Visual analysis: ~1-2 minutes
+- Regression comparison: ~10 seconds
+- Fix generation: ~30 seconds
+
+**Total**: ~5-8 minutes (excluding one-time Playwright install)
+
+## CI/CD Integration
+
+### GitHub Actions
+
+The skill generates GitHub Actions workflow examples. Basic setup:
+
+```yaml
+name: Playwright E2E Tests
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+      - run: npm ci
+      - run: npx playwright install --with-deps
+      - run: npm run test:e2e
+      - uses: actions/upload-artifact@v3
+        if: always()
+        with:
+          name: playwright-screenshots
+          path: screenshots/
+```
+
+### Baseline Management
+
+**In CI**:
+- Store baselines in repository: `git add screenshots/baselines/`
+- Tests fail if visual diffs exceed threshold
+- Review artifacts before merging
+
+**Locally**:
+- Update baselines: `npm run test:e2e:update-snapshots`
+- Commit updated baselines after review
+
+## Advanced Usage
+
+### Custom Test Generation
+
+After initial setup, you can:
+
+1. **Add more tests** - Follow the pattern in generated specs
+2. **Customize viewports** - Edit playwright.config.ts
+3. **Add custom assertions** - Extend screenshot helpers
+4. **Configure browsers** - Enable Firefox/WebKit in config
+5. **Adjust thresholds** - Modify visual diff sensitivity
+
+### Visual Analysis Customization
+
+The skill's analysis focuses on:
+
+- WCAG 2.1 AA accessibility compliance (see `data/accessibility-checks.md`)
+- Common UI bug patterns (see `data/common-ui-bugs.md`)
+- Framework-specific best practices
+
+### Integration with Existing Tests
+
+This skill complements your existing test suite:
+
+- **Unit tests** (Vitest/Jest) - Test logic and calculations
+- **Integration tests** - Test component interaction
+- **E2E tests** (Playwright) - Test full user workflows + visual regression
+
+All three work together without conflicts.
+
+## Troubleshooting
+
+### "Application not detected"
+
+**Solution**: Specify manually
+```
+"Set up Playwright for my [framework] app running on port [port]"
+```
+
+### "Dev server not running"
+
+**Solution**: The skill will attempt to start it automatically. If that fails:
+```bash
+npm run dev  # Start your dev server first
+```
+Then re-run the skill.
+
+### "Screenshot capture timeout"
+
+**Solution**: Increase timeout in playwright.config.ts:
+```typescript
+timeout: 60000, // 60 seconds instead of default 30
+```
+
+### "Visual analysis found too many false positives"
+
+**Solution**: Adjust the visual diff threshold:
+```typescript
+expect(await page.screenshot()).toMatchSnapshot({
+  maxDiffPixelRatio: 0.05, // Allow 5% difference
+});
+```
+
+## Requirements
+
+- **Node.js**: >=16.0.0
+- **npm**: >=7.0.0
+- **Disk space**: ~500MB for Playwright browsers (one-time)
+- **Memory**: ~500MB during test execution
+
+## Best Practices
+
+1. **Baseline management** - Commit baselines to git, update deliberately
+2. **Screenshot organization** - Use .gitignore for current/diffs, keep baselines
+3. **Test critical paths** - Focus on user journeys that matter (80/20 rule)
+4. **Run in CI** - Catch regressions before production
+5. **Review diffs carefully** - Not all changes are bugs
+6. **Use semantic selectors** - Prefer getByRole over CSS selectors
+7. **Capture context** - Take screenshots before AND after interactions
+
+## Learn More
+
+- [Playwright Documentation](https://playwright.dev/)
+- [Visual Regression Testing Guide](https://playwright.dev/docs/test-snapshots)
+- [Accessibility Testing](https://playwright.dev/docs/accessibility-testing)
+- [CI/CD Integration](https://playwright.dev/docs/ci)
+
+## Support
+
+Issues with this skill? Please report at:
+- [Claude Code Issues](https://github.com/anthropics/claude-code/issues)
+
+---
+
+**Created with**: skill-creator v0.1.0
+**Skill Version**: 0.1.0
+**Last Updated**: 2025-11-01