Class JsonValueAssertions

Namespace

JsonAssertions.TUnit

Assembly

JsonAssertions.TUnit.dll

Fluent TUnit entry points for asserting the value at a dot-separated JSON path. Each method is generated into a TUnit assertion chain via the [GenerateAssertion] source generator and delegates to JsonPath and JsonValueComparison in the framework-agnostic core. Both a JSON string and a JsonElement are accepted as the asserted value; the expected value may be a string, a bool, or a number. The integer overloads (int / uint / long / ulong) each match the value whether the JSON encodes it as a number or as a numeric string, because the encoding depends on the serializer (System.Text.Json writes a number; Protobuf's JsonFormatter can emit a string, and serializes 64-bit ints as strings to avoid 53-bit precision loss); the double overload matches a JSON number.

[SuppressMessage("Performance", "MA0109:Consider adding an overload with a Span<T> or Memory<T>", Justification = "The one-of overloads take T[] so callers can use a C# 12 collection expression literal (HasJsonValueOneOf(\"status\", [\"Healthy\", \"Degraded\"])); a ReadOnlySpan<T> overload cannot be expressed under TUnit's [GenerateAssertion] source generator (ref struct parameters are unsupported), and assertion call sites do not need the allocation profile a Span overload would provide.")]
public static class JsonValueAssertions

Inheritance

object

JsonValueAssertions

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

The methods return TUnit.Assertions.Core.AssertionResult so a failure surfaces either where the path resolution stopped, or the value that was found in place of the expected one (via JsonFailureMessage). The string overloads parse into a disposable JsonDocument and delegate to the JsonElement overload within the document's lifetime, because a JsonElement is only valid while its backing document is alive.

Methods

HasJsonValue(string, string, bool)

Asserts the JSON string has the boolean value expected at the dot-separated path.

[GenerateAssertion]
public static AssertionResult HasJsonValue(this string json, string path, bool expected)

Parameters

json string

The JSON document text.

path string

A dot-separated property path, for example user.active.

expected bool

The expected boolean value.

Returns

AssertionResult

HasJsonValue(string, string, double)

Asserts the JSON string has the numeric value expected at the dot-separated path.

[GenerateAssertion]
public static AssertionResult HasJsonValue(this string json, string path, double expected)

Parameters

json string

The JSON document text.

path string

A dot-separated property path, for example user.age.

expected double

The expected numeric value.

Returns

AssertionResult

HasJsonValue(string, string, int)

Asserts the JSON string has the 32-bit integer value expected at the dot-separated path, matching whether the JSON encodes it as a number or as a numeric string. System.Text.Json writes int32 as a JSON number while Protobuf's JsonFormatter can emit a JSON string; both are matched.

[GenerateAssertion]
public static AssertionResult HasJsonValue(this string json, string path, int expected)

Parameters

json string

The JSON document text.

path string

A dot-separated property path, for example user.age.

expected int

The expected 32-bit integer value.

Returns

AssertionResult

HasJsonValue(string, string, long)

Asserts the JSON string has the 64-bit integer value expected at the dot-separated path, matching whether the JSON encodes it as a number or as a numeric string (parsed with InvariantCulture). Protobuf's JsonFormatter serializes int64 as a JSON string to avoid the 53-bit precision loss a JSON number would incur, while System.Text.Json writes it as a JSON number; both are matched.

[GenerateAssertion]
public static AssertionResult HasJsonValue(this string json, string path, long expected)

Parameters

json string

The JSON document text.

path string

A dot-separated property path, for example guid.high.

expected long

The expected 64-bit integer value.

Returns

AssertionResult

HasJsonValue(string, string, string)

Asserts the JSON string has the string value expected at the dot-separated path.

[GenerateAssertion]
public static AssertionResult HasJsonValue(this string json, string path, string expected)

Parameters

json string

The JSON document text.

path string

A dot-separated property path, for example user.name.

expected string

The expected string value.

Returns

AssertionResult

HasJsonValue(string, string, uint)

Asserts the JSON string has the unsigned 32-bit integer value expected at the dot-separated path, matching whether the JSON encodes it as a number or as a numeric string. System.Text.Json writes uint32 as a JSON number while Protobuf's JsonFormatter can emit a JSON string; both are matched.

[GenerateAssertion]
public static AssertionResult HasJsonValue(this string json, string path, uint expected)

Parameters

json string

The JSON document text.

path string

A dot-separated property path, for example user.age.

expected uint

The expected unsigned 32-bit integer value.

Returns

AssertionResult

HasJsonValue(string, string, ulong)

Asserts the JSON string has the unsigned 64-bit integer value expected at the dot-separated path, matching whether the JSON encodes it as a number or as a numeric string (parsed with InvariantCulture). Protobuf's JsonFormatter serializes uint64 as a JSON string for the same precision reason as int64, while System.Text.Json writes it as a JSON number; both are matched.

[GenerateAssertion]
public static AssertionResult HasJsonValue(this string json, string path, ulong expected)

Parameters

json string

The JSON document text.

path string

A dot-separated property path, for example guid.low.

expected ulong

The expected unsigned 64-bit integer value.

Returns

AssertionResult

HasJsonValue(JsonElement, string, bool)

Asserts the JSON element has the boolean value expected at the dot-separated path.

[GenerateAssertion]
public static AssertionResult HasJsonValue(this JsonElement element, string path, bool expected)

Parameters

element JsonElement

The JSON element to navigate from.

path string

A dot-separated property path, for example user.active.

expected bool

The expected boolean value.

Returns

AssertionResult

HasJsonValue(JsonElement, string, double)

Asserts the JSON element has the numeric value expected at the dot-separated path.

[GenerateAssertion]
public static AssertionResult HasJsonValue(this JsonElement element, string path, double expected)

Parameters

element JsonElement

The JSON element to navigate from.

path string

A dot-separated property path, for example user.age.

expected double

The expected numeric value.

Returns

AssertionResult

HasJsonValue(JsonElement, string, int)

Asserts the JSON element has the 32-bit integer value expected at the dot-separated path, matching a JSON number or a numeric JSON string and comparing exactly.

[GenerateAssertion]
public static AssertionResult HasJsonValue(this JsonElement element, string path, int expected)

Parameters

element JsonElement

The JSON element to navigate from.

path string

A dot-separated property path, for example user.age.

expected int

The expected 32-bit integer value.

Returns

AssertionResult

HasJsonValue(JsonElement, string, long)

Asserts the JSON element has the 64-bit integer value expected at the dot-separated path, matching a JSON number or a numeric JSON string (parsed with InvariantCulture) and comparing exactly.

[GenerateAssertion]
public static AssertionResult HasJsonValue(this JsonElement element, string path, long expected)

Parameters

element JsonElement

The JSON element to navigate from.

path string

A dot-separated property path, for example guid.high.

expected long

The expected 64-bit integer value.

Returns

AssertionResult

HasJsonValue(JsonElement, string, string)

Asserts the JSON element has the string value expected at the dot-separated path.

[GenerateAssertion]
public static AssertionResult HasJsonValue(this JsonElement element, string path, string expected)

Parameters

element JsonElement

The JSON element to navigate from.

path string

A dot-separated property path, for example user.name.

expected string

The expected string value.

Returns

AssertionResult

HasJsonValue(JsonElement, string, uint)

Asserts the JSON element has the unsigned 32-bit integer value expected at the dot-separated path, matching a JSON number or a numeric JSON string and comparing exactly.

[GenerateAssertion]
public static AssertionResult HasJsonValue(this JsonElement element, string path, uint expected)

Parameters

element JsonElement

The JSON element to navigate from.

path string

A dot-separated property path, for example user.age.

expected uint

The expected unsigned 32-bit integer value.

Returns

AssertionResult

HasJsonValue(JsonElement, string, ulong)

Asserts the JSON element has the unsigned 64-bit integer value expected at the dot-separated path, matching a JSON number or a numeric JSON string (parsed with InvariantCulture) and comparing exactly.

[GenerateAssertion]
public static AssertionResult HasJsonValue(this JsonElement element, string path, ulong expected)

Parameters

element JsonElement

The JSON element to navigate from.

path string

A dot-separated property path, for example guid.low.

expected ulong

The expected unsigned 64-bit integer value.

Returns

AssertionResult

HasJsonValueMatching(string, string, Func<JsonElement, bool>)

Asserts the value at path satisfies the predicate. When path contains the [*] wildcard, the predicate must hold on every expanded element; the failure names the first element that is missing or fails, and an empty match set passes vacuously. The predicate sees the resolved JsonElement and decides pass/fail; failure messages do not surface the predicate's intent (use a descriptive call site or wrap the assertion in .Because(...)).

[GenerateAssertion]
public static AssertionResult HasJsonValueMatching(this string json, string path, Func<JsonElement, bool> predicate)

Parameters

json string

The JSON document text.

path string

A path of dot-separated property names and zero-based bracket indices, for example user.age, optionally with the [] wildcard to match every element of an array (for example [].on).

predicate Func<JsonElement, bool>

A predicate that returns true for matching elements; receives each element resolved at path.

Returns

AssertionResult

HasJsonValueMatching(JsonElement, string, Func<JsonElement, bool>)

Asserts the value at path satisfies predicate. When path contains the [*] wildcard, the predicate must hold on every expanded element; the failure names the first element that is missing or fails, and an empty match set passes vacuously.

[GenerateAssertion]
public static AssertionResult HasJsonValueMatching(this JsonElement element, string path, Func<JsonElement, bool> predicate)

Parameters

element JsonElement

The JSON element to navigate from.

path string

A path of dot-separated property names and zero-based bracket indices, for example user.age, optionally with the [*] wildcard to match every element of an array.

predicate Func<JsonElement, bool>

A predicate that returns true for matching elements.

Returns

AssertionResult

HasJsonValueOneOf(string, string, double[])

Asserts the value at path is a JSON number equal to any of candidates. Values beyond double precision are out of scope for this overload.

[GenerateAssertion]
public static AssertionResult HasJsonValueOneOf(this string json, string path, double[] candidates)

Parameters

json string

The JSON document text.

path string

A path of dot-separated property names and zero-based bracket indices, for example response.code.

candidates double[]

The acceptable numeric values.

Returns

AssertionResult

HasJsonValueOneOf(string, string, int[])

Asserts the value at path is a 32-bit integer equal to any of candidates, encoded as either a JSON number or a numeric JSON string, for System.Text.Json or Protobuf-style int32 values.

[GenerateAssertion]
public static AssertionResult HasJsonValueOneOf(this string json, string path, int[] candidates)

Parameters

json string

The JSON document text.

path string

A path of dot-separated property names and zero-based bracket indices, for example response.code.

candidates int[]

The acceptable 32-bit integer values.

Returns

AssertionResult

HasJsonValueOneOf(string, string, long[])

Asserts the value at path is a 64-bit integer equal to any of candidates, encoded as either a JSON number or a numeric JSON string (parsed with InvariantCulture), for System.Text.Json or Protobuf-style int64 values.

[GenerateAssertion]
public static AssertionResult HasJsonValueOneOf(this string json, string path, long[] candidates)

Parameters

json string

The JSON document text.

path string

A path of dot-separated property names and zero-based bracket indices, for example message.sequence.

candidates long[]

The acceptable 64-bit integer values.

Returns

AssertionResult

HasJsonValueOneOf(string, string, string[])

Asserts the value at path is a JSON string equal to any of candidates. The discoverable form of "value is one of {a, b, c}".

[GenerateAssertion]
public static AssertionResult HasJsonValueOneOf(this string json, string path, string[] candidates)

Parameters

json string

The JSON document text.

path string

A path of dot-separated property names and zero-based bracket indices, for example health.status.

candidates string[]

The acceptable string values; ordinal comparison.

Returns

AssertionResult

HasJsonValueOneOf(string, string, uint[])

Asserts the value at path is an unsigned 32-bit integer equal to any of candidates, encoded as either a JSON number or a numeric JSON string, for System.Text.Json or Protobuf-style uint32 values.

[GenerateAssertion]
public static AssertionResult HasJsonValueOneOf(this string json, string path, uint[] candidates)

Parameters

json string

The JSON document text.

path string

A path of dot-separated property names and zero-based bracket indices, for example response.code.

candidates uint[]

The acceptable unsigned 32-bit integer values.

Returns

AssertionResult

HasJsonValueOneOf(string, string, ulong[])

Asserts the value at path is an unsigned 64-bit integer equal to any of candidates, encoded as either a JSON number or a numeric JSON string (parsed with InvariantCulture), for System.Text.Json or Protobuf-style uint64 values.

[GenerateAssertion]
public static AssertionResult HasJsonValueOneOf(this string json, string path, ulong[] candidates)

Parameters

json string

The JSON document text.

path string

A path of dot-separated property names and zero-based bracket indices, for example message.sequence.

candidates ulong[]

The acceptable unsigned 64-bit integer values.

Returns

AssertionResult

HasJsonValueOneOf(JsonElement, string, double[])

Asserts the value at path is a JSON number equal to any of candidates.

[GenerateAssertion]
public static AssertionResult HasJsonValueOneOf(this JsonElement element, string path, double[] candidates)

Parameters

element JsonElement

The JSON element to navigate from.

path string

A path of dot-separated property names and zero-based bracket indices, for example response.code.

candidates double[]

The acceptable numeric values.

Returns

AssertionResult

HasJsonValueOneOf(JsonElement, string, int[])

Asserts the value at path is a 32-bit integer equal to any of candidates, encoded as either a JSON number or a numeric JSON string.

[GenerateAssertion]
public static AssertionResult HasJsonValueOneOf(this JsonElement element, string path, int[] candidates)

Parameters

element JsonElement

The JSON element to navigate from.

path string

A path of dot-separated property names and zero-based bracket indices, for example response.code.

candidates int[]

The acceptable 32-bit integer values.

Returns

AssertionResult

HasJsonValueOneOf(JsonElement, string, long[])

Asserts the value at path is a 64-bit integer equal to any of candidates, encoded as either a JSON number or a numeric JSON string (parsed with InvariantCulture).

[GenerateAssertion]
public static AssertionResult HasJsonValueOneOf(this JsonElement element, string path, long[] candidates)

Parameters

element JsonElement

The JSON element to navigate from.

path string

A path of dot-separated property names and zero-based bracket indices, for example message.sequence.

candidates long[]

The acceptable 64-bit integer values.

Returns

AssertionResult

HasJsonValueOneOf(JsonElement, string, string[])

Asserts the value at path is a JSON string equal to any of candidates.

[GenerateAssertion]
public static AssertionResult HasJsonValueOneOf(this JsonElement element, string path, string[] candidates)

Parameters

element JsonElement

The JSON element to navigate from.

path string

A path of dot-separated property names and zero-based bracket indices, for example health.status.

candidates string[]

The acceptable string values; ordinal comparison.

Returns

AssertionResult

HasJsonValueOneOf(JsonElement, string, uint[])

Asserts the value at path is an unsigned 32-bit integer equal to any of candidates, encoded as either a JSON number or a numeric JSON string.

[GenerateAssertion]
public static AssertionResult HasJsonValueOneOf(this JsonElement element, string path, uint[] candidates)

Parameters

element JsonElement

The JSON element to navigate from.

path string

A path of dot-separated property names and zero-based bracket indices, for example response.code.

candidates uint[]

The acceptable unsigned 32-bit integer values.

Returns

AssertionResult

HasJsonValueOneOf(JsonElement, string, ulong[])

Asserts the value at path is an unsigned 64-bit integer equal to any of candidates, encoded as either a JSON number or a numeric JSON string (parsed with InvariantCulture).

[GenerateAssertion]
public static AssertionResult HasJsonValueOneOf(this JsonElement element, string path, ulong[] candidates)

Parameters

element JsonElement

The JSON element to navigate from.

path string

A path of dot-separated property names and zero-based bracket indices, for example message.sequence.

candidates ulong[]

The acceptable unsigned 64-bit integer values.

Returns

AssertionResult

HasJsonValueParsableAs<T>(string, string)

Asserts the value at path is a JSON string whose text parses as T via TryParse(string, IFormatProvider, out TSelf) against InvariantCulture. Covers the "value parses as Guid / DateTimeOffset / Uri" pattern without committing to a particular parser per call site.

[GenerateAssertion]
public static AssertionResult HasJsonValueParsableAs<T>(this string json, string path) where T : IParsable<T>

Parameters

json string

The JSON document text.

path string

A path of dot-separated property names and zero-based bracket indices, for example order.id.

Returns

AssertionResult

Type Parameters

T

The target type implementing IParsable<TSelf>.

HasJsonValueParsableAs<T>(JsonElement, string)

Asserts the value at path is a JSON string whose text parses as T.

[GenerateAssertion]
public static AssertionResult HasJsonValueParsableAs<T>(this JsonElement element, string path) where T : IParsable<T>

Parameters

element JsonElement

The JSON element to navigate from.

path string

A path of dot-separated property names and zero-based bracket indices, for example order.id.

Returns

AssertionResult

Type Parameters

T

The target type implementing IParsable<TSelf>.