---
type: End-to-End Test Configuration
title: End-to-End Tests
description: Overview of the end-to-end test setup including configuration (e2e.config.ts), test structure using @e2e-dev/web, and key scenarios for request flow, tenant onboarding, and capability invocation.
tags: [testing, e2e, configuration, playwright]
verified:
  - by: openwiki/0.7.2
    at: 2026-10-14T20:42:32.326Z
---

## End-to-End Test Suite

The end-to-end (E2E) test suite validates critical user journeys and system integrations by running the full application stack against a real browser. It uses the `@e2e-dev/web` test runner (a wrapper around Playwright) to orchestrate the application, browser, and assertions.

### Configuration (`e2e.config.ts`)

The test runner is configured via `e2e.config.ts` at the repository root. Key sections:

- **Agents**: Define the LLM model used for AI-assisted test steps (if any). Currently, only the default agent is configured, using `gateway("openai/gpt-6-luna-fast")` with a system prompt directing thorough verification. Note that the existing sign-up test is deterministic and does not require the agent.
- **Targets**: Specify the application under test and the browser engine.
  - *App*: The application is started via `bun run dev`, which concurrently runs the admin interface (port 3001) and the server API (port 3000). The configuration sets `DATABASE_URL` to point to a Postgres instance (default `localhost:5433`), which must be started separately (e.g., `bun run db:start`). The app target reuses existing processes, logs to `.e2e/logs/app.log`, and has a 2‑minute startup timeout.
  - *Engine*: Uses `web()` (i.e., Chromium) via the `@e2e-dev/web` adapter.
- **Test Files**: Glob pattern `tests/**/*.e2e.ts` collects test modules.

### Test Structure

Test files reside in `/tests` and follow the naming convention `*.e2e.ts`. Each test uses the `test` function from `@e2e-dev/web`, which provides fixtures:
- `app`: Methods to control the application (e.g., `app.open(path)` to navigate to a route).
- `browser`: Assertions on the browser state (e.g., `expect(browser).toHaveURL(path)`).
- `screen`: Locators for interacting with the page (built on Playwright's `Locator` API, extended with convenience methods like `getByLabel`, `getByRole`, etc.).

The existing test `sign-up.e2e.ts` demonstrates a typical flow:
1. Navigate to `/login`.
2. Fill the sign‑up form (Name, Email, Password).
3. Submit the form.
4. Assert navigation to `/dashboard` and visibility of welcome text and a protected API message.

### Key Scenarios Covered

While the current suite includes only the admin sign‑up test, the infrastructure supports broader scenarios:

- **Request Flow**: Tests can exercise full HTTP request paths by interacting with the UI that triggers backend endpoints (e.g., submitting a form that calls `/api/signup`). The `app.open` and UI interactions drive the request flow from the browser through the server to the database.
- **Tenant Onboarding**: The sign‑up test itself represents tenant (admin) onboarding. Extending this pattern, one could test onboarding for different roles or verify post‑sign‑up setup steps (e.g., creating an initial workspace).
- **Capability Invocation**: After authentication, tests can invoke protected capabilities (e.g., accessing a dashboard widget that calls a private API). The existing test already checks for a protected API message (`"API: This is private"`), confirming that the backend enforces authorization and the UI reflects the result.

### Relationships with Other Documentation

- **Logging**: E2E test runs produce application logs (`.e2e/logs/app.log`) and browser traces/logs (configurable via the test runner). Refer to the logging strategy for correlating test failures with system logs ([Logging](/operations/logging)).
- **Testing Strategy**: The E2E suite complements unit and integration tests as part of a layered testing approach ([Testing Strategy](/testing/strategy)).
- **Request Flow**: Understanding the server‑side request handling aids in interpreting E2E test results ([Request Flow](/workflows/request-flow)).

### Running the Tests

Prerequisites:
1. Start Postgres: `bun run db:start`.
2. Launch the application in development mode (the E2E config will reuse a running instance or start one): `bun run dev` (or let the test runner start it).
3. Execute the test suite: `bun run test:e2e` (assuming a script is defined in `package.json`; otherwise, use the `e2e` CLI directly).

### Extension Points

- **Custom Agents**: Add additional LLM‑powered test steps by defining new agents in the `agents` section.
- **Alternative Browsers**: Change the `engine` to use Firefox or WebKit by adjusting the `web()` call (see `@e2e-dev/web` documentation).
- **Environment Overrides**: Override `DATABASE_URL` and other variables via the shell or a `.env` file; the E2E config respects `process.env.E2E_DATABASE_URL` as shown.