End-to-End Test Scenarios
Relevant source files
The following files were used as context for generating this wiki page:
End-to-End (E2E) test scenarios in Coral are managed by Reel, a standalone tool for recording and reviewing browser-test journeys. These scenarios provide automated verification and watchable evidence of cross-process journeys and local/remote parity claims. Unlike unit or architecture tests, Reel uses real-browser sessions via Playwright Chromium to validate the integrated product stack, including genuine sign-in flows and database interactions.
Sources: apps/reef/e2e/README.md:1-12, AGENTS.md:214-218
Test Suite Architecture
The E2E system organizes scenarios into three primary suites based on the deployment target and authentication requirements. All suites run the production Reef server and real Coral processes in a temporary, private state.
Suite Types
| Suite | Description | Scope |
|---|---|---|
main | Default suite using genuine Coral sign-in and full identity journeys. | scenarios/main/ |
local-mode | Validates deployments with sign-in disabled, using an implicit Organization Owner. | scenarios/local-mode/ |
desktop | Tests the packaged Desktop app, including supervisor behavior and window management. | scenarios/desktop/ |
Sources: apps/reef/e2e/README.md:36-45, apps/reef/e2e/README.md:204-209
Execution Flow
The test runner initializes a unique container and network for each invocation. It coordinates multiple components, including the OIDC provider, Coral, and the Reef server.
The flow shows the lifecycle of an E2E run from initialization in a Docker container to artifact generation.
Sources: apps/reef/e2e/README.md:155-165, apps/reef/e2e/support/scenario-reporter.ts:20-55
Scenario Management and Artifacts
Every test scenario produces a set of structured artifacts stored in a unique run directory. The ScenarioReporter tracks the lifecycle of these tests and generates metadata used by the evidence viewer.
Artifact Structure
Artifacts are organized hierarchically to support retries and multi-actor sessions:
- Run Metadata (
run.json): Contains commit hash, dirty state, and target configurations. - Scenario Metadata (
scenario.json): Tracks the overall outcome, duration, and source path of a specific test. - Session Evidence: Includes
result.json,trace.zip, video recordings (session.webm), and numbered screenshots.
Sources: apps/reef/e2e/support/artifacts.ts:83-145, apps/reef/e2e/support/scenario-reporter.ts:74-101
Parity Scenarios
Parity scenarios verify that domain facts remain consistent across different topologies (e.g., local vs. remote). These use shared .ts modules to define assertions that are registered by multiple entry files.
This diagram illustrates how shared logic is reused to ensure behavioral parity between suites.
Sources: apps/reef/e2e/README.md:286-305
Evidence Review and Visualization
Reel includes a standalone viewer that renders test evidence using the Wax design system. The viewer is a server-side rendered (SSR) application that provides a landing page for run history and detailed pages for specific scenarios.
Viewer Navigation Components
- Landing Page: Displays the latest scenario run, run history, and harness self-checks.
- Scenario Page: Shows the whole test outcome, including failure stacks, retries, and ordered session links.
- Session View: Provides playback controls, source code snapshots, and direct links to traces/logs.
Sources: apps/reef/e2e/viewer/run-pages.tsx:95-135, apps/reef/e2e/viewer/scenario-page.tsx:18-45
Security and Isolation
The viewer binds strictly to the loopback address (127.0.0.1) and enforces a Content Security Policy (CSP) that permits only trusted playback scripts. It validates that all requested evidence files reside within the authorized run directory to prevent path traversal.
Sources: apps/reef/e2e/README.md:82-90, apps/reef/e2e/support/viewer.test.ts:248-265
Implementation Guidelines
When writing or maintaining E2E scenarios, developers must follow specific project boundaries:
- Actor Creation: Use
createActors(context)to provision fresh identities (e.g.,owner,alice,bob) with genuine storage states. - Resource Cleanup: Scenarios must own their resource cleanup; the harness handles browser lifecycle and artifact finalization.
- Isolation: Do not use database seeding or test-only production routes. All prerequisites must be arranged through real APIs.
- Evidence Sensitivity: Treat all artifacts as sensitive, as traces and videos may contain tokens or private content.
Sources: apps/reef/e2e/README.md:386-405, apps/reef/e2e/README.md:470-480, AGENTS.md:220-225
The E2E test system serves as the final integration checkpoint for Coral, ensuring that cross-process journeys function correctly across different deployment modes while providing durable evidence for review.