diff --git a/CHANGELOG.md b/CHANGELOG.md --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,12 @@ Changes ======= +Version 0.11.3 +-------------- + +Expose and document several of the internals of +`Test.Tasty.Ingredients.ConsoleReporter`. + Version 0.11.2.5 ---------------- diff --git a/Test/Tasty/Ingredients/ConsoleReporter.hs b/Test/Tasty/Ingredients/ConsoleReporter.hs --- a/Test/Tasty/Ingredients/ConsoleReporter.hs +++ b/Test/Tasty/Ingredients/ConsoleReporter.hs @@ -5,6 +5,20 @@ ( consoleTestReporter , Quiet(..) , HideSuccesses(..) + -- * Internals + -- | The following functions and datatypes are internals that are exposed to + -- simplify the task of rolling your own custom console reporter UI. + + -- ** Output colouring + , UseColor(..) + , useColor + -- ** Test failure statistics + , Statistics(..) + , printStatistics + -- ** Outputting results + , TestOutput(..) + , buildTestOutput + , foldTestOutput ) where import Control.Monad.State hiding (fail) @@ -40,13 +54,19 @@ -- | 'TestOutput' is an intermediary between output formatting and output -- printing. It lets us have several different printing modes (normal; print -- failures only; quiet). +-- +-- @since 0.11.3 data TestOutput = PrintTest {- print test name -} (IO ()) {- print test result -} (Result -> IO ()) + -- ^ Action that prints the test name and an action that renders the + -- result of the action. | PrintHeading (IO ()) TestOutput - | Skip - | Seq TestOutput TestOutput + -- ^ Action that prints the heading of a test group and the 'TestOutput' + -- for that test group. + | Skip -- ^ Inactive test (e.g. not matching the current pattern) + | Seq TestOutput TestOutput -- ^ Two sets of 'TestOuput' on the same level -- The monoid laws should hold observationally w.r.t. the semantics defined -- in this module @@ -56,8 +76,12 @@ type Level = Int -produceOutput :: (?colors :: Bool) => OptionSet -> TestTree -> TestOutput -produceOutput opts tree = +-- | Build the 'TestOutput' for a 'TestTree' and 'OptionSet'. The @colors@ +-- ImplicitParam controls whether the output is colored. +-- +-- @since 0.11.3 +buildTestOutput :: (?colors :: Bool) => OptionSet -> TestTree -> TestOutput +buildTestOutput opts tree = let -- Do not retain the reference to the tree more than necessary !alignment = computeAlignment opts tree @@ -113,11 +137,21 @@ } opts tree +-- | Fold function for the 'TestOutput' tree into a 'Monoid'. +-- +-- @since 0.11.3 foldTestOutput - :: (?colors :: Bool, Monoid b) + :: Monoid b => (IO () -> IO Result -> (Result -> IO ()) -> b) + -- ^ Eliminator for test cases. The @IO ()@ prints the testname. The + -- @IO Result@ blocks until the test is finished, returning it's 'Result'. + -- The @Result -> IO ()@ function prints the formatted output. -> (IO () -> b -> b) - -> TestOutput -> StatusMap -> b + -- ^ Eliminator for test groups. The @IO ()@ prints the test group's name. + -- The @b@ is the result of folding the test group. + -> TestOutput -- ^ The @TestOutput@ being rendered. + -> StatusMap -- ^ The @StatusMap@ received by the 'TestReporter' + -> b foldTestOutput foldTest foldHeading outputTree smap = flip evalState 0 $ getApp $ go outputTree where go (PrintTest printName printResult) = Ap $ do @@ -217,9 +251,15 @@ -------------------------------------------------- -- {{{ +-- | Track the number of tests that were run and failures of a 'TestTree' or +-- sub-tree. +-- +-- @since 0.11.3 data Statistics = Statistics - { statTotal :: !Int - , statFailures :: !Int + { statTotal :: !Int -- ^ Number of active tests (e.g., that match the + -- pattern specified on the commandline), inactive tests + -- are not counted. + , statFailures :: !Int -- ^ Number of active tests that failed. } instance Monoid Statistics where @@ -231,6 +271,12 @@ (\r -> Statistics 1 (if resultSuccessful r then 0 else 1)) <$> getResultFromTVar var) +-- | @printStatistics@ reports test success/failure statistics and time it took +-- to run. The 'Time' results is intended to be filled in by the 'TestReporter' +-- callback. The @colors@ ImplicitParam controls whether coloured output is +-- used. +-- +-- @since 0.11.3 printStatistics :: (?colors :: Bool) => Statistics -> Time -> IO () printStatistics st time = do printf "\n" @@ -334,7 +380,7 @@ ?colors = useColor whenColor isTerm let - output = produceOutput opts tree + output = buildTestOutput opts tree case () of { _ | hideSuccesses && isTerm -> @@ -370,8 +416,12 @@ optionCLParser = mkFlagCLParser mempty (HideSuccesses True) -- | When to use color on the output +-- +-- @since 0.11.3 data UseColor - = Never | Always | Auto + = Never + | Always + | Auto -- ^ Only if stdout is an ANSI color supporting terminal deriving (Eq, Ord, Typeable) -- | Control color output @@ -382,7 +432,9 @@ optionHelp = return "When to use colored output. Options are 'never', 'always' and 'auto' (default: 'auto')" -- | @useColor when isTerm@ decides if colors should be used, --- where @isTerm@ denotes where @stdout@ is a terminal device. +-- where @isTerm@ indicates whether @stdout@ is a terminal device. +-- +-- @since 0.11.3 useColor :: UseColor -> Bool -> Bool useColor when isTerm = case when of diff --git a/tasty.cabal b/tasty.cabal --- a/tasty.cabal +++ b/tasty.cabal @@ -2,7 +2,7 @@ -- see http://haskell.org/cabal/users-guide/ name: tasty -version: 0.11.2.5 +version: 0.11.3 synopsis: Modern and extensible testing framework description: Tasty is a modern testing framework for Haskell. It lets you combine your unit tests, golden @@ -33,6 +33,7 @@ Test.Tasty.Runners Test.Tasty.Ingredients, Test.Tasty.Ingredients.Basic + Test.Tasty.Ingredients.ConsoleReporter other-modules: Test.Tasty.Parallel, Test.Tasty.Core, @@ -43,7 +44,6 @@ Test.Tasty.Runners.Reducers, Test.Tasty.Runners.Utils, Test.Tasty.CmdLine, - Test.Tasty.Ingredients.ConsoleReporter Test.Tasty.Ingredients.ListTests Test.Tasty.Ingredients.IncludingOptions build-depends: