libghc-chell-doc 0.4.0.1-6 / usr / share / doc / libghc-chell-doc / html / chell.txt

-- 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 TemplateHaskell #-}
--   
--   import Test.Chell
--   
--   tests_Math :: Suite
--   tests_Math = suite "math"
--       [ test_Addition
--       , test_Subtraction
--       ]
--   
--   test_Addition :: Test
--   test_Addition = assertions "addition" $ do
--       $expect (equal (2 + 1) 3)
--       $expect (equal (1 + 2) 3)
--   
--   test_Subtraction :: Test
--   test_Subtraction = assertions "subtraction" $ do
--       $expect (equal (2 - 1) 1)
--       $expect (equal (1 - 2) (-1))
--   
--   main :: IO ()
--   main = defaultMain [tests_Math]
--   </pre>
--   
--   <pre>
--   $ ghc --make chell-example.hs
--   $ ./chell-example
--   PASS: 2 tests run, 2 tests passed
--   </pre>
@package chell
@version 0.4.0.1


-- | 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 TemplateHaskell #-}
--   
--   import Test.Chell
--   
--   suite_Math :: Suite
--   suite_Math = <a>suite</a> "math"
--       [ test_Addition
--       , test_Subtraction
--       ]
--   
--   test_Addition :: Test
--   test_Addition = <a>assertions</a> "addition" $ do
--       $<a>expect</a> (<a>equal</a> (2 + 1) 3)
--       $<a>expect</a> (<a>equal</a> (1 + 2) 3)
--   
--   test_Subtraction :: Test
--   test_Subtraction = <a>assertions</a> "subtraction" $ do
--       $<a>expect</a> (<a>equal</a> (2 - 1) 1)
--       $<a>expect</a> (<a>equal</a> (1 - 2) (-1))
--   
--   main :: IO ()
--   main = <a>defaultMain</a> [suite_Math]
--    
--   </pre>
--   
--   <pre>
--   $ ghc --make chell-example.hs
--   $ ./chell-example
--   PASS: 2 tests run, 2 tests passed
--   </pre>
module Test.Chell

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

-- | A suite is a named collection of tests.
--   
--   Note: earlier versions of Chell permitted arbitrary nesting of test
--   suites. This feature proved too unwieldy, and was removed. A similar
--   result can be achieved with <a>suiteTests</a>; see the documentation
--   for <a>suite</a>.
data Suite

-- | Define a new <a>Suite</a>, with the given name and children.
--   
--   Note: earlier versions of Chell permitted arbitrary nesting of test
--   suites. This feature proved too unwieldy, and was removed. A similar
--   result can be achieved with <a>suiteTests</a>:
--   
--   <pre>
--   test_Addition :: Test
--   test_Subtraction :: Test
--   test_Show :: Test
--   
--   suite_Math :: Suite
--   suite_Math = <a>suite</a> "math"
--       [ test_Addition
--       , test_Subtraction
--       ]
--   
--   suite_Prelude :: Suite
--   suite_Prelude = <a>suite</a> "prelude"
--       (
--         [ test_Show
--         ]
--         ++ suiteTests suite_Math
--       )
--    
--   </pre>
suite :: String -> [Test] -> Suite

-- | Get a suite's name. Suite names may be any string, but are typically
--   plain ASCII so users can easily type them on the command line.
--   
--   <pre>
--   $ ghci chell-example.hs
--   Ok, modules loaded: Main.
--   
--   *Main&gt; suiteName tests_Math
--   "math"
--   </pre>
suiteName :: Suite -> String

-- | Get the full list of tests contained within this <a>Suite</a>. Each
--   test is given its full name within the test hierarchy, where names are
--   separated by periods.
--   
--   <pre>
--   $ ghci chell-example.hs
--   Ok, modules loaded: Main.
--   
--   *Main&gt; suiteTests tests_Math
--   [Test "math.addition",Test "math.subtraction"]
--   </pre>
suiteTests :: Suite -> [Test]
class SuiteOrTest a

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

-- | Conditionally skip tests, depending on the result of a runtime check.
--   The predicate is checked before each test is started.
--   
--   <pre>
--   tests :: Suite
--   tests = <a>suite</a> "tests"
--       [ test_Foo
--       , <a>skipWhen</a> noNetwork test_PingGoogle
--       , test_Bar
--       ]
--    
--   </pre>
skipWhen :: SuiteOrTest a => IO Bool -> a -> a

-- | See <a>assertions</a>.
data Assertions a

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

-- | See <a>assert</a> and <a>expect</a>.
class IsAssertion a

-- | A single pass/fail assertion. Failed assertions include an explanatory
--   message.
data Assertion

-- | See <a>Assertion</a>.
assertionPassed :: Assertion

-- | See <a>Assertion</a>.
assertionFailed :: String -> Assertion
assert :: Q Exp
expect :: Q Exp
die :: Q Exp
trace :: Q Exp

-- | Attach a note to a test run. Notes will be printed to stdout and
--   included in reports, even if the test fails or aborts. Notes are
--   useful for debugging failing tests.
note :: String -> String -> Assertions ()

-- | Register an IO action to be run after the test completes. This action
--   will run even if the test failed or aborted.
afterTest :: IO () -> Assertions ()
requireLeft :: Q Exp
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 :: Show a => Maybe a -> Assertion

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

-- | Assert that some value is <tt>Right</tt>.
right :: Show a => 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 -> IO 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 -> IO 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; see <a>equalLines</a>.
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

-- | Variant of <a>equalLines</a> which allows a user-specified
--   line-splitting predicate.
equalLinesWith :: Ord a => (a -> [String]) -> a -> a -> Assertion

-- | A <a>Test</a> is, essentially, an IO action that returns a
--   <a>TestResult</a>. Tests are aggregated into suites (see
--   <a>Suite</a>).
data Test

-- | Define a test, with the given name and implementation.
test :: String -> (TestOptions -> IO TestResult) -> Test

-- | Get the name a test was given when it was defined; see <a>test</a>.
testName :: Test -> String

-- | 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

-- | The result of running a test.
--   
--   To support future extensions to the testing API, any users of this
--   module who pattern-match against the <a>TestResult</a> constructors
--   should include a default case. If no default case is provided, a
--   warning will be issued.
data TestResult

-- | The test passed, and generated the given notes.
TestPassed :: [(String, String)] -> TestResult

-- | The test did not run, because it was skipped with <a>skipIf</a> or
--   <a>skipWhen</a>.
TestSkipped :: TestResult

-- | The test failed, generating the given notes and failures.
TestFailed :: [(String, String)] -> [Failure] -> TestResult

-- | The test aborted with an error message, and generated the given notes.
TestAborted :: [(String, String)] -> String -> TestResult

-- | Contains details about a test failure.
data Failure

-- | An empty <a>Failure</a>; use the field accessors to populate this
--   value.
failure :: Failure

-- | If given, the location of the failing assertion, expectation, etc.
--   
--   <a>failureLocation</a> is a field accessor, and can be used to update
--   a <a>Failure</a> value.
failureLocation :: Failure -> Maybe Location

-- | If given, a message which explains why the test failed.
--   
--   <a>failureMessage</a> is a field accessor, and can be used to update a
--   <a>Failure</a> value.
failureMessage :: Failure -> String

-- | Contains details about a location in the test source file.
data Location

-- | An empty <a>Location</a>; use the field accessors to populate this
--   value.
location :: Location

-- | A path to a source file, or empty if not provided.
--   
--   <a>locationFile</a> is a field accessor, and can be used to update a
--   <a>Location</a> value.
locationFile :: Location -> String

-- | A Haskell module name, or empty if not provided.
--   
--   <a>locationModule</a> is a field accessor, and can be used to update a
--   <a>Location</a> value.
locationModule :: Location -> String

-- | A line number, or Nothing if not provided.
--   
--   <a>locationLine</a> is a field accessor, and can be used to update a
--   <a>Location</a> value.
locationLine :: Location -> Maybe Integer

-- | Test options are passed to each test, and control details about how
--   the test should be run.
data TestOptions

-- | Default test options.
--   
--   <pre>
--   $ ghci
--   Prelude&gt; import Test.Chell
--   
--   Test.Chell&gt; testOptionSeed defaultTestOptions
--   0
--   
--   Test.Chell&gt; testOptionTimeout defaultTestOptions
--   Nothing
--   </pre>
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.
--   
--   <a>testOptionSeed</a> is a field accessor, and can be used to update a
--   <a>TestOptions</a> value.
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.
--   
--   <a>testOptionTimeout</a> is a field accessor, and can be used to
--   update a <a>TestOptions</a> value.
testOptionTimeout :: TestOptions -> Maybe Int
instance GHC.Show.Show Test.Chell.Assertion
instance GHC.Classes.Eq Test.Chell.Assertion
instance Test.Chell.IsAssertion Test.Chell.Assertion
instance Test.Chell.IsAssertion GHC.Types.Bool
instance Test.Chell.IsAssertion a => Test.Chell.IsAssertion (GHC.Types.IO a)
instance GHC.Base.Functor Test.Chell.Assertions
instance GHC.Base.Applicative Test.Chell.Assertions
instance GHC.Base.Monad Test.Chell.Assertions
instance Control.Monad.IO.Class.MonadIO Test.Chell.Assertions
instance Test.Chell.IsText GHC.Base.String
instance Test.Chell.IsText Data.Text.Internal.Text
instance Test.Chell.IsText Data.Text.Internal.Lazy.Text
instance Test.Chell.IsText Data.ByteString.Internal.ByteString
instance Test.Chell.IsText Data.ByteString.Lazy.Internal.ByteString