MockServerClient 7.1.0

MockServerClient for .NET

A hand-written, idiomatic .NET client for MockServer's control-plane REST API.

Installation

The NuGet package is MockServerClient (the assembly and namespace remain MockServer.Client):

dotnet add package MockServerClient

Or via PackageReference in your .csproj:

<PackageReference Include="MockServerClient" Version="7.0.1" />

Supported Targets

• .NET Standard 2.0 (for broad compatibility: .NET Framework 4.6.1+, .NET Core 2.0+, Mono 5.4+)
• .NET 8.0 (for modern APIs and best performance)

Usage

using MockServer.Client;
using MockServer.Client.Models;

// Create client
using var client = new MockServerClient("localhost", 1080);

// Create an expectation with fluent API
client.When(
    HttpRequest.Request()
        .WithMethod("GET")
        .WithPath("/hello")
        .WithQueryStringParameter("name", "world")
).Respond(
    HttpResponse.Response()
        .WithStatusCode(200)
        .WithHeader("Content-Type", "application/json")
        .WithBody("{\"message\":\"hello world\"}")
);

// Verify the request was received
client.Verify(
    HttpRequest.Request().WithPath("/hello"),
    VerificationTimes.AtLeastTimes(1)
);

// Reset all expectations
client.Reset();

Forward Expectations

client.When(
    HttpRequest.Request().WithPath("/proxy")
).Forward(
    HttpForward.Forward()
        .WithHost("backend.example.com")
        .WithPort(443)
        .WithScheme("HTTPS")
);

Verify Sequence

client.VerifySequence(
    HttpRequest.Request().WithPath("/first"),
    HttpRequest.Request().WithPath("/second")
);

Retrieve Recorded Requests

var requests = client.RetrieveRecordedRequests(
    HttpRequest.Request().WithPath("/api")
);

Async API

All operations have async variants:

await client.VerifyAsync(
    HttpRequest.Request().WithPath("/hello"),
    VerificationTimes.AtLeastTimes(1)
);

Interactive Breakpoints

Register breakpoint matchers to pause forwarded/proxied traffic at REQUEST, RESPONSE, RESPONSE_STREAM, or INBOUND_STREAM phases. A callback WebSocket connection is opened automatically.

using MockServer.Client.Models;
using System.Text.Json.Nodes;

// REQUEST-only breakpoint
var id = client.AddRequestBreakpoint(
    HttpRequest.Request().WithPath("/api/.*").Build(),
    request => request // continue with original
);

// REQUEST + RESPONSE breakpoint
var id2 = client.AddRequestResponseBreakpoint(
    HttpRequest.Request().WithPath("/api/.*").Build(),
    request => request,
    (request, response) => response
);

// Streaming breakpoint
var id3 = client.AddStreamBreakpoint(
    HttpRequest.Request().WithPath("/stream/.*").Build(),
    new[] { BreakpointPhase.ResponseStream },
    frame => StreamFrameDecision.Continue(frame.CorrelationId!)
);

// Manage matchers
var list = client.ListBreakpointMatchers();
client.RemoveBreakpointMatcher(id);
client.ClearBreakpointMatchers();

Stream frame decisions: StreamFrameDecision.Continue, .Modify, .Drop, .Inject, .Close.

Start / Launch MockServer

The .NET client can download and launch a local MockServer instance directly -- no Java installation and no Docker required. The launcher downloads a self-contained platform bundle (mockserver-<version>-<os>-<arch>) from the GitHub Release, verifies its SHA-256, caches it per-user, and starts it.

Quick start

using MockServer.Client;

// Download (first run) and start MockServer on port 1080
using var launcher = MockServerBinaryLauncher.Start(port: 1080);
Console.WriteLine($"MockServer started, PID {launcher.Process?.Id}");

// ... use MockServer ...

launcher.Stop();
// or let the using statement dispose and stop it automatically

Async API

using var launcher = await MockServerBinaryLauncher.StartAsync(port: 1080);

Just ensure the binary is present

string launcherPath = await MockServerBinaryLauncher.EnsureBinaryAsync();
// or synchronously:
string launcherPath = MockServerBinaryLauncher.EnsureBinary();

Specify a version

using var launcher = MockServerBinaryLauncher.Start(port: 1080, version: "7.1.0");

API reference

Supported platforms

Environment variables

Version

By default the launcher downloads the MockServer version matching this NuGet package (derived from the <Version> property in the .csproj at build time). Pass an explicit version argument to override.

Building

cd mockserver-client-dotnet
dotnet build
dotnet test

Requirements

• .NET SDK 8.0+ (for building)
• System.Net.WebSockets.ClientWebSocket (built-in, for breakpoint callback WebSocket)
• No external runtime dependencies beyond System.Text.Json (included via .NET or NuGet for netstandard2.0)

License

Apache 2.0 - see LICENSE