JsonAssertions.TUnit 0.6.1

JsonAssertions.TUnit

Scope: Test projects only. Not intended for production code.

Part of the DotNetAssertions family of assertion extensions for TUnit.

TUnit-native JSON assertions for .NET. Fluent entry points over TUnit's Assert.That(...) pipeline for asserting against System.Text.Json documents, HTTP response bodies (including RFC 7807 ProblemDetails), and the registration state of source-generated JsonSerializerContext instances. AOT-compatible, trimmable, no runtime reflection in the assertion path.

Full documentation, design notes, and roadmap: github.com/JohnVerheij/JsonAssertions.TUnit

Status

Each path / value / shape entry point is available over a JSON string, a System.Text.Json.JsonElement, and an HttpResponseMessage (whose body is read as the JSON document). HTTP-response and AOT-context assertions target their natural receiver type.

The path is a dot-separated property navigation with optional [N] zero-based bracket indices and an optional leading $ JSONPath root reference: user.name, items[0].id, objects[0].entries[1].id, $[0] for a root-array first element. The [*] wildcard (v0.4.0+) matches every element of an array on HasJsonProperty and HasJsonValueMatching (items[*].id). See the path-syntax notes on GitHub for the full grammar.

Two notes on [*]. It is a "for all" quantifier, so [*].id passes vacuously on an empty array, whereas [0].id fails on one; a naive [0] to [*] migration silently drops the implicit non-emptiness check, so pair the wildcard with HasNonEmptyJsonArray("items") when emptiness should fail the test. And [*] fits existence and genuinely-uniform value checks only: an element-specific check (for example "the element at index 2 has id 2", HasJsonValue("items[2].id", 2)) must stay index-scoped rather than become [*].

The point over a hand-rolled TryGetProperty(...).IsTrue() helper is the failure message: every assertion renders a path-context block saying where resolution stopped, not merely that it did.

Install

dotnet add package JsonAssertions.TUnit

Requirements: TUnit 1.58.0 or later, .NET 10. System.Text.Json is in-box on .NET 10, so the package carries no runtime dependency beyond TUnit.

Quick start

using System.Text.Json;

[Test]
public async Task ResponseBodyHasExpectedShape(CancellationToken ct)
{
    string json = """{"user":{"name":"alice","age":30},"roles":["admin"]}""";

    await Assert.That(json).HasJsonProperty("user.name");
    await Assert.That(json).HasJsonValue("user.age", 30);
    await Assert.That(json).HasJsonArrayLength("roles", 1);
}

The fluent entry points auto-import via TUnit.Assertions.Extensions. The same entry points work on a JsonElement, and directly on an HttpResponseMessage:

// Reads the response body and asserts against it. The cancellation token flows to the read.
await Assert.That(response).HasJsonProperty("user.name", ct);
await Assert.That(response).HasJsonValue("user.age", 30, ct);

Each integer overload (int / uint / long / ulong) matches the value whether the JSON encodes it as a number or a numeric string; long / ulong exist because protobuf serializes 64-bit ints as JSON strings (to avoid 53-bit precision loss) while System.Text.Json writes them as numbers. double matches a JSON number only. Use the L / UL suffix to assert a 64-bit value (HasJsonValue("guid.high", 123456789012345L)).

When an assertion fails, the message names the failure point:

to have a JSON property at path "user.address.city"
  resolved as far as: user.address
  no property "city" on "user.address"

A response body or string that is not valid JSON fails the assertion with an explained message rather than throwing a raw JsonException.

Subset matching (ContainsJson, 0.6.0+)

One declarative assertion in place of a block of per-property checks. The expected fields must be present and equal; the response may carry any additional fields the test does not want to pin. The failure lists every wrong path, not just the first.

await Assert.That(response).ContainsJson("""
    { "status": "Healthy",
      "entries": [ { "name": "db", "status": "Healthy" } ] }
    """, ct);

Do not fold a volatile value into the expected subset. ContainsJson asserts equality for every field you put in it - "subset" constrains which fields are checked, not how strictly they are compared. A duration reading, a server-generated identifier, or a status that legitimately varies gets pinned to whatever the response said the day the test was written, which asserts more than the contract does and fails on the first run that differs. Collapsing a block of per-property checks feels mechanical, so a volatile field is easy to sweep in with the stable ones, turning a presence check into an equality check. Keep those fields on their own presence or predicate assertion, or exclude them with o => o.IgnorePath("...").

Namespaces

The package places its own types in two namespaces, the same shape as the rest of the assertion family, and the source generator emits the fluent entry points into TUnit's:

Only the source-generated entry points auto-import. The other three rows need two using directives between them (using JsonAssertions; covers both of its rows), which a single GlobalUsings.cs puts in front of every test file:

global using JsonAssertions;       // core types + GetJsonValue<T>()
global using JsonAssertions.TUnit; // .AsJsonContext()

The extraction methods are the one part of the package that does not hang off Assert.That(...): they extend the receiver, because they return a value rather than asserting one.

using JsonAssertions;   // the extraction methods live here, and do not auto-import

// RIGHT: the receiver, not the assertion
var orderId = await response.GetJsonValueAsync<int>("orderId", ct);

// WRONG: ValueAssertion<HttpResponseMessage> has no such method
// await Assert.That(response).GetJsonValueAsync<int>("orderId", ct);

Roadmap

• Semantic JSON equality already ships as IsEquivalentJsonTo (0.5.0); subset matching (ContainsJson) and typed extraction (GetJsonValue<T> / GetJsonString / GetJsonElement) in 0.6.0. Further increments are demand-driven.

Family

Part of an assertion family for TUnit:

• LogAssertions.TUnit
• SnapshotAssertions.TUnit
• TimeAssertions.TUnit
• MathAssertions.TUnit
• SseAssertions.TUnit
• GrpcAssertions.TUnit

License

MIT. Copyright (c) 2026 John Verheij.