Test.Tasty.Ingredients

tasty-0.11.2.4: Modern and extensible testing framework

Safe Haskell | None
Language | Haskell2010

Test.Tasty.Ingredients

Description

This module contains the core definitions related to ingredients.

Ingredients themselves are provided by other modules (usually under the `Test.Tasty.Ingredients.*` hierarchy).

Synopsis

- data Ingredient
  - = TestReporter [OptionDescription] (OptionSet -> TestTree -> Maybe (StatusMap -> IO (Time -> IO Bool)))
  - | TestManager [OptionDescription] (OptionSet -> TestTree -> Maybe (IO Bool))
- tryIngredients :: [Ingredient] -> OptionSet -> TestTree -> Maybe (IO Bool)
- ingredientOptions :: Ingredient -> [OptionDescription]
- ingredientsOptions :: [Ingredient] -> [OptionDescription]
- suiteOptions :: [Ingredient] -> TestTree -> [OptionDescription]
- composeReporters :: Ingredient -> Ingredient -> Ingredient

# Documentation

data Ingredient #

`Ingredient`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 `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.

The first kind is `TestReporter`. If the ingredient that agrees to run is a `TestReporter`, then tasty will automatically launch the tests and pass a `StatusMap` 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).

`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 if it wants them to be run). 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 (Time -> IO Bool))) | For the explanation on how the callback works, see the documentation for `launchTestTree`.
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.

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.

composeReporters :: Ingredient -> Ingredient -> Ingredient #

Compose two `TestReporter` 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 `composeReporters` with a `TestManager`, it only works for `TestReporter` ingredients.