NatsSandbox 0.1.0

🧩 NATS Sandbox

Simple local orchestration of temporary NATS server for .NET 6–9 — built for tests, benchmarks, and experiments.

✨ Overview

NATS Sandbox spins up disposable NATS server with zero manual setup.
It automatically downloads the NATS binary, starts it locally, and tears it down when finished — so you can focus on messaging, not ops.

Why you'll love it

• 🧱 Self-contained — no external dependencies; no docker; everything runs in-process
• ⚡ Temporary — perfect for unit & integration testing
• 🧭 Cross-platform — works on Windows, Linux, macOS
• 🪶 Simple API — a single call: using var runner = NatsRunner.Run();

📦 Installation

dotnet add package NatsSandbox

Requires .NET 6 or newer.

Example

using NATS.Client.Core;
using NatsSandbox;
using Xunit;

public class IntegrationTests : IAsyncLifetime
{
    private INatsRunner _runner = null!;
    private NatsConnection _nats = null!;

    public async Task InitializeAsync()
    {
        _runner = NatsRunner.Run();
        _nats = new NatsConnection(new NatsOpts { Url = _runner.Url });
        await _nats.ConnectAsync();
    }

    public async Task DisposeAsync()
    {
        await _nats.DisposeAsync();
        _runner.Dispose();
    }

    [Fact]
    public async Task Publish_And_Subscribe_Works()
    {
        var tcs = new TaskCompletionSource<bool>();

        _ = Task.Run(async () =>
        {
            await foreach (var msg in _nats.SubscribeAsync<string>("test.subject"))
            {
                Assert.Equal("Hello", msg.Data);
                tcs.TrySetResult(true);
                break;
            }
        });

        await Task.Delay(200);
        await _nats.PublishAsync("test.subject", "Hello");

        await tcs.Task.WaitAsync(TimeSpan.FromSeconds(5));
    }
}

NatsRunnerOptions

You can fully customise HTTP behavior (headers, auth token, rate-limit handling) via your own IHttpTransport implementation.

Use a Specific Port

var runner = NatsRunner.Run(new NatsRunnerOptions
{
    Port = 4222
});

Enable Logging

var runner = NatsRunner.Run(new NatsRunnerOptions
{
    StandardOutputLogger = Console.WriteLine,
    EnableDebugLogging = true
});

Troubleshooting

Test Hangs or Times Out

The NATS binary download might be slow on first run. Subsequent runs use the cached binary.

Port Already in Use

Don't specify a port - let NatsSandbox choose a random available port (default behavior).

Windows Firewall Prompt

Click "Allow" when prompted. NATS needs to open a network port for communication.

🖥️ Supported Platforms

🧰 Development Notes

• Caches binaries per version tag in %LOCALAPPDATA%/nats-sandbox/bin/vX.Y.Z
• Performs platform-specific extraction and sets executable permissions on Unix
• Thread-safe via internal SemaphoreSlim during version checks

🪪 License

MIT © Wassim K— see LICENSE