tasty-0.11.2.1: Modern and extensible testing framework

Safe Haskell | None
Language | Haskell2010

Test.Tasty

Contents

- Organizing tests
- Running tests
- Adjusting and querying options
  - Standard options
- Resources

Description

This module defines the main data types and functions needed to use Tasty.

Synopsis

- type TestName = String
- data TestTree
- testGroup :: TestName -> [TestTree] -> TestTree
- defaultMain :: TestTree -> IO ()
- defaultMainWithIngredients :: [Ingredient] -> TestTree -> IO ()
- defaultIngredients :: [Ingredient]
- includingOptions :: [OptionDescription] -> Ingredient
- adjustOption :: IsOption v => (v -> v) -> TestTree -> TestTree
- localOption :: IsOption v => v -> TestTree -> TestTree
- askOption :: IsOption v => (v -> TestTree) -> TestTree
- data Timeout
  - = Timeout Integer String
  - | NoTimeout
- mkTimeout :: Integer -> Timeout
- withResource :: IO a -> (a -> IO ()) -> (IO a -> TestTree) -> TestTree

# Organizing tests

type TestName = String #

The name of a test or a group of tests

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

testGroup :: TestName -> [TestTree] -> TestTree #

Create a named group of test cases or other groups

# Running tests

defaultMain :: TestTree -> IO () #

Parse the command line arguments and run the tests.

When the tests finish, this function calls `exitWith` 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 `defaultMain` returns, you need to catch the exception and then re-throw it. Example:

    import Test.Tasty
    import Test.Tasty.HUnit
    import System.Exit
    import Control.Exception

    test = testCase "Test 1" (2 @?= 3)

    main = defaultMain test
      `catch` (\e -> do
        if e == ExitSuccess
          then putStrLn "Yea"
          else putStrLn "Nay"
        throwIO e)

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

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

When the tests finish, this function calls `exitWith` with the exit code that indicates whether any tests have failed. See `defaultMain` for details.

defaultIngredients :: [Ingredient] #

List of the default ingredients. This is what `defaultMain` uses.

At the moment it consists of `listingTests` and `consoleTestReporter`.

includingOptions :: [OptionDescription] -> Ingredient #

This ingredient doesn't do anything apart from registering additional options.

The option values can be accessed using `askOption`.

# Adjusting and querying options

Normally options are specified on the command line. But you can also have different options for different subtrees in the same tree, using the functions below.

Note that ingredient options (number of threads, hide successes etc.) set in this way will not have any effect. This is for modifying per-test options, such as timeout, number of generated tests etc.

adjustOption :: IsOption v => (v -> v) -> TestTree -> TestTree #

Locally adjust the option value for the given test subtree

localOption :: IsOption v => v -> TestTree -> TestTree #

Locally set the option value for the given test subtree

askOption :: IsOption v => (v -> TestTree) -> TestTree #

Customize the test tree based on the run-time options

## Standard options

data Timeout #

Timeout to be applied to individual tests

Constructors

Timeout Integer String | `String` is the original representation of the timeout (such as `"0.5m"`), so that we can print it back. `Integer` is the number of microseconds.
NoTimeout |

Instances

Show Timeout # |
Methods showsPrec :: Int -> Timeout -> ShowS # show :: Timeout -> String # showList :: [Timeout] -> ShowS #
IsOption Timeout # |
Methods defaultValue :: Timeout # parseValue :: String -> Maybe Timeout # optionName :: Tagged * Timeout String # optionHelp :: Tagged * Timeout String # optionCLParser :: Parser Timeout #

mkTimeout #

Arguments

:: Integer | microseconds
-> Timeout |

A shortcut for creating `Timeout` values

# Resources

Sometimes several tests need to access the same resource — say, a file or a socket. We want to create or grab the resource before the tests are run, and destroy or release afterwards.

withResource #

Arguments

:: IO a | initialize the resource
-> (a -> IO ()) | free the resource
-> (IO a -> TestTree) | ``IO` a` is an action which returns the acquired resource. Despite it being an `IO` action, the resource it returns will be acquired only once and shared across all the tests in the tree.
-> TestTree |

Acquire the resource to run this test (sub)tree and release it afterwards