aweXpect.Json 4.2.0

aweXpect.Json

aweXpect.Json extends aweXpect with expectations for JSON strings, JsonElement, JsonNode and the JSON serialization of objects with System.Text.Json.

Installation

dotnet add package aweXpect.Json

The package brings Expect.That with it, but not the expectations for strings, numbers or collections, so reference aweXpect as well, e.g. for the IsEqualTo of IsEqualTo(…).AsJson(). The expectations live in the namespace aweXpect, so using aweXpect; is all you need; only the customization lives in aweXpect.Json.

The examples write That(...) instead of Expect.That(...), which needs using static aweXpect.Expect; (see Getting started).

At a glance

string json = """{"title": "Let It Be", "artist": "The Beatles", "durationSeconds": 243}""";

// compare JSON strings by their structure instead of their formatting
string expected = """{ "artist": "The Beatles", "title": "Let It Be", "durationSeconds": 243 }""";
await That(json).IsEqualTo(expected).AsJson();

// verify that a string is valid JSON that matches an expected value
await That(json).IsValidJsonMatching(new { title = "Let It Be" });

// verify single values of a JsonElement or JsonNode
JsonElement track = JsonDocument.Parse(json).RootElement;
await That(track)
    .HasProperty("title", t => t.IsString("Let It Be")).And
    .HasProperty("durationSeconds", d => d.IsNumber<int>()).And
    .DoesNotHaveProperty("password");

// verify the JSON contract of a type, e.g. `record Track(string Title, string Artist)`
await That(new Track("Let It Be", "The Beatles")).IsJsonSerializedAs(
    """{"Title": "Let It Be", "Artist": "The Beatles"}""");

A failing comparison names every difference by its JSON path. If the title was "Yesterday", IsValidJsonMatching would fail with:

Expected that json
is valid JSON which matches new { title = "Let It Be" },
but it differed as $.title was "Yesterday" instead of "Let It Be"

JSON options:
 - ignore additional properties

Overview

Expectations for string:

Expectations for JsonElement and JsonNode:

Expectations for any object, serialized with System.Text.Json:

The comparisons can be relaxed with options like TreatingNullAsAbsent(), IgnoringArrayOrder(), IgnoringMember(name) or ComparingNumbersWithin(tolerance), see Matching JSON.

Customization

Set a value under Customize.aweXpect.Json() for the current async flow, or under Customize.aweXpect.Global.Json() for all tests.

Documentation

The full documentation is available at docs.testably.org:

• JSON strings: comparing strings as JSON and validating them
• Matching JSON: Matches and MatchesExactly, and the options to relax the comparison
• Objects, arrays and value kinds: HasProperty, HasValueAt, HasElementAt, IsObject, WhoseProperties, IsArray, WhoseElements and the value kinds
• JsonNode: the same expectations for a JsonNode and its subtypes
• Serialization: IsJsonSerializable and IsJsonSerializedAs
• Customization: the default JsonDocumentOptions and JsonSerializerOptions