natsdotnet/docs/plans/2026-03-12-e2e-extended-design.md

NATS.E2E.Tests Extended Coverage — Design

Date: 2026-03-12 Status: Approved

Overview

Extend the existing NATS.E2E.Tests project with phased test coverage that progressively exercises more complex NATS server functionality. All tests are black-box: the server runs as a child process, tests connect via NATS.Client.Core (and NATS.Client.JetStream for Phase 5).

Infrastructure Extensions

NatsServerProcess Changes

• Add optional string[]? extraArgs to constructor, appended after -p <port>
• Add WithConfigFile(string content) static factory — writes content to a temp file, passes -c <path>, cleans up on dispose
• Add MonitorPort property — allocates a second free port when monitoring is needed, passes -m <port>

New Fixtures (Infrastructure/)

Each fixture gets its own [CollectionDefinition]:

Fixture	Collection	Config
NatsServerFixture (existing)	E2E	Default, no auth/TLS/JS
AuthServerFixture	E2E-Auth	Config file with users, tokens, NKeys, permissions
MonitorServerFixture	E2E-Monitor	-m <port> for HTTP monitoring
TlsServerFixture	E2E-TLS	Self-signed certs generated at startup, --tlscert/--tlskey/--tlscacert
AccountServerFixture	E2E-Accounts	Config with two isolated accounts
JetStreamServerFixture	E2E-JetStream	Config with jetstream { store_dir: <tmpdir> }

Shared Helper

E2ETestHelper static class:

• CreateClient(int port) — returns NatsConnection
• Timeout(int seconds = 10) — returns CancellationToken

NuGet Additions

• NATS.NKeys — already in Directory.Packages.props, add to E2E csproj
• NATS.Client.JetStream — add to Directory.Packages.props and E2E csproj

Phase 1: Core Messaging (11 tests)

File: CoreMessagingTests.cs — [Collection("E2E")]

Test	Verifies
WildcardStar_MatchesSingleToken	Sub foo.*, pub foo.bar → received
WildcardGreaterThan_MatchesMultipleTokens	Sub foo.>, pub foo.bar.baz → received
WildcardStar_DoesNotMatchMultipleTokens	Sub foo.*, pub foo.bar.baz → no message
QueueGroup_LoadBalances	3 queue subs, 30 msgs → distributed across all 3
QueueGroup_MixedWithPlainSub	1 plain + 2 queue subs → plain gets all, 1 queue gets each
Unsub_StopsDelivery	Sub, unsub, pub → no message
Unsub_WithMaxMessages	Auto-unsub after 3, pub 5 → only 3 received
FanOut_MultipleSubscribers	3 subs, 1 pub → all 3 receive
EchoOff_PublisherDoesNotReceiveSelf	echo: false, self-pub → no echo
VerboseMode_OkResponses	Raw socket, verbose: true → +OK after SUB
NoResponders_Returns503	no_responders: true, request with no subs → 503

Phase 2: Auth & Permissions (12 tests)

File: AuthTests.cs — [Collection("E2E-Auth")]

Config includes: user/pass pair, token, NKey public key, permission-restricted users, max_subs: 5 user.

Test	Verifies
UsernamePassword_ValidCredentials_Connects	Correct user/pass → connected
UsernamePassword_InvalidPassword_Rejected	Wrong pass → rejected
UsernamePassword_NoCredentials_Rejected	No creds to auth server → rejected
TokenAuth_ValidToken_Connects	Correct token → connected
TokenAuth_InvalidToken_Rejected	Wrong token → rejected
NKeyAuth_ValidSignature_Connects	Valid NKey sig → connected
NKeyAuth_InvalidSignature_Rejected	Wrong NKey sig → rejected
Permission_PublishAllowed_Succeeds	Pub to allowed subject → delivered
Permission_PublishDenied_NoDelivery	Pub to denied subject → not delivered
Permission_SubscribeDenied_Rejected	Sub to denied subject → rejected
MaxSubscriptions_ExceedsLimit_Rejected	6th sub on max_subs: 5 user → rejected
MaxPayload_ExceedsLimit_Disconnected	Oversized message → disconnected

Phase 3: Monitoring & Config (7 tests)

File: MonitoringTests.cs — [Collection("E2E-Monitor")]

Fixture exposes MonitorPort and HttpClient MonitorClient.

Test	Verifies
Healthz_ReturnsOk	GET /healthz → 200, {"status":"ok"}
Varz_ReturnsServerInfo	GET /varz → JSON with server_id, version, port
Varz_ReflectsMessageCounts	Publish msgs, GET /varz → in_msgs > 0
Connz_ListsActiveConnections	2 clients, GET /connz → num_connections: 2
Connz_SortByParameter	GET /connz?sort=bytes_to → sorted
Connz_LimitAndOffset	5 clients, GET /connz?limit=2&offset=1 → 2 entries
Subz_ReturnsSubscriptionStats	Subs active, GET /subz → count > 0

Phase 4: TLS & Account Isolation (6 tests)

File: TlsTests.cs — [Collection("E2E-TLS")]

Fixture generates self-signed CA + server cert + client cert using System.Security.Cryptography at startup.

Test	Verifies
Tls_ClientConnectsSecurely	TLS connect + ping succeeds
Tls_PlainTextConnection_Rejected	Non-TLS connect → fails
Tls_PubSub_WorksOverEncryptedConnection	Full pub/sub over TLS

File: AccountIsolationTests.cs — [Collection("E2E-Accounts")]

Config with ACCT_A and ACCT_B, each with its own user.

Test	Verifies
Accounts_SameAccount_MessageDelivered	Two ACCT_A clients → pub/sub works
Accounts_CrossAccount_MessageNotDelivered	ACCT_A pub, ACCT_B sub → no message
Accounts_EachAccountHasOwnNamespace	Both accounts sub foo.bar independently

Phase 5: JetStream (10 tests)

File: JetStreamTests.cs — [Collection("E2E-JetStream")]

Fixture enables JetStream with temp store_dir.

Test	Verifies
Stream_CreateAndInfo	Create stream, verify info matches config
Stream_ListAndNames	Create 3 streams, list/names returns all
Stream_Delete	Create, delete, verify gone
Stream_PublishAndGet	Publish msgs, get by sequence
Stream_Purge	Publish, purge, verify count = 0
Consumer_CreatePullAndConsume	Pull consumer, publish 5, pull → receive 5
Consumer_AckExplicit	Explicit ack, verify no redelivery
Consumer_ListAndDelete	Create consumers, list, delete, verify
Retention_LimitsMaxMessages	max_msgs: 10, publish 15 → stream has 10
Retention_MaxAge	Short max_age, verify msgs expire

Test Count Summary

Phase	Tests	New Files
1 — Core Messaging	11	CoreMessagingTests.cs
2 — Auth & Permissions	12	AuthTests.cs, AuthServerFixture.cs
3 — Monitoring	7	MonitoringTests.cs, MonitorServerFixture.cs
4 — TLS & Accounts	6	TlsTests.cs, TlsServerFixture.cs, AccountIsolationTests.cs, AccountServerFixture.cs
5 — JetStream	10	JetStreamTests.cs, JetStreamServerFixture.cs
Total	46

Plus infrastructure changes: NatsServerProcess.cs (edit), E2ETestHelper.cs (new).