Initial commit

skills/testing/playwright-e2e-automation/reference/ci-cd-integration.md

@@ -0,0 +1,134 @@
+# CI/CD Integration
+
+## GitHub Actions Example
+
+```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
+        with:
+          node-version: 18
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Install Playwright browsers
+        run: npx playwright install --with-deps
+
+      - name: Run Playwright tests
+        run: npm run test:e2e
+
+      - name: Upload screenshots
+        if: always()
+        uses: actions/upload-artifact@v3
+        with:
+          name: playwright-screenshots
+          path: screenshots/
+
+      - name: Upload HTML report
+        if: always()
+        uses: actions/upload-artifact@v3
+        with:
+          name: playwright-report
+          path: playwright-report/
+```
+
+## Baseline Management in CI
+
+### 1. Store baselines in repository
+
+```bash
+git add screenshots/baselines/
+git commit -m "chore: update visual regression baselines"
+```
+
+### 2. Update baselines on approval
+
+1. Run tests locally: `npm run test:e2e`
+2. Review diffs: `npx playwright show-report`
+3. Update baselines: `npm run test:e2e:update-snapshots`
+4. Commit updated baselines
+
+### 3. Fail CI on visual regressions
+
+- Configure threshold in playwright.config.ts
+- Tests fail if diffs exceed threshold
+- Review in CI artifacts before merging
+
+## GitLab CI Example
+
+```yaml
+e2e-tests:
+  image: mcr.microsoft.com/playwright:v1.40.0-jammy
+  stage: test
+  script:
+    - npm ci
+    - npm run test:e2e
+  artifacts:
+    when: always
+    paths:
+      - screenshots/
+      - playwright-report/
+    expire_in: 7 days
+```
+
+## CircleCI Example
+
+```yaml
+version: 2.1
+jobs:
+  e2e-tests:
+    docker:
+      - image: mcr.microsoft.com/playwright:v1.40.0-jammy
+    steps:
+      - checkout
+      - run: npm ci
+      - run: npm run test:e2e
+      - store_artifacts:
+          path: screenshots
+      - store_artifacts:
+          path: playwright-report
+```
+
+## Best Practices
+
+### Screenshot Artifact Storage
+
+- Always upload screenshots as artifacts
+- Keep artifacts for at least 7 days
+- Consider cloud storage for long-term retention
+
+### Parallel Execution
+
+```yaml
+# Run tests across multiple shards
+- name: Run Playwright tests
+  run: npx playwright test --shard=${{ matrix.shard }}/${{ strategy.job-total }}
+  strategy:
+    matrix:
+      shard: [1, 2, 3, 4]
+```
+
+### Caching
+
+```yaml
+- name: Cache Playwright browsers
+  uses: actions/cache@v3
+  with:
+    path: ~/.cache/ms-playwright
+    key: playwright-${{ hashFiles('package-lock.json') }}
+```
+
+### Notifications
+
+Configure notifications for test failures:
+- Slack integration
+- Email alerts
+- PR comments with screenshot diffs

skills/testing/playwright-e2e-automation/reference/troubleshooting.md

@@ -0,0 +1,186 @@
+# Troubleshooting Guide
+
+## Framework Version Errors
+
+### Tailwind CSS v4 Syntax Mismatch
+
+**Symptom**: Console error "Cannot apply unknown utility class" or "Utilities must be known at build time"
+
+**Cause**: Tailwind v4 installed but CSS uses old v3 `@tailwind` directive syntax
+
+**Root Cause**: Breaking change in Tailwind v4 - changed from `@tailwind` to `@import` syntax
+
+**Detection**: Pre-flight health check catches this before running tests
+
+**Auto-fix Available**: Yes - skill detects version and uses correct template
+
+**Manual Fix**:
+```css
+// Old (v3):
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+// New (v4):
+@import "tailwindcss";
+```
+
+**Also Update**: `postcss.config.js` - change `tailwindcss: {}` to `'@tailwindcss/postcss': {}`
+
+**Prevention**: Skill consults `data/framework-versions.yaml` and selects appropriate template
+
+**Documentation**: https://tailwindcss.com/docs/upgrade-guide
+
+---
+
+### PostCSS Plugin Not Found
+
+**Symptom**: Build error "Plugin tailwindcss not found" or "Cannot find module 'tailwindcss'"
+
+**Cause**: Tailwind v4 renamed PostCSS plugin but config uses old name
+
+**Root Cause**: PostCSS plugin changed from `tailwindcss` to `@tailwindcss/postcss` in v4
+
+**Detection**: Pre-flight check or build error
+
+**Auto-fix Available**: Yes - version detection selects correct PostCSS template
+
+**Manual Fix**:
+```javascript
+// postcss.config.js
+// Old (v3):
+export default {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+};
+
+// New (v4):
+export default {
+  plugins: {
+    '@tailwindcss/postcss': {},
+    autoprefixer: {},
+  },
+};
+```
+
+**Verification**: Run `npm list @tailwindcss/postcss` to confirm installation
+
+**Prevention**: Skill uses `templates/configs/postcss-tailwind-v4.js` for Tailwind v4
+
+---
+
+### Version Incompatibility Warning
+
+**Symptom**: Skill warns "Unknown version detected" or "Version outside known ranges"
+
+**Cause**: Framework version not in compatibility database
+
+**Impact**: Skill may use outdated templates or incorrect syntax
+
+**Solution**:
+1. Check `data/framework-versions.yaml` for supported versions
+2. If version is newer, skill uses latest known template (may need manual adjustment)
+3. If version is older, skill may suggest upgrading
+
+**Reporting**: Please report unknown versions as GitHub issues to improve skill
+
+**Workaround**: Manually specify template paths if needed
+
+---
+
+## Common Issues
+
+### Application not detected
+
+**Cause**: Unrecognized framework or missing package.json
+
+**Solution**: Ask user to specify app type and dev server command manually
+
+**Fallback**: Use generic static site configuration
+
+---
+
+### Dev server not running
+
+**Cause**: Application not started before running tests
+
+**Solution**: Attempt to start server automatically using detected script (npm run dev)
+
+**Fallback**: Prompt user to start server manually
+
+---
+
+### Playwright installation fails
+
+**Cause**: Network issues, permissions, incompatible Node version
+
+**Solution**:
+- Check Node version (>=16)
+- Retry with --force
+- Suggest manual installation
+
+**Debugging**: Show full error output, check npm logs
+
+---
+
+### Screenshot capture fails
+
+**Cause**: Timeout waiting for page load, element not found, navigation error
+
+**Solution**:
+- Increase timeout
+- Add explicit waits
+- Capture partial screenshot on failure
+
+**Recovery**: Continue with other tests, report failure with details
+
+---
+
+### No baselines exist for comparison
+
+**Cause**: First test run, baselines deleted
+
+**Solution**: Current screenshots become baselines automatically
+
+**Message**: "No baselines found. Current screenshots saved as baselines."
+
+---
+
+### Visual analysis fails
+
+**Cause**: LLM API error, screenshot file corruption, unsupported format
+
+**Solution**:
+- Retry analysis
+- Skip corrupted images
+- Validate PNG format
+
+**Fallback**: Provide raw screenshots for manual inspection
+
+---
+
+## Performance Characteristics
+
+### Execution Times (Typical React App)
+
+| Phase | Time |
+|-------|------|
+| Application detection | ~5 seconds |
+| Playwright installation | ~2-3 minutes (one-time) |
+| Configuration generation | ~10 seconds |
+| Test generation | ~30 seconds |
+| Test execution (5 tests) | ~30-60 seconds |
+| Screenshot capture | ~1-2 seconds per screenshot |
+| Visual analysis (10 screenshots) | ~1-2 minutes |
+| Regression comparison | ~10 seconds |
+| Fix generation | ~30 seconds |
+
+**Total end-to-end time**: ~5-8 minutes (excluding Playwright install)
+
+### Resource Usage
+
+- **Disk space**: ~500MB (Playwright browsers)
+- **Memory**: ~500MB during test execution
+- **Screenshots**: ~1-2MB per full-page screenshot