MIT licensed by Freckle Engineering
Maintained by [email protected]
This version can be pinned in stack with:hspec-expectations-json-1.0.2.0@sha256:ec7af341c4cad2335cd42ed5b535aff6cebc4253df48c3368a763600f42ca6a5,3449

Hspec Expectations for JSON Values

Hackage Stackage Nightly Stackage LTS CI

Comparing JSON Values in Haskell tests comes with some challenges:

  • In API responses, additive changes are typically safe and an important way to evolve responses without breaking clients. Therefore, assertions against such responses often want to ignore any unexpected keys in Objects (at any depth), as any clients would.

  • Order often doesn’t matter in API responses either, so it should be possible to assert equality regardless of Array ordering (again, at any depth).

  • When an assertion fails, showing the difference clearly needs to take the above into account (i.e. it can’t show keys you’ve ignored, or ordering differences you didn’t care about), and it has to display things clearly, e.g. as a diff.

This library handles all these things.

Usage

NOTE: this is effectively a distillation of the Haddocks, please view them directly for your installed version, to ensure accurate information.

Four expectations exist with the following behaviors:

Assertion that fails on: extra Object keys wrong Array order
shouldBeJson Yes Yes
shouldBeUnorderedJson Yes No
shouldMatchJson No No
shouldMatchOrderedJson No Yes

Each of these, when they fail, print a difference between the objects, where the expected-on object has been normalized to avoid indicating any of the differences your expectation is ignoring.

shouldBeJson

Passing:

catchFailure $
  [aesonQQ| { "a": true, "b": false } |] `shouldBeJson`
  [aesonQQ| { "a": true, "b": false } |]

Failing:

catchFailure $
  [aesonQQ| { "a": true, "b": false } |] `shouldBeJson`
  [aesonQQ| { "a": true, "b": true  } |]
   {
       "a": true,
---    "b": true
+++    "b": false
   }

shouldBeUnorderedJson

Passing:

catchFailure $
  [aesonQQ| { "a": [true, false], "b": false } |] `shouldBeUnorderedJson`
  [aesonQQ| { "a": [false, true], "b": false } |]

Failing:

catchFailure $
  [aesonQQ| { "a": [true, false], "b": false, "c": true } |] `shouldBeUnorderedJson`
  [aesonQQ| { "a": [false, true], "b": true             } |]
   {
       "a": [
           false,
           true
       ],
---    "b": true
+++    "b": false,
+++    "c": true
   }

shouldMatchJson

Passing:

catchFailure $
  [aesonQQ| { "a": [true, false], "b": false, "c": true } |] `shouldMatchJson`
  [aesonQQ| { "a": [false, true], "b": false            } |]

Failing:

catchFailure $
  [aesonQQ| { "a": [true, false], "b": false, "c": true } |] `shouldMatchJson`
  [aesonQQ| { "a": [false, true], "b": true             } |]
   {
       "a": [
           false,
           true
       ],
---    "b": true
+++    "b": false
   }

shouldMatchOrderedJson

Passing:

catchFailure $
  [aesonQQ| { "a": [true, false], "b": false, "c": true } |] `shouldMatchOrderedJson`
  [aesonQQ| { "a": [true, false], "b": false            } |]

Failing:

catchFailure $
  [aesonQQ| { "a": [true, false], "b": false, "c": true } |] `shouldMatchOrderedJson`
  [aesonQQ| { "a": [false, true], "b": true             } |]
   {
       "a": [
---        false,
---        true
+++        true,
+++        false
       ],
---    "b": true
+++    "b": false
   }

LICENSE | CHANGELOG

Changes

Unreleased

v1.0.2.0

  • Add shouldBeJsonNormalized and Normalizer to better support configurable matching
  • Added new option for treatNullsAsMissing that will treat nulls fields as if they are the same as omitted ones when doing a comparison

v1.0.1.1

  • Add invariant for all matchers for equality. (ex: forall a. a shouldMatchJson a)

v1.0.1.0

  • Colorize diff in expectation failure, if connected to a terminal or running on GitHub Actions.
  • Add a .Lifted module with MonadIO versions

v1.0.0.6

  • Support GHC 9.0 and 9.2
  • Re-add support for aeson-1.x

v1.0.0.5

  • Add lower bound for aeson 2.x

v1.0.0.4

  • Remove dependencies upper bounds

v1.0.0.3

  • Less restrictive upper bound on base

v1.0.0.2

  • Add explicit and relaxed aeson and text bounds

v1.0.0.1

  • Relax base (GHC) upper bound

v1.0.0.0

First tagged release.