Skip to main content
Version: 5.5

Matching JSON content

This module is available for JVM and JS targets.


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


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

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


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


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


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

Targets: Multiplatform


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

Targets: Multiplatform


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


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


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

Targets: JVM