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


-- | A simple and intuitive library for automated testing.
--   
--   Chell is a simple and intuitive library for automated testing. It
--   natively supports assertion-based testing, and can use companion
--   libraries such as <tt>chell-quickcheck</tt> to support more complex
--   testing strategies.
--   
--   An example test suite, which verifies the behavior of artithmetic
--   operators.
--   
--   <pre>
--   {-# LANGUAGE OverloadedStrings #-}
--   {-# LANGUAGE TemplateHaskell #-}
--   
--   import Test.Chell
--   
--   test_Math :: Suite
--   test_Math = suite "math" [test_Addition, test_Subtraction]
--   
--   test_Addition :: Suite
--   test_Addition = assertions "addition" $ do
--       $expect (equal (2 + 1) 3)
--       $expect (equal (1 + 2) 3)
--   
--   test_Subtraction :: Suite
--   test_Subtraction = assertions "subtraction" $ do
--       $expect (equal (2 - 1) 1)
--       $expect (equal (1 - 2) (-1))
--   
--   main :: IO ()
--   main = defaultMain [test_Math]
--   </pre>
--   
--   <pre>
--   $ ghc --make chell-example.hs
--   $ ./chell-example
--   PASS: 2 tests run, 2 tests passed
--   </pre>
@package chell
@version 0.2.5

module Test.Chell

-- | A simple default main function, which runs a list of tests and logs
--   statistics to stderr.
defaultMain :: [Suite] -> IO ()

-- | A tree of <a>Test</a>s; use the <a>test</a> and <a>suite</a> helper
--   functions to build up a <a>Suite</a>.
data Suite
suite :: Text -> [Suite] -> Suite
suiteName :: Suite -> Text

-- | The full list of <a>Test</a>s contained within this <a>Suite</a>. Each
--   <a>Test</a> is returned with its name modified to include the name of
--   its parent <a>Suite</a>s.
suiteTests :: Suite -> [Test]
test :: Test -> Suite

-- | Conditionally skip tests. Use this to avoid commenting out tests which
--   are currently broken, or do not work on the current platform.
--   
--   <pre>
--   tests = <a>suite</a> "tests"
--       [ <a>skipIf</a> builtOnUnix test_WindowsSpecific
--       ]
--   </pre>
skipIf :: Bool -> Suite -> Suite

-- | Conditionally skip tests, depending on the result of a runtime check.
--   The predicate is checked before each test is started.
--   
--   <pre>
--   tests = <a>suite</a> "tests"
--       [ <a>skipWhen</a> noNetwork test_PingGoogle
--       ]
--   </pre>
skipWhen :: IO Bool -> Suite -> Suite
newtype Assertion
Assertion :: (IO AssertionResult) -> Assertion
data AssertionResult
AssertionPassed :: AssertionResult
AssertionFailed :: Text -> AssertionResult
class IsAssertion a
data Assertions a

-- | Convert a sequence of pass/fail assertions into a runnable test.
--   
--   <pre>
--   test_Equality :: Suite
--   test_Equality = assertions "equality" $ do
--       $assert (1 == 1)
--       $assert (equal 1 1)
--   </pre>
assertions :: Text -> Assertions a -> Suite

-- | Convert a sequence of pass/fail assertions into a runnable test.
--   
--   This is easier to use than <a>assertions</a> when the result is going
--   to be modified (eg, by a wrapper) before being used in a test suite.
--   
--   Most users should use <a>assertions</a> instead, to avoid the extra
--   wrapping step.
--   
--   Since: 0.2.3
assertionsTest :: Text -> Assertions a -> Test

-- | Run an <a>Assertion</a>. If the assertion fails, the test will
--   immediately fail.
--   
--   <a>assert</a> is a Template Haskell macro, to retain the source-file
--   location from which it was used. Its effective type is:
--   
--   <pre>
--   $assert :: <a>IsAssertion</a> assertion =&gt; assertion -&gt; <a>Assertions</a> ()
--   </pre>
assert :: Q Exp

-- | Run an <a>Assertion</a>. If the assertion fails, the test will
--   continue to run until it finishes (or until an <a>assert</a> fails).
--   
--   <a>expect</a> is a Template Haskell macro, to retain the source-file
--   location from which it was used. Its effective type is:
--   
--   <pre>
--   $expect :: <a>IsAssertion</a> assertion =&gt; assertion -&gt; <a>Assertions</a> ()
--   </pre>
expect :: Q Exp

-- | Cause a test to immediately fail, with a message.
--   
--   <a>die</a> is a Template Haskell macro, to retain the source-file
--   location from which it was used. Its effective type is:
--   
--   <pre>
--   $die :: <a>String</a> -&gt; <a>Assertions</a> a
--   </pre>
--   
--   Since: 0.2.4
die :: Q Exp

-- | Print a message from within a test. This is just a helper for
--   debugging, so you don't have to import <tt>Debug.Trace</tt>.
trace :: Text -> Assertions ()

-- | Attach metadata to a test run. This will be included in reports.
note :: Text -> Text -> Assertions ()

-- | Register an IO action to be run after the test completes. This action
--   will run even if the test failed or threw an exception.
--   
--   Since: 0.2.3
afterTest :: IO () -> Assertions ()

-- | Require an <a>Either</a> value to be <a>Left</a>, and return its
--   contents. If the value is <a>Right</a>, fail the test.
--   
--   <a>requireLeft</a> is a Template Haskell macro, to retain the
--   source-file location from which it was used. Its effective type is:
--   
--   <pre>
--   $requireLeft :: <a>Show</a> b =&gt; <a>Either</a> a b -&gt; <a>Assertions</a> a
--   </pre>
--   
--   Since: 0.2.4
requireLeft :: Q Exp

-- | Require an <a>Either</a> value to be <a>Right</a>, and return its
--   contents. If the value is <a>Left</a>, fail the test.
--   
--   <a>requireRight</a> is a Template Haskell macro, to retain the
--   source-file location from which it was used. Its effective type is:
--   
--   <pre>
--   $requireRight :: <a>Show</a> a =&gt; <a>Either</a> a b -&gt; <a>Assertions</a> b
--   </pre>
--   
--   Since: 0.2.4
requireRight :: Q Exp

-- | Assert that two values are equal.
equal :: (Show a, Eq a) => a -> a -> Assertion

-- | Assert that two values are not equal.
notEqual :: (Eq a, Show a) => a -> a -> Assertion

-- | Assert that two values are within some delta of each other.
equalWithin :: (Real a, Show a) => a -> a -> a -> Assertion

-- | Assert that some value is <tt>Just</tt>.
just :: Maybe a -> Assertion

-- | Assert that some value is <tt>Nothing</tt>.
nothing :: Maybe a -> Assertion

-- | Assert that some value is <tt>Left</tt>.
left :: Either a b -> Assertion

-- | Assert that some value is <tt>Right</tt>.
right :: Either a b -> Assertion

-- | Assert that some computation throws an exception matching the provided
--   predicate. This is mostly useful for exception types which do not have
--   an instance for <tt>Eq</tt>, such as <tt><a>ErrorCall</a></tt>.
throws :: Exception err => (err -> Bool) -> IO a -> Assertion

-- | Assert that some computation throws an exception equal to the given
--   exception. This is better than just checking that the correct type was
--   thrown, because the test can also verify the exception contains the
--   correct information.
throwsEq :: (Eq err, Exception err, Show err) => err -> IO a -> Assertion

-- | Assert a value is greater than another.
greater :: (Ord a, Show a) => a -> a -> Assertion

-- | Assert a value is greater than or equal to another.
greaterEqual :: (Ord a, Show a) => a -> a -> Assertion

-- | Assert a value is less than another.
lesser :: (Ord a, Show a) => a -> a -> Assertion

-- | Assert a value is less than or equal to another.
lesserEqual :: (Ord a, Show a) => a -> a -> Assertion

-- | Assert that two containers have the same items, in any order.
sameItems :: (Foldable container, Show item, Ord item) => container item -> container item -> Assertion

-- | Assert that two containers have the same items, in the same order.
equalItems :: (Foldable container, Show item, Ord item) => container item -> container item -> Assertion

-- | Class for types which can be treated as text.
class IsText a

-- | Assert that two pieces of text are equal. This uses a diff algorithm
--   to check line-by-line, so the error message will be easier to read on
--   large inputs.
equalLines :: (Ord a, IsText a) => a -> a -> Assertion
data Test
Test :: Text -> (TestOptions -> IO TestResult) -> Test

-- | <pre>
--   testName (Test name _) = name
--   </pre>
testName :: Test -> Text

-- | Run a test, wrapped in error handlers. This will return
--   <a>TestAborted</a> if the test throws an exception or times out.
runTest :: Test -> TestOptions -> IO TestResult
data TestOptions

-- | Default test options.
--   
--   <pre>
--   <a>testOptionSeed</a> defaultTestOptions = 0
--   <a>testOptionTimeout</a> defaultTestOptions = Nothing
--   </pre>
--   
--   Since: 0.2.3
defaultTestOptions :: TestOptions

-- | Get the RNG seed for this test run. The seed is generated once, in
--   <tt>defaultMain</tt>, and used for all tests. It is also logged to
--   reports using a note.
--   
--   When using <tt>defaultMain</tt>, users may specify a seed using the
--   <tt>--seed</tt> command-line option.
testOptionSeed :: TestOptions -> Int

-- | An optional timeout, in millseconds. Tests which run longer than this
--   timeout will be aborted.
--   
--   When using <tt>defaultMain</tt>, users may specify a timeout using the
--   <tt>--timeout</tt> command-line option.
testOptionTimeout :: TestOptions -> Maybe Int
data TestResult
TestPassed :: [(Text, Text)] -> TestResult
TestSkipped :: TestResult
TestFailed :: [(Text, Text)] -> [Failure] -> TestResult
TestAborted :: [(Text, Text)] -> Text -> TestResult
data Failure
Failure :: (Maybe Location) -> Text -> Failure
data Location
Location :: Text -> Text -> Integer -> Location
locationFile :: Location -> Text
locationModule :: Location -> Text
locationLine :: Location -> Integer

-- | Deprecated in 0.2.4: use <a>die</a> instead.
fail :: Q Exp
instance IsText ByteString
instance IsText ByteString
instance IsText Text
instance IsText Text
instance IsText String
instance MonadIO Assertions
instance Monad Assertions
instance Applicative Assertions
instance Functor Assertions
instance IsAssertion Bool
instance IsAssertion Assertion