Class JsonExtraction

Namespace

JsonAssertions

Assembly

JsonAssertions.TUnit.dll

Extraction helpers that read a typed value out of a JSON document at a dot/bracket path and return it, for tests that need the value rather than an assertion: pulling an id from a response to drive the next request, or reading a count to cross-check against an array length. Each helper navigates with the same JsonPath resolver the assertions use and throws a JsonExtractionException whose message says where the path stopped and why, replacing a hand-rolled JsonDocument.Parse(...).RootElement.GetProperty(...).GetInt32() chain (which throws bare BCL exceptions with no path context). These are plain extension methods, not TUnit assertions; the value they return is used directly.

public static class JsonExtraction

Inheritance

object

JsonExtraction

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Methods

GetJsonElement(string, string)

Parses json and reads the JSON element at path as a detached copy. See GetJsonElement(JsonElement, string).

public static JsonElement GetJsonElement(this string json, string path)

Parameters

json string

The JSON document text.

path string

A path of dot-separated property names and zero-based bracket indices.

Returns

JsonElement

A detached copy of the element at the path.

Exceptions

ArgumentNullException

A required argument is null.

JsonExtractionException

The text is not valid JSON, or the path does not resolve.

GetJsonElement(JsonElement, string)

Reads the JSON element (any kind) at path as a detached copy that stays valid after the source document is disposed, for grabbing an object or array subtree to inspect or enumerate.

public static JsonElement GetJsonElement(this JsonElement element, string path)

Parameters

element JsonElement

The JSON element to navigate from.

path string

A path of dot-separated property names and zero-based bracket indices.

Returns

JsonElement

A detached (Clone()d) copy of the element at the path.

Exceptions

ArgumentNullException

path is null.

JsonExtractionException

The path does not resolve.

GetJsonElementAsync(HttpResponseMessage, string, CancellationToken)

Reads the response body and reads the JSON element at path as a detached copy. See GetJsonElement(JsonElement, string).

public static Task<JsonElement> GetJsonElementAsync(this HttpResponseMessage response, string path, CancellationToken cancellationToken = default)

Parameters

response HttpResponseMessage

The HTTP response whose body is the JSON document.

path string

A path of dot-separated property names and zero-based bracket indices.

cancellationToken CancellationToken

Flows to the response-body read.

Returns

Task<JsonElement>

A detached copy of the element at the path.

Exceptions

ArgumentNullException

A required argument is null.

JsonExtractionException

The body is not valid JSON, or the path does not resolve.

GetJsonString(string, string)

Parses json and reads the JSON string value at path. See GetJsonString(JsonElement, string).

public static string GetJsonString(this string json, string path)

Parameters

json string

The JSON document text.

path string

A path of dot-separated property names and zero-based bracket indices.

Returns

string

The string value.

Exceptions

ArgumentNullException

A required argument is null.

JsonExtractionException

The text is not valid JSON, the path does not resolve, or the value is not a JSON string.

GetJsonString(JsonElement, string)

Reads the JSON string value at path. The value must be a JSON string (a number, boolean, object, or array is a failure; use GetJsonValue<T>(JsonElement, string) or GetJsonElement(JsonElement, string) for those).

public static string GetJsonString(this JsonElement element, string path)

Parameters

element JsonElement

The JSON element to navigate from.

path string

A path of dot-separated property names and zero-based bracket indices.

Returns

string

The string value.

Exceptions

ArgumentNullException

path is null.

JsonExtractionException

The path does not resolve, or the value is not a JSON string.

GetJsonStringAsync(HttpResponseMessage, string, CancellationToken)

Reads the response body and reads the JSON string value at path. See GetJsonString(JsonElement, string).

public static Task<string> GetJsonStringAsync(this HttpResponseMessage response, string path, CancellationToken cancellationToken = default)

Parameters

response HttpResponseMessage

The HTTP response whose body is the JSON document.

path string

A path of dot-separated property names and zero-based bracket indices.

cancellationToken CancellationToken

Flows to the response-body read.

Returns

Task<string>

The string value.

Exceptions

ArgumentNullException

A required argument is null.

JsonExtractionException

The body is not valid JSON, the path does not resolve, or the value is not a JSON string.

GetJsonValueAsync<T>(HttpResponseMessage, string, CancellationToken)

Reads the response body and reads the value at path as T. See GetJsonValue<T>(JsonElement, string). When the same response is queried for several values, prefer reading it once to a JsonElement and using the element overloads.

public static Task<T> GetJsonValueAsync<T>(this HttpResponseMessage response, string path, CancellationToken cancellationToken = default) where T : IParsable<T>

Parameters

response HttpResponseMessage

The HTTP response whose body is the JSON document.

path string

A path of dot-separated property names and zero-based bracket indices.

cancellationToken CancellationToken

Flows to the response-body read.

Returns

Task<T>

The parsed value.

Type Parameters

T

The target type implementing IParsable<TSelf>.

Exceptions

ArgumentNullException

A required argument is null.

JsonExtractionException

The body is not valid JSON, the path does not resolve, or the value does not parse as T.

GetJsonValue<T>(string, string)

Parses json and reads the value at path as T. See GetJsonValue<T>(JsonElement, string).

public static T GetJsonValue<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.

Returns

T

The parsed value.

Type Parameters

T

The target type implementing IParsable<TSelf>.

Exceptions

ArgumentNullException

A required argument is null.

JsonExtractionException

The text is not valid JSON, the path does not resolve, or the value does not parse as T.

GetJsonValue<T>(JsonElement, string)

Reads the value at path and parses it as T. A JSON string is parsed from its text; a JSON number or boolean is parsed from its literal (so GetJsonValue<int>("cycleId") reads either 42 or "42"). Parsing uses InvariantCulture.

public static T GetJsonValue<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.

Returns

T

The parsed value.

Type Parameters

T

The target type implementing IParsable<TSelf> (for example int, long, bool, Guid, DateTimeOffset).

Exceptions

ArgumentNullException

path is null.

JsonExtractionException

The path does not resolve, or the value does not parse as T.