aweXpect.Json

Expectations for JSON strings and System.Text.Json for aweXpect.

At a glance

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

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

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

// verify single values of a JsonElement or JsonNode
JsonElement track = JsonDocument.Parse(json).RootElement;
await Expect.That(track).IsObject(o => o
    .With("title").Matching("Let It Be").And
    .With("durationSeconds").ANumber());

// verify the JSON contract of a type, e.g. `record Track(string Title, string Artist)`
await Expect.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

Expectation	Subject	Summary
IsEqualTo(…).AsJson()	string	equal to the expected JSON, compared by structure
IsValidJson	string	can be parsed as JSON
IsValidJsonMatching	string	valid JSON that matches the expected value
IsValidJsonMatchingExactly	string	valid JSON that matches the expected value exactly
Matches	JsonElement, JsonNode	matches the expected value, additional properties allowed
MatchesExactly	JsonElement, JsonNode	matches the expected value exactly
IsObject	JsonElement, JsonNode	a JSON object, optionally with expectations on it
IsArray	JsonElement, JsonNode	a JSON array, optionally with expectations on it
IsArray().WhoseElements	JsonElement, JsonNode	collection expectations on the elements of a JSON array
IsString	JsonElement, JsonNode	a JSON string
IsNumber	JsonElement, JsonNode	a JSON number
IsBoolean	JsonElement, JsonNode	a JSON boolean, i.e. true or false
IsNull	JsonElement	the JSON value null
IsJsonSerializable	object	survives a round trip through the JSON serializer
IsJsonSerializedAs	object	serialized by the JSON serializer as the expected JSON

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

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: IsObject, IsArray, WhoseElements, the value kinds and JsonNode subjects
• Serialization: IsJsonSerializable and IsJsonSerializedAs
• Customization: the default JsonDocumentOptions and JsonSerializerOptions