Anarchy.Toolkit.Web.MockServer
1.1.0
See the version list below for details.
dotnet add package Anarchy.Toolkit.Web.MockServer --version 1.1.0
NuGet\Install-Package Anarchy.Toolkit.Web.MockServer -Version 1.1.0
<PackageReference Include="Anarchy.Toolkit.Web.MockServer" Version="1.1.0" />
<PackageVersion Include="Anarchy.Toolkit.Web.MockServer" Version="1.1.0" />
<PackageReference Include="Anarchy.Toolkit.Web.MockServer" />
paket add Anarchy.Toolkit.Web.MockServer --version 1.1.0
#r "nuget: Anarchy.Toolkit.Web.MockServer, 1.1.0"
#:package Anarchy.Toolkit.Web.MockServer@1.1.0
#addin nuget:?package=Anarchy.Toolkit.Web.MockServer&version=1.1.0
#tool nuget:?package=Anarchy.Toolkit.Web.MockServer&version=1.1.0
Anarchy.Toolkit.Web.MockServer
Part of Anarchy I/O Toolkit, a .NET developer platform · Pillar: Infrastructure · Layer: Web · Package catalog
An HTTP mock server for integration and end-to-end tests: JSON expectations, pluggable middlewares, request recording and colourful console output.
dotnet add package Anarchy.Toolkit.Web.MockServer
- Expectations follow MockServer's JSON shape, so existing
expectations/*.jsonfiles work as they are. - Your own middlewares run between expectation matching and the answer: they can answer by themselves or change the match.
- Every request can be appended to a JSON-lines file, and is queryable through the
/__mockcontrol API (seeAnarchy.Toolkit.Testing.MockServerfor test assertions). - It listens on port
6001, or the next free one when that is taken.
When to use it
Use it to stand in for the HTTP services an application calls while integration or end-to-end tests run against it.
It is a console application whose lifetime is usually driven by the Fallout IMockServerBuild targets or a Makefile,
but it can also be run by hand, spawned from a test, or started in-process with MockServerHost.StartAsync.
How to use it
Write expectations, one object or an array per file:
[
{
"httpRequest": { "method": "GET", "path": "/orders/{id}", "headers": { "Authorization": ["Bearer .+"] } },
"httpResponse": { "statusCode": 200, "headers": { "Content-Type": ["application/json"] }, "body": { "id": 1 } }
},
{
"httpRequest": { "method": "POST", "path": "/orders", "body": { "type": "JSON", "json": { "customerId": 7 } } },
"httpResponse": { "statusCode": 201, "delay": { "timeUnit": "MILLISECONDS", "value": 50 } },
"times": { "remainingTimes": 1 },
"priority": 10
}
]
- Paths are exact (
/orders), templated (/orders/{id}) or regular expressions (/orders/[0-9]+); exact beats templated beats regular expression, afterpriority. - Query parameters and headers must contain every listed value (each one a regular expression).
- Bodies match when the request contains the given JSON (or equals it with
"matchType": "STRICT"), a string,{ "type": "STRING", "string": …, "subString": true }or{ "type": "REGEX", "regex": … }. - Responses write a string body as-is and anything else as JSON.
Run it:
dotnet Anarchy.Toolkit.Web.MockServer.dll -e "mocks/**/*.json" --record artifacts/mock-requests.jsonl -v detailed
| Option | Environment | Description |
|---|---|---|
-p, --port |
MOCKSERVER_PORT |
Port (default 6001 or the next free one; 0 lets the OS choose; an explicit port that is taken fails). |
--host |
MOCKSERVER_HOST |
Host (default localhost). |
-e, --expectations |
MOCKSERVER_EXPECTATIONS (;-separated) |
File, directory or glob; repeatable. |
-w, --watch |
MOCKSERVER_WATCH |
Reload expectations when the files change. |
-r, --record |
MOCKSERVER_RECORD |
Append every request to a JSON-lines file. |
--record-limit |
MOCKSERVER_RECORD_LIMIT |
Requests kept in memory (default 1000, 0 = all). |
--log-buffer |
MOCKSERVER_LOG_BUFFER |
Log entries kept in memory for the UI and /__mock/logs (default 1000, 0 = all). |
--no-ui |
MOCKSERVER_UI=false |
Do not serve the UI, on hosts that plug one in (Anarchy.Toolkit.Web.MockServer.Ui). |
--kill-timeout |
MOCKSERVER_KILL_TIMEOUT |
Stop after this many seconds. |
--unmatched-status |
MOCKSERVER_UNMATCHED_STATUS |
Status when nothing matches (default 404). |
-v, --verbosity |
MOCKSERVER_VERBOSITY |
quiet, minimal, normal (default), detailed (headers and bodies) or diagnostic (responses and ASP.NET Core logs). |
-q, --quiet |
Same as --verbosity quiet. |
|
--no-color |
NO_COLOR |
Plain output. |
Once listening it always prints MOCKSERVER_READY port=<port> url=<url>, whatever the verbosity, for whoever spawned it.
Your own host and middlewares
return await MockServerEntryPoint.RunAsync(args, server => server
.AddExpectationsFrom("mocks")
.UseMiddleware<FakeAuthMiddleware>()
.Use(async (context, next) => {
var mock = context.GetMockServer();
if (mock.Request.Path.StartsWith("/stock") && mock.Request.Query.ContainsKey("sku"))
{
await context.Response.WriteAsJsonAsync(new { sku = mock.Request.Query["sku"][0], available = 3 });
mock.AnsweredBy = "stock middleware";
return;
}
await next(context);
}, name: "stock middleware"));
Middlewares are listed, in order, by GET /__mock/middlewares and the UI: classes by type name, delegates by the
name given (or their method). Extensions such as the UI hook in with ConfigureWebApplication, ExtendPipeline and
AnnounceUi.
Recording received requests
Every request that is not for /__mock is recorded, standalone or in a host of your own, so tests can assert on what
the system under test sent:
- In memory, always: the last
--record-limitrequests (1000 by default,0keeps them all), served byGET /__mock/requestsand cleared byDELETE /__mock/requestsorPOST /__mock/reset. This is whatMockServerClient.GetRequestsAsyncand theAssertReceivedAsyncassertions ofAnarchy.Toolkit.Testing.MockServerread, while the server runs. - In a file, with
--record <file>: one JSON object per line, truncated at startup and never cleared by the control API. Read it withRecordedRequestsFile.Read, e.g. after the server stopped or from another process. The FalloutIMockServerBuildtargets record toartifacts/mock-server/requests.jsonlby default.
Each record has its sequence, timestamp, method, path, query, headers, body, the expectation (or middleware) that answered, the status code and the duration.
Logs
Everything the server writes (startup, requests, warnings, errors, and ASP.NET Core warnings) is also kept in an
in-memory log of --log-buffer entries, whatever the console verbosity, so --quiet keeps the CLI silent while the
UI or GET /__mock/logs?after=<sequence> still follows it.
Control API
| Endpoint | Description |
|---|---|
GET /__mock/health |
Ready check. |
GET /__mock/requests?method=&path= |
Recorded requests, optionally filtered. |
DELETE /__mock/requests |
Forgets recorded requests. |
GET/PUT/DELETE /__mock/expectations |
Lists, adds (one or an array) or removes (?id=) runtime expectations. |
POST /__mock/reset |
Forgets requests and runtime expectations. |
POST /__mock/reload |
Reloads expectation files. |
GET /__mock/logs?after= |
Log entries, optionally only those after a sequence number. |
GET /__mock/middlewares |
The consumer middlewares, in pipeline order. |
Releases
1.1.0
- feat(Web.MockServer): keep an in-memory log and describe plugged-in middlewares
1.0.1
- docs(packages): identify each package's pillar and layer
- build(packages): attribute the copyright to Leandro Melão Medeiros
- build: relicense under Apache-2.0 and update the package metadata
- fix(mock-server): default to port 6001, which browsers allow
1.0.0
- Initial release.
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
-
net10.0
- Anarchy.Toolkit.Core (>= 1.1.1)
- Humanizer (>= 3.0.10)
- Newtonsoft.Json (>= 13.0.4)
- Spectre.Console (>= 0.57.2)
NuGet packages (2)
Showing the top 2 NuGet packages that depend on Anarchy.Toolkit.Web.MockServer:
| Package | Downloads |
|---|---|
|
Anarchy.Toolkit.Testing.MockServer
Test helpers for Anarchy.Toolkit.Web.MockServer: a control API client, assertions on received requests, a record-file reader, and a fixture that connects to a running mock server or spawns one. |
|
|
Anarchy.Toolkit.Web.MockServer.Ui
Browser UI for Anarchy.Toolkit.Web.MockServer, built on Anarchy.Toolkit.Web.Ui: loaded expectations, received requests, plugged-in middlewares and a live log. Runs standalone or from a host of your own. |
GitHub repositories
This package is not used by any popular GitHub repositories.
Initial release.