Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Updated docs for new json matchers (#1988)
- Loading branch information
Showing
12 changed files
with
126 additions
and
15 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -2,6 +2,7 @@ | |
id: android_matchers | ||
title: Android Matchers | ||
slug: android-matchers.html | ||
sidebar_label: Android | ||
--- | ||
|
||
|
||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,6 +1,7 @@ | ||
--- | ||
title: Arrow | ||
slug: arrow.html | ||
sidebar_label: Arrow | ||
--- | ||
|
||
|
||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,6 +1,8 @@ | ||
--- | ||
id: compiler | ||
title: Compiler Matchers | ||
slug: compiler-matchers.html | ||
sidebar_label: Compiler | ||
--- | ||
|
||
|
||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -2,6 +2,7 @@ | |
id: core | ||
title: Core Matchers | ||
slug: core-matchers.html | ||
sidebar_label: Core | ||
--- | ||
|
||
|
||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,22 +1,122 @@ | ||
--- | ||
title: Json Matchers | ||
slug: json-matchers.html | ||
sidebar_label: 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 | ||
|
||
Matchers for JSON are provided by the `kotest-assertions-json` module. | ||
`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. | ||
|
||
| JSON | For convenience, JSONs are simply strings | | ||
| -------- | ---- | | ||
| `str?.shouldMatchJson(json?)` | Asserts that the JSON is equal to another JSON ignoring properties' order and formatting. | | ||
| `str?.shouldContainJsonKey("$.json.path")` | Asserts that the JSON contains a JSON path. | | ||
| `str?.shouldContainJsonKeyValue("$.json.path", value)` | Asserts that the JSON contains a JSON path with a specific `value`. | | ||
| `str?.shouldMatchJsonResource("/file.json")` | Asserts that the JSON is equal to the existing `/file.json` ignoring properties' order and formatting. | | ||
For example, the following two JSON strings would be considered equal: | ||
|
||
```json | ||
{ | ||
"name": "sam", | ||
"location": "chicago", | ||
"age" : 41 | ||
} | ||
``` | ||
|
||
and | ||
|
||
```json | ||
{ "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: | ||
|
||
```kotlin | ||
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 | ||
|
||
```json | ||
{ "a": "foo", "b": "bar" } | ||
``` | ||
|
||
and | ||
|
||
```json | ||
{ "b": "bar", "a": "foo" } | ||
``` | ||
|
||
would be considered equal. Setting this parameter to `CompareOrder.Strict` means that the above example would fail. For example: | ||
|
||
```kotlin | ||
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 are built using the Jackson library | ||
JSON matchers on the JVM are built using the Jackson library. | ||
::: |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,6 +1,7 @@ | ||
--- | ||
title: Jsoup Matchers | ||
slug: jsoup-matchers.html | ||
sidebar_label: Jsoup | ||
--- | ||
|
||
|
||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,6 +1,7 @@ | ||
--- | ||
title: Klock Matchers | ||
slug: klock-matchers.html | ||
sidebar_label: Klock | ||
--- | ||
|
||
|
||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,6 +1,7 @@ | ||
--- | ||
title: Konform Matchers | ||
slug: konform-matchers.html | ||
sidebar_label: Konform | ||
--- | ||
|
||
|
||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -2,6 +2,7 @@ | |
id: ktor | ||
title: Ktor Matchers | ||
slug: ktor-matchers.html | ||
sidebar_label: Ktor | ||
--- | ||
|
||
|
||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -2,5 +2,6 @@ | |
id: sql-matchers | ||
title: SQL Matchers | ||
slug: sql-matchers.html | ||
sidebar_label: SQL | ||
--- | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters