Initial commit

skills/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