Initial commit: AetherForge Linux (forge-mesh) v0.1.0-dev

docs/TESTING.md

@@ -0,0 +1,89 @@
+# AetherForge Testing Guide
+
+This document describes how to run backend and frontend tests for AetherForge Linux.
+
+## Backend (Go)
+
+From the repository root:
+
+```bash
+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
+
+```bash
+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:
+
+```bash
+./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`.