Frontend Fixtures & E2E Screenshots
Relevant source files
The following files were used as context for generating this wiki page:
Opificia uses a frontend fixture mode to develop and test the web application without a live backend. This system provides recorded run data to the frontend, allowing developers and AI agents to verify UI changes across various run states. The screenshot system automates the capture of these states to provide visual feedback during development.
Sources: apps/web/fixtures/plugin.ts:7-13, AGENTS.md:78-84
Fixture System Architecture
The fixture system intercepts API requests using a Vite plugin. When the web app runs in fixture mode, the Vite dev server answers /api requests itself using recorded events from real Opificia runs.
The diagram shows how the Vite middleware intercepts frontend API calls and serves static data from recorded run sources.
Key Data Structures
The fixture system relies on a set of predefined scenarios that map to specific run states.
| Name | Type | Description |
|---|---|---|
SourceRun | Interface | Holds repository metadata and a sequence of events. |
Scenario | Type | Defines a specific test case with an ID, source data, and target state. |
SOURCES | Record | A collection of real run data including timeline, egress, and cancelled runs. |
Sources: apps/web/fixtures/runs.ts:11-14, apps/web/fixtures/plugin.ts:17-29
End-to-End Screenshots
The screenshot script automates Playwright to capture the web app in multiple states, themes, and widths. This allows AI coding agents to "see" the web app after making changes.
The sequence shows the automated flow of starting the fixture server, navigating to specific run IDs, and capturing images.
Screenshot Configurations
The system captures a "Standard" set of screenshots covering the main application lifecycle:
- Home: The dashboard view.
- Planning: A run in the
planningstate. - Review: A run
awaiting_approval. - Building: A run in the
implementingstate. - PR Open: A completed run with an open pull request.
- Failed/Cancelled: Error states.
- Narrow Views: 400px width captures to test mobile responsiveness.
Sources: apps/web/scripts/screenshot.ts:1-12, apps/web/scripts/screenshot.ts:33-47
API Simulation Logic
The fixture plugin simulates various backend endpoints to ensure the frontend functions correctly in isolation.
Authentication and Organization
The plugin mocks the Better Auth session and organization endpoints. It returns a fixed PERSON (Ada Lovelace) and ORGANIZATION (Example) to the frontend.
Sources: apps/web/fixtures/plugin.ts:98-111
Event Streaming
The /api/runs/:id/stream endpoint simulates Server-Sent Events (SSE). It writes recorded events to the response stream and sends a heartbeat every 15 seconds to keep the connection open.
Sources: apps/web/fixtures/plugin.ts:128-136
Time Shifting
To ensure that "relative time" (e.g., "5 minutes ago") appears correctly, the plugin shifts the timestamps of recorded events relative to the current time (Date.now()).
Sources: apps/web/fixtures/plugin.ts:64-69
Automated Verification for Agents
AI agents are instructed to run the screenshot command after modifying apps/web. This provides them with visual confirmation of layout, spacing, and theme compatibility.
pnpm --filter @opificia/web screenshot: Captures the standard set.--bottom: Scrolls themainelement to the end before capturing, useful for viewing pull request details.--theme: Supportslight,dark, orboth.
Sources: AGENTS.md:85-91, apps/web/scripts/screenshot.ts:25-27
Summary
The Frontend Fixtures and E2E Screenshot system enables reliable UI development without backend dependencies. By intercepting API calls via Vite and serving time-shifted recorded data, the project ensures that both human developers and AI agents can verify complex state transitions and visual layouts. This architecture supports the project's goal of allowing agents to operate autonomously while providing humans with clear visual evidence of their work.
Sources: apps/web/fixtures/plugin.ts:7-13, apps/web/src/run/conversation.tsx:501-525