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


-- | A Testing Framework for Haskell
--   
--   Hspec is a testing framework for Haskell. Some of Hspec's distinctive
--   features are:
--   
--   <ul>
--   <li>a friendly DSL for defining tests</li>
--   <li>integration with QuickCheck, SmallCheck, and HUnit</li>
--   <li>parallel test execution</li>
--   <li>automatic discovery of test files</li>
--   </ul>
--   
--   The Hspec Manual is at <a>https://hspec.github.io/</a>.
@package hspec
@version 2.11.16



-- | <i>Deprecated: Use <a>Test.Hspec.Api.Formatters.V1</a> instead.</i>
module Test.Hspec.Formatters

module Test.Hspec.Runner


-- | Hspec is a testing framework for Haskell.
--   
--   This is the library reference for Hspec. The <a>User's Manual</a>
--   contains more in-depth documentation.
module Test.Hspec

-- | A <a>SpecWith</a> that can be evaluated directly by the <a>hspec</a>
--   function as it does not require any parameters.
type Spec = SpecWith ()

-- | A <tt><a>SpecWith</a> a</tt> represents a test or group of tests that
--   require an <tt>a</tt> value to run.
--   
--   In the common case, a <a>Spec</a> is a <tt><a>SpecWith</a> ()</tt>
--   which requires <tt>()</tt> and can thus be executed with <a>hspec</a>.
--   
--   To supply an argument to <a>SpecWith</a> tests to turn them into
--   <a>Spec</a>, use functions from <a>Test.Hspec.Core.Hooks</a> such as
--   <a>around</a>, <a>before</a>, <a>mapSubject</a> and similar.
--   
--   Values of this type are created by <a>it</a>, <a>describe</a> and
--   similar.
type SpecWith a = SpecM a ()

-- | A type class for examples, that is to say, test bodies as used in
--   <a>it</a> and similar functions.
class Example e

-- | The argument type that is needed to run this <a>Example</a>. If
--   <a>Arg</a> is <tt>()</tt>, no argument is required and the
--   <a>Example</a> can be run as-is.
--   
--   The value of <a>Arg</a> is the difference between <a>Spec</a> (aka
--   <tt><a>SpecWith</a> ()</tt>), which can be executed, and
--   <tt><a>SpecWith</a> a</tt>, which cannot be executed without turning
--   it into <a>Spec</a> first.
--   
--   To supply an argument to examples, use the functions in
--   <a>Test.Hspec.Core.Hooks</a> such as <a>around</a>, <a>before</a>,
--   <a>mapSubject</a> and similar.
type family Arg e

-- | The <tt>it</tt> function creates a spec item.
--   
--   A spec item consists of:
--   
--   <ul>
--   <li>a textual description of a desired behavior</li>
--   <li>an example for that behavior</li>
--   </ul>
--   
--   <pre>
--   describe "absolute" $ do
--     it "returns a positive number when given a negative number" $
--       absolute (-1) == 1
--   </pre>
--   
--   <tt><a>Example</a> a</tt> optionally accepts an argument
--   <tt><a>Arg</a> a</tt>, which is then given to the test body. This is
--   useful for provisioning resources for a test which are created and
--   cleaned up outside the test itself. See <a>Arg</a> for details.
--   
--   Note that this function is often on the scene of nasty type errors due
--   to GHC failing to infer the type of <tt>do</tt> notation in the test
--   body. It can be helpful to use <a>TypeApplications</a> to explicitly
--   specify the intended <a>Example</a> type.
it :: (HasCallStack, Example a) => String -> a -> SpecWith (Arg a)

-- | <tt>specify</tt> is an alias for <a>it</a>.
specify :: (HasCallStack, Example a) => String -> a -> SpecWith (Arg a)

-- | The <tt>describe</tt> function combines a list of specs into a larger
--   spec.
describe :: HasCallStack => String -> SpecWith a -> SpecWith a

-- | <tt>context</tt> is an alias for <a>describe</a>.
context :: HasCallStack => String -> SpecWith a -> SpecWith a

-- | <tt>example</tt> is a type restricted version of <a>id</a>. It can be
--   used to get better error messages on type mismatches.
--   
--   Compare e.g.
--   
--   <pre>
--   it "exposes some behavior" $ example $ do
--     putStrLn
--   </pre>
--   
--   with
--   
--   <pre>
--   it "exposes some behavior" $ do
--     putStrLn
--   </pre>
example :: Expectation -> Expectation

-- | <a>parallel</a> marks all spec items of the given spec to be safe for
--   parallel evaluation.
parallel :: SpecWith a -> SpecWith a

-- | <a>sequential</a> marks all spec items of the given spec to be
--   evaluated sequentially.
sequential :: SpecWith a -> SpecWith a

-- | Run an IO action while constructing the spec tree.
--   
--   <a>SpecM</a> is a monad to construct a spec tree, without executing
--   any spec items itself. <tt>runIO</tt> allows you to run IO actions
--   during this construction phase. The IO action is always run when the
--   spec tree is constructed (e.g. even when <tt>--dry-run</tt> is
--   specified). If you do not need the result of the IO action to
--   construct the spec tree, <a>beforeAll</a> may be more suitable for
--   your use case.
runIO :: IO r -> SpecM a r

-- | <a>pending</a> can be used to mark a spec item as pending.
--   
--   If you want to textually specify a behavior but do not have an example
--   yet, use this:
--   
--   <pre>
--   describe "fancyFormatter" $ do
--     it "can format text in a way that everyone likes" $
--       pending
--   </pre>
pending :: HasCallStack => Expectation

-- | <a>pendingWith</a> is similar to <a>pending</a>, but it takes an
--   additional string argument that can be used to specify the reason for
--   why the spec item is pending.
pendingWith :: HasCallStack => String -> Expectation

-- | Changing <a>it</a> to <a>xit</a> marks the corresponding spec item as
--   pending.
--   
--   This can be used to temporarily disable a spec item.
xit :: (HasCallStack, Example a) => String -> a -> SpecWith (Arg a)

-- | <tt>xspecify</tt> is an alias for <a>xit</a>.
xspecify :: (HasCallStack, Example a) => String -> a -> SpecWith (Arg a)

-- | Changing <a>describe</a> to <a>xdescribe</a> marks all spec items of
--   the corresponding subtree as pending.
--   
--   This can be used to temporarily disable spec items.
xdescribe :: HasCallStack => String -> SpecWith a -> SpecWith a

-- | <tt>xcontext</tt> is an alias for <a>xdescribe</a>.
xcontext :: HasCallStack => String -> SpecWith a -> SpecWith a

-- | <a>focus</a> focuses all spec items of the given spec.
--   
--   Applying <a>focus</a> to a spec with focused spec items has no effect.
focus :: SpecWith a -> SpecWith a

-- | <tt>fit</tt> is an alias for <tt>fmap focus . it</tt>
fit :: (HasCallStack, Example a) => String -> a -> SpecWith (Arg a)

-- | <tt>fspecify</tt> is an alias for <a>fit</a>.
fspecify :: (HasCallStack, Example a) => String -> a -> SpecWith (Arg a)

-- | <tt>fdescribe</tt> is an alias for <tt>fmap focus . describe</tt>
fdescribe :: HasCallStack => String -> SpecWith a -> SpecWith a

-- | <tt>fcontext</tt> is an alias for <a>fdescribe</a>.
fcontext :: HasCallStack => String -> SpecWith a -> SpecWith a

-- | An <a>IO</a> action that expects an argument of type <tt>a</tt>.
--   
--   This type is what <a>Example</a>s are ultimately unlifted into for
--   execution.
type ActionWith a = a -> IO ()

-- | Run a custom action before every spec item.
before :: IO a -> SpecWith a -> Spec

-- | Run a custom action before every spec item.
before_ :: IO () -> SpecWith a -> SpecWith a

-- | Run a custom action before every spec item.
beforeWith :: (b -> IO a) -> SpecWith a -> SpecWith b

-- | Run a custom action before the first spec item.
beforeAll :: HasCallStack => IO a -> SpecWith a -> Spec

-- | Run a custom action before the first spec item.
beforeAll_ :: HasCallStack => IO () -> SpecWith a -> SpecWith a

-- | Run a custom action with an argument before the first spec item.
beforeAllWith :: HasCallStack => (b -> IO a) -> SpecWith a -> SpecWith b

-- | Run a custom action after every spec item.
after :: ActionWith a -> SpecWith a -> SpecWith a

-- | Run a custom action after every spec item.
after_ :: IO () -> SpecWith a -> SpecWith a

-- | Run a custom action after the last spec item.
afterAll :: HasCallStack => ActionWith a -> SpecWith a -> SpecWith a

-- | Run a custom action after the last spec item.
afterAll_ :: HasCallStack => IO () -> SpecWith a -> SpecWith a

-- | Run a custom action before and/or after every spec item, supplying it
--   with an argument obtained via IO.
--   
--   This is useful for tasks like creating a file handle or similar
--   resource before a test and destroying it after the test.
around :: (ActionWith a -> IO ()) -> SpecWith a -> Spec

-- | Run a custom action before and/or after every spec item.
around_ :: (IO () -> IO ()) -> SpecWith a -> SpecWith a

-- | Run a custom action before and/or after every spec item.
aroundWith :: (ActionWith a -> ActionWith b) -> SpecWith a -> SpecWith b

-- | Wrap an action around the given spec.
aroundAll :: HasCallStack => (ActionWith a -> IO ()) -> SpecWith a -> Spec

-- | Wrap an action around the given spec.
aroundAll_ :: HasCallStack => (IO () -> IO ()) -> SpecWith a -> SpecWith a

-- | Wrap an action around the given spec. Changes the arg type inside.
aroundAllWith :: HasCallStack => (ActionWith a -> ActionWith b) -> SpecWith a -> SpecWith b

-- | Modify the subject under test.
--   
--   Note that this resembles a contravariant functor on the first type
--   parameter of <a>SpecM</a>. This is because the subject is passed
--   inwards, as an argument to the spec item.
mapSubject :: (b -> a) -> SpecWith a -> SpecWith b

-- | Ignore the subject under test for a given spec.
ignoreSubject :: SpecWith () -> SpecWith a

-- | Run a given spec and write a report to <a>stdout</a>. Exit with
--   <a>exitFailure</a> if at least one spec item fails.
--   
--   <i>Note</i>: <a>hspec</a> handles command-line options and reads
--   config files. This is not always desirable. Use <a>evalSpec</a> and
--   <a>runSpecForest</a> if you need more control over these aspects.
hspec :: Spec -> IO ()

module Test.Hspec.QuickCheck

-- | Use modified <a>Args</a> for given spec.
modifyArgs :: (Args -> Args) -> SpecWith a -> SpecWith a

-- | Use a modified <a>maxSuccess</a> for given spec.
modifyMaxSuccess :: (Int -> Int) -> SpecWith a -> SpecWith a

-- | Use a modified <a>maxDiscardRatio</a> for given spec.
modifyMaxDiscardRatio :: (Int -> Int) -> SpecWith a -> SpecWith a

-- | Use a modified <a>maxSize</a> for given spec.
modifyMaxSize :: (Int -> Int) -> SpecWith a -> SpecWith a

-- | Use a modified <a>maxShrinks</a> for given spec.
modifyMaxShrinks :: (Int -> Int) -> SpecWith a -> SpecWith a

-- | <pre>
--   prop ".." $
--     ..
--   </pre>
--   
--   is a shortcut for
--   
--   <pre>
--   <a>it</a> ".." $ <a>property</a> $
--     ..
--   </pre>
prop :: (HasCallStack, Testable prop) => String -> prop -> Spec

-- | <pre>
--   xprop ".." $
--     ..
--   </pre>
--   
--   is a shortcut for
--   
--   <pre>
--   <a>xit</a> ".." $ <a>property</a> $
--     ..
--   </pre>
xprop :: (HasCallStack, Testable prop) => String -> prop -> Spec

-- | <pre>
--   fprop ".." $
--     ..
--   </pre>
--   
--   is a shortcut for
--   
--   <pre>
--   <a>fit</a> ".." $ <a>property</a> $
--     ..
--   </pre>
fprop :: (HasCallStack, Testable prop) => String -> prop -> Spec
