json.md

title	slug	sidebar_label
Json Matchers	json-matchers.html	Json

Kotest provides powerful JSON assertions in the kotest-assertions-json module. These allow flexible testing of json strings without the need to worry about formatting or ordering. They provide precise error messages when comparing json so that the error can be easily found in a large json structure.

This module is available for JVM and JS 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.

CompareMode

shouldEqualJson supports a parameter called CompareMode which can be used to guide comparison of types that contain compatible values.

By setting this to CompareMode.Lenient, types that can be coerced to match are considered equal. For example, the string value "true" and the boolean value true will be considered equal if compare mode is lenient.

Similarly, the string value "123" and the number value 123 will match in lenient mode.

For example:

val a = """ { "a": "true", "b": "123" } """
val b = """ { "a": true, "b": 123 } """

// this would pass
a.shouldEqualJson(b, CompareOrder.Lenient)

// this would fail
a.shouldEqualJson(b)

:::note Longs and doubles will always attempt to match regardless of this setting. :::

The default is CompareMode.Strict which will consider any values unequal if they have different types.

CompareOrder

shouldEqualJson additionally supports a parameter called CompareOrder which can be used to force object comparision to consider field order. By default, the order of fields in an object does not matter, and so

{ "a": "foo", "b": "bar" }

and

{ "b": "bar", "a": "foo" }

would be considered equal. Setting this parameter to CompareOrder.Strict means that the above example would fail. For example:

val a = """ { "a": "foo", "b": "bar" } """
val b = """ { "b": "bar", "a": "foo" } """

// this would fail
a.shouldEqualJson(b, CompareOrder.Strict)

// this would pass
a.shouldEqualJson(b)

Targets: JVM, JS

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?.shouldContainJsonKey("$.json.path") asserts that the JSON is equal to the existing /file.json ignoring properties' order and formatting.

Targets: JVM

:::note JSON matchers on the JVM are built using the Jackson library. :::