Mock Server
How to stand in for the HTTP services an application calls, in integration and end-to-end tests and while developing:
Anarchy.Toolkit.Web.MockServer (the server), Anarchy.Toolkit.Testing.MockServer (assertions) and the
IMockServerBuild targets (lifecycle). The package READMEs list every option; this guide is about choosing and
combining them.
What to use when
| Need | Use |
|---|---|
| Fixed answers for an upstream API | Expectation files (tests/mocks/**/*.json), loaded with --expectations / MockServerExpectations. |
| Answers that depend on the request (computed bodies, fake auth) | A middleware in your own host (server.Use(...)), see Your own host. |
| A test that needs one specific answer | A runtime expectation: MockServerClient.AddExpectationAsync, reset with ResetAsync. |
| Asserting what the application sent | AssertReceivedAsync / ShouldHaveReceived while the server runs, or RecordedRequestsFile.Read afterwards. |
| Failing on calls nothing mocks | ShouldAllHaveBeenMatched() on the recorded requests. |
| Starting it around the tests | make test_integration_mocked / make test_end_to_end_mocked (exposes MOCKSERVER_URL). |
| Keeping mocks in step with an OpenAPI document | make mock_server_sync_openapi SPEC=<file-or-url>. |
| Recording a real upstream’s answers as expectations | A forwarding middleware, see Recording a real upstream. |
| Editing expectations while the server runs | --watch (or ARGS=--watch), or POST /__mock/reload. |
| Looking at what happened | The UI at /__mock/ui (with Anarchy.Toolkit.Web.MockServer.Ui), -v detailed, or GET /__mock/logs. |
Setting it up
- Add a runnable project whose name ends in
MockServer(for examplesrc/Api/MockServer), referencingAnarchy.Toolkit.Web.MockServer, withreturn await MockServerEntryPoint.RunAsync(args);as itsProgram.cs. - Implement
IMockServerBuildinbuild/Build.csand point it at the expectations, in.fallout/parameters.json("MockServerExpectations": ["tests/mocks"]) or in code. - Point the application’s upstream base URLs at the mock server in its test settings. The targets set
MOCKSERVER_URL; tests that run on their own (from an IDE) use aMockServerFixture, which spawns the server when that variable is missing. - Run
make test_end_to_end_mocked: it starts the server, runs the tests, records every request toartifacts/mock-server/requests.jsonland stops it.
Expectations
Expectations use MockServer’s JSON shape: one object or an array per file, with httpRequest (method, path, query, headers, body matchers)
and httpResponse (status, headers, body, delay), plus priority and times. Paths can be exact, {id} templates
or regular expressions. Keep one file per upstream endpoint or scenario, under a folder per upstream.
Asserting
public class QuoteTests(CarriersMockServer mock) : IClassFixture<CarriersMockServer>
{
[Fact]
public async Task Quote_AsksEveryCarrier()
{
await mock.Client.ResetAsync(TestContext.Current.CancellationToken);
// … call the application …
await mock.Client.AssertReceivedAsync("POST", "/carriers/{carrier}/quotes", times: 2);
}
}
To check a whole run instead, after the server stopped, read the record file and fail on anything no expectation answered:
RecordedRequestsFile.Read("artifacts/mock-server/requests.jsonl").ShouldAllHaveBeenMatched();
Your own host
When fixed answers are not enough, write the host’s Program.cs yourself and plug in middlewares. They run after
expectation matching: context.GetMockServer() gives the parsed request and the matched Expectation (or
null), and a middleware either answers (setting AnsweredBy, which the records and the UI show) or calls next.
return await MockServerEntryPoint.RunAsync(args, server => server
.AddExpectationsFrom("tests/mocks")
.Use(async (context, next) => {
var mock = context.GetMockServer();
if (mock.Expectation is null && mock.Request.Path.StartsWith("/stock", StringComparison.Ordinal))
{
await context.Response.WriteAsJsonAsync(new { available = 3 });
mock.AnsweredBy = "stock middleware";
return;
}
await next(context);
}, name: "stock middleware"));
Recording a real upstream
The server has no built-in proxy mode: recording is rare (refreshing mocks after an upstream changed), needs credentials and decisions about what to keep, and fits in one middleware. Forward what no expectation matches to the real service and save each answer as an expectation file, then review the files, strip anything sensitive and commit them:
var upstream = new HttpClient { BaseAddress = new Uri(Environment.GetEnvironmentVariable("RECORD_UPSTREAM")!) };
const string output = "tests/mocks/recorded";
Directory.CreateDirectory(output);
return await MockServerEntryPoint.RunAsync(args, server => server
.AddExpectationsFrom("tests/mocks")
.Use(async (context, next) => {
var mock = context.GetMockServer();
if (mock.Expectation is not null || upstream.BaseAddress is null)
{
await next(context);
return;
}
var request = mock.Request;
using var forward = new HttpRequestMessage(new HttpMethod(request.Method), request.Path + context.Request.QueryString);
if (request.Body is { Length: > 0 } body)
forward.Content = new StringContent(body, Encoding.UTF8, context.Request.ContentType ?? "application/json");
using var response = await upstream.SendAsync(forward, context.RequestAborted);
var content = await response.Content.ReadAsStringAsync(context.RequestAborted);
var expectation = new JsonObject {
["httpRequest"] = new JsonObject { ["method"] = request.Method, ["path"] = request.Path },
["httpResponse"] = new JsonObject {
["statusCode"] = (int)response.StatusCode,
["headers"] = new JsonObject { ["Content-Type"] = new JsonArray(response.Content.Headers.ContentType?.ToString() ?? "application/json") },
["body"] = content
}
};
var name = $"{request.Method}{request.Path.Replace('/', '_')}.json".ToLowerInvariant();
await File.WriteAllTextAsync(Path.Combine(output, name),
expectation.ToJsonString(new JsonSerializerOptions { WriteIndented = true }), context.RequestAborted);
context.Response.StatusCode = (int)response.StatusCode;
context.Response.ContentType = response.Content.Headers.ContentType?.ToString();
await context.Response.WriteAsync(content, context.RequestAborted);
mock.AnsweredBy = "recording proxy";
}, name: "recording proxy"));
Run it with RECORD_UPSTREAM=https://… make mock_server, exercise the application, and stop it. Add query, header
or body matchers to the saved httpRequest when one path has several answers. The toolkit’s unit tests run this
recipe, so it stays correct.
What it covers
Matching on JSON bodies, regular expressions, times and priority follow MockServer’s expectation format. Callbacks, templates (Velocity, JavaScript) and proxy forwarding are not built in: write a middleware, such as the recording middleware, and assert on what was received with AssertReceivedAsync / ShouldHaveReceived, or on unmocked calls with ShouldAllHaveBeenMatched. IMockServerBuild starts the server around the tests, so no container is needed.