e2e-project-structure

E2E Project Structure

Standard Directory Layout

The default structure places all E2E artefacts under tests/e2e/ at the repository root:

tests/
  e2e/
    specs/               ← test spec files (*.spec.ts)
    pages/               ← Page Object Model classes (*.page.ts)
    fixtures/
      test.ts            ← extended test + expect export
    helpers/             ← shared utilities (e.g., date formatters, API helpers)
    .auth/               ← storageState files (git-ignored)
    auth.setup.ts        ← global auth setup project
playwright.config.ts     ← Playwright configuration at repo root

Create .gitignore entries for auth state:

tests/e2e/.auth/
test-results/
playwright-report/

File Naming Conventions

Artefact	Pattern	Example
Spec file	<feature>.spec.ts	login.spec.ts, checkout.spec.ts
Page Object	<page-name>.page.ts	login.page.ts, checkout.page.ts
Fixture barrel	test.ts	fixtures/test.ts
Auth setup	auth.setup.ts	tests/e2e/auth.setup.ts
Helper module	<name>.helper.ts	helpers/date.helper.ts

All file names use kebab-case. No index.ts barrel exports — import directly from the source file.

Co-located Pattern Variant

When .playwright-agent.json sets "testPattern": "co-located", place spec files alongside the source files they test rather than in a central tests/e2e/specs/ directory. No separate pages/ directory is used.

src/
  features/
    login/
      LoginPage.tsx
      login.spec.ts        ← co-located E2E spec
    checkout/
      CheckoutPage.tsx
      checkout.spec.ts
tests/e2e/
  fixtures/
    test.ts
  auth.setup.ts
playwright.config.ts

Update testDir and testMatch in playwright.config.ts accordingly:

export default defineConfig({
  testDir: './src',
  testMatch: '**/*.spec.ts',
});

Monorepo Adaptation

In a monorepo, use the directoryMapping key in .playwright-agent.json to map app packages to their test directories:

{
  "directoryMapping": {
    "apps/web": "apps/web/tests/e2e",
    "apps/admin": "apps/admin/tests/e2e"
  }
}

Each mapped app gets its own tests/e2e/ subtree with the same internal structure. Shared fixtures can live in a packages/e2e-fixtures/ workspace package and be imported across app test suites.

apps/
  web/
    tests/e2e/
      specs/
      pages/
      fixtures/
      auth.setup.ts
  admin/
    tests/e2e/
      specs/
      pages/
      fixtures/
      auth.setup.ts
packages/
  e2e-fixtures/       ← shared fixtures workspace package
    src/
      test.ts
      auth.ts

playwright.config.ts Scaffold

Generate this baseline config when scaffolding a new E2E project:

import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  testDir: './tests/e2e',
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 1 : undefined,
  reporter: process.env.CI ? [['html'], ['github']] : [['html'], ['list']],
  use: {
    baseURL: process.env.BASE_URL ?? 'http://localhost:3000',
    trace: 'on-first-retry',
    video: 'on-first-retry',
  },
  projects: [
    { name: 'setup', testMatch: '**/auth.setup.ts' },
    {
      name: 'chromium',
      use: {
        ...devices['Desktop Chrome'],
        storageState: 'tests/e2e/.auth/user.json',
      },
      dependencies: ['setup'],
    },
  ],
});

Checklist

When scaffolding a new E2E module, verify:

• tests/e2e/ directory created (or monorepo equivalent)
• tests/e2e/fixtures/test.ts created with extended test and expect
• tests/e2e/auth.setup.ts created and wired into playwright.config.ts as a setup project
• tests/e2e/.auth/ added to .gitignore
• playwright.config.ts exists at the repo root (or app root in monorepo)
• testDir, baseURL, storageState paths verified in config
• test-results/ and playwright-report/ added to .gitignore