-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Test that your (Aeson) JSON encoding matches your expectations
--   
--   Test that your (Aeson) JSON encoding matches your expectations
@package json-assertions
@version 1.0.4


-- | <tt>json-assertions</tt> is a library for validating that your JSON
--   encoding matches what you are actually expecting. It does this by
--   providing you with a DSL to traverse a JSON document at the same time
--   as you traverse the value that was encoded. As you traverse the JSON
--   document, you are building up assertions (by asserting that you expect
--   certain keys and array indices to exist), and you can also add your
--   own assertions to check the contents of object properties.
--   
--   <a>JSONTest</a> is an indexed monad, so you will need to enable
--   <tt>RebindableSyntax</tt> and bring indexed monadic bind into scope:
--   
--   <pre>
--   
--   import Prelude hiding (Monad(..))
--   import Control.Monad.Indexed ((&gt;&gt;&gt;=), ireturn)
--   import Test.JSON.Assertions
--   import Data.Aeson
--   
--   return :: a -&gt; JSONTest i i a
--   return = ireturn
--   
--   (&gt;&gt;=) :: m i j a -&gt; (a -&gt; m j k b) -&gt; m i k b
--   (&gt;&gt;=) = (&gt;&gt;&gt;=)
--   </pre>
--   
--   You can now write tests as an action in the <a>JSONTest</a> monad. The
--   first index is the type of the object you wish to encode, and the
--   second parameter is the type that the test ends in. For example,
--   consider the following:
--   
--   <pre>
--   data Person = Person { personName :: String }
--   instance ToJSON Person where
--     toJSON p = object [ "name" .= personName p ]
--   </pre>
--   
--   We can write a test to check that the JSON encoding of a
--   <tt>Person</tt>'s name is correct:
--   
--   <pre>
--   personTest :: JSONTest Person String String
--   personTest = do
--     expectedName &lt;- key "name"
--     assertEq expectedName
--   </pre>
--   
--   For more information, you may wish to read
--   <a>http://ocharles.org.uk/blog/posts/2013-11-24-using-indexed-free-monads-to-quickcheck-json.html</a>.
module Test.JSON.Assertions

-- | Traverse into the value underneath a specific key in the JSON
--   structure. The return value is the value inside the Haskell value -
--   that is, the result applying the associated morphism.
key :: String -> (i -> j) -> JSONTest i j j

-- | Traverse the specific index of a JSON array. The return value is the
--   value inside the Haskell value - that is, the result applying the
--   associated morphism.
nth :: Int -> (i -> j) -> JSONTest i j j

-- | Assert that the current JSON value is exactly equal to the result of
--   calling <a>toJSON</a> on a value.
assertEq :: ToJSON a => a -> JSONTest i i ()

-- | Using <a>stop</a> discards the indices in the monad, which can help
--   when you need to <tt>isum</tt> multiple tests that end in different
--   states.
stop :: JSONTest a () r

-- | Finalize a <a>JSONTest</a> by calling <a>stop</a> at the end.
jsonTest :: JSONTest i j a -> JSONTest i () a

-- | Run a <a>JSONTest</a> against a Haskell value that can be encoded to
--   JSON. Returns a list of strings describing the failed assertions, or
--   the empty list if all assertions were satisfied.
testJSON :: ToJSON i => JSONTest i j a -> i -> [String]
type JSONTest = IxFree JSONF
instance IxFunctor JSONF