Test.Tasty.Runners

API for test runners

Working with the test tree

data TestTree

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

Groups can be created using testGroup.

Constructors

forall t . IsTest t => SingleTest TestName t

A single test of some particular type

TestGroup TestName [TestTree]

Assemble a number of tests into a cohesive group

PlusTestOptions (OptionSet -> OptionSet) TestTree

Add some options to child tests

WithResource ResourceSpec TestTree

foldTestTree

Arguments

:: Monoid b

=> (forall t. IsTest t => OptionSet -> TestName -> t -> b)

interpret a single test

-> (TestName -> b -> b)

interpret a test group

-> (ResourceSpec -> b -> b)

deal with the resource

-> OptionSet

initial options

-> TestTree

-> b

Fold a test tree into a single value.

Apart from pure convenience, this function also does the following useful things:

1. Keeping track of the current options (which may change due to PlusTestOptions nodes)
2. Filtering out the tests which do not match the patterns

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.

data ResourceSpec

ResourceSpec describes how to acquire a resource (the first field) and how to release it (the second field).

Constructors

forall a . ResourceSpec (IO a) (a -> IO ())

Ingredients

data Ingredient

Ingredients 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 IsTest), 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 OptionSet, whether to run. That's what the Maybe 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. TestReporter, if it agrees to run, automatically launches tests execution, and gets the StatusMap which it uses to report the progress and results to the user.

TestManager 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 TestReporter, it has to launch the tests manually). It is therefore more general than TestReporter. TestReporter is provided just for convenience.

The function's result should indicate whether all the tests passed.

In the TestManager 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 True. Sometimes, even if some tests run and fail, it still makes sense to return True.

Constructors

TestReporter [OptionDescription] (OptionSet -> TestTree -> Maybe (StatusMap -> IO Bool))

TestManager [OptionDescription] (OptionSet -> TestTree -> Maybe (IO Bool))

tryIngredients :: [Ingredient] -> OptionSet -> TestTree -> Maybe (IO Bool)

Run the first Ingredient that agrees to be run.

If no one accepts the task, return Nothing. This is usually a sign of misconfiguration.

ingredientOptions :: Ingredient -> [OptionDescription]

Return the options which are relevant for the given ingredient.

Note that this isn't the same as simply pattern-matching on Ingredient. E.g. options for a TestReporter automatically include NumThreads.

ingredientsOptions :: [Ingredient] -> [OptionDescription]

Like ingredientOption, but folds over multiple ingredients.

Standard console ingredients

Console test reporter

consoleTestReporter :: Ingredient

A simple console UI

Tests list

listingTests :: Ingredient

The ingredient that provides the test listing functionality

newtype ListTests

This option, when set to True, specifies that we should run in the «list tests» mod

Constructors

ListTests Bool

Instances

Eq ListTests

Ord ListTests

Typeable ListTests

IsOption ListTests

testsNames :: OptionSet -> TestTree -> [TestName]

Obtain the list of all tests in the suite

Command line handling

optionParser :: [OptionDescription] -> Parser OptionSet

Generate a command line parser from a list of option descriptions

suiteOptionParser :: [Ingredient] -> TestTree -> Parser OptionSet

The command line parser for the test suite

defaultMainWithIngredients :: [Ingredient] -> TestTree -> IO ()

Parse the command line arguments and run the tests using the provided ingredient list

Running tests

data Status

Current status of a test

Constructors

NotStarted

test has not started running yet

Executing Progress

test is being run

Exception SomeException

test threw an exception and was aborted

Done Result

test finished with a given result

data Result

A test result

Constructors

Result

Fields

resultSuccessful :: Bool

resultSuccessful should be True for a passed test and False for a failed one.

resultDescription :: String

resultDescription 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, resultDescription should typically provide more information about the failure.

data Progress

Test progress information.

This may be used by a runner to provide some feedback to the user while a long-running test is executing.

Constructors

Progress

Fields

progressText :: String

textual information about the test's progress

progressPercent :: Float

progressPercent should be a value between 0 and 1. If it's impossible to compute the estimate, use 0.

type StatusMap = IntMap (TVar Status)

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.

launchTestTree :: OptionSet -> TestTree -> IO StatusMap

Start running all the tests in a test tree in parallel. The number of threads is determined by the NumThreads option.

Return a map from the test number (starting from 0) to its status variable.

newtype NumThreads

Number of parallel threads to use for running tests.

Note that this is not included in coreOptions. Instead, it's automatically included in the options for any TestReporter ingredient by ingredientOptions, because the way test reporters are handled already involves parallelism. Other ingredients may also choose to include this option.

Constructors

NumThreads

Fields

getNumThreads :: Int

Instances

Eq NumThreads

Num NumThreads

Ord NumThreads

Typeable NumThreads

IsOption NumThreads

Options

suiteOptions :: [Ingredient] -> TestTree -> [OptionDescription]

All the options relevant for this test suite. This includes the options for the test tree and ingredients, and the core options.

coreOptions :: [OptionDescription]

The list of all core options, i.e. the options not specific to any provider or ingredient, but to tasty itself. Currently only contains TestPattern.

Patterns

data TestPattern

A pattern to filter tests. For the syntax description, see http://documentup.com/feuerbach/tasty#using-patterns

Instances

Read TestPattern

Typeable TestPattern

IsOption TestPattern

parseTestPattern :: String -> TestPattern

Parse a pattern

noPattern :: TestPattern

A pattern that matches anything.

testPatternMatches :: TestPattern -> [String] -> Bool

Test a path (which is the sequence of group titles, possibly followed by the test title) against a pattern