hspec-golden-aeson
Use tests to monitor changes in Aeson serialization
https://github.com/plow-technologies/hspec-golden-aeson#readme
LTS Haskell 23.0: | 0.9.0.0 |
Stackage Nightly 2024-12-09: | 0.9.0.0 |
Latest on Hackage: | 0.9.0.0 |
hspec-golden-aeson-0.9.0.0@sha256:aa17274114026661ba4dfc9c60c230673c8f408bd86482fd611d2d5cb6aff996,2179
Module documentation for 0.9.0.0
- Test
- Test.Aeson
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
toSettings
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.