-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Testing in monads and transformers without explicit specs
--
-- A quick-and-dirty unit test system without test specifications,
-- motivated by easy examination of intermediate results of computations
-- in monad transformers. See the GitHub repository
-- https://github.com/jphmrst/TLT/ for documentation, or the
-- Haddock page for additional examples.
@package TLT
@version 0.4.0.0
-- | Options representation for the TLT testing system. See
-- TLT for more information.
module Test.TLT.Options
-- | Record of options which may be specified for running and reporting TLT
-- tests.
data TLTopts
TLTopts :: Bool -> Bool -> TLTopts
[optShowPasses] :: TLTopts -> Bool
[optQuitAfterFailReport] :: TLTopts -> Bool
-- | Default initial options.
defaultOpts :: TLTopts
-- | Update the display of showing passes in a TLTopts record.
withShowPasses :: TLTopts -> Bool -> TLTopts
-- | Update the display of showing passes in a TLTopts record.
withExitAfterFail :: TLTopts -> Bool -> TLTopts
-- | Results representation for the TLT testing system. See
-- TLT for more information.
module Test.TLT.Results
-- | Reasons why a test might fail.
data TestFail
-- | A failure arising from an Assertion which is not met.
Asserted :: String -> TestFail
-- | A failure associated with a call to a Haskell function triggering an
-- error.
Erred :: String -> TestFail
-- | Default conversion of a TestFail to a descriptive string.
formatFail :: TestFail -> String
-- | Hierarchical structure holding the result of running tests, possibly
-- grouped into tests.
data TestResult
Test :: String -> [TestFail] -> TestResult
-- | The Ints are respectively the total number of tests executed,
-- and total number of failures detected.
Group :: String -> Int -> Int -> [TestResult] -> TestResult
-- | Return the number of failed tests reported in a TestResult.
failCount :: TestResult -> Int
-- | Return the number of tests described by a TestResult.
testCount :: TestResult -> Int
-- | Return the number of failed tests described in a list of
-- TestResults.
totalFailCount :: [TestResult] -> Int
-- | Return the number of tests described in a list of TestResults.
totalTestCount :: [TestResult] -> Int
-- | Buffer for accumulating test results in the TLT testing
-- system. See TLT for more information.
module Test.TLT.Buffer
-- | Accumulator for test results, in the style of a simplified Huet's
-- zipper which only ever adds to the end of the structure.
data TRBuf
Buf :: TRBuf -> Int -> Int -> String -> [TestResult] -> TRBuf
Top :: Int -> Int -> [TestResult] -> TRBuf
-- | Add a single test result to a TRBuf.
addResult :: TRBuf -> TestResult -> TRBuf
-- | Convert the topmost group of a bottom-up TRBuf into a completed
-- top-down report about the group.
currentGroup :: TRBuf -> TestResult
-- | Derive a new TRBuf corresponding to finishing the current group
-- and continuing to accumulate results into its enclosure.
popGroup :: TRBuf -> TRBuf
-- | Convert a TRBuf into a list of top-down TestResults.
closeTRBuf :: TRBuf -> [TestResult]
-- | Main state and monad definitions for the TLT testing system.
-- See TLT for more information.
module Test.TLT.Class
-- | Synonym for the elements of the TLT state.
type TLTstate = (TLTopts, TRBuf)
-- | Monad transformer for TLT tests. This layer stores the results from
-- tests as they are executed.
newtype TLT (m :: * -> *) r
TLT :: StateT TLTstate m r -> TLT (m :: * -> *) r
[unwrap] :: TLT (m :: * -> *) r -> StateT TLTstate m r
-- | 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.
class (Monad m, Monad n) => MonadTLT m n | m -> n
-- | Lift TLT operations within a monad transformer stack. Note that with
-- enough transformer types included in this class, the liftTLT
-- function should usually be unnecessary: the commands in this module
-- which actually configure testing, or specify a test, already
-- liftTLT their own result. So they will all act as top-level
-- transformers in MonadTLT.
liftTLT :: MonadTLT m n => TLT n a -> m a
-- | 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.
class (MonadTLT m nt, Monad m, MonadTLT ne nt) => MonadTLTExcept m e nt ne | m -> e, m -> ne
liftTLTExcept :: MonadTLTExcept m e nt ne => ExceptT e ne a -> m a
runToExcept :: MonadTLTExcept m e nt ne => m a -> ExceptT e ne a
-- | Execute the tests specified in a TLT monad without output
-- side-effects, returning the final options and result reports.
--
-- This function is primarily useful when calling TLT from some other
-- package. If you are using TLT itself as your test framework, and
-- wishing to see its human-oriented output directly, consider using
-- tlt instead.
runTLT :: Monad m => TLT m r -> m (TLTopts, [TestResult])
-- | 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.
reportAllTestResults :: MonadTLT m n => Bool -> m ()
-- | 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.
setExitAfterFailDisplay :: MonadTLT m n => Bool -> m ()
-- | Report a failure. Useful in pattern-matching cases which are entirely
-- not expected.
tltFail :: MonadTLT m n => String -> String -> m ()
-- | Report a success. Useful in default cases.
tltPass :: MonadTLT m n => String -> m ()
-- | Organize the tests in the given subcomputation as a separate group
-- within the test results we will report.
inGroup :: MonadTLT m n => String -> m a -> m a
-- | Ensure that a computation in ExceptT completes without an
-- uncaught exception.
noUncaught :: MonadTLTExcept m e nt ne => String -> m a -> m ()
-- | Ensure that a computation in ExceptT does throw an uncaught
-- exception, allowing further testing of the exception.
uncaughtWith :: MonadTLTExcept m e nt ne => String -> m a -> (e -> ExceptT e ne ()) -> m ()
-- | Ensure that a computation in ExceptT does throw an uncaught
-- exception.
uncaught :: forall {m} {e} {nt :: Type -> Type} {ne :: Type -> Type} {a}. MonadTLTExcept m e nt ne => String -> m a -> m ()
instance Control.Monad.Trans.Class.MonadTrans Test.TLT.Class.TLT
instance GHC.Base.Monad m => GHC.Base.Monad (Test.TLT.Class.TLT m)
instance GHC.Base.Monad m => GHC.Base.Applicative (Test.TLT.Class.TLT m)
instance GHC.Base.Functor m => GHC.Base.Functor (Test.TLT.Class.TLT m)
instance Test.TLT.Class.MonadTLT m nt => Test.TLT.Class.MonadTLTExcept (Control.Monad.Trans.Except.ExceptT e m) e nt m
instance Test.TLT.Class.MonadTLTExcept m e nt ne => Test.TLT.Class.MonadTLTExcept (Control.Monad.Trans.Identity.IdentityT m) e nt ne
instance (Test.TLT.Class.MonadTLTExcept m e nt ne, GHC.Base.Monoid w) => Test.TLT.Class.MonadTLTExcept (Control.Monad.Trans.Writer.Lazy.WriterT w m) e nt ne
instance (Test.TLT.Class.MonadTLTExcept m e nt ne, GHC.Base.Monoid w) => Test.TLT.Class.MonadTLTExcept (Control.Monad.Trans.Writer.Strict.WriterT w m) e nt ne
instance GHC.Base.Monad m => Test.TLT.Class.MonadTLT (Test.TLT.Class.TLT m) m
instance (Test.TLT.Class.MonadTLT m n, GHC.Base.Functor f) => Test.TLT.Class.MonadTLT (Control.Monad.Trans.Free.FreeT f m) n
instance Test.TLT.Class.MonadTLT m n => Test.TLT.Class.MonadTLT (Control.Monad.Trans.Identity.IdentityT m) n
instance Test.TLT.Class.MonadTLT m n => Test.TLT.Class.MonadTLT (Control.Monad.Trans.Maybe.MaybeT m) n
instance Test.TLT.Class.MonadTLT m n => Test.TLT.Class.MonadTLT (Control.Monad.Trans.Reader.ReaderT r m) n
instance Test.TLT.Class.MonadTLT m n => Test.TLT.Class.MonadTLT (Control.Monad.Trans.Resource.Internal.ResourceT m) n
instance Test.TLT.Class.MonadTLT m n => Test.TLT.Class.MonadTLT (Control.Monad.Trans.State.Strict.StateT s m) n
instance Test.TLT.Class.MonadTLT m n => Test.TLT.Class.MonadTLT (Control.Monad.Trans.Except.ExceptT e m) n
instance Test.TLT.Class.MonadTLT m n => Test.TLT.Class.MonadTLT (Control.Monad.Trans.State.Lazy.StateT s m) n
instance Test.TLT.Class.MonadTLT m n => Test.TLT.Class.MonadTLT (Control.Monad.ST.Trans.Internal.STT s m) n
instance (Test.TLT.Class.MonadTLT m n, GHC.Base.Monoid w) => Test.TLT.Class.MonadTLT (Control.Monad.Trans.Writer.Lazy.WriterT w m) n
instance (Test.TLT.Class.MonadTLT m n, GHC.Base.Monoid w) => Test.TLT.Class.MonadTLT (Control.Monad.Trans.Writer.Strict.WriterT w m) n
-- | Default results reporting for the TLT testing system. See
-- TLT for more information.
module Test.TLT.Report
-- | 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.
tlt :: MonadIO m => TLT m r -> m ()
-- | Report the results of tests.
report :: TLTopts -> [TestResult] -> IO ()
-- | Command to set an ANSI terminal to boldface black.
boldBlack :: IO ()
-- | Command to set an ANSI terminal to boldface red.
boldRed :: IO ()
-- | Command to set an ANSI terminal to boldface green.
boldGreen :: IO ()
-- | Command to set an ANSI terminal to medium-weight red.
mediumRed :: IO ()
-- | Command to set an ANSI terminal to medium-weight green.
mediumGreen :: IO ()
-- | Command to set an ANSI terminal to medium-weight blue.
mediumBlue :: IO ()
-- | Command to set an ANSI terminal to medium-weight black.
mediumBlack :: IO ()
-- | Command to set an ANSI terminal to the standard TLT weight and color
-- for a passing test.
greenPass :: IO ()
-- | Command to set an ANSI terminal to the standard TLT weight and color
-- for a failing test.
redFail :: IO ()
-- | Assertion infrastructure for the TLT testing system. See
-- TLT for more information.
module Test.TLT.Assertion
-- | 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.
type Assertion m = m [TestFail]
-- | This assertion always fails with the given message.
assertFailed :: Monad m => String -> Assertion m
-- | This assertion always succeeds.
assertSuccess :: Monad m => Assertion m
-- | 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.
--
(~:) :: MonadTLT m n => String -> Assertion m -> m ()
infix 0 ~:
-- | 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.
--
(~::-) :: MonadTLT m n => String -> Bool -> m ()
infix 0 ~::-
-- | 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.
--
(~::) :: MonadTLT m n => String -> m Bool -> m ()
infix 0 ~::
-- | 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.
liftAssertion2Pure :: Monad m => (a -> a -> Bool) -> (a -> a -> String) -> a -> a -> Assertion m
-- | 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 (@==-)
--
assertion2PtoM :: Monad m => (a -> a -> Assertion m) -> a -> m a -> Assertion m
-- | 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.
liftAssertion2M :: Monad m => (a -> a -> Bool) -> (a -> a -> String) -> a -> m a -> Assertion m
-- | 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")
--
liftAssertionPure :: Monad m => (a -> Bool) -> (a -> String) -> a -> Assertion m
-- | 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
--
assertionPtoM :: Monad m => (a -> Assertion m) -> m a -> Assertion m
-- | 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.
liftAssertionM :: Monad m => (a -> Bool) -> (a -> String) -> m a -> Assertion m
-- | Standard assertion vocabulary for the TLT testing system. See
-- TLT for more information.
module Test.TLT.Standard
-- | 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
--
(@==-) :: (Monad m, Eq a, Show a) => a -> a -> Assertion m
infix 1 @==-
-- | 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
--
(@==) :: (Monad m, Eq a, Show a) => a -> m a -> Assertion m
infix 1 @==
-- | 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.
(@/=-) :: (Monad m, Eq a, Show a) => a -> a -> Assertion m
infix 1 @/=-
-- | 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.
(@/=) :: (Monad m, Eq a, Show a) => a -> m a -> Assertion m
infix 1 @/=
-- | 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.
(@<-) :: (Monad m, Ord a, Show a) => a -> a -> Assertion m
infix 1 @<-
-- | 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.
(@<) :: (Monad m, Ord a, Show a) => a -> m a -> Assertion m
infix 1 @<
-- | 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.
(@>-) :: (Monad m, Ord a, Show a) => a -> a -> Assertion m
infix 1 @>-
-- | 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.
(@>) :: (Monad m, Ord a, Show a) => a -> m a -> Assertion m
infix 1 @>
-- | 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.
(@<=-) :: (Monad m, Ord a, Show a) => a -> a -> Assertion m
infix 1 @<=-
-- | 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.
(@<=) :: (Monad m, Ord a, Show a) => a -> m a -> Assertion m
infix 1 @<=
-- | 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.
(@>=-) :: (Monad m, Ord a, Show a) => a -> a -> Assertion m
infix 1 @>=-
-- | 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.
(@>=) :: (Monad m, Ord a, Show a) => a -> m a -> Assertion m
infix 1 @>=
-- | Assert that a pure traversable structure (such as a list) is empty.
emptyP :: (Monad m, Traversable t) => t a -> Assertion m
-- | Assert that a traversable structure (such as a list) returned from a
-- computation is empty.
empty :: (Monad m, Traversable t) => m (t a) -> Assertion m
-- | Assert that a pure traversable structure (such as a list) is nonempty.
nonemptyP :: (Monad m, Traversable t) => t a -> Assertion m
-- | Assert that a traversable structure (such as a list) returned from a
-- computation is non-empty.
nonempty :: (Monad m, Traversable t) => m (t a) -> Assertion m
-- | Assert that a Maybe value is Nothing.
nothingP :: Monad m => Maybe a -> Assertion m
-- | Assert that a Maybe result of a computation is Nothing.
nothing :: Monad m => m (Maybe a) -> Assertion m
-- | TLT is a small unit test system oriented towards examining
-- intermediate results of computations in monad transformers. It is
-- intended to be lightweight for the programmer, and does not require
-- tests to be specified in some sort of formal list of tests. Rather,
-- tests are simply commands in a monad stack which includes the
-- transformer layer Test.TLT.
--
-- This module is a re-exporter for the various Test.TLT.*
-- modules which define distinct portions of the TLT system. These
-- exports are oriented towards the simple use of TLT as a test
-- framework. When using TLT more programmatically, such as when
-- integrating TLT into another test framework, it may be necessary to
-- import the more internally-oriented functions of the individual
-- modules.
module Test.TLT
-- | 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.
tlt :: MonadIO m => TLT m r -> m ()
-- | Monad transformer for TLT tests. This layer stores the results from
-- tests as they are executed.
data TLT (m :: * -> *) r
-- | 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.
class (Monad m, Monad n) => MonadTLT m n | m -> n
-- | Lift TLT operations within a monad transformer stack. Note that with
-- enough transformer types included in this class, the liftTLT
-- function should usually be unnecessary: the commands in this module
-- which actually configure testing, or specify a test, already
-- liftTLT their own result. So they will all act as top-level
-- transformers in MonadTLT.
liftTLT :: MonadTLT m n => TLT n a -> m a
-- | 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.
reportAllTestResults :: MonadTLT m n => Bool -> m ()
-- | 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.
setExitAfterFailDisplay :: MonadTLT m n => Bool -> m ()
-- | 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.
--
(~:) :: MonadTLT m n => String -> Assertion m -> m ()
infix 0 ~:
-- | 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.
--
(~::) :: MonadTLT m n => String -> m Bool -> m ()
infix 0 ~::
-- | 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.
--
(~::-) :: MonadTLT m n => String -> Bool -> m ()
infix 0 ~::-
-- | Report a failure. Useful in pattern-matching cases which are entirely
-- not expected.
tltFail :: MonadTLT m n => String -> String -> m ()
-- | Organize the tests in the given subcomputation as a separate group
-- within the test results we will report.
inGroup :: MonadTLT m n => String -> m a -> m a
-- | 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.
type Assertion m = m [TestFail]
-- | 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
--
(@==-) :: (Monad m, Eq a, Show a) => a -> a -> Assertion m
infix 1 @==-
-- | 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.
(@/=-) :: (Monad m, Eq a, Show a) => a -> a -> Assertion m
infix 1 @/=-
-- | 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.
(@<-) :: (Monad m, Ord a, Show a) => a -> a -> Assertion m
infix 1 @<-
-- | 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.
(@>-) :: (Monad m, Ord a, Show a) => a -> a -> Assertion m
infix 1 @>-
-- | 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.
(@<=-) :: (Monad m, Ord a, Show a) => a -> a -> Assertion m
infix 1 @<=-
-- | 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.
(@>=-) :: (Monad m, Ord a, Show a) => a -> a -> Assertion m
infix 1 @>=-
-- | 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
--
(@==) :: (Monad m, Eq a, Show a) => a -> m a -> Assertion m
infix 1 @==
-- | 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.
(@/=) :: (Monad m, Eq a, Show a) => a -> m a -> Assertion m
infix 1 @/=
-- | 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.
(@<) :: (Monad m, Ord a, Show a) => a -> m a -> Assertion m
infix 1 @<
-- | 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.
(@>) :: (Monad m, Ord a, Show a) => a -> m a -> Assertion m
infix 1 @>
-- | 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.
(@<=) :: (Monad m, Ord a, Show a) => a -> m a -> Assertion m
infix 1 @<=
-- | 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.
(@>=) :: (Monad m, Ord a, Show a) => a -> m a -> Assertion m
infix 1 @>=
-- | Assert that a traversable structure (such as a list) returned from a
-- computation is empty.
empty :: (Monad m, Traversable t) => m (t a) -> Assertion m
-- | Assert that a traversable structure (such as a list) returned from a
-- computation is non-empty.
nonempty :: (Monad m, Traversable t) => m (t a) -> Assertion m
-- | Assert that a pure traversable structure (such as a list) is empty.
emptyP :: (Monad m, Traversable t) => t a -> Assertion m
-- | Assert that a pure traversable structure (such as a list) is nonempty.
nonemptyP :: (Monad m, Traversable t) => t a -> Assertion m
-- | Assert that a Maybe result of a computation is Nothing.
nothing :: Monad m => m (Maybe a) -> Assertion m
-- | Assert that a Maybe value is Nothing.
nothingP :: Monad m => Maybe a -> Assertion m
-- | This assertion always fails with the given message.
assertFailed :: Monad m => String -> Assertion m
-- | This assertion always succeeds.
assertSuccess :: Monad m => Assertion m
-- | 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")
--
liftAssertionPure :: Monad m => (a -> Bool) -> (a -> String) -> a -> Assertion m
-- | 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
--
assertionPtoM :: Monad m => (a -> Assertion m) -> m a -> Assertion m
-- | 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.
liftAssertionM :: Monad m => (a -> Bool) -> (a -> String) -> m a -> Assertion m
-- | 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.
liftAssertion2Pure :: Monad m => (a -> a -> Bool) -> (a -> a -> String) -> a -> a -> Assertion m
-- | 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 (@==-)
--
assertion2PtoM :: Monad m => (a -> a -> Assertion m) -> a -> m a -> Assertion m
-- | 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.
liftAssertion2M :: Monad m => (a -> a -> Bool) -> (a -> a -> String) -> a -> m a -> Assertion m
-- | 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.
class (MonadTLT m nt, Monad m, MonadTLT ne nt) => MonadTLTExcept m e nt ne | m -> e, m -> ne
liftTLTExcept :: MonadTLTExcept m e nt ne => ExceptT e ne a -> m a
runToExcept :: MonadTLTExcept m e nt ne => m a -> ExceptT e ne a
-- | Ensure that a computation in ExceptT completes without an
-- uncaught exception.
noUncaught :: MonadTLTExcept m e nt ne => String -> m a -> m ()
-- | Ensure that a computation in ExceptT does throw an uncaught
-- exception.
uncaught :: forall {m} {e} {nt :: Type -> Type} {ne :: Type -> Type} {a}. MonadTLTExcept m e nt ne => String -> m a -> m ()
-- | Ensure that a computation in ExceptT does throw an uncaught
-- exception, allowing further testing of the exception.
uncaughtWith :: MonadTLTExcept m e nt ne => String -> m a -> (e -> ExceptT e ne ()) -> m ()