Janady13/llms-txt-hub / apps/e2e/README.md

1# End-to-End Testing with Playwright 2 3This directory contains comprehensive E2E tests for the llms-txt hub application using Playwright. 4 5## 🚀 Quick Start 6 7```bash 8# Install Playwright browsers 9npm run test:install 10 11# Run all E2E tests 12npm run test:e2e 13 14# Run only smoke tests (fastest) 15npm run test:e2e:smoke 16 17# Run with visual interface 18npm run test:e2e:ui 19 20# Debug tests step-by-step 21npm run test:e2e:debug 22``` 23 24## 📁 Test Structure 25 26``` 27apps/e2e/ 28├── tests/ 29│ ├── pages.spec.ts # Page load and content tests 30│ ├── interactions.spec.ts # User interaction tests 31│ └── home.spec.ts # Original homepage test 32├── playwright.config.ts # Playwright configuration 33└── README.md # This file 34``` 35 36## 🧪 Test Categories 37 38### 1. **Page Tests** (`pages.spec.ts`) 39- **Main Pages**: Homepage, About, Guides, Websites, Members, Projects, FAQ, News 40- **Category Pages**: Developer Tools, Featured categories 41- **Search Functionality**: Search page with query parameters 42- **Legal Pages**: Privacy, Terms, Cookies 43- **Error Handling**: 404 page testing 44- **Responsive Design**: Mobile viewport testing 45- **Performance**: Load time validation 46- **Accessibility**: Basic accessibility checks 47 48### 2. **Interaction Tests** (`interactions.spec.ts`) 49- **Search**: Search input and submission 50- **Filtering**: Category and sort controls 51- **Load More**: Pagination and infinite scroll 52- **Navigation**: Footer links, breadcrumbs, back-to-top 53- **Forms**: Newsletter signup, contact forms 54- **Mobile**: Mobile menu, mobile search 55- **External Links**: External link verification 56 57## ⚙️ Configuration Optimizations 58 59### Performance Settings 60```typescript 61{ 62 workers: 4, // Parallel execution locally 63 timeout: 30000, // 30 seconds per test 64 actionTimeout: 10000, // 10 seconds for actions 65 navigationTimeout: 15000, // 15 seconds for page loads 66 fullyParallel: true // Maximum parallelization 67} 68``` 69 70### Browser Optimizations 71- **Chrome args** for faster execution: 72 - `--disable-dev-shm-usage` 73 - `--disable-extensions` 74 - `--no-sandbox` 75 - Background throttling disabled 76 77### Test Environments 78- **Desktop**: Primary Chromium testing 79- **Mobile**: Pixel 5 simulation (reduced test scope) 80- **Cross-browser**: Firefox/Safari commented out for speed 81 82## 🔧 Available Scripts 83 84| Script | Description | 85|--------|-------------| 86| `test:e2e` | Run all E2E tests across all browsers | 87| `test:e2e:fast` | Run tests only on Chromium (fastest) | 88| `test:e2e:smoke` | Run essential page tests only | 89| `test:e2e:ui` | Run tests with Playwright UI | 90| `test:e2e:debug` | Debug tests step-by-step | 91| `test:e2e:headed` | Run tests with visible browser | 92| `test:install` | Install Playwright browsers | 93| `report` | View last test results | 94 95## 🔄 Lefthook Integration 96 97### Pre-push Hook 98E2E smoke tests automatically run before pushing code: 99 100```yaml 101e2e-smoke: 102 run: cd apps/e2e && npm run test:e2e:smoke 103``` 104 105This ensures: 106- ✅ Critical user journeys work 107- ✅ Main pages load correctly 108- ✅ No regressions in core functionality 109- ⚡ Fast execution (~2-3 minutes) 110 111## 🎯 Test Philosophy 112 113### Focused on User Journeys 114Tests simulate real user behavior: 115- Page navigation 116- Search and filtering 117- Form interactions 118- Mobile usage patterns 119 120### Performance Optimized 121- **Fast feedback**: Smoke tests complete quickly 122- **Parallel execution**: Multiple tests run simultaneously 123- **Browser optimization**: Reduced overhead for speed 124- **Smart retries**: Only retry on CI environments 125 126### Resilient & Maintainable 127- **Flexible selectors**: Tests work across UI changes 128- **Conditional interactions**: Handle optional UI elements gracefully 129- **Clear test structure**: Easy to understand and maintain 130 131## 📊 Expected Coverage 132 133The E2E tests cover: 134- **~15 main pages** across the application 135- **~20 user interactions** including search, navigation, forms 136- **Mobile responsiveness** for critical flows 137- **Error states** and edge cases 138- **Performance benchmarks** for load times 139 140## 🐛 Debugging Tips 141 142### Test Failures 1431. **Check screenshots**: Available in `test-results/` after failures 1442. **View trace**: Use `report` command to see detailed execution trace 1453. **Run headed**: Use `test:e2e:headed` to see browser visually 1464. **Debug mode**: Use `test:e2e:debug` for step-by-step debugging 147 148### Common Issues 149- **Timing issues**: Increase timeout values in config 150- **Selector changes**: Update selectors when UI changes 151- **Server not ready**: Ensure dev server starts before tests 152 153### Performance Issues 154- **Slow tests**: Check network conditions and server performance 155- **Parallel conflicts**: Reduce worker count if tests interfere 156- **Memory issues**: Increase system memory or reduce parallelization 157 158## 🚀 CI/CD Integration 159 160The configuration automatically adjusts for CI environments: 161- **Single worker** in CI (prevents conflicts) 162- **More retries** for flaky network conditions 163- **GitHub reporter** for clean CI output 164- **Video recording** only on failures (saves space) 165 166## 🔮 Future Enhancements 167 168Potential improvements: 169- **Visual regression testing** with Playwright screenshots 170- **API testing** alongside UI tests 171- **Cross-browser matrix** for comprehensive coverage 172- **Mobile device testing** with real device farm 173- **Load testing** integration 174 175--- 176 177The E2E test suite provides confidence that the application works correctly from a user perspective while maintaining fast feedback cycles for developers.