This should be used to wrap the test that contains checks. This initializes the environment needed for the checks to run, and on exit from the test, reports any (and all) failed checks as a test failure.

A convenient Constraint to apply to functions that will perform checks (i.e. call check one or more times)

This is used to run a check within the code. The first argument is the "name" of this check, the second is a function that takes a value and returns True if the value is OK, or False if the value fails the check. The last argument is the value to check.

>>> :set -XOverloadedStrings
>>> :{
>>> defaultMain $ testCase "odd numbers" $ withChecklist "odds" $ do
>>> let three = 3 :: Int
>>> check "three is odd" odd three
>>> check "two is odd" odd (2 :: Int)
>>> check "7 + 3 is odd" odd $ 7 + three
>>> check "7 is odd" odd (7 :: Int)
>>> :}
tst1: FAIL
  Exception: ERROR: numbers
    2 checks failed in this checklist:
    ↪Failed check of "two is odd" with "2"
    ↪Failed check of "7 + 3 is odd" with "10"

Any check failures are also printed to stdout (and omitted from the above for clarity). This is so that those failures are reported even if a more standard test assertion is used that prevents completion of the checklist. Thus, if an `assertEqual "values" three 7` had been added to the above, that would have been the only actual (and immediate) fail for the test, but any failing checks appearing before that assertEqual would still have printed.

Sometimes checks are provided in common testing code, often in setup/preparation for the main tests. In some cases, the check is not applicable for that particular test. This function can be used to discard any pending failures for the associated named check.

This is especially useful when a common code block is used to perform a set of checks: if a few of the common checks are not appropriate for the current situation, discardCheck can be used to throw away the results of those checks by matching on the check name.

The checkValues is a checklist that tests various values that can be derived from the input value. The input value is provided, along with an Assignment list of extraction functions and the expected result value (and name) of that extraction. Each extraction is performed as a check within the checklist.

This is convenient to gather together a number of validations on a single datatype and represent them economically.

One example is testing the fields of a record structure:

{-# LANGUAGE PatternSynonyms, OverloadedStrings #-}

import Data.Parameterized.Context ( pattern Empty, pattern (:>) )
import Test.Tasty.Checklist

data Struct = MyStruct { foo :: Int, bar :: Char, baz :: String }

instance Show Struct where
   show s = baz s <> " is " <> foo s <> bar s

someFun :: Int -> Struct
someFun n = MyStruct (n * 6)
              (if n * 6 == 42 then '!' else '?')
              "The answer to the universe"

oddAnswer :: Struct -> Bool
oddAnswer = odd . foo

test = testCase "someFun result" $
   someFun 3 `checkValues`
        (Empty
        :> Val "foo" foo 42
        :> Val "baz field" baz "The answer to the universe"
        :> Val "shown" show "The answer to the universe is 42!"
        :> Val "odd answer" oddAnswer False
        :> Val "double-checking foo" foo 42
        )

Running this test:

>>> defaultMain test
ERROR: on input "The answer to the universe is 18?"
  2 checks failed:
  ↪Failed check of "foo" with "42"
  ↪Failed check of "shown" with "The answer to the universe is 42!"

In this case, several of the values checked were correct, but more than one was wrong. Helpfully, this test output lists all the wrong answers for the single input provided.

Each entry in the Assignment list for checkValues should be one of these DerivedVal values.

The ChecklistFailures exception is thrown if any checks have failed during testing.

The TestShow class is defined to provide a way for the various data objects tested by this module to be displayed when tests fail. The default testShow will use a Show instance, but this can be overridden if there are alternate ways t o display a particular object (e.g. pretty-printing, etc.)

A helper function for defining a testShow for lists of items.

instance TestShow [Int] where testShow = testShowList