Web Frontend and Worker Tests
Relevant source files
The following files were used as context for generating this wiki page:
Web Frontend and Worker Tests ensure the reliability of the flyhard interactive auction platform, covering the Next.js frontend, Cloudflare Workers, and the SQLite-backed Durable Object. The testing suite validates critical paths including artwork uploads, Stripe checkout flows, auction bidding logic, and real-time livery updates via WebSockets.
The testing infrastructure utilizes Vitest and Miniflare to execute a full integration suite that simulates the production Cloudflare environment. These tests isolate external dependencies like the Stripe API while verifying that the internal state management in the Durable Object correctly handles concurrent bids and automated refunds.
Sources: apps/website/package.json:44, apps/website/README.md:104-109, apps/website/tests/auction.test.ts:1-20
Testing Architecture
The project uses a local integration testing environment that spins up the actual Worker script within a Miniflare instance. This environment includes persistence layers for R2 (artwork storage) and Durable Objects (auction logic).
Integration Components
- Miniflare: Simulates the Cloudflare Workers runtime, including D1/SQLite and R2 bindings.
- Esbuild: Bundles the test fixture worker (
auction-worker.ts) before test execution. - Outbound Service Mock: Intercepts external requests to
api.stripe.comandemail.testto simulate payment and notification providers.
The diagram shows how the Vitest runner orchestrates Miniflare to test Worker logic against mocked external services and persistent storage.
Sources: apps/website/tests/auction.test.ts:39-106, apps/website/README.md:104-106
Auction Logic and Rule Verification
Tests enforce strict auction rules regarding bid increments, slot availability, and placement fitting. The system validates that each new bid is at least $1.00 USD higher than the current winner.
Key Validation Checks
- Bid Increments: The system converts dollars to cents and rejects bids that do not meet the full dollar increment requirement.
- Slot Management: The frontend and worker must manage a specific inventory of slots (e.g., 7 large panels in the preferred inventory).
- Retired Slots: Tests verify that retired slots cannot initiate new checkout sessions.
| Rule Category | Description | Source File Reference |
|---|---|---|
| Minimum Bid | New bids must be $\ge$ current bid + $1.00. | auction.test.ts:285-300 |
| Currency | Uses USD cents to avoid floating point errors. | auction.test.ts:285-288 |
| Slot Limit | Maintains specific counts for car faces (e.g., 2 left, 1 right). | auction.test.ts:208-215 |
| Persistence | History and placements must be committed in one transaction. | README.md:83-85 |
Sources: apps/website/tests/auction.test.ts:207-300, apps/website/README.md:73-80
Payment and Checkout Flow
The checkout process involves multiple stages: artwork upload, Stripe session creation, and webhook-driven publication. Tests simulate Stripe's checkout.session.completed events to verify that artwork only goes live after successful payment.
Checkout Lifecycle
- Artwork Upload: User uploads PNG/JPG to
/api/artwork. - Session Creation: Worker validates the bid and creates a Stripe Checkout session with a stable idempotency key.
- Payment Verification: Stripe sends a signed webhook to
/api/stripe/webhook. - Publication: The Durable Object commits the new placement and triggers a WebSocket broadcast.
The sequence diagram illustrates the asynchronous nature of the payment and publication flow verified in tests.
Sources: apps/website/tests/auction.test.ts:139-195, apps/website/README.md:76-85
Outbid Notifications and Emails
The system includes a transactional email flow to notify users when they have been outbid. These tests verify the reliability of the Cloudflare Email Service integration and the Durable Object's outbox queue.
Notification Requirements
- Address Recovery: If a user's email is missing from the local DB, the system must recover it from Stripe before sending the notification.
- Retry Logic: A Durable Object alarm must recover temporary email failures.
- Sandbox Isolation: In test mode, all emails are routed to a configured test recipient to prevent spamming actual users.
Sources: apps/website/tests/auction.test.ts:420-530, apps/website/README.md:92-95
Frontend Interaction Tests
The frontend components in auction-site.tsx are tested for their ability to react to live state updates and handle user navigation.
Frontend Features Validated
- Real-time Updates: Reconnecting live updates and displaying online user counts via
useAuction. - View Selection: Switching between "perspective", "left", "right", "top", "front", and "back" camera angles.
- Form Validation: Size-checking messages (max 140 characters) and verifying that terms are accepted before checkout.
Sources: apps/website/src/components/auction-site.tsx:90-130, apps/website/src/app/terms/page.tsx:8-40, apps/website/README.md:112-115
Development and Test Scripts
Testing and verification are performed using the following scripts defined in package.json:
{
"scripts": {
"typecheck": "tsc --noEmit",
"test": "vitest run",
"check": "npm run typecheck && npm test && npm run build:worker"
}
}
Sources: apps/website/package.json:8-12
Web Frontend and Worker Tests provide a comprehensive safety net for the auction platform, ensuring that complex multi-step financial transactions and real-time livery synchronization behave predictably across different network and payment states.