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


-- | Modern and extensible testing framework
--   
--   See <a>http://documentup.com/feuerbach/tasty</a>
@package tasty
@version 0.2


-- | Extensible options. They are used for provider-specific settings,
--   runner-specific settings and core settings (number of threads, test
--   pattern).
module Test.Tasty.Options

-- | An option is a data type that inhabits the <a>IsOption</a> type class.
class Typeable v => IsOption v where optionCLParser = nullOption (reader parse <> long name <> value defaultValue <> help helpString) where name = untag (optionName :: Tagged v String) helpString = untag (optionHelp :: Tagged v String) parse = maybe (Left (ErrorMsg $ "Could not parse " ++ name)) Right . parseValue
defaultValue :: IsOption v => v
parseValue :: IsOption v => String -> Maybe v
optionName :: IsOption v => Tagged v String
optionHelp :: IsOption v => Tagged v String
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 :: IsOption v => (v -> v) -> OptionSet -> OptionSet

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

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

-- | Safe read function. Defined here for convenience to use for
--   <a>parseValue</a>.
safeRead :: Read a => String -> Maybe a
instance [overlap ok] Monoid OptionSet


-- | 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 :: IsTest t => OptionSet -> t -> (Progress -> IO ()) -> IO Result
testOptions :: IsTest t => Tagged t [OptionDescription]

-- | A test result
data Result
Result :: Bool -> String -> Result

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

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

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


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

-- | Fold a test tree into a single value.
--   
--   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 => (forall t. IsTest t => OptionSet -> TestName -> t -> b) -> (TestName -> b -> b) -> OptionSet -> TestTree -> b

-- | Generate a command line parser for all the options relevant for this
--   test tree. Also includes <a>coreOptions</a>.
treeOptionParser :: TestTree -> Parser OptionSet

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

-- | Parse the command line arguments and run the tests using the provided
--   runner
defaultMainWithRunner :: Runner -> 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 threw an exception and was aborted
Exception :: SomeException -> Status

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

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

-- | A <a>Runner</a> is responsible for user interaction during the test
--   run.
--   
--   It is provided with the <a>StatusMap</a>, so the tests are already
--   launched and all it needs to do is notifying the user about the
--   progress and then displaying the overall results in the end.
--   
--   The function's result should indicate whether all the tests passed.
type Runner = OptionSet -> TestTree -> StatusMap -> IO Bool

-- | Execute a <a>Runner</a>.
--   
--   This is a shortcut which runs <a>launchTestTree</a> behind the scenes.
execRunner :: Runner -> OptionSet -> TestTree -> IO Bool

-- | Start running all the tests in a test tree in parallel. The number of
--   threads is determined by the <a>NumThreads</a> option.
--   
--   Return a map from the test number (starting from 0) to its status
--   variable.
launchTestTree :: OptionSet -> TestTree -> IO StatusMap

-- | A simple console UI
runUI :: Runner

-- | Number of parallel threads to use for running tests
newtype NumThreads
NumThreads :: Int -> NumThreads
getNumThreads :: NumThreads -> Int

-- | The list of all core options
coreOptions :: [OptionDescription]

-- | A pattern to filter tests. For the syntax description, see
--   <a>http://documentup.com/feuerbach/tasty#using-patterns</a>
data TestPattern

-- | Parse a pattern
parseTestPattern :: String -> TestPattern

-- | A pattern that matches anything.
noPattern :: TestPattern

-- | Test a path (which is the sequence of group titles, possibly followed
--   by the test title) against a pattern
testPatternMatches :: TestPattern -> [String] -> Bool


-- | This module defines the main data types and functions needed to use
--   Tasty.
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 using the standard
--   console runner
defaultMain :: TestTree -> IO ()

-- | Parse the command line arguments and run the tests using the provided
--   runner
defaultMainWithRunner :: Runner -> TestTree -> IO ()

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