e2e-test-conventions

E2E Test Conventions

These conventions apply to all Playwright E2E test code. Read and follow them whenever generating, modifying, or reviewing tests.

---

Technology Stack

• Playwright for browser automation and test running
• TypeScript for all test code (no plain JavaScript)
• Framework-agnostic — adapt selectors and helpers to whatever UI framework the project uses

---

Project Structure

The e2e/ directory follows this layout:

e2e/
├── auth/                    # Authentication setup (runs before all tests)
│   └── auth.setup.ts        # Logs in and saves session state
├── fixtures/                # Custom Playwright fixtures
│   └── base.ts              # Extends Playwright's test with custom fixtures
├── helpers/                 # Shared utility functions (NOT page objects)
│   └── env-config.ts        # Environment resolution
├── poms/                    # Page Object Models (one file per page)
│   └── base.page.ts         # Abstract base class — all POMs extend this
├── test-data/               # External test data (JSON files)
├── tests/                   # Test specs organised by suite
│   ├── handover/            # Ticket-driven handover tests (temporary)
│   ├── regression/          # Full regression tests (permanent)
│   └── smoke/               # Quick critical-path checks
├── playwright.config.ts
├── tsconfig.json
└── .env.example             # Template for environment variables

Rules:

• Do NOT create files outside this structure
• Do NOT move existing files without explicit permission

See references/folder-structure.md for details on each directory.

---

Browser × Suite Configuration

The Playwright config defines projects using {browser}:{suite} naming:

Browsers: chromium, firefox, webkit, mobile-chrome, mobile-safari

Suites:

Suite	Directory	Purpose	Lifecycle
regression	tests/regression/	Full regression	Permanent
handover	tests/handover/	Ticket-driven handover	Temporary — promote or delete
smoke	tests/smoke/	Critical-path sanity	Permanent