Initial commit
This commit is contained in:
Zhongwei Li
134
skills/playwright-e2e-automation/reference/ci-cd-integration.md
Normal file
134
skills/playwright-e2e-automation/reference/ci-cd-integration.md
Normal file
@@ -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
|
||||
186
skills/playwright-e2e-automation/reference/troubleshooting.md
Normal file
186
skills/playwright-e2e-automation/reference/troubleshooting.md
Normal file
@@ -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
|
||||
Reference in New Issue
Block a user