# Go-to-.NET Systematic Test Parity Design

**Date:** 2026-02-23
**Status:** Approved
**Scope:** Systematically map every Go NATS server test function to .NET equivalents, fill all gaps to achieve behavioral test parity.

## 1. Current State

The .NET port has all source code implemented (~170 source files, 236 test files, 867 passing tests). However, the Go reference has **3,451+ test functions** across 88 test files. Systematic mapping reveals **~18% coverage** of Go test intents.

### Coverage Matrix

| Subsystem | Go Tests | .NET Tests | Coverage | Phase |
|-----------|----------|-----------|----------|-------|
| Parser | 17 | 8 | 47% | A |
| SubList | 62 | 22 | 35% | A |
| Client | 82 | 3 | 4% | A |
| Server | 44 | 17 | 39% | A |
| Routes | 70 | 12 | 17% | A |
| Gateways | 88 | 9 | 10% | A |
| Leaf Nodes | 110 | 8 | 7% | A |
| Auth | 12 | 10 | 83% | A |
| Accounts | 64 | 18 | 28% | A |
| JetStream Core | 472 | 82 | 17% | C |
| JetStream Clustering | 503 | 4 | 1% | C |
| Storage | 269 | 2 | 1% | B |
| Config/Reload | 159 | 77 | 48% | B |
| Monitoring/Events | 184 | 28 | 15% | B |
| RAFT | 104 | 15 | 14% | B |
| MQTT | 123 | 8 | 7% | D |
| WebSocket | 61 | 66 | 108% | - |
| JWT | 88 | 61 | 69% | D |
| **TOTAL** | **~2,512** | **~454** | **~18%** | |

## 2. Architecture and Approach

### Hybrid Dependency-First Phasing

Execute in 4 gated phases ordered by dependency criticality:

1. **Phase A (Foundation):** Client, Parser, SubList, Server, Routes, Gateways, Leaf Nodes, Accounts (~440 tests)
2. **Phase B (Distributed Substrate):** RAFT, Storage, Config/Reload, Monitoring/Events (~594 tests)
3. **Phase C (JetStream Depth):** JetStream Core, JetStream Clustering (~889 tests)
4. **Phase D (Protocol Surfaces):** MQTT, Auth/JWT hardening (~135 tests)

### Test Philosophy

- **Behavioral equivalence, not 1:1 test count parity.** One .NET test may cover multiple Go tests if it preserves the same contract and failure detection power.
- **Every Go test intent mapped.** Maintain `go-dotnet-test-mapping.md` tracking every Go test function to .NET tests or explicit N/A rationale.
- **Primary KPI:** Contract coverage by subsystem, not raw test count.
- **Test-first:** Write failing test, then implement/fix, then verify pass.

### Execution Model

- Each phase is a gate — must pass full `dotnet test` before advancing.
- Within phases, subsystems are independent and run in parallel via subagents.
- Use `model: "sonnet"` for straightforward test porting, `model: "opus"` for complex protocol/concurrency tests.
- One commit per subsystem batch.
- JetStream sentinel tests run during Phase A as early-warning canaries.

## 3. Phase A: Foundation (~440 tests)

### A1: Client Tests (79 missing)

**Go file:** `client_test.go` (82 tests)
**Current .NET:** `ClientTests.cs` (3 tests)

Categories to fill:
- Basic pub/sub (8): ClientSimplePubSub, PubSubNoEcho, PubWithQueueSub, PubSubWithReply
- Header handling (12): HeaderDeliverMsg, HeaderStrippedMsg, SliceHeader, SetHeaderOrdering
- UNSUB & auto-unsub (5): ClientUnSub, UnSubMax, AutoUnsubExactReceived
- Slow consumer (5): NoClientLeakOnSlowConsumer, MaxPending, FlushOutbound
- TLS connection (8): CloseTLSConnection, TLSHandshakeFirst, TLSFallbackDelay
- Auth & permissions (6): AuthTimeout, ResponsePermissions, QueueSubscribePermissions
- Client lifecycle (8): RemoveSubsOnDisconnect, MapRemoval, ConnectionName, Limits
- Message tracing (5): TraceMsg, TraceMsgHeaders, TraceMsgDelivery
- Protocol edge cases (10): ConnectProto, TypeString, SplitSubjectQueue, IPv6Address
- Miscellaneous (12): PingNotSentTooSoon, GWReplyPrefix, ReadloopWarning

New test files:
- `ClientPubSubTests.cs` — basic messaging
- `ClientHeaderTests.cs` — HPUB/HMSG handling
- `ClientLifecycleTests.cs` — connect/disconnect/cleanup
- `ClientSlowConsumerTests.cs` — backpressure
- `ClientTlsTests.cs` — TLS scenarios

### A2: Parser Tests (9 missing)

**Go file:** `parser_test.go` (17 tests)
**Current .NET:** `ParserTests.cs` (8 tests)

Missing: ParsePubSizeOverflow, ParsePubArg, ParsePubBadSize, ParseHeaderPubArg, ParseRoutedHeaderMsg, ParseRouteMsg, ParseMsgSpace, ShouldFail (parametrized negatives), MaxControlLine.

Add to existing `ParserTests.cs`.

### A3: SubList Tests (40 missing)

**Go file:** `sublist_test.go` (62 tests)
**Current .NET:** `SubListTests.cs` + `SubjectMatchTests.cs` (22 tests)

Categories:
- No-cache variants (~16): Add as `[Theory]` data rows
- Concurrency/race (3): RaceOnRemove, RaceOnInsert, RaceOnMatch — use `Task.WhenAll`
- Validation (6): InvalidSubjectsInsert, ValidLiteralSubjects
- Edge cases (8): LargeSubs, EmptyTokens, WildcardsAsLiterals
- Remote subs (2): RemoteQueueSubscriptions
- Utilities (5): SubjectCollide, SubjectToken, IsSubsetMatch

### A4: Server Tests (27 missing)

**Go file:** `server_test.go` (44 tests)
**Current .NET:** ServerTests.cs + related (17 tests)

Major gaps: TLS version/cipher config (5), advertise URLs (3), max subscriptions (1), lame duck info (1), startup/shutdown edge cases (6), config validation (5), misc (6).

### A5: Routes (58 missing)

**Go file:** `routes_test.go` (70 tests)
**Current .NET:** Route*Tests.cs (12 tests)

Major gaps: Route config/TLS (10), auth over routes (5), compression variants (15), per-account routing (5), pool management (5), slow consumer/reconnect (8), race conditions (5), misc (5).

### A6: Gateways (79 missing)

**Go file:** `gateway_test.go` (88 tests)
**Current .NET:** Gateway*Tests.cs (9 tests)

Major gaps: Basic gateway flow (5), auth/TLS (8), service imports/exports (10), queue handling (8), interest tracking (10), reply mapping (5), URL discovery (5), compression (5), error handling (10), misc (13).

### A7: Leaf Nodes (102 missing)

**Go file:** `leafnode_test.go` (110 tests)
**Current .NET:** Leaf*Tests.cs (8 tests)

Major gaps: Auth (10), TLS (8), loop detection (8), permissions (5), queue distribution (8), compression (5), WebSocket (15), import/export (10), topology (10), slow consumer (3), misc (20).

### A8: Accounts (46 missing)

**Go file:** `accounts_test.go` (64 tests)
**Current .NET:** Account*Tests.cs (18 tests)

Major gaps: Config parsing (8), import/export (12), subject mapping (6), connection limits (4), service exports (5), latency tracking (3), misc (8).

## 4. Phase B: Distributed Substrate (~594 tests)

### B1: RAFT Consensus (89 missing)

**Go file:** `raft_test.go` (104 tests)
**Current .NET:** Raft*Tests.cs (15 tests)

Categories: Election mechanics (15), log replication (20), snapshot (15), membership changes (10), partition handling (10), edge cases (19).

Write .NET-native scenario tests — RAFT timing behavior differs between goroutines and async/await. Focus on state-machine correctness invariants.

### B2: Storage (267 missing)

**Go files:** `filestore_test.go` (232), `memstore_test.go` (37)
**Current .NET:** 2 tests

Build a storage contract suite + fault-injection harness:
- Contract tests: append/read/delete, compaction, retention/TTL, index rebuild, checksums, snapshot/recovery
- Failure tests: partial writes, fsync failures, restart during compaction, torn metadata, concurrent access
- Run same contracts against both `MemStore` and `FileStore` via `IStreamStore`
- Focus on externally visible durability/invariants

Categories: FileStore basics (40), block management (30), retention/limits (25), recovery (35), compression (15), encryption (15), subject indexing (20), MemStore (35), snapshot/restore (15), failure injection (20), performance (17).

### B3: Config & Reload (82 missing)

**Go files:** `opts_test.go` (86), `reload_test.go` (73)
**Current .NET:** Config*Tests.cs (77 tests)

Categories: CLI arg parsing (10), config file features (15), subsystem config (15), TLS config (10), auth config (8), hot reload (15), validation (9).

### B4: Monitoring & Events (156 missing)

**Go files:** `monitor_test.go` (100), `events_test.go` (51), `msgtrace_test.go` (33)
**Current .NET:** Monitor*Tests.cs + Event*Tests.cs (28 tests)

Categories: /varz (20), /connz (25), /routez+/gatewayz+/leafz (20), /jsz (15), /healthz (5), system events (30), message tracing (25), signal handling (10), rate-limit logging (6).

## 5. Phase C: JetStream Depth (~889 tests)

### C1: JetStream Core (390 missing)

**Go files:** `jetstream_test.go` (312), `jetstream_consumer_test.go` (160)
**Current .NET:** JetStream*Tests.cs (82 tests)

Categories: Stream lifecycle (40), publish semantics (30), consumer delivery (50), ack policies (25), retention policies (20), flow control (15), ordered consumers (10), subject transforms (15), mirror/source (25), API endpoints (30), account/permission (20), error handling (20), batching (15), direct API (10), misc (65).

### C2: JetStream Clustering (499 missing)

**Go files:** `jetstream_cluster_[1-4]_test.go` (456), `jetstream_super_cluster_test.go` (47)
**Current .NET:** 4 tests

Write .NET-native cluster tests using in-process multi-server fixtures. Don't attempt 1:1 Go test translation — cover same behavioral contracts.

Categories: Cluster formation (30), multi-replica streams (50), consumer replication (40), leader failover (30), snapshot/catchup (25), super-cluster (45), mirror/source in cluster (30), account isolation (20), stream recovery (30), consumer edge cases (30), scaling (20), config reload (15), integration (134).

## 6. Phase D: Protocol Surfaces (~135 tests)

### D1: MQTT (115 missing)

**Go file:** `mqtt_test.go` (123 tests)
**Current .NET:** Mqtt*Tests.cs (8 tests)

Categories: Packet parsing (15), QoS handling (20), session management (15), auth/TLS (10), keep-alive (5), topic handling (15), will messages (5), retain (5), integration (25).

### D2: Auth/JWT Hardening (~20 missing)

JWT at 69% — fill claim validation edge cases, token rotation, revocation.

## 7. Completion Gates

### Per-Phase Gates
- Phase A: `dotnet test` passes. Client pub/sub, routing, gateway, leaf node basics verified.
- Phase B: RAFT election/append/snapshot pass. FileStore append/read/recovery pass. Monitor endpoints return valid JSON.
- Phase C: All JetStream API endpoints work. Stream/consumer lifecycle correct. Cluster failover preserves data.
- Phase D: MQTT pub/sub works. JWT full claim validation passes.

### Final Gate
- Every Go test intent mapped in `go-dotnet-test-mapping.md`
- `dotnet test` passes with zero failures
- No subsystem below 60% behavioral coverage
- `differences.md` synchronized with verified behavior

## 8. Error Handling and Testing Strategy

- Preserve protocol-specific error semantics (NATS, MQTT, JetStream)
- Fail closed on account/auth/consensus violations
- Test-first for every capability
- Happy-path + edge/failure coverage per capability
- Integration tests for inter-server, RAFT/cluster, and restart durability
- Unit tests for deterministic parser/state primitives
- Use Shouldly assertions, xUnit 3, NSubstitute — never Assert.*, FluentAssertions, or Moq
