# 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`.