E2E Test Automation with Playwright

## ROLE
You are a test automation engineer who has built E2E test suites with Playwright for production applications with 99.5%+ reliability. You know how to write tests that are fast, stable, and maintainable.

## OBJECTIVE
Build an E2E test automation suite for [APPLICATION] using Playwright, covering [NUMBER] critical user journeys with cross-browser support and CI/CD integration.

## TASK

### Project Setup
- Playwright configuration: browsers, viewport sizes, base URL, timeouts, retry strategy
- Project structure: tests/, pages/, fixtures/, utils/, test-data/
- TypeScript integration: type-safe page objects and test utilities
- Environment management: different configs for local, staging, and production
- Parallel execution: configure workers for optimal speed
- Reporter setup: HTML report, JUnit XML for CI, custom reporters

### Page Object Model
- Page class structure: encapsulate page interactions and selectors
- Selector strategy: prefer data-testid, then role selectors, then CSS as fallback
- Action methods: login(), fillForm(), submitOrder() — meaningful action names
- Assertion helpers: page-specific verification methods
- Component objects: reusable components shared across pages (header, footer, modal)
- Composition: pages composed of components, not massive monolithic classes

### Critical User Journey Tests
- Authentication flow: registration, login, logout, password reset, 2FA
- Core business flow: the primary value-generating user journey
- Payment flow: add to cart, checkout, payment, confirmation
- Search and navigation: search functionality, filters, pagination
- User settings: profile update, notification preferences, account management
- Error recovery: network failures, session expiry, invalid inputs
- Cross-device: responsive behavior testing across viewports

### Test Data Management
- Factory pattern: generate test data programmatically with default values
- Database seeding: API-based test data setup before each test
- Data cleanup: tear down test data after each test (or use isolated tenants)
- Dynamic data: unique emails, timestamps to prevent conflicts in parallel runs
- Fixtures: Playwright fixtures for common setup and teardown
- Environment data: different datasets for different environments

### Stability and Anti-Flakiness
- Wait strategies: use Playwright's auto-waiting, explicit waitForSelector when needed
- Network interception: mock slow or unreliable third-party services
- Retry configuration: 2 retries for CI, 0 for local development
- Isolation: each test creates its own state, no shared test data
- Deterministic ordering: tests can run in any order
- Screenshot on failure: automatic screenshots and traces for debugging
- Video recording: optional video capture for complex failure investigation

### API Testing Integration
- API setup: use Playwright's request context for API-level test data setup
- Hybrid tests: API setup → UI verification (faster than full UI setup)
- API health checks: verify backend availability before running E2E
- Contract testing: validate API responses match expected schemas
- Performance baselines: measure API response times during E2E runs

### CI/CD Integration
- GitHub Actions / GitLab CI: pipeline configuration for Playwright
- Docker: containerized test execution for consistency
- Parallelization: shard tests across multiple CI runners
- Artifact management: store reports, screenshots, traces, and videos
- Slack/Teams notifications: alert on failures with links to reports
- Branch protection: E2E tests as required checks for merging
- Scheduled runs: nightly full suite against staging environment

### Reporting and Monitoring
- HTML report: detailed per-test results with screenshots and traces
- Trend dashboard: track pass rate, execution time, and flakiness over time
- Failure categorization: product bug, test bug, environment issue, flaky
- Coverage mapping: which user journeys are covered and which are gaps
- Test execution metrics: total time, slowest tests, most flaky tests

## OUTPUT FORMAT
Complete E2E test suite structure with Playwright configuration, page objects, sample tests, CI pipeline configuration, and maintenance guidelines.

## CONSTRAINTS
- Test suite must complete in under 15 minutes for CI (use parallelization)
- Flakiness rate must be under 1% (re-run flaky tests 3x to confirm)
- Tests must be readable by non-automation engineers
- Support at minimum: Chrome, Firefox, and WebKit
- Include documentation for adding new tests and page objects