dennisdoomen/mockly

Fluent HTTP mocking for .NET like it should have been done

📚 Documentation

Visit the official documentation website for comprehensive guides, API reference, and examples.

• Quick Start - Get started in 5 minutes
• Usage Guide - Learn core features
• Advanced Features - Custom matchers, assertions, and more
• Building - Build from source
• Contributing - Contribution guidelines

About

What’s this?

Mockly is a powerful and flexible HTTP mocking library for .NET that makes it easy to test code that depends on HttpClient. It provides a fluent API for configuring HTTP request mocks, capturing request details, and asserting on HTTP interactions in your tests.

The library supports:

• .NET Framework 4.7.2 and higher
• .NET 8.0 and higher
• FluentAssertions 7.x and 8.x integration for expressive test assertions

What’s so special about that?

Unlike other HTTP mocking libraries, Mockly offers:

• Fluent, intuitive API - Chain method calls to build complex mocking scenarios with ease
• Wildcard pattern matching - Match URLs using wildcards (*) in paths and query strings
• First-class header matching - Match request headers, bearer tokens, and content types directly
• Custom matchers - Use predicates for advanced request matching logic
• Request capture & inspection - Automatically capture all requests with full metadata (headers, body, timestamp)
• Powerful assertions - Built-in FluentAssertions extensions for verifying HTTP behavior
• Diagnostic support - Detailed error messages when unexpected requests occur
• Extensibility - Design allows for custom response generators and matchers
• Zero configuration - Works out of the box with sensible defaults
• Performance optimized - Regex patterns are cached for efficient matching
• Invocation limits - Restrict how many times a mock can respond using Once(), Twice(), or Times(n)
• Response latency - Simulate slow endpoints with After(TimeSpan) to test timeout, cancellation and resilience

Who created this?

Mockly is created and maintained by Dennis Doomen, also the creator of FluentAssertions, PackageGuard, Reflectify, Pathy and the .NET Library Starter Kit. It’s designed to work seamlessly with modern .NET testing practices and integrates naturally with FluentAssertions for expressive test assertions.

Power in Simplicity

using var mock = new HttpMock();

// 1. Match with full URL shortcuts and wildcards
// 2. Filter by specific query parameters
// 3. Use custom JSON options for serialization
var options = new JsonSerializerOptions { PropertyNamingPolicy = JsonNamingPolicy.CamelCase };

mock.ForGet("https://api.github.com/repos/*/issues?state=open")
    .WithQueryParam("page", "1")
    .Using(options)
    .RespondsWithJsonContent(new[] { 
        new { Id = 1, Title = "Found a bug" },
        new { Id = 2, Title = "Feature request" }
    });

// 4. Match Bearer tokens and other headers
// 5. Match request body using JSON equivalence
// 6. Capture requests for later verification
var creations = new RequestCollection();

mock.ForPost()
    .WithPath("/api/users")
    .WithBearerToken("secret-token")
    .WithBody(new { Name = "John", Role = "Admin" })
    .CollectingRequestsIn(creations)
    .RespondsWithStatus(HttpStatusCode.Created);

// 7. Built-in support for Problem Details (RFC 7807)
mock.ForGet("/api/users/999")
    .RespondsWithProblemDetails(HttpStatusCode.NotFound, "User not found");

// Get the pre-configured HttpClient and start testing!
var client = mock.GetClient();

// 8. Assert your expectations with FluentAssertions
mock.Should().HaveAllRequestsCalled();
creations.Should().ContainRequestFor("/api/users")
    .Which.HasHeader("X-Trace-Id");

Key Features

🎯 Fluent Request Matching

mock.ForGet().WithPath("/api/users/*").RespondsWithJsonContent(user);
mock.ForPost().WithPath("/api/data").WithQuery("?filter=*").RespondsWithStatus(HttpStatusCode.Created);
mock.ForGet().WithPath("/api/secure").WithHeader("X-Api-Key").RespondsWithStatus(HttpStatusCode.OK);
mock.ForPost().WithPath("/api/auth").WithBearerToken("eyJ*").RespondsWithStatus(HttpStatusCode.OK);
mock.ForPost().WithPath("/api/json").WithContentType("application/json").RespondsWithStatus(HttpStatusCode.OK);

🏷️ Response Headers

Configure response headers such as Location, ETag or a custom Content-Type. Content headers are routed to the response content automatically; all other headers are added to the response headers.

mock.ForPost().WithPath("/api/users")
    .RespondsWithStatus(HttpStatusCode.Created)
    .WithHeader("Location", "/api/users/123")
    .WithHeader("ETag", "\"v1\"");

📃 Clear Reporting

When an unexpected request occurs and there are configured mocks, Mockly helps you diagnose by reporting the closest matching mock, broken down criterion by criterion (method, scheme/host, path, query, headers, body), so you can quickly see exactly what to adjust in your setup.

Unexpected request to:
  POST https://api.example.com/api/users

Closest matching mock:
  POST https://*/api/users
    method       ✓ POST
    scheme/host  ✓ api.example.com
    path         ✓ /api/users
    query        ✓ (none)
    header       ✗ expected "X-Tenant: acme" but the request had no such header
    body         ✗ expected property "role" to be "Admin" but found "User"

Registered mocks:
 - POST https://*/api/users where header "X-Tenant" matches "acme"

When the mismatch isn’t on a single request, dump the whole conversation instead:

output.WriteLine(mock.GetTrafficReport());

🔍 Request Capture & Inspection

var patches = new RequestCollection();
mock.ForPatch().WithPath("/api/update").CollectingRequestsIn(patches);

// After test execution
patches.Count.Should().Be(3);
patches.First().Path.Should().Contain("/api/update");

✅ Powerful Assertions

mock.Should().HaveAllRequestsCalled();
mock.Requests.Should().NotBeEmpty();
mock.Requests.Should().NotContainUnexpectedCalls();

// Assert JSON-equivalence using a JSON string (ignores formatting/ordering)
mock.Requests.Should().ContainRequest()
    .WithBodyMatchingJson("{ \"id\": 1, \"name\": \"John\" }");

// Assert the body deserializes and is equivalent to an object graph
var expected = new { id = 1, name = "John" };

mock.Requests.Should().ContainRequestFor("https://api.example.com/*")
    .WithBodyEquivalentTo(expected);

🎨 Multiple Response Types

• JSON content with automatic serialization
• Test data builder integration via IResponseBuilder
• Raw string content
• Custom HTTP status codes
• Custom response generators
• OData support

🔁 Sequenced Responses

Configure a sequence of responses for the same matched request so consecutive calls get different responses (e.g. the classic “fail twice, then succeed” retry test). Chain ThenRespondsWith*(...) after any RespondsWith* method. The last response repeats for any calls beyond the configured sequence.

mock.ForGet().WithPath("/resource")
    .RespondsWithStatus(HttpStatusCode.ServiceUnavailable)
    .ThenRespondsWithStatus(HttpStatusCode.ServiceUnavailable)
    .ThenRespondsWithStatus(HttpStatusCode.OK);

The ThenRespondsWith* family mirrors the RespondsWith* methods (ThenRespondsWithJsonContent, ThenRespondsWithContent, ThenRespondsWithODataResult, and ThenRespondsWith(Func)).

🔐 Auth & Rate-Limit Scenarios

Match basic auth credentials or API keys, and simulate the OAuth, token-refresh and rate-limiting flows that resilience libraries like Microsoft.Extensions.Http.Resilience are built to handle:

mock.ForGet("/api/secure").WithBasicAuth("user", "pass");
mock.ForGet("/api/secure").WithApiKey("X-Api-Key");

// OAuth token endpoint, with a correctly shaped token response
mock.ForPost("/token").RespondsWithOAuthToken("abc", expiresIn: TimeSpan.FromMinutes(5));

// The classic token-refresh test: first call 401, retry after refresh succeeds
mock.ForGet("/api/data").RespondsWithUnauthorizedThenSuccess("""{"value":42}""");

// 429 with a Retry-After header
mock.ForGet("/api/data").RespondsWithRateLimit(retryAfter: TimeSpan.FromSeconds(2));

🛡️ Fail-Fast Testing

mock.FailOnUnexpectedCalls = true; // Default behavior
// Throws UnexpectedRequestException if an unmocked request is made

📥 Import From cURL

Bootstrap a mock from an existing curl command, such as the output of a browser’s “Copy as cURL”:

mock.ImportFromCurl("""
    curl -X POST https://api.example.com/users \
      -H 'Content-Type: application/json' \
      --data-raw '{"name":"mockly"}'
    """)
    .RespondsWithStatus(HttpStatusCode.Created);

The method (-X), URL, headers (-H) and body (-d/--data/--data-raw) are translated into the equivalent matching configuration. Importing HAR files is planned for a future release.

Quick Start

Install the package:

dotnet add package mockly

To get the assertions, also install one of the two assertion packages, depending on which version of FluentAssertions you’re using:

dotnet add package FluentAssertions.Mockly.v7
dotnet add package FluentAssertions.Mockly.v8

Basic usage:

using Mockly;
using FluentAssertions;

// Arrange
var mock = new HttpMock();
mock.ForGet()
    .WithPath("/api/users/123")
    .RespondsWithJsonContent(new { Id = 123, Name = "John Doe" });

HttpClient client = mock.GetClient();

// Act
// Note: BaseAddress defaults to https://localhost/
var response = await client.GetAsync("/api/users/123");
var content = await response.Content.ReadAsStringAsync();

// Assert
response.StatusCode.Should().Be(HttpStatusCode.OK);
content.Should().Contain("John Doe");
mock.Should().HaveAllRequestsCalled();

For complete documentation and advanced examples, visit mockly.org

[!TIP] This project ships an Agent Skill that helps AI Coding Agents use Mockly effectively. This file will be stored in the .agents/skills/mockly directory of your project when you build the project. You can disable this behavior by setting false in your project or Directory.Build.props.

Building

To build this repository locally, you need:

• The .NET SDKs for .NET 4.7 and 8.0.
• Visual Studio, JetBrains Rider or Visual Studio Code with the C# DevKit

Build using PowerShell:

./build.ps1

Or with the Nuke tool:

nuke

For more details, see the Building documentation.

Contributing

Your contributions are always welcome! Please have a look at the contribution guidelines first.

For detailed contribution information, visit the Contributing documentation.

Previous contributors:

(Made with contrib.rocks)

Versioning

This library uses Semantic Versioning to give meaning to the version numbers. For the versions available, see the releases on this repository.

Credits

This library wouldn’t have been possible without the following tools, packages and companies:

• FluentAssertions - Fluent API for asserting the results of unit tests by Dennis Doomen
• Nuke - Smart automation for DevOps teams and CI/CD pipelines by Matthias Koch
• xUnit - Community-focused unit testing tool for .NET by Brad Wilson
• Coverlet - Cross platform code coverage for .NET by Toni Solarin-Sodara
• GitVersion - From git log to SemVer in no time
• ReportGenerator - Converts coverage reports by Daniel Palme
• StyleCopyAnalyzer - StyleCop rules for .NET
• Roslynator - A set of code analysis tools for C# by Josef Pihrt
• CSharpCodingGuidelines - Roslyn analyzers by Bart Koelman to go with the C# Coding Guidelines
• Meziantou - Another set of awesome Roslyn analyzers by Gérald Barré

Related Projects

You may also be interested in:

• FluentAssertions - The assertion library that Mockly integrates with
• PackageGuard - Get a grip on your open-source packages
• Reflectify - Reflection extensions without causing dependency pains
• Pathy - Fluently building and using file and directory paths without binary dependencies
• .NET Library Starter Kit - A battle-tested starter kit for building open-source and internal NuGet libraries

License

This project is licensed under the MIT License - see the LICENSE file for details.