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


-- | Shared utilities for writing unit and property tests.
--   
--   Shared utilities for writing unit and property tests.
@package cardano-wallet-test-utils
@version 2020.12.8


-- | Helper functions for testing.
module Test.Hspec.Extra

-- | Run a <tt>bracket</tt> resource acquisition function around all the
--   specs. The bracket opens before the first test case and closes after
--   the last test case.
--   
--   It works by actually spawning a new thread responsible for the
--   resource acquisition, passing the resource along to the parent threads
--   via a shared MVar. Then, there's a bit of logic to synchronize both
--   threads and make sure that:
--   
--   a) The 'Resource Owner' thread is terminated when the main thread is
--   done with the resource.
--   
--   b) The 'Main Thread' only exists when the resource owner has released
--   the resource. Exiting the main thread before the 'Resource Owner' has
--   released the resource could left a hanging resource open. This is
--   particularly annoying when the resource is a running process!
--   
--   Main Thread Resource Owner x | Spawn |-----------------------&gt;x | |
--   | |-- Acquire resource | Send Resource | |&lt;-----------------------|
--   | | | | ... ... Await main thread signal | | | | | Send Signal |
--   |-----------------------&gt;| | | | ... Release resource | Send Done |
--   |&lt;-----------------------| | Exit | Exit
aroundAll :: forall a. HasCallStack => (ActionWith a -> IO ()) -> SpecWith a -> Spec

-- | A drop-in replacement for <a>it</a> that'll automatically retry a
--   scenario once if it fails, to cope with potentially flaky tests.
--   
--   It also has a timeout of 10 minutes.
it :: HasCallStack => String -> ActionWith ctx -> SpecWith ctx

-- | Like <tt>it</tt> but with a custom timeout, which makes it realistic
--   to test.
itWithCustomTimeout :: HasCallStack => Int -> String -> ActionWith ctx -> SpecWith ctx

-- | Mark a test pending because of flakiness, with given reason. Unless
--   the RUN_FLAKY_TESTS environment variable is set.
flakyBecauseOf :: String -> Expectation


-- | Extra helper functions for QuickCheck
module Test.QuickCheck.Extra

-- | Resize a generator to grow with the size parameter, but remains
--   reasonably sized. That is handy when testing on data-structures that
--   can be arbitrarily large and, when large entities don't really bring
--   any value to the test itself.
--   
--   It uses a square root function which makes the size parameter grows
--   quadratically slower than normal. That is,
--   
--   TODO: table
reasonablySized :: Gen a -> Gen a


-- | Utility function for finding the package test data directory.
module Test.Utils.Paths

-- | A TH function to get the test data directory.
--   
--   It combines the current source file location and cabal file to locate
--   the package directory in such a way that works in both the stack/cabal
--   package build and ghci.
--   
--   For the Nix build, rather than baking in a path that starts with
--   <tt>/build</tt>, it makes the test data path relative to the current
--   directory.
getTestData :: Q Exp

-- | A variant of <a>getTestData</a> which lets you specify the test data
--   <a>FilePath</a> relative to the package root directory.
getTestDataPath :: FilePath -> Q Exp

-- | Infer from environment variables whether we are running within a Nix
--   build (and not just a nix-shell).
inNixBuild :: IO Bool

module Test.Utils.Roundtrip
jsonRoundtripAndGolden :: forall a. (Arbitrary a, ToJSON a, FromJSON a, Typeable a) => FilePath -> Proxy a -> Spec
httpApiDataRoundtrip :: forall a. (Arbitrary a, FromHttpApiData a, ToHttpApiData a, Typeable a, Eq a, Show a) => Proxy a -> Spec


-- | Provides a simple static files web server to be used as a fixture in
--   tests which need a HTTP server.
module Test.Utils.StaticServer

-- | Run a localhost HTTP file server on any free port, while executing the
--   given action.
withStaticServer :: FilePath -> (String -> IO a) -> IO a


-- | Provides utility functions relating to testing with times and dates.
module Test.Utils.Time

-- | A wrapper for <a>UTCTime</a> whose <a>Arbitrary</a> instance spans a
--   uniform range of dates and a mixture of time precisions.
data UniformTime

-- | Generate <a>UTCTime</a> values over a uniform range of dates and a
--   mixture of time precisions.
--   
--   Dates will be generated in a range that's bounded by
--   <a>defaultLowerBound</a> and <a>defaultUpperBound</a>.
genUniformTime :: Gen UTCTime

-- | Generate <a>UTCTime</a> values over a uniform range of dates and a
--   mixture of time precisions.
--   
--   Dates will be generated in a range that's bounded by the given minimum
--   and maximum Julian day arguments.
genUniformTimeWithinRange :: Day -> Day -> Gen UTCTime
getUniformTime :: UniformTime -> UTCTime
instance GHC.Show.Show Test.Utils.Time.UniformTime
instance GHC.Classes.Ord Test.Utils.Time.UniformTime
instance GHC.Classes.Eq Test.Utils.Time.UniformTime
instance Test.QuickCheck.Arbitrary.Arbitrary Test.Utils.Time.UniformTime


-- | Provides functions for setting up and capturing logging so that
--   expectations about logging can be asserted in test scenarios.
module Test.Utils.Trace

-- | Run an action with a logging <tt>Trace</tt> object, and a function to
--   get all messages that have been traced.
withLogging :: ((Tracer IO msg, IO [msg]) -> IO a) -> IO a

-- | Run an action with a <tt>Trace</tt>, returning captured log messages
--   along with the result of the action.
captureLogging :: (Tracer IO msg -> IO a) -> IO ([msg], a)

-- | Count elements in the list matching the given Prism. Handy for
--   counting log messages which are typically constructed as sum types
--   with many constructors.
--   
--   A Prism look scary but can be obtained very easily if the target type
--   is deriving <tt>Generic</tt>. From there, use
--   
--   `Data.Generics.Sum.Constructor#_Ctor` from `generic-lens`.
--   
--   <b>Example:</b>
--   
--   <pre>
--   &gt;&gt;&gt; data MySumType = MyConstructor | MyOtherConstructor deriving Generic
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; xs = [ MyConstructor, MyOtherConstructor, MyConstructor ]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; count (_Ctor @"MyConstructor") xs
--   2
--   </pre>
countMsg :: Prism' s a -> [s] -> Int


-- | Utility function for making test suites pass on Windows.
module Test.Utils.Windows
skipOnWindows :: HasCallStack => String -> Expectation
pendingOnWindows :: HasCallStack => String -> Expectation
pendingOnWine :: HasCallStack => String -> Expectation
whenWindows :: IO () -> IO ()
isWindows :: Bool
nullFileName :: FilePath

-- | Use the presence of <tt>winepath.exe</tt> to detect when running tests
--   under Wine.
getIsWine :: IO Bool


-- | File path related test utilities.
module Test.Utils.FilePath

-- | A file or directory name. The <a>Arbitrary</a> instance will generate
--   values which are valid on Windows and POSIX.
--   
--   
--   <a>https://docs.microsoft.com/en-us/windows/win32/fileio/naming-a-file</a>
newtype PathElement
PathElement :: FilePath -> PathElement
instance GHC.Classes.Eq Test.Utils.FilePath.PathElement
instance GHC.Show.Show Test.Utils.FilePath.PathElement
instance Test.QuickCheck.Arbitrary.Arbitrary Test.Utils.FilePath.PathElement
