Execute the tests specified in a TLT monad, and report the results as text output.

When using TLT from some other package (as opposed to using TLT itself as your test framework, and wishing to see its human-oriented output directly), consider using runTLT instead.

Monad transformer for TLT tests. This layer stores the results from tests as they are executed.

Extending TLT operations across other monad transformers. For easiest and most flexible testing, declare the monad transformers of your application as instances of this class.

This function controls whether tlt will report only tests which fail, suppressing any display of tests which pass, or else report the results of all tests. The default is the former: the idea is that no news should be good news, with the programmer bothered only with problems which need fixing.

This function controls whether the main tlt executable should exit after displaying test results which include at least one failing test. By default, it will exit in this situation. The idea is that a test suite can be broken into parts when it makes sense to run the latter parts only when the former parts all pass.

Label and perform a test of an Assertion.

Example

test :: Monad m => TLT m ()
test = do
  "2 is 2 as result" ~: 2 @== return 2    -- This test passes.
  "2 not 3" ~: 2 @/=- 3                   -- This test fails.

Label and perform a test of a boolean value returned by a computation in the wrapped monad m.

Example

test :: Monad m => TLT m ()
test = do
  "True passes" ~::- True               -- This test passes.
  "2 is 2 as single Bool" ~::- 2 == 2   -- This test passes.
  "2 is 3!?" ~::- 2 == 2                -- This test fails.

Label and perform a test of a (pure) boolean value.

Example

test :: Monad m => TLT m ()
test = do
  "True passes" ~::- return True                 -- This test passes.
  "2 is 2 as single Bool" ~::- return (2 == 2)   -- This test passes.
  "2 is 3!?" ~::- myFn 4 "Hammer"                -- Passes if myFn (which
                                                 -- must be monadic)
                                                 -- returns True.

Report a failure. Useful in pattern-matching cases which are entirely not expected.

Organize the tests in the given subcomputation as a separate group within the test results we will report.

An assertion is a computation (typically in the monad wrapped by TLT) which returns a list of zero of more reasons for the failure of the assertion. A successful computation returns an empty list: no reasons for failure, hence success.

Assert that two values are equal. This assertion takes an expected and an actual value; see (@==) to compare the result of a monadic computation to an expected value.

Examples

test :: Monad m => TLT m ()
test = do
  "Make sure that 2 is still equal to itself" ~: 2 @==- 2
  "Make sure that there are four lights" ~: 4 @==- length lights

Assert that two values are not equal. This assertion takes an expected and an actual value; see (@/=) to compare the result of a monadic computation to an expected value.

Assert that a given boundary is strictly less than some value. This assertion takes an expected and an actual value; see (@<) to compare the result of a monadic computation to an expected value.

Assert that a given boundary is strictly less than some value. This assertion takes an expected and an actual value; see (@>) to compare the result of a monadic computation to an expected value.

Assert that a given boundary is strictly less than some value. This assertion takes an expected and an actual value; see (@<=) to compare the result of a monadic computation to an expected value.

Assert that a given boundary is strictly less than some value. This assertion takes an expected and an actual value; see (@>=) to compare the result of a monadic computation to an expected value.

Assert that a calculated value is as expected. This assertion compare the result of a monadic computation to an expected value; see (@==-) to compare an actual value to the expected value.

Examples

test :: Monad m => TLT m ()
test = do
  "Make sure that 2 is still equal to itself" ~: 2 @== return 2
  "Make sure that there are four lights" ~: 4 @== countLights
                                            -- where countLights :: m Int

Assert that a calculated value differs from some known value. This assertion compares the result of a monadic computation to an expected value; see (@/=-) to compare an actual value to the expected value.

Assert that a given, constant boundary is strictly less than some calculated value. This assertion compares the result of a /monadic computation/ to an expected value; see (@<-) to compare an actual value to the expected value.

Assert that a given, constant boundary is strictly less than some calculated value. This assertion compares the result of a /monadic computation/ to an expected value; see (@>-) to compare an actual value to the expected value.

Assert that a given, constant boundary is strictly less than some calculated value. This assertion compares the result of a /monadic computation/ to an expected value; see (@<=-) to compare an actual value to the expected value.

Assert that a given, constant boundary is strictly less than some calculated value. This assertion compares the result of a /monadic computation/ to an expected value; see (@>=-) to compare an actual value to the expected value.

Assert that a traversable structure (such as a list) returned from a computation is empty.

Assert that a traversable structure (such as a list) returned from a computation is non-empty.

Assert that a pure traversable structure (such as a list) is empty.

Assert that a pure traversable structure (such as a list) is nonempty.

Assert that a Maybe result of a computation is Nothing.

Assert that a Maybe value is Nothing.

This assertion always fails with the given message.

This assertion always succeeds.

Transform a unary function on a value (plus a generator of a failure message) into a unary function returning an Assertion for a pure given actual value.

Example

The TLT assertion emptyP (defined in Standard) is built from the Traversable predicate null

emptyP :: (Monad m, Traversable t) => t a -> Assertion m
emptyP = liftAssertionPure null
           (\ _ -> "Expected empty structure but got non-empty")

Given an Assertion for a pure (actual) value, lift it to an Assertion expecting the value to be returned from a computation.

Example

The TLT assertion empty (defined in Standard) on monadic computations returning lists is defined in terms of the corresponging assertion on pure list-valued expressions.

empty :: (Monad m, Traversable t) => m (t a) -> Assertion m
empty = assertionPtoM emptyP

Transform a unary function on an actual value (plus a generator of a failure message) into an Assertion where the value is to be returned from a subcomputation.

Transform a binary function on an expected and an actual value (plus a binary generator of a failure message) into an Assertion for a pure given actual value.

Example

TLT's scalar-testing operators like @==- are defined with this function:

(@==-) :: (Monad m, Eq a, Show a) => a -> a -> Assertion m
(@==-) = liftAssertion2Pure (==) $
  \ exp actual -> "Expected " ++ show exp ++ " but got " ++ show actual

The (==) operator tests equality, and the result here allows the assertion that a value should be exactly equal to a target. The second argument formats the detail reported when the assertion fails.

Given an Assertion for two pure values (expected and actual), lift it to an Assertion expecting the actual value to be returned from a computation.

Examples

The TLT assertion `Test.TLT.(==)` lifts `Test.TLT.(==-)` (both defined in Standard) from expecting a pure actual result to expecting a computation returning a value to test.

(@==) :: (Monad m, Eq a, Show a) => a -> m a -> Assertion m
(@==) = assertion2PtoM (@==-)

Transform a binary function on expected and actual values (plus a generator of a failure message) into an Assertion where the actual value is to be returned from a subcomputation.

Enabling TLT checking of the completion of computations with- or without uncaught exceptions in a (possibly embedded) ExceptT or Except monad.

In general, it is more difficult to automatically deduce MonadTLTExcept instances than MonadTLT because runToExcept instances bodies will frequently require additional parameters to functions such as runReaderT, or values corresponding to Nothing, which are specific to a particular scenario.

Note that using MonadTLTExcept imposes the restriction that the TLT transformer layer must be wrapped within the ExceptT transformer layer.

Ensure that a computation in ExceptT completes without an uncaught exception.

Ensure that a computation in ExceptT completes without an uncaught exception.

Ensure that a computation in ExceptT does throw an uncaught exception.

Ensure that a computation in ExceptT does throw an uncaught exception, allowing further testing of the exception.