Skip to content
Company OS
Esc
↑↓navigate↵open⌘Jpreview
On this page

End-to-End Tests

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.

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).
  • Testing Strategy: The E2E suite complements unit and integration tests as part of a layered testing approach (Testing Strategy).
  • Request Flow: Understanding the server‑side request handling aids in interpreting E2E test results (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.

Was this page helpful?