LINUX-AETHERFORGE/docs/TESTING.md

AetherForge Testing Guide

This document describes how to run backend and frontend tests for AetherForge Linux.

Backend (Go)

From the repository root:

make test
# or
go test ./...

Frontend (React / Vitest)

The Command Deck lives in web/. Tests use Vitest, Testing Library, jsdom, and MSW (Mock Service Worker) for HTTP mocks.

Prerequisites

cd web
npm install

Scripts

Command	Description
npm run test	Run all frontend tests once
npm run test:watch	Watch mode
npm run test:coverage	Run with V8 coverage report

From the repo root:

./scripts/test-frontend.sh
# or
make test-frontend

Configuration

• web/vitest.config.ts — merges Vite config with Vitest (jsdom, @/ alias, coverage)
• web/src/test/setupTests.ts — MSW server lifecycle, RTL cleanup, session reset
• web/src/test/mocks/handlers.ts — REST handlers for fleet, WS ticket, calibrate, crucible
• web/src/test/test-utils.tsx — renderWithProviders() with MemoryRouter + auth
• web/src/test/mockWebSocket.ts — WebSocket mock for fleet heartbeat tests
• web/src/test/mockEventSource.ts — EventSource mock for Seer SSE tests

Test layout

Tests are colocated with source files:

web/src/
  App.test.tsx
  pages/*.test.tsx
  hooks/*.test.ts
  components/**/*.test.tsx
  lib/*.test.ts

What is covered

Area	Tests
Login gate	ProtectedRoute, App redirect unauthenticated users
Dashboard	Host cards from mock /api/v1/fleet, WS connection badge
WebSocket hook	useFleetWebSocket receives heartbeat frames
Auth/session	sessionStorage credentials, Basic header
Routes	Login, Dashboard, Forge, Calibrate, Crucible, Seer render without crash
Calibrate	Mining profile form POSTs to fleet API
Crucible	Terminal dispatch sends batch command
Seer	SSE connect button, live status, message ingestion
Components	HostCard, Badge variants, hashrate formatting

Writing new tests

1. Add MSW handlers in src/test/mocks/handlers.ts for new API endpoints.
2. Use renderWithProviders(<Component />, { authenticated: true }) for protected views.
3. Call installMockWebSocket() / installMockEventSource() when testing realtime features.
4. Place new tests beside the module: MyComponent.test.tsx.

Troubleshooting

• Unhandled MSW request — add a handler or use server.use() in the test.
• WebSocket flakiness — use waitFor after MockWebSocket.latest()?.simulateMessage(...).
• Auth redirects — pass authenticated: false to renderWithProviders or clear sessionStorage.