1. What Is It and Why Do You Need It?

WireMock.Net is a powerful library for creating HTTP mock servers (stubs) in the .NET ecosystem. It's a direct C# implementation of the popular Java project WireMock. The library's main purpose is to emulate the behavior of real HTTP/HTTPS services (REST APIs, SOAP, gRPC, etc.) during testing or development.

Why is this necessary? In modern microservice architectures, your application often depends on dozens of external APIs. Using real services in unit or integration tests leads to several problems: unstable tests due to server unavailability, slow performance, financial costs from paid API calls, and the inability to test rare scenarios (e.g., a 500 error or timeout). WireMock.Net solves these issues by letting you "replace" the external service locally.

Key use cases: unit testing HTTP clients (HttpClient), integration testing web applications, offline development (when the backend isn't ready yet), testing error handling and timeouts, and creating isolated test environments (sandboxes).

2. Installation

The library is distributed via NuGet. Use one of the following commands to install it:

Via .NET CLI (recommended):

dotnet add package WireMock.Net

Via Package Manager Console (Visual Studio):

Install-Package WireMock.Net

For async testing and Fluent Assertions (optional but useful):

dotnet add package WireMock.Net.FluentAssertions

Note: Unlike Python (pip) or Node.js (npm), .NET uses the NuGet package manager.

3. Quick Start — Minimal Working Example

Create a console application or a test project (xUnit/NUnit). Below is minimal code that starts a mock server on port 9876, returning a JSON response to a GET request.

using WireMock.Server;
using WireMock.RequestBuilders;
using WireMock.ResponseBuilders;

// 1. Start the server (defaults to a random port, but we'll specify one)
var server = WireMockServer.Start(9876);

// 2. Configure a stub
server.Given(
    Request.Create()
        .WithPath("/api/users/1")
        .UsingGet()
)
.RespondWith(
    Response.Create()
        .WithStatusCode(200)
        .WithHeader("Content-Type", "application/json")
        .WithBody("{ \"id\": 1, \"name\": \"John Doe\" }")
);

Console.WriteLine($"Mock server running on {server.Urls[0]}");
Console.WriteLine("Press any key to stop...");
Console.ReadKey();

// 3. Stop the server
server.Stop();

After running, open your browser or use curl: curl http://localhost:9876/api/users/1. You'll get the JSON response.

4. Key Methods/Functions/Classes

4.1. WireMockServer.Start()

Signature: public static WireMockServer Start(int? port = null, bool ssl = false)

Description: A static method that creates and starts a mock server instance. If no port is specified, a random available port is chosen.

// Start on port 5000
var server = WireMockServer.Start(5000);

// Start on a random port
var serverRandom = WireMockServer.Start();

4.2. server.Given()

Signature: public IRespondWithAwareResponseBuilder Giv