hspec-golden-aeson: Use tests to monitor changes in Aeson serialization

This is a package candidate release! Here you can preview how this package release will appear once published to the main package index (which can be accomplished via the 'maintain' link below). Please note that once a package has been published to the main package index it cannot be undone! Please consult the package uploading documentation for more information.

[maintain] [Publish]

Warnings:

Use tests to monitor changes in Aeson serialization


[Skip to Readme]

Properties

Versions 0.1.0.0, 0.2.0.0, 0.2.0.1, 0.2.0.2, 0.2.0.3, 0.2.1.0, 0.3.0.0, 0.3.1.0, 0.4.0.0, 0.5.0.0, 0.5.1.0, 0.6.0.0, 0.7.0.0, 0.9.0.0, 0.9.0.0
Change log ChangeLog.md
Dependencies aeson, aeson-pretty, base (>=4.7 && <5), bytestring, directory, filepath, hspec, HUnit, QuickCheck, quickcheck-arbitrary-adt (>=0.3.0.0), random, transformers [details]
License BSD-3-Clause
Copyright 2016 Plow Technologies
Author James M.C. Haver II
Maintainer mchaver@gmail.com
Category Testing
Home page https://github.com/plow-technologies/hspec-golden-aeson#readme
Bug tracker https://github.com/plow-technologies/hspec-golden-aeson/issues
Source repo head: git clone https://github.com/plow-technologies/hspec-golden-aeson
Uploaded by albertov at 2021-03-15T12:26:49Z

Modules

[Index] [Quick Jump]

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees


Readme for hspec-golden-aeson-0.9.0.0

[back to package description]

hspec-golden-aeson

Arbitrary

GoldenSpecs functions write golden files if they do not exist. When they do exist they use a seed from the golden file to create an arbitrary value of a type and check if the serialization matches the file. If it fails it means that there has been a change in the Aeson serialization or a change in the data type.

RoundtripSpecs make sure that a type is able to be encoded to JSON, decoded from JSON back to the original type, and equal the same value. If it fails then there may be an issue with the ToJSON and FromJSON instances.

ToADTArbitrary

ToADTArbitrary is a type class that helps create arbitrary values for every constructor in a type. GoldenADTSpecs and RoundtripADTSpecs function similarly to their Arbitrary counterparts, but will specifically test each constructor. This is very useful for sum types.

Usage

{-# LANGUAGE DeriveGeneric #-}

-- base
import GHC.Generics (Generic)
import Data.Proxy

-- aeson
import Data.Aeson (ToJSON)

-- QuickCheck
import Test.QuickCheck (Arbitrary (..), oneof)

-- quickcheck-arbitrary-adt
import Test.QuickCheck.Arbitrary.ADT (ToADTArbitrary)

-- hspec-golden-aeson
import Test.Aeson.GenericSpecs (mkGoldenFileForType)

-- product type
data Person =
  Person
    { name :: String
    , address :: String
    , age :: Int
    } deriving (Eq,Read,Show,Generic)

instance ToJSON Person

-- derive ToADTArbitrary generically
instance ToADTArbitrary Person
instance Arbitrary Person where
  arbitrary = Person <$> arbitrary <*> arbitrary <*> arbitrary

-- sum type
data OnOrOff
  = On
  | Off
  deriving (Eq,Read,Show,Generic)

instance ToJSON OnOrOff

-- derive ToADTArbitrary generically
instance ToADTArbitrary OnOrOff
instance Arbitrary OnOrOff where
  arbitrary = oneof [pure On, pure Off]


main :: IO ()
main = do
  -- only create the golden files, do not run tests
  mkGoldenFileForType 10 (Proxy :: Proxy Person) "golden"
  mkGoldenFileForType 10 (Proxy :: Proxy OnOrOff) "golden"
  
  -- for an arbitrary instance of each constructor
  -- make sure that ToJSON and FromJSON are defined such that 
  -- they same value is maintained
  roundtripSpecs (Proxy :: Proxy Person)
  roundtripSpecs (Proxy :: Proxy OnOrOff)

  -- the first time it create files if they do not exist
  -- if they exist then it will test serialization against the files along with the roundtrip tests
  -- files are saved in "golden" dir.
  goldenSpecs (Proxy :: Proxy Person)
  goldenSpecs (Proxy :: Proxy OnOrOff)
  
  -- use the module name as a dir when saving and opening files
  goldenSpecs (defaultSettings { useModuleNameAsSubDirectory = True }) (Proxy :: Proxy Person)
  goldenSpecs (defaultSettings { useModuleNameAsSubDirectory = True }) (Proxy :: Proxy OnOrOff)
  
  -- control the location of the golde files
  let topDir = "json-tests"
  goldenSpecs (defaultSettings {goldenDirectoryOption = CustomDirectoryName topDir}) (Proxy :: Proxy Person)
  goldenSpecs (defaultSettings {goldenDirectoryOption = CustomDirectoryName topDir}) (Proxy :: Proxy OnOrOff)