> ## Documentation Index
> Fetch the complete documentation index at: https://system.muzemus.online/llms.txt
> Use this file to discover all available pages before exploring further.

# E2E testing

> Browser end-to-end testing with Playwright

## Playwright setup

```typescript theme={null}
// frontend/playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  testDir: './e2e',
  timeout: 30000,
  retries: 1,
  use: {
    baseURL: 'http://localhost:5173',
    screenshot: 'only-on-failure',
    trace: 'retain-on-failure',
  },
  projects: [
    { name: 'chromium', use: { browserName: 'chromium' } },
  ],
});
```

## Test structure

The suite uses the Page Object Model with role-aware fixtures:

```
frontend/e2e/
├── fixtures/        # auth fixture: loginAs helper, pre-authenticated admin page
├── page-objects/    # one class per screen
└── specs/           # journey specs
```

All specs use accessible locators (`getByRole`, `getByLabel`, `getByText`) rather than CSS selectors, and no `waitForTimeout` calls.

### Page object example

```typescript theme={null}
// frontend/e2e/page-objects/LoginPage.ts
import { Page } from '@playwright/test';

export class LoginPage {
  constructor(private page: Page) {}

  async goto() {
    await this.page.goto('/login');
  }

  async login(email: string, password: string) {
    await this.page.getByLabel('Email').fill(email);
    await this.page.getByLabel('Password').fill(password);
    await this.page.getByRole('button', { name: 'Sign In' }).click();
  }
}
```

## Journey coverage

| Spec file                | Journey                                                                      |
| ------------------------ | ---------------------------------------------------------------------------- |
| `auth-flow.spec.ts`      | Login, invalid login feedback, role-based redirect, logout, expired session  |
| `manager-order.spec.ts`  | Employee selection, entitlement preview, size selection, submission          |
| `admin-orders.spec.ts`   | Approval/rejection, status progression, production queue                     |
| `client-context.spec.ts` | Client switch refetches scoped data without cross-client leaks               |
| `bulk-import.spec.ts`    | CSV/XLSX upload, preview, validation errors, import batch tracking           |
| `error-ux.spec.ts`       | Backend errors surface as toasts or inline messages; error boundary recovery |

## Test data

E2E tests require seeded data: known employees, stores, and categories; test accounts per role; and pre-existing entitlement rule sets. Deterministic CSV/XLSX generators and persona credentials come from the shared test-data module, and the seed runs before the suite.

## Debugging

| Command                               | Purpose                                   |
| ------------------------------------- | ----------------------------------------- |
| `pnpm e2e:ui`                         | Playwright UI for interactive development |
| `pnpm e2e -- --debug`                 | Pause on failure                          |
| `pnpm e2e -- --headed`                | Visible browser                           |
| `npx playwright show-trace trace.zip` | Inspect a failed test's trace             |

Known runner quirks (single-browser coverage, occasional hangs on server reuse in combined runs) are tracked in [Known limitations](/engineering/known-limitations).