# E2E Test Full Gap Coverage Design

**Date:** 2026-03-12
**Scope:** All 3 priority tiers from `e2e_gaps.md` (~45-55 new tests)

## Decisions

- **Multi-server fixtures:** Real multi-process only where required (cluster, leaf, gateway). Single server with feature flags for MQTT and WebSocket.
- **Gateway topology:** Minimal two-server (not full multi-cluster).
- **Shutdown/drain:** Both client drain and server shutdown tests.
- **MQTT client:** MQTTnet NuGet package.
- **WebSocket client:** Built-in `System.Net.WebSockets.ClientWebSocket` speaking raw NATS protocol.

## New Fixtures

| Fixture | Servers | Config |
|---------|---------|--------|
| `ClusterFixture` | 3 `NatsServerProcess` instances | Route config pointing at each other |
| `LeafNodeFixture` | 2 instances (hub + leaf) | Leaf config pointing at hub |
| `GatewayFixture` | 2 standalone instances | Gateway config connecting them |
| `MqttServerFixture` | 1 instance | MQTT port enabled |
| `WebSocketServerFixture` | 1 instance | WebSocket port enabled |

Existing `MonitorServerFixture` is already created but unused — use as-is.

## New Test Files

### 1. `MonitoringTests.cs` (existing `MonitorServerFixture`)

- `/varz` — returns JSON with server_name, version, connections
- `/connz` — reflects connected client count
- `/healthz` — returns 200 OK

### 2. `HeaderTests.cs` (existing `NatsServerFixture`)

- Publish with headers, receive with headers intact
- Multiple headers on a single message
- Empty header value round-trip

### 3. `ShutdownDrainTests.cs` (own server per test, no shared fixture)

- Client drain completes in-flight messages then disconnects
- Server kill mid-connection — client detects disconnection gracefully

### 4. `ClusterTests.cs` (new `ClusterFixture`)

- Message published on node A received by subscriber on node B
- Subscriber on node C receives after joining mid-stream
- Queue group across cluster nodes delivers once total

### 5. `LeafNodeTests.cs` (new `LeafNodeFixture`)

- Message published on hub received by leaf subscriber
- Message published on leaf received by hub subscriber
- Only subscribed subjects propagate to hub

### 6. `GatewayTests.cs` (new `GatewayFixture`)

- Message crosses gateway from server A to server B
- No cross-delivery when no interest on remote side

### 7. `MqttTests.cs` (new `MqttServerFixture`)

- MQTT subscribe → NATS publish → MQTT receives
- MQTT publish → NATS subscribe → NATS receives
- MQTT QoS 0 and QoS 1 delivery

### 8. `WebSocketTests.cs` (new `WebSocketServerFixture`)

- Connect via WebSocket, subscribe, receive message
- Pub/sub round-trip over WebSocket

## Additions to Existing `JetStreamTests.cs`

- Push consumer (server-initiated delivery)
- AckAll policy
- AckNone policy
- Interest retention
- WorkQueue retention
- Ordered consumer
- Stream mirroring
- Stream sourcing

## New File: `AdvancedTests.cs`

- JWT authentication (inline server with JWT config)
- Account imports/exports (cross-account service call)
- Subject transforms
- Config file loading (full config file, verify behavior)
- System events (`$SYS.>` subscription, detect connect event)
- Max connections enforcement
- Service latency tracking

## New NuGet Dependency

- **MQTTnet** — added to `Directory.Packages.props` and `NATS.E2E.Tests.csproj`

## Estimated Impact

- ~45-55 new tests
- 5 new fixtures + 7 new test files + 1 existing file extended
- Total E2E: ~90-95 tests (from current 42)