Hledger.Utils.Test

Locally adjust the option value for the given test subtree.

Customize the test tree based on the run-time options.

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

At the moment it consists of listingTests and consoleTestReporter.

Locally set the option value for the given test subtree.

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

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.

The after combinator declares dependencies between tests.

If a TestTree is wrapped in after, 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 DependencyType argument is set to AllSucceed 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.

Examples

The following test will be executed only after all tests that contain Foo anywhere in their path finish.

after AllFinish "Foo" $
   

testCase "A test that depends on Foo.Bar" $ ...

Note, however, that our test also happens to contain Foo as part of its name, so it also matches the pattern and becomes a dependency of itself. This will result in a Test.Tasty.DependencyLoop exception. To avoid this, either change the test name so that it doesn't mention Foo or make the pattern more specific.

You can use AWK patterns, for instance, to specify the full path to the dependency.

after AllFinish "$0 == \"Tests.Foo.Bar\"" $
   

testCase "A test that depends on Foo.Bar" $ ...

Or only specify the dependency's own name, ignoring the group names:

after AllFinish "$NF == \"Bar\"" $
   

testCase "A test that depends on Foo.Bar" $ ...

Like after, but accepts the pattern as a syntax tree instead of a string. Useful for generating a test tree programmatically.

Examples

Only match on the test's own name, ignoring the group names:

after_ AllFinish (EQ (Field NF) (StringLit "Bar")) $
   

testCase "A test that depends on Foo.Bar" $ ...

Create a named group of test cases or other groups. Tests are executed in order and each test is considered a dependency of the next one. If filtering by TestPattern (--pattern) is in action, any test matching the pattern also shields earlier tests from filtering out, even if they themselves do not match the pattern.

For parallel execution, see testGroup. For ordered test execution, but with default filtering behavior, see inOrderTestGroup.

Note that this is will only work when used with the default TestManager. If you use another manager, like tasty-rerun for instance, sequentiality might possibly be ignored.

Create a named group of test cases that will be played sequentially, in the exact order provided. Similarly to testGroup and in contrast to dependentTestGroup, filtering by TestPattern is applied uniformly.

Note that this is will only work when used with the default TestManager. If you use another manager, like tasty-rerun for instance, the fact that these tests should be run in the given order might possibly be ignored.

Legacy name for dependentTestGroup.

Create a named group of test cases or other groups. Tests are executed in parallel. For sequential execution, see dependentTestGroup.

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

The option values can be accessed using askOption.

A shortcut for creating Timeout values.

These are the two ways in which one test may depend on the others.

This is the same distinction as the hard vs soft dependencies in TestNG.

The name of a test or a group of tests.

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.

Timeout to be applied to individual tests.

Turn an Assertion into a tasty test case

Like testCase, except in case the test succeeds, the returned string will be shown as the description. If the empty string is returned, it will be ignored.

Asserts that the specified actual value is equal to the expected value (with the expected value on the left-hand side).

An infix and flipped version of assertBool. E.g. instead of

assertBool "Non-empty list" (null [1])

you can write

null [1] @? "Non-empty list"

@? is also overloaded to accept IO Bool predicates, so instead of

do
  e <- doesFileExist "test"
  e @? "File does not exist"

you can write

doesFileExist "test" @? "File does not exist"

Asserts that the specified actual value is equal to the expected value (with the actual value on the left-hand side).

Asserts that the specified condition holds.

Asserts that the specified actual value is equal to the expected value. The output message will contain the prefix, the expected value, and the actual value.

If the prefix is the empty string (i.e., ""), then the prefix is omitted and only the expected and actual values are output.

Unconditionally signals that a failure has occured. All other assertions can be expressed with the form:

   if conditionIsMet
       then return ()
       else assertFailure msg

Signals an assertion failure if a non-empty message (i.e., a message other than "") is passed.

Create a multi-step unit test.

Example:

main = defaultMain $ testCaseSteps "Multi-step test" $ \step -> do
  step "Preparing..."
  -- do something

  step "Running part 1"
  -- do something

  step "Running part 2"
  -- do something
  assertFailure "BAM!"

  step "Running part 3"
  -- do something

The step calls are mere annotations. They let you see which steps were performed successfully, and which step failed.

You can think of step as putStrLn, except putStrLn would mess up the output with the console reporter and get lost with the others.

For the example above, the output will be

Multi-step test: FAIL
  Preparing...
  Running part 1
  Running part 2
    BAM!

1 out of 1 tests failed (0.00s)

Note that:

• Tasty still treats this as a single test, even though it consists of multiple steps.

• The execution stops after the first failure. When we are looking at a failed test, we know that all displayed steps but the last one were successful, and the last one failed. The steps after the failed one are not displayed, since they didn't run.

Request a CallStack.

NOTE: The implicit parameter ?callStack :: CallStack is an implementation detail and should not be considered part of the CallStack API, we may decide to change the implementation in the future.

Allows the extension of the assertion mechanism.

Since an Assertion can be a sequence of Assertions and IO actions, there is a fair amount of flexibility of what can be achieved. As a rule, the resulting Assertion should be the body of a TestCase or part of a TestCase; it should not be used to assert multiple, independent conditions.

If more complex arrangements of assertions are needed, Test and Testable should be used.

An assertion is simply an IO action. Assertion failure is indicated by throwing an exception, typically HUnitFailure.

Instead of throwing the exception directly, you should use functions like assertFailure and assertBool.

Test cases are composed of a sequence of one or more assertions.

An ad-hoc class used to overload the @? operator.

The only intended instances of this class are Bool and IO Bool.

You shouldn't need to interact with this class directly.

The result of an assertion that hasn't been evaluated yet.

Most test cases follow the following steps:

1. Do some processing or an action.

2. Assert certain conditions.

However, this flow is not always suitable. AssertionPredicate allows for additional steps to be inserted without the initial action to be affected by side effects. Additionally, clean-up can be done before the test case has a chance to end. A potential work flow is:

1. Write data to a file.

2. Read data from a file, evaluate conditions.

3. Clean up the file.

4. Assert that the side effects of the read operation meet certain conditions.

5. Assert that the conditions evaluated in step 2 are met.

Exception thrown by assertFailure etc.

Assert any Left value.

Assert any Right value.

Assert that this stateful parser runnable in IO successfully parses all of the given input text, showing the parse error if it fails. Suitable for hledger's JournalParser parsers.

Assert a parser produces an expected value.

Like assertParseEq, but transform the parse result with the given function before comparing it.

Assert that this stateful parser runnable in IO fails to parse the given input text, with a parse error containing the given string.

Run a stateful parser in IO like assertParse, then assert that the final state (the wrapped state, not megaparsec's internal state), transformed by the given function, matches the given expected value.