hspec-golden-aeson

Use tests to monitor changes in Aeson serialization

https://github.com/plow-technologies/hspec-golden-aeson#readme

LTS Haskell 23.2:0.9.0.0
Stackage Nightly 2024-12-28:0.9.0.0
Latest on Hackage:0.9.0.0

See all snapshots hspec-golden-aeson appears in

BSD-3-Clause licensed by James M.C. Haver II
Maintained by [email protected]
This version can be pinned in stack with:hspec-golden-aeson-0.9.0.0@sha256:aa17274114026661ba4dfc9c60c230673c8f408bd86482fd611d2d5cb6aff996,2179

Module documentation for 0.9.0.0

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)

Changes

Revision history for hspec-golden-aeson

0.9.0.0 – 2021-03-15

  • Breaking change: Objects are now serialized with sorted keys for better cross-platform compatibility

0.8.0.0 – 2021-03-12

  • Breaking change: Seed is now an Int32 so golden files are more portable. This requires regenerating all golden files which have a seed that overflows
  • Breaking change: Golden files are no longer generated automatically if they don’t exist, to create them, set the CREATE_MISSING_GOLDEN environment variable. This is to prevent missing golden files from silently making golden tests degrade to round-trip tests
  • Add a RECREATE_MISSING_GOLDEN environemnt variable. When present it will cause golden files to be re-created if they cause the test to fail. This is useful for updating golden files when serialization has been purposedly modified and to update the seed if it breaks due to overflow now that it is only 32bit wide.

0.7.0.0 – 2018-05-17

  • Breaking change: allow roundtripAndGoldenADTSpecs test to pass when random samples generated from the seed in the golden file do not produce the same Haskell samples, but yet decoding and re-encoding the golden file still produces the same bytes as in the golden file.
  • Add an additional faulty file ending in .faulty.reencoded.json when the byte-for-byte decode/encode round-trip fails. This allows you to compare the encoding changes without the noise of the random sample change. In this case, the test will output a message indicating whether decoding the golden file produces the same Haskell values as decoding the re-encoded files. If they produce the same values, that is likely a minor encoding change, but still a change so tests fail.
  • Add RandomMismatchOption to Settings so you can have the old behavior of failing tests when random samples change.

0.6.0.0 – 2018-01-04

  • Test encoding in roundtripAndGoldenADTSpecs' and 'roundtripAndGoldenADTSpecsWithSettings functions. This may break current tests because only decoding was tested previously.

0.5.1.0 – 2018-01-04

  • Remove ‘Wredundant-constraints’ flag.

0.5.0.0 – 2018-01-02

  • Add ‘Arbitrary’ requirement for ‘roundtripADTSpecs’, ‘roundtripAndGoldenADTSpecs’ and ‘roundtripAndGoldenADTSpecsWithSettings’ because ‘Arbitrary’ was a redundant constrain for ‘ToADTArbitrary’ in quickcheck-arbitrary-adt.

0.4.0.0 – 2017-12-10

  • Fix behavior for ‘mkGoldenFileForType’. Intention is to create a file in a dir for each constructor, but it was only creating a file for one of the constructors of a type.

0.3.1.0 – 2017-12-02

  • Expose ‘roundtripAndGoldenSpecsWithSettings’.

0.3.0.0 – 2017-11-14

  • Add mkGoldenFileForType.
  • Rename internal function fromTypeable to mkTypeNameInfo.
  • Move TopDir, ModuleName, TypeName, TypeNameInfo and mkTypeNameInfo into Test.Aeson.Internal.Util.

0.2.1.0 – 2017-08-08

  • Added the ability to run an automated test withought needing a Show, Eq, or Typeable instance.
  • Cleaned up error messages, mostly involving redundant types

0.2.0.3 – 2016-09-08

  • Tests were breaking because Test.Types.MismatchedToAndFromSerialization was missing from the cabal file.

0.2.0.2 – 2016-09-07

  • Forgot to add fixes to the test, in previous version they were not compiling.

0.2.0.1 – 2016-09-01

  • Fix error in ‘goldenSpecsWithNote’, behavior for useModuleNameAsSubDirectory was flipped around and also providing the module name surrounded by quotes.
  • Add more tests.

0.2.0.0 – 2016-08-23

  • Make directory and golden file naming flexible.
  • Include optional Settings type that allows users to set the directory name and size of tests.
  • Require quickcheck-arbitrary-adt >= 0.2.0.0.

0.1.0.0 – 2016-08-12

  • First version.