From 3b572a5e142d7bce9bac037947283a9b94ca1869 Mon Sep 17 00:00:00 2001 From: Sam Sam Date: Mon, 1 Feb 2021 21:53:48 -0600 Subject: [PATCH] Updated docs for new json matchers (#1988) --- .../docs/assertions/android_matchers.md | 1 + documentation/docs/assertions/arrow.md | 1 + documentation/docs/assertions/compiler.md | 2 + documentation/docs/assertions/core.md | 1 + documentation/docs/assertions/json.md | 116 ++++++++++++++++-- documentation/docs/assertions/jsoup.md | 1 + documentation/docs/assertions/klock.md | 1 + documentation/docs/assertions/konform.md | 1 + .../docs/assertions/kotlinx-datetime.md | 1 + documentation/docs/assertions/ktor.md | 1 + documentation/docs/assertions/sql.md | 1 + documentation/sidebars.js | 14 +-- 12 files changed, 126 insertions(+), 15 deletions(-) diff --git a/documentation/docs/assertions/android_matchers.md b/documentation/docs/assertions/android_matchers.md index 5a84169276c..8ba023176ff 100644 --- a/documentation/docs/assertions/android_matchers.md +++ b/documentation/docs/assertions/android_matchers.md @@ -2,6 +2,7 @@ id: android_matchers title: Android Matchers slug: android-matchers.html +sidebar_label: Android --- diff --git a/documentation/docs/assertions/arrow.md b/documentation/docs/assertions/arrow.md index 7fbd2eeb888..46e2c661d3c 100644 --- a/documentation/docs/assertions/arrow.md +++ b/documentation/docs/assertions/arrow.md @@ -1,6 +1,7 @@ --- title: Arrow slug: arrow.html +sidebar_label: Arrow --- diff --git a/documentation/docs/assertions/compiler.md b/documentation/docs/assertions/compiler.md index 4d65a5d7bb1..3bd98377c5b 100644 --- a/documentation/docs/assertions/compiler.md +++ b/documentation/docs/assertions/compiler.md @@ -1,6 +1,8 @@ --- +id: compiler title: Compiler Matchers slug: compiler-matchers.html +sidebar_label: Compiler --- diff --git a/documentation/docs/assertions/core.md b/documentation/docs/assertions/core.md index fb3b9cabf61..f78b6da34e5 100644 --- a/documentation/docs/assertions/core.md +++ b/documentation/docs/assertions/core.md @@ -2,6 +2,7 @@ id: core title: Core Matchers slug: core-matchers.html +sidebar_label: Core --- diff --git a/documentation/docs/assertions/json.md b/documentation/docs/assertions/json.md index aec558bd985..fa4b489d1a1 100644 --- a/documentation/docs/assertions/json.md +++ b/documentation/docs/assertions/json.md @@ -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. ::: diff --git a/documentation/docs/assertions/jsoup.md b/documentation/docs/assertions/jsoup.md index 30658ef549a..518370563c2 100644 --- a/documentation/docs/assertions/jsoup.md +++ b/documentation/docs/assertions/jsoup.md @@ -1,6 +1,7 @@ --- title: Jsoup Matchers slug: jsoup-matchers.html +sidebar_label: Jsoup --- diff --git a/documentation/docs/assertions/klock.md b/documentation/docs/assertions/klock.md index 4fbaa0ac32d..8e4389bdcfb 100644 --- a/documentation/docs/assertions/klock.md +++ b/documentation/docs/assertions/klock.md @@ -1,6 +1,7 @@ --- title: Klock Matchers slug: klock-matchers.html +sidebar_label: Klock --- diff --git a/documentation/docs/assertions/konform.md b/documentation/docs/assertions/konform.md index a3fdcec3a90..a168cdc95de 100644 --- a/documentation/docs/assertions/konform.md +++ b/documentation/docs/assertions/konform.md @@ -1,6 +1,7 @@ --- title: Konform Matchers slug: konform-matchers.html +sidebar_label: Konform --- diff --git a/documentation/docs/assertions/kotlinx-datetime.md b/documentation/docs/assertions/kotlinx-datetime.md index a33d0441b9a..f96642bdcb8 100644 --- a/documentation/docs/assertions/kotlinx-datetime.md +++ b/documentation/docs/assertions/kotlinx-datetime.md @@ -2,6 +2,7 @@ id: kotlinx_datetime title: Kotlinx Datetime Matchers slug: kotlinx-datetime-matchers.html +sidebar_label: Kotlinx Datetime --- diff --git a/documentation/docs/assertions/ktor.md b/documentation/docs/assertions/ktor.md index feefcb366f8..2049235f4ed 100644 --- a/documentation/docs/assertions/ktor.md +++ b/documentation/docs/assertions/ktor.md @@ -2,6 +2,7 @@ id: ktor title: Ktor Matchers slug: ktor-matchers.html +sidebar_label: Ktor --- diff --git a/documentation/docs/assertions/sql.md b/documentation/docs/assertions/sql.md index 44c27b37a66..c4788417439 100644 --- a/documentation/docs/assertions/sql.md +++ b/documentation/docs/assertions/sql.md @@ -2,5 +2,6 @@ id: sql-matchers title: SQL Matchers slug: sql-matchers.html +sidebar_label: SQL --- diff --git a/documentation/sidebars.js b/documentation/sidebars.js index 81e71e7c101..35e6bed664a 100644 --- a/documentation/sidebars.js +++ b/documentation/sidebars.js @@ -29,17 +29,17 @@ module.exports = { label: "Matcher Modules", collapsed: false, items: [ - 'assertions/android_matchers', - 'assertions/arrow', - 'assertions/compiler', 'assertions/core', 'assertions/json', - 'assertions/jsoup', - 'assertions/klock', - 'assertions/konform', - 'assertions/kotlinx_datetime', 'assertions/ktor', + 'assertions/android_matchers', + 'assertions/kotlinx_datetime', + 'assertions/arrow', 'assertions/sql-matchers', + 'assertions/konform', + 'assertions/klock', + 'assertions/compiler', + 'assertions/jsoup', ] } ],