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


-- | Modern and extensible testing framework
--   
--   Tasty is a modern testing framework for Haskell. It lets you combine
--   your unit tests, golden tests, QuickCheck/SmallCheck properties, and
--   any other types of tests into a single test suite.
@package tasty
@version 1.2.3


-- | Extensible options. They are used for provider-specific settings,
--   ingredient-specific settings and core settings (such as the test name
--   pattern).
module Test.Tasty.Options

-- | An option is a data type that inhabits the <a>IsOption</a> type class.
class Typeable v => IsOption v

-- | The value to use if the option was not supplied explicitly
defaultValue :: IsOption v => v

-- | Try to parse an option value from a string. Consider using
--   <a>safeReadBool</a> for boolean options and <a>safeRead</a> for
--   numeric options.
parseValue :: IsOption v => String -> Maybe v

-- | The option name. It is used to form the command line option name, for
--   instance. Therefore, it had better not contain spaces or other fancy
--   characters. It is recommended to use dashes instead of spaces.
optionName :: IsOption v => Tagged v String

-- | The option description or help string. This can be an arbitrary
--   string.
optionHelp :: IsOption v => Tagged v String

-- | A command-line option parser.
--   
--   It has a default implementation in terms of the other methods. You may
--   want to override it in some cases (e.g. add a short flag) and
--   <a>flagCLParser</a>, <a>mkFlagCLParser</a> and <a>mkOptionCLParser</a>
--   might come in handy.
--   
--   Even if you override this, you still should implement all the methods
--   above, to allow alternative interfaces.
--   
--   Do not supply a default value here for this parser! This is because if
--   no value was provided on the command line we may lookup the option
--   e.g. in the environment. But if the parser always succeeds, we have no
--   way to tell whether the user really provided the option on the command
--   line.
optionCLParser :: IsOption v => Parser v

-- | A set of options. Only one option of each type can be kept.
--   
--   If some option has not been explicitly set, the default value is used.
data OptionSet

-- | Set the option value
setOption :: IsOption v => v -> OptionSet -> OptionSet

-- | Change the option value
changeOption :: forall v. IsOption v => (v -> v) -> OptionSet -> OptionSet

-- | Query the option value
lookupOption :: forall v. IsOption v => OptionSet -> v

-- | Create a singleton <a>OptionSet</a>
singleOption :: IsOption v => v -> OptionSet

-- | The purpose of this data type is to capture the dictionary
--   corresponding to a particular option.
data OptionDescription
[Option] :: IsOption v => Proxy v -> OptionDescription

-- | Command-line parser to use with flags
flagCLParser :: forall v. IsOption v => Maybe Char -> v -> Parser v

-- | Command-line flag parser that takes additional option modifiers.
mkFlagCLParser :: forall v. IsOption v => Mod FlagFields v -> v -> Parser v

-- | Command-line option parser that takes additional option modifiers.
mkOptionCLParser :: forall v. IsOption v => Mod OptionFields v -> Parser v

-- | Safe read function. Defined here for convenience to use for
--   <a>parseValue</a>.
safeRead :: Read a => String -> Maybe a

-- | Parse a <a>Bool</a> case-insensitively
safeReadBool :: String -> Maybe Bool
instance GHC.Base.Monoid Test.Tasty.Options.OptionSet
instance GHC.Base.Semigroup Test.Tasty.Options.OptionSet

module Test.Tasty.Patterns.Types
data Expr
IntLit :: !Int -> Expr

-- | number of fields
NF :: Expr
Add :: Expr -> Expr -> Expr
Sub :: Expr -> Expr -> Expr
Neg :: Expr -> Expr
Not :: Expr -> Expr
And :: Expr -> Expr -> Expr
LT :: Expr -> Expr -> Expr
GT :: Expr -> Expr -> Expr
LE :: Expr -> Expr -> Expr
GE :: Expr -> Expr -> Expr
EQ :: Expr -> Expr -> Expr
NE :: Expr -> Expr -> Expr
Or :: Expr -> Expr -> Expr
Concat :: Expr -> Expr -> Expr
Match :: Expr -> String -> Expr
NoMatch :: Expr -> String -> Expr

-- | nth field of the path, where 1 is the outermost group name and 0 is
--   the whole test name, using <tt>.</tt> (dot) as a separator
Field :: Expr -> Expr
StringLit :: String -> Expr
If :: Expr -> Expr -> Expr -> Expr

-- | an ERE token by itself, like <tt><i>foo</i></tt> but not like <tt>$1 ~
--   <i>foo</i></tt>
ERE :: String -> Expr
ToUpperFn :: Expr -> Expr
ToLowerFn :: Expr -> Expr
LengthFn :: Maybe Expr -> Expr
MatchFn :: Expr -> String -> Expr
SubstrFn :: Expr -> Expr -> Maybe Expr -> Expr
instance GHC.Classes.Eq Test.Tasty.Patterns.Types.Expr
instance GHC.Show.Show Test.Tasty.Patterns.Types.Expr


-- | See
--   <a>http://pubs.opengroup.org/onlinepubs/9699919799/utilities/awk.html</a>
--   for the full awk grammar.
module Test.Tasty.Patterns.Parser

-- | A separate <a>Parser</a> data type ensures that we don't forget to
--   skip spaces.
data Parser a

-- | Run a parser
runParser :: Parser a -> String -> ParseResult a
data ParseResult a
Success :: a -> ParseResult a
Invalid :: ParseResult a
Ambiguous :: [a] -> ParseResult a

-- | The awk-like expression parser
expr :: Parser Expr

-- | Parse an awk expression
parseAwkExpr :: String -> Maybe Expr
instance GHC.Show.Show a => GHC.Show.Show (Test.Tasty.Patterns.Parser.ParseResult a)
instance GHC.Base.MonadPlus Test.Tasty.Patterns.Parser.Parser
instance GHC.Base.Monad Test.Tasty.Patterns.Parser.Parser
instance GHC.Base.Alternative Test.Tasty.Patterns.Parser.Parser
instance GHC.Base.Applicative Test.Tasty.Patterns.Parser.Parser
instance GHC.Base.Functor Test.Tasty.Patterns.Parser.Parser

module Test.Tasty.Patterns.Eval
type Path = Seq String

-- | Evaluate an awk expression
eval :: Expr -> M Value

-- | Run the <a>M</a> monad with a given list of fields
--   
--   The field list should not include <tt>$0</tt>; it's calculated
--   automatically.
withFields :: Seq String -> M a -> Either String a
asB :: Value -> M Bool
instance GHC.Show.Show Test.Tasty.Patterns.Eval.Value


-- | API for test providers
module Test.Tasty.Providers

-- | The interface to be implemented by a test provider.
--   
--   The type <tt>t</tt> is the concrete representation of the test which
--   is used by the provider.
class Typeable t => IsTest t

-- | Run the test
--   
--   This method should cleanly catch any exceptions in the code to test,
--   and return them as part of the <a>Result</a>, see <a>FailureReason</a>
--   for an explanation. It is ok for <a>run</a> to raise an exception if
--   there is a problem with the test suite code itself (for example, if a
--   file that should contain example data or expected output is not
--   found).
run :: IsTest t => OptionSet -> t -> (Progress -> IO ()) -> IO Result

-- | The list of options that affect execution of tests of this type
testOptions :: IsTest t => Tagged t [OptionDescription]

-- | <a>Result</a> of a passed test
testPassed :: String -> Result

-- | <a>Result</a> of a failed test
testFailed :: String -> Result

-- | A test result
data Result

-- | Test progress information.
--   
--   This may be used by a runner to provide some feedback to the user
--   while a long-running test is executing.
data Progress
Progress :: String -> Float -> Progress

-- | textual information about the test's progress
[progressText] :: Progress -> String

-- | <a>progressPercent</a> should be a value between 0 and 1. If it's
--   impossible to compute the estimate, use 0.
[progressPercent] :: Progress -> Float

-- | The name of a test or a group of tests
type TestName = String

-- | The main data structure defining a test suite.
--   
--   It consists of individual test cases and properties, organized in
--   named groups which form a tree-like hierarchy.
--   
--   There is no generic way to create a test case. Instead, every test
--   provider (tasty-hunit, tasty-smallcheck etc.) provides a function to
--   turn a test case into a <a>TestTree</a>.
--   
--   Groups can be created using <a>testGroup</a>.
data TestTree

-- | Convert a test to a leaf of the <a>TestTree</a>
singleTest :: IsTest t => TestName -> t -> TestTree


-- | This module contains the core definitions related to ingredients.
--   
--   Ingredients themselves are provided by other modules (usually under
--   the <tt>Test.Tasty.Ingredients.*</tt> hierarchy).
module Test.Tasty.Ingredients

-- | <a>Ingredient</a>s make your test suite tasty.
--   
--   Ingredients represent different actions that you can perform on your
--   test suite. One obvious ingredient that you want to include is one
--   that runs tests and reports the progress and results.
--   
--   Another standard ingredient is one that simply prints the names of all
--   tests.
--   
--   Similar to test providers (see <a>IsTest</a>), every ingredient may
--   specify which options it cares about, so that those options are
--   presented to the user if the ingredient is included in the test suite.
--   
--   An ingredient can choose, typically based on the <a>OptionSet</a>,
--   whether to run. That's what the <a>Maybe</a> is for. The first
--   ingredient that agreed to run does its work, and the remaining
--   ingredients are ignored. Thus, the order in which you arrange the
--   ingredients may matter.
--   
--   Usually, the ingredient which runs the tests is unconditional and thus
--   should be placed last in the list. Other ingredients usually run only
--   if explicitly requested via an option. Their relative order thus
--   doesn't matter.
--   
--   That's all you need to know from an (advanced) user perspective. Read
--   on if you want to create a new ingredient.
--   
--   There are two kinds of ingredients.
--   
--   The first kind is <a>TestReporter</a>. If the ingredient that agrees
--   to run is a <a>TestReporter</a>, then tasty will automatically launch
--   the tests and pass a <a>StatusMap</a> to the ingredient. All the
--   ingredient needs to do then is to process the test results and
--   probably report them to the user in some way (hence the name).
--   
--   <a>TestManager</a> is the second kind of ingredient. It is typically
--   used for test management purposes (such as listing the test names),
--   although it can also be used for running tests (but, unlike
--   <a>TestReporter</a>, it has to launch the tests manually if it wants
--   them to be run). It is therefore more general than
--   <a>TestReporter</a>. <a>TestReporter</a> is provided just for
--   convenience.
--   
--   The function's result should indicate whether all the tests passed.
--   
--   In the <a>TestManager</a> case, it's up to the ingredient author to
--   decide what the result should be. When no tests are run, the result
--   should probably be <a>True</a>. Sometimes, even if some tests run and
--   fail, it still makes sense to return <a>True</a>.
data Ingredient

-- | For the explanation on how the callback works, see the documentation
--   for <a>launchTestTree</a>.
TestReporter :: [OptionDescription] -> (OptionSet -> TestTree -> Maybe (StatusMap -> IO (Time -> IO Bool))) -> Ingredient
TestManager :: [OptionDescription] -> (OptionSet -> TestTree -> Maybe (IO Bool)) -> Ingredient

-- | Run the first <a>Ingredient</a> that agrees to be run.
--   
--   If no one accepts the task, return <a>Nothing</a>. This is usually a
--   sign of misconfiguration.
tryIngredients :: [Ingredient] -> OptionSet -> TestTree -> Maybe (IO Bool)

-- | Return the options which are relevant for the given ingredient.
--   
--   Note that this isn't the same as simply pattern-matching on
--   <a>Ingredient</a>. E.g. options for a <a>TestReporter</a>
--   automatically include <a>NumThreads</a>.
ingredientOptions :: Ingredient -> [OptionDescription]

-- | Like <tt>ingredientOption</tt>, but folds over multiple ingredients.
ingredientsOptions :: [Ingredient] -> [OptionDescription]

-- | All the options relevant for this test suite. This includes the
--   options for the test tree and ingredients, and the core options.
suiteOptions :: [Ingredient] -> TestTree -> [OptionDescription]

-- | Compose two <a>TestReporter</a> ingredients which are then executed in
--   parallel. This can be useful if you want to have two reporters active
--   at the same time, e.g., one which prints to the console and one which
--   writes the test results to a file.
--   
--   Be aware that it is not possible to use <a>composeReporters</a> with a
--   <a>TestManager</a>, it only works for <a>TestReporter</a> ingredients.
composeReporters :: Ingredient -> Ingredient -> Ingredient


-- | Console reporter ingredient
module Test.Tasty.Ingredients.ConsoleReporter

-- | A simple console UI
consoleTestReporter :: Ingredient

-- | Do not print test results (see README for details)
newtype Quiet
Quiet :: Bool -> Quiet

-- | Report only failed tests
newtype HideSuccesses
HideSuccesses :: Bool -> HideSuccesses

-- | By default, when the option <tt>--hide-successes</tt> is given and the
--   output goes to an ANSI-capable terminal, we employ some ANSI terminal
--   tricks to display the name of the currently running test and then
--   erase it if it succeeds.
--   
--   These tricks sometimes fail, however—in particular, when the test
--   names happen to be longer than the width of the terminal window. See
--   
--   <ul>
--   <li><a>https://github.com/feuerbach/tasty/issues/152</a></li>
--   <li><a>https://github.com/feuerbach/tasty/issues/250</a></li>
--   </ul>
--   
--   When that happens, this option can be used to disable the tricks. In
--   that case, the test name will be printed only once the test fails.
newtype AnsiTricks
AnsiTricks :: Bool -> AnsiTricks

-- | When to use color on the output
data UseColor
Never :: UseColor
Always :: UseColor

-- | Only if stdout is an ANSI color supporting terminal
Auto :: UseColor

-- | <tt>useColor when isTerm</tt> decides if colors should be used, where
--   <tt>isTerm</tt> indicates whether <tt>stdout</tt> is a terminal
--   device.
useColor :: UseColor -> Bool -> Bool

-- | Track the number of tests that were run and failures of a
--   <a>TestTree</a> or sub-tree.
data Statistics
Statistics :: !Int -> !Int -> Statistics

-- | Number of active tests (e.g., that match the pattern specified on the
--   commandline), inactive tests are not counted.
[statTotal] :: Statistics -> !Int

-- | Number of active tests that failed.
[statFailures] :: Statistics -> !Int

-- | <tt>computeStatistics</tt> computes a summary <a>Statistics</a> for a
--   given state of the <a>StatusMap</a>. Useful in combination with
--   <tt>printStatistics</tt>
computeStatistics :: StatusMap -> IO Statistics

-- | <tt>printStatistics</tt> reports test success/failure statistics and
--   time it took to run. The <a>Time</a> results is intended to be filled
--   in by the <a>TestReporter</a> callback. The <tt>colors</tt>
--   ImplicitParam controls whether coloured output is used.
printStatistics :: (?colors :: Bool) => Statistics -> Time -> IO ()

-- | <tt>printStatisticsNoTime</tt> reports test success/failure statistics
--   The <tt>colors</tt> ImplicitParam controls whether coloured output is
--   used.
printStatisticsNoTime :: (?colors :: Bool) => Statistics -> IO ()

-- | <a>TestOutput</a> is an intermediary between output formatting and
--   output printing. It lets us have several different printing modes
--   (normal; print failures only; quiet).
data TestOutput

-- | Name of a test, an action that prints the test name, and an action
--   that renders the result of the action.
PrintTest :: String -> IO () -> (Result -> IO ()) -> TestOutput

-- | Name of a test group, an action that prints the heading of a test
--   group and the <a>TestOutput</a> for that test group.
PrintHeading :: String -> IO () -> TestOutput -> TestOutput

-- | Inactive test (e.g. not matching the current pattern)
Skip :: TestOutput

-- | Two sets of <tt>TestOuput</tt> on the same level
Seq :: TestOutput -> TestOutput -> TestOutput

-- | Build the <a>TestOutput</a> for a <a>TestTree</a> and
--   <a>OptionSet</a>. The <tt>colors</tt> ImplicitParam controls whether
--   the output is colored.
buildTestOutput :: (?colors :: Bool) => OptionSet -> TestTree -> TestOutput

-- | Fold function for the <a>TestOutput</a> tree into a <a>Monoid</a>.
foldTestOutput :: Monoid b => (String -> IO () -> IO Result -> (Result -> IO ()) -> b) -> (String -> IO () -> b -> b) -> TestOutput -> StatusMap -> b
instance GHC.Classes.Ord Test.Tasty.Ingredients.ConsoleReporter.UseColor
instance GHC.Classes.Eq Test.Tasty.Ingredients.ConsoleReporter.UseColor
instance GHC.Classes.Ord Test.Tasty.Ingredients.ConsoleReporter.HideSuccesses
instance GHC.Classes.Eq Test.Tasty.Ingredients.ConsoleReporter.HideSuccesses
instance GHC.Classes.Ord Test.Tasty.Ingredients.ConsoleReporter.Quiet
instance GHC.Classes.Eq Test.Tasty.Ingredients.ConsoleReporter.Quiet
instance GHC.Classes.Ord a => GHC.Base.Monoid (Test.Tasty.Ingredients.ConsoleReporter.Maximum a)
instance GHC.Classes.Ord a => GHC.Base.Semigroup (Test.Tasty.Ingredients.ConsoleReporter.Maximum a)
instance Test.Tasty.Options.IsOption Test.Tasty.Ingredients.ConsoleReporter.AnsiTricks
instance Test.Tasty.Options.IsOption Test.Tasty.Ingredients.ConsoleReporter.UseColor
instance Test.Tasty.Options.IsOption Test.Tasty.Ingredients.ConsoleReporter.HideSuccesses
instance Test.Tasty.Options.IsOption Test.Tasty.Ingredients.ConsoleReporter.Quiet
instance GHC.Base.Monoid Test.Tasty.Ingredients.ConsoleReporter.Statistics
instance GHC.Base.Semigroup Test.Tasty.Ingredients.ConsoleReporter.Statistics
instance GHC.Base.Monoid Test.Tasty.Ingredients.ConsoleReporter.TestOutput
instance GHC.Base.Semigroup Test.Tasty.Ingredients.ConsoleReporter.TestOutput


-- | This module exports the basic ingredients defined in the
--   <tt>tasty</tt> packages.
--   
--   Note that if <tt>defaultIngredients</tt> from <a>Test.Tasty</a> suits
--   your needs, use that instead of importing this module.
module Test.Tasty.Ingredients.Basic

-- | A simple console UI
consoleTestReporter :: Ingredient

-- | Do not print test results (see README for details)
newtype Quiet
Quiet :: Bool -> Quiet

-- | Report only failed tests
newtype HideSuccesses
HideSuccesses :: Bool -> HideSuccesses

-- | The ingredient that provides the test listing functionality
listingTests :: Ingredient

-- | This option, when set to <a>True</a>, specifies that we should run in
--   the «list tests» mode
newtype ListTests
ListTests :: Bool -> ListTests

-- | Obtain the list of all tests in the suite
testsNames :: OptionSet -> TestTree -> [TestName]

-- | This ingredient doesn't do anything apart from registering additional
--   options.
--   
--   The option values can be accessed using <tt>askOption</tt>.
includingOptions :: [OptionDescription] -> Ingredient


-- | API for test runners
module Test.Tasty.Runners

-- | The main data structure defining a test suite.
--   
--   It consists of individual test cases and properties, organized in
--   named groups which form a tree-like hierarchy.
--   
--   There is no generic way to create a test case. Instead, every test
--   provider (tasty-hunit, tasty-smallcheck etc.) provides a function to
--   turn a test case into a <a>TestTree</a>.
--   
--   Groups can be created using <a>testGroup</a>.
data TestTree

-- | A single test of some particular type
SingleTest :: TestName -> t -> TestTree

-- | Assemble a number of tests into a cohesive group
TestGroup :: TestName -> [TestTree] -> TestTree

-- | Add some options to child tests
PlusTestOptions :: (OptionSet -> OptionSet) -> TestTree -> TestTree

-- | Acquire the resource before the tests in the inner tree start and
--   release it after they finish. The tree gets an <a>IO</a> action which
--   yields the resource, although the resource is shared across all the
--   tests.
WithResource :: ResourceSpec a -> (IO a -> TestTree) -> TestTree

-- | Ask for the options and customize the tests based on them
AskOptions :: (OptionSet -> TestTree) -> TestTree

-- | Only run after all tests that match a given pattern finish (and,
--   depending on the <a>DependencyType</a>, succeed)
After :: DependencyType -> Expr -> TestTree -> TestTree

-- | Fold a test tree into a single value.
--   
--   The fold result type should be a monoid. This is used to fold multiple
--   results in a test group. In particular, empty groups get folded into
--   <a>mempty</a>.
--   
--   Apart from pure convenience, this function also does the following
--   useful things:
--   
--   <ol>
--   <li>Keeping track of the current options (which may change due to
--   <a>PlusTestOptions</a> nodes)</li>
--   <li>Filtering out the tests which do not match the patterns</li>
--   </ol>
--   
--   Thus, it is preferred to an explicit recursive traversal of the tree.
--   
--   Note: right now, the patterns are looked up only once, and won't be
--   affected by the subsequent option changes. This shouldn't be a problem
--   in practice; OTOH, this behaviour may be changed later.
foldTestTree :: Monoid b => TreeFold b -> OptionSet -> TestTree -> b

-- | An algebra for folding a <a>TestTree</a>.
--   
--   Instead of constructing fresh records, build upon <a>trivialFold</a>
--   instead. This way your code won't break when new nodes/fields are
--   indroduced.
data TreeFold b
TreeFold :: (forall t. IsTest t => OptionSet -> TestName -> t -> b) -> (TestName -> b -> b) -> (forall a. ResourceSpec a -> (IO a -> b) -> b) -> (DependencyType -> Expr -> b -> b) -> TreeFold b
[foldSingle] :: TreeFold b -> forall t. IsTest t => OptionSet -> TestName -> t -> b
[foldGroup] :: TreeFold b -> TestName -> b -> b
[foldResource] :: TreeFold b -> forall a. ResourceSpec a -> (IO a -> b) -> b
[foldAfter] :: TreeFold b -> DependencyType -> Expr -> b -> b

-- | <a>trivialFold</a> can serve as the basis for custom folds. Just
--   override the fields you need.
--   
--   Here's what it does:
--   
--   <ul>
--   <li>single tests are mapped to <a>mempty</a> (you probably do want to
--   override that)</li>
--   <li>test groups are returned unmodified</li>
--   <li>for a resource, an IO action that throws an exception is passed
--   (you want to override this for runners/ingredients that execute
--   tests)</li>
--   </ul>
trivialFold :: Monoid b => TreeFold b

-- | <a>ResourceSpec</a> describes how to acquire a resource (the first
--   field) and how to release it (the second field).
data ResourceSpec a
ResourceSpec :: IO a -> (a -> IO ()) -> ResourceSpec a

-- | Monoid generated by <a>*&gt;</a>
newtype Traversal f
Traversal :: f () -> Traversal f
[getTraversal] :: Traversal f -> f ()

-- | Monoid generated by <tt><a>liftA2</a> (<a>&lt;&gt;</a>)</tt>
--   
--   Starting from GHC 8.6, a similar type is available from
--   <a>Data.Monoid</a>. This type is nevertheless kept for compatibility.
newtype Ap f a
Ap :: f a -> Ap f a
[getApp] :: Ap f a -> f a

-- | <a>Ingredient</a>s make your test suite tasty.
--   
--   Ingredients represent different actions that you can perform on your
--   test suite. One obvious ingredient that you want to include is one
--   that runs tests and reports the progress and results.
--   
--   Another standard ingredient is one that simply prints the names of all
--   tests.
--   
--   Similar to test providers (see <a>IsTest</a>), every ingredient may
--   specify which options it cares about, so that those options are
--   presented to the user if the ingredient is included in the test suite.
--   
--   An ingredient can choose, typically based on the <a>OptionSet</a>,
--   whether to run. That's what the <a>Maybe</a> is for. The first
--   ingredient that agreed to run does its work, and the remaining
--   ingredients are ignored. Thus, the order in which you arrange the
--   ingredients may matter.
--   
--   Usually, the ingredient which runs the tests is unconditional and thus
--   should be placed last in the list. Other ingredients usually run only
--   if explicitly requested via an option. Their relative order thus
--   doesn't matter.
--   
--   That's all you need to know from an (advanced) user perspective. Read
--   on if you want to create a new ingredient.
--   
--   There are two kinds of ingredients.
--   
--   The first kind is <a>TestReporter</a>. If the ingredient that agrees
--   to run is a <a>TestReporter</a>, then tasty will automatically launch
--   the tests and pass a <a>StatusMap</a> to the ingredient. All the
--   ingredient needs to do then is to process the test results and
--   probably report them to the user in some way (hence the name).
--   
--   <a>TestManager</a> is the second kind of ingredient. It is typically
--   used for test management purposes (such as listing the test names),
--   although it can also be used for running tests (but, unlike
--   <a>TestReporter</a>, it has to launch the tests manually if it wants
--   them to be run). It is therefore more general than
--   <a>TestReporter</a>. <a>TestReporter</a> is provided just for
--   convenience.
--   
--   The function's result should indicate whether all the tests passed.
--   
--   In the <a>TestManager</a> case, it's up to the ingredient author to
--   decide what the result should be. When no tests are run, the result
--   should probably be <a>True</a>. Sometimes, even if some tests run and
--   fail, it still makes sense to return <a>True</a>.
data Ingredient

-- | For the explanation on how the callback works, see the documentation
--   for <a>launchTestTree</a>.
TestReporter :: [OptionDescription] -> (OptionSet -> TestTree -> Maybe (StatusMap -> IO (Time -> IO Bool))) -> Ingredient
TestManager :: [OptionDescription] -> (OptionSet -> TestTree -> Maybe (IO Bool)) -> Ingredient

-- | Time in seconds. Used to measure how long the tests took to run.
type Time = Double

-- | Run the first <a>Ingredient</a> that agrees to be run.
--   
--   If no one accepts the task, return <a>Nothing</a>. This is usually a
--   sign of misconfiguration.
tryIngredients :: [Ingredient] -> OptionSet -> TestTree -> Maybe (IO Bool)

-- | Return the options which are relevant for the given ingredient.
--   
--   Note that this isn't the same as simply pattern-matching on
--   <a>Ingredient</a>. E.g. options for a <a>TestReporter</a>
--   automatically include <a>NumThreads</a>.
ingredientOptions :: Ingredient -> [OptionDescription]

-- | Like <tt>ingredientOption</tt>, but folds over multiple ingredients.
ingredientsOptions :: [Ingredient] -> [OptionDescription]

-- | A simple console UI
consoleTestReporter :: Ingredient

-- | The ingredient that provides the test listing functionality
listingTests :: Ingredient

-- | This option, when set to <a>True</a>, specifies that we should run in
--   the «list tests» mode
newtype ListTests
ListTests :: Bool -> ListTests

-- | Obtain the list of all tests in the suite
testsNames :: OptionSet -> TestTree -> [TestName]

-- | Parse the command-line and environment options passed to tasty.
--   
--   Useful if you need to get the options before <tt>defaultMain</tt> is
--   called.
--   
--   Once within the test tree, <tt>askOption</tt> should be used instead.
--   
--   The arguments to this function should be the same as for
--   <a>defaultMainWithIngredients</a>. If you don't use any custom
--   ingredients, pass <tt>defaultIngredients</tt>.
parseOptions :: [Ingredient] -> TestTree -> IO OptionSet

-- | Generate a command line parser from a list of option descriptions
optionParser :: [OptionDescription] -> Parser OptionSet

-- | The command line parser for the test suite
suiteOptionParser :: [Ingredient] -> TestTree -> Parser OptionSet

-- | Parse the command line arguments and run the tests using the provided
--   ingredient list.
--   
--   When the tests finish, this function calls <a>exitWith</a> with the
--   exit code that indicates whether any tests have failed. See
--   <tt>defaultMain</tt> for details.
defaultMainWithIngredients :: [Ingredient] -> TestTree -> IO ()

-- | Current status of a test
data Status

-- | test has not started running yet
NotStarted :: Status

-- | test is being run
Executing :: Progress -> Status

-- | test finished with a given result
Done :: Result -> Status

-- | A test result
data Result
Result :: Outcome -> String -> String -> Time -> Result

-- | Did the test fail? If so, why?
[resultOutcome] :: Result -> Outcome

-- | <a>resultDescription</a> may contain some details about the test. For
--   a passed test it's ok to leave it empty. Providers like SmallCheck and
--   QuickCheck use it to provide information about how many tests were
--   generated.
--   
--   For a failed test, <a>resultDescription</a> should typically provide
--   more information about the failure.
[resultDescription] :: Result -> String

-- | The short description printed in the test run summary, usually
--   <tt>OK</tt> or <tt>FAIL</tt>.
[resultShortDescription] :: Result -> String

-- | How long it took to run the test, in seconds.
[resultTime] :: Result -> Time

-- | Outcome of a test run
--   
--   Note: this is isomorphic to <tt><a>Maybe</a>
--   <a>FailureReason</a></tt>. You can use the <tt>generic-maybe</tt>
--   package to exploit that.
data Outcome

-- | test succeeded
Success :: Outcome

-- | test failed because of the <a>FailureReason</a>
Failure :: FailureReason -> Outcome

-- | If a test failed, <a>FailureReason</a> describes why
data FailureReason

-- | test provider indicated failure of the code to test, either because
--   the tested code returned wrong results, or raised an exception
TestFailed :: FailureReason

-- | the test code itself raised an exception. Typical cases include
--   missing example input or output files.
--   
--   Usually, providers do not have to implement this, as their <a>run</a>
--   method may simply raise an exception.
TestThrewException :: SomeException -> FailureReason

-- | test didn't complete in allotted time
TestTimedOut :: Integer -> FailureReason

-- | a dependency of this test failed, so this test was skipped.
TestDepFailed :: FailureReason

-- | <a>True</a> for a passed test, <a>False</a> for a failed one.
resultSuccessful :: Result -> Bool

-- | Test progress information.
--   
--   This may be used by a runner to provide some feedback to the user
--   while a long-running test is executing.
data Progress
Progress :: String -> Float -> Progress

-- | textual information about the test's progress
[progressText] :: Progress -> String

-- | <a>progressPercent</a> should be a value between 0 and 1. If it's
--   impossible to compute the estimate, use 0.
[progressPercent] :: Progress -> Float

-- | Mapping from test numbers (starting from 0) to their status variables.
--   
--   This is what an ingredient uses to analyse and display progress, and
--   to detect when tests finish.
type StatusMap = IntMap (TVar Status)

-- | Start running the tests (in background, in parallel) and pass control
--   to the callback.
--   
--   Once the callback returns, stop running the tests.
--   
--   The number of test running threads is determined by the
--   <a>NumThreads</a> option.
launchTestTree :: OptionSet -> TestTree -> (StatusMap -> IO (Time -> IO a)) -> IO a

-- | Number of parallel threads to use for running tests.
--   
--   Note that this is <i>not</i> included in <a>coreOptions</a>. Instead,
--   it's automatically included in the options for any
--   <tt>TestReporter</tt> ingredient by <tt>ingredientOptions</tt>,
--   because the way test reporters are handled already involves
--   parallelism. Other ingredients may also choose to include this option.
newtype NumThreads
NumThreads :: Int -> NumThreads
[getNumThreads] :: NumThreads -> Int

-- | Exceptions related to dependencies between tests.
data DependencyException

-- | Test dependencies form a loop. In other words, test A cannot start
--   until test B finishes, and test B cannot start until test A finishes.
DependencyLoop :: DependencyException

-- | All the options relevant for this test suite. This includes the
--   options for the test tree and ingredients, and the core options.
suiteOptions :: [Ingredient] -> TestTree -> [OptionDescription]

-- | The list of all core options, i.e. the options not specific to any
--   provider or ingredient, but to tasty itself. Currently contains
--   <a>TestPattern</a> and <a>Timeout</a>.
coreOptions :: [OptionDescription]
newtype TestPattern
TestPattern :: Maybe Expr -> TestPattern
parseExpr :: String -> Maybe Expr
parseTestPattern :: String -> Maybe TestPattern
noPattern :: TestPattern
type Path = Seq String
exprMatches :: Expr -> Path -> Bool
testPatternMatches :: TestPattern -> Path -> Bool

-- | Catch possible exceptions that may arise when evaluating a string. For
--   normal (total) strings, this is a no-op.
--   
--   This function should be used to display messages generated by the test
--   suite (such as test result descriptions).
--   
--   See e.g. <a>https://github.com/feuerbach/tasty/issues/25</a>
formatMessage :: String -> IO String
forceElements :: [a] -> ()

-- | Install signal handlers so that e.g. the cursor is restored if the
--   test suite is killed by SIGTERM. Upon a signal, a
--   <a>SignalException</a> will be thrown to the thread that has executed
--   this action.
--   
--   This function is called automatically from the <tt>defaultMain*</tt>
--   family of functions. You only need to call it explicitly if you call
--   <tt>tryIngredients</tt> yourself.
--   
--   This function does nothing on non-UNIX systems or when compiled with
--   GHC older than 7.6.
installSignalHandlers :: IO ()

-- | This exception is thrown when the program receives a signal, assuming
--   <a>installSignalHandlers</a> was called.
--   
--   The <a>CInt</a> field contains the signal number, as in <a>Signal</a>.
--   We don't use that type synonym, however, because it's not available on
--   non-UNIXes.
newtype SignalException
SignalException :: CInt -> SignalException

-- | Measure the time taken by an <a>IO</a> action to run
timed :: IO a -> IO (Time, a)

-- | Get monotonic time
--   
--   Warning: This is not the system time, but a monotonically increasing
--   time that facilitates reliable measurement of time differences.
getTime :: IO Time


-- | This module defines the main data types and functions needed to use
--   Tasty.
--   
--   To create a test suite, you also need one or more test providers, such
--   as <a>tasty-hunit</a> or <a>tasty-quickcheck</a>.
--   
--   A simple example (using tasty-hunit) is
--   
--   <pre>
--   import Test.Tasty
--   import Test.Tasty.HUnit
--   
--   main = defaultMain tests
--   
--   tests :: TestTree
--   tests = testGroup "Tests"
--     [ testCase "2+2=4" $
--         2+2 @?= 4
--     , testCase "7 is even" $
--         assertBool "Oops, 7 is odd" (even 7)
--     ]
--   </pre>
--   
--   Take a look at the <a>README</a>: it contains a comprehensive list of
--   test providers, a bigger example, and a lot of other information.
module Test.Tasty

-- | The name of a test or a group of tests
type TestName = String

-- | The main data structure defining a test suite.
--   
--   It consists of individual test cases and properties, organized in
--   named groups which form a tree-like hierarchy.
--   
--   There is no generic way to create a test case. Instead, every test
--   provider (tasty-hunit, tasty-smallcheck etc.) provides a function to
--   turn a test case into a <a>TestTree</a>.
--   
--   Groups can be created using <a>testGroup</a>.
data TestTree

-- | Create a named group of test cases or other groups
testGroup :: TestName -> [TestTree] -> TestTree

-- | Parse the command line arguments and run the tests.
--   
--   When the tests finish, this function calls <tt>exitWith</tt> with the
--   exit code that indicates whether any tests have failed. Most external
--   systems (stack, cabal, travis-ci, jenkins etc.) rely on the exit code
--   to detect whether the tests pass. If you want to do something else
--   after <a>defaultMain</a> returns, you need to catch the exception and
--   then re-throw it. Example:
--   
--   <pre>
--   import Test.Tasty
--   import Test.Tasty.HUnit
--   import System.Exit
--   import Control.Exception
--   
--   test = testCase "Test 1" (2 @?= 3)
--   
--   main = defaultMain test
--     `catch` (\e -&gt; do
--       if e == ExitSuccess
--         then putStrLn "Yea"
--         else putStrLn "Nay"
--       throwIO e)
--   </pre>
defaultMain :: TestTree -> IO ()

-- | Parse the command line arguments and run the tests using the provided
--   ingredient list.
--   
--   When the tests finish, this function calls <a>exitWith</a> with the
--   exit code that indicates whether any tests have failed. See
--   <tt>defaultMain</tt> for details.
defaultMainWithIngredients :: [Ingredient] -> TestTree -> IO ()

-- | List of the default ingredients. This is what <a>defaultMain</a> uses.
--   
--   At the moment it consists of <a>listingTests</a> and
--   <a>consoleTestReporter</a>.
defaultIngredients :: [Ingredient]

-- | This ingredient doesn't do anything apart from registering additional
--   options.
--   
--   The option values can be accessed using <tt>askOption</tt>.
includingOptions :: [OptionDescription] -> Ingredient

-- | Locally adjust the option value for the given test subtree
adjustOption :: IsOption v => (v -> v) -> TestTree -> TestTree

-- | Locally set the option value for the given test subtree
localOption :: IsOption v => v -> TestTree -> TestTree

-- | Customize the test tree based on the run-time options
askOption :: IsOption v => (v -> TestTree) -> TestTree

-- | Timeout to be applied to individual tests
data Timeout

-- | <a>String</a> is the original representation of the timeout (such as
--   <tt>"0.5m"</tt>), so that we can print it back. <a>Integer</a> is the
--   number of microseconds.
Timeout :: Integer -> String -> Timeout
NoTimeout :: Timeout

-- | A shortcut for creating <a>Timeout</a> values
mkTimeout :: Integer -> Timeout

-- | Acquire the resource to run this test (sub)tree and release it
--   afterwards
withResource :: IO a -> (a -> IO ()) -> (IO a -> TestTree) -> TestTree

-- | These are the two ways in which one test may depend on the others.
--   
--   This is the same distinction as the <a>hard vs soft dependencies in
--   TestNG</a>.
data DependencyType

-- | The current test tree will be executed after its dependencies finish,
--   and only if all of the dependencies succeed.
AllSucceed :: DependencyType

-- | The current test tree will be executed after its dependencies finish,
--   regardless of whether they succeed or not.
AllFinish :: DependencyType

-- | The <a>after</a> combinator declares dependencies between tests.
--   
--   If a <a>TestTree</a> is wrapped in <a>after</a>, the tests in this
--   tree will not run until certain other tests («dependencies») have
--   finished. These dependencies are specified using an AWK pattern (see
--   the «Patterns» section in the README).
--   
--   Moreover, if the <a>DependencyType</a> argument is set to
--   <a>AllSucceed</a> and at least one dependency has failed, this test
--   tree will not run at all.
--   
--   Tasty does not check that the pattern matches any tests (let alone the
--   correct set of tests), so it is on you to supply the right pattern.
--   
--   <h4><b>Examples</b></h4>
--   
--   The following test will be executed only after all tests that contain
--   <tt>Foo</tt> anywhere in their path finish.
--   
--   <pre>
--   <a>after</a> <a>AllFinish</a> "Foo" $
--      <tt>testCase</tt> "A test that depends on Foo.Bar" $ ...
--   </pre>
--   
--   Note, however, that our test also happens to contain <tt>Foo</tt> as
--   part of its name, so it also matches the pattern and becomes a
--   dependency of itself. This will result in a <tt>DependencyLoop</tt>
--   exception. To avoid this, either change the test name so that it
--   doesn't mention <tt>Foo</tt> or make the pattern more specific.
--   
--   You can use AWK patterns, for instance, to specify the full path to
--   the dependency.
--   
--   <pre>
--   <a>after</a> <a>AllFinish</a> "$0 == \"Tests.Foo.Bar\"" $
--      <tt>testCase</tt> "A test that depends on Foo.Bar" $ ...
--   </pre>
--   
--   Or only specify the dependency's own name, ignoring the group names:
--   
--   <pre>
--   <a>after</a> <a>AllFinish</a> "$NF == \"Bar\"" $
--      <tt>testCase</tt> "A test that depends on Foo.Bar" $ ...
--   </pre>
after :: DependencyType -> String -> TestTree -> TestTree

-- | Like <a>after</a>, but accepts the pattern as a syntax tree instead of
--   a string. Useful for generating a test tree programmatically.
--   
--   <h4><b>Examples</b></h4>
--   
--   Only match on the test's own name, ignoring the group names:
--   
--   <pre>
--   <a>after_</a> <a>AllFinish</a> (<a>EQ</a> (<a>Field</a> <a>NF</a>) (<a>StringLit</a> "Bar")) $
--      <tt>testCase</tt> "A test that depends on Foo.Bar" $ ...
--   </pre>
after_ :: DependencyType -> Expr -> TestTree -> TestTree
