Skip to main content
Version: 6.3 🚧

Matching JSON content

This module is available for all targets.

shouldEqualJson​

json.shouldEqualJson(other) asserts that the left-hand side represents the same JSON structure as the right-hand side.

The matcher allows for different formatting, and for different order of keys.

For example, the following two JSON strings would be considered equal:

{
"name": "sam",
"location": "chicago",
"age": 41
}

and

{ "age": 41, "name": "sam", "location": "chicago" }

The inverse of this matcher is shouldNotEqualJson which will error if two JSON strings are considered equal.

compareJsonOptions​

shouldEqualJson supports an additional parameter of type CompareJsonOptions which supports the following flags to toggle behaviour of the JSON comparison:

Usage:​

Options can be specified inline, like:

a.shouldEqualJson(b, compareJsonOptions { arrayOrder = ArrayOrder.Strict })

Another option is to define a compare function which suits your desires, like:

val myOptions = compareJsonOptions {
typeCoercion = TypeCoercion.Enabled
arrayOrder = ArrayOrder.Lenient
}

infix fun String.lenientShouldEqualJson(other: String) = this.shouldEqualJson(other, myOptions)

"[1, 2]" lenientShouldEqualJson "[2, 1]" // This will pass

Parameters​

NamePurposePossible valuesDefault value
PropertyOrderDetermines if the order of properties in JSON objects are considered when comparingPropertyOrder.Strict, PropertyOrder.LenientPropertyOrder.Lenient, i.e. order of properties DON'T matter
ArrayOrderDetermines if the order of elements in JSON arrays are considered when comparingArrayOrder.Strict, ArrayOrder.LenientArrayOrder.Strict, i.e. order of elements DO matter
FieldComparisonDetermines if comparison will fail if JSON objects actual contain extra properties, when compared to expectedFieldComparison.Strict, FieldComparison.LenientFieldComparison.Strict, i.e. extra properties will cause inequality
NumberFormatDetermines if comparison of numbers are strict with regards to number format. For instance, if 100.0 and 100 are considered equal.NumberFormat.Strict, NumberFormat.LenientNumberFormat.Lenient, i.e. number formats DON'T matter
TypeCoercionDetermines if types will try to be coerced, for instance when a string contains a number or boolean valueTypeCoercion.Enabled, TypeCoercion.DisabledTypeCoercion.Disabled, i.e. types will NOT be coerced

overrideMatchers​

For comparisons that the options above can't express, overrideMatchers replaces the structural comparison of a JSON subtree with a custom matcher, keyed by a path into the document — analogous to the field matching overrideMatchers for data classes.

Paths use the same dotted format as the paths in comparison error messages: "users" targets a top-level field, "users.[0].name" a field of the first array element, and the empty string "" targets the whole document.

// require the actual users array to contain everything from the expected one,
// ignoring order and allowing extra elements
"""{ "users": [{ "name": "sam" }, { "name": "bob" }] }""" shouldEqualJson {
overrideMatchers = mapOf("users" to matchArraysContainingAll())
"""{ "users": [{ "name": "sam" }] }"""
}

Ready-made matchers include:

  • matchArraysContainingAll() — every element of the expected array must be matched by some element of the actual array, ignoring order and extra elements
  • matchStringsIgnoringCase() — string values are compared ignoring case

matchArraysContainingAll() compares the array elements structurally with the options of the enclosing comparison, but overrideMatchers rules do not apply inside those elements — elements match in any order, so a nested override path would have no stable meaning.

Custom matchers implement JsonSubtreeMatcher and receive the expected and the actual subtree, plus the active CompareJsonOptions, so a matcher can reuse the options configured on the enclosing comparison:

val ignoreBuildMetadata = JsonSubtreeMatcher { expected, actual, _ ->
val passed = expected is JsonNode.StringNode && actual is JsonNode.StringNode &&
actual.value.substringBefore('+') == expected.value
MatcherResult(
passed,
{ "expected version ${expected.value} but was ${actual.value}" },
{ "Expected values to not match" },
)
}

"""{ "version": "1.10.0+build.5" }""" shouldEqualJson {
overrideMatchers = mapOf("version" to ignoreBuildMetadata)
"""{ "version": "1.10.0" }"""
}

When a custom matcher fails, its failure message is reported at the subtree's path, e.g. At 'version' expected version <expected> but was <actual>.

Targets: Multiplatform

shouldEqualSpecifiedJson​

Alias for shouldEqualJson, with default options except FieldComparison which is set to FieldComparison.Lenient instead.

val a = """ { "a": true, "date": "2019-11-03" } """
val b = """ { "a": true } """

// this would pass
a shouldEqualSpecifiedJson b

// this would fail
a shouldEqualJson b

The inverse of this matcher is shouldNotEqualSpecifiedJson which will error if two JSON strings are considered equal.

Targets: Multiplatform

shouldEqualSpecifiedJsonIgnoringOrder​

Alias for shouldEqualJson, with default options except

  • FieldComparison which is set to FieldComparison.Lenient
  • ArrayOrder which is set to ArrayOrder.Lenient

Targets: Multiplatform

shouldBeEmptyJsonArray​

json.shouldBeEmptyJsonArray() asserts that the JSON is an empty array ([]).

Targets: Multiplatform

shouldBeEmptyJsonObject​

json.shouldBeEmptyJsonObject() asserts that the JSON is an empty array ({}).

Targets: Multiplatform

shouldBeJsonArray​

json.shouldBeJsonArray() asserts that the JSON is an array.

The inverse of this matcher is shouldNotBeJsonArray which will error if the JSON string is an array.

Targets: Multiplatform

shouldBeJsonObject​

json.shouldBeJsonObject() asserts that the JSON is an object.

The inverse of this matcher is shouldNotBeJsonObject which will error if the JSON string is an object.

Targets: Multiplatform

shouldBeValidJson​

json.shouldBeValidJson() asserts that the string is valid JSON.

The inverse of this matcher is shouldNotBeValidJson which will error if the string is valid JSON.

Targets: Multiplatform

shouldContainJsonKey​

json.shouldContainJsonKey("$.json.path") asserts that a JSON string contains the given JSON path.

The inverse of this matcher is shouldNotContainJsonKey which will error if a JSON string does contain the given JSON path.

Targets: JVM

shouldContainJsonKeyValue​

str.shouldContainJsonKeyValue("$.json.path", value) asserts that a JSON string contains a JSON path with a specific value.

The inverse of this matcher is shouldNotContainJsonKeyValue which will error if a JSON string does contain the given value at the given JSON path.

Targets: JVM

shouldMatchJsonResource​

json.shouldMatchJsonResource("/file.json") asserts that the JSON is equal to the existing test resource /file.json, ignoring properties' order and formatting.

Targets: JVM