Test.QuickCheck.Property

Combinators for constructing properties.

Property and Testable types

newtype Property

The type of properties.

Constructors

MkProperty

Fields

• unProperty :: Gen Prop

Instances

Testable Property

Methods

property :: Property -> Property

class Testable prop where

The class of properties, i.e., types which QuickCheck knows how to test. Typically a property will be a function returning Bool or Property.

If a property does no quantification, i.e. has no parameters and doesn't use forAll, it will only be tested once. This may not be what you want if your property is an IO Bool. You can change this behaviour using the again combinator.

Minimal complete definition

property

Methods

property :: prop -> Property

Convert the thing to a property.

Instances

Testable Bool

Methods

property :: Bool -> Property

Testable ()

Methods

property :: () -> Property

Testable Result

Methods

property :: Result -> Property

Testable Prop

Methods

property :: Prop -> Property

Testable Discard

Methods

property :: Discard -> Property

Testable Property

Methods

property :: Property -> Property

Testable prop => Testable (Gen prop)

Methods

property :: Gen prop -> Property

(Arbitrary a, Show a, Testable prop) => Testable (a -> prop)

Methods

property :: (a -> prop) -> Property

data Discard

If a property returns Discard, the current test case is discarded, the same as if a precondition was false.

Constructors

Discard

Instances

Testable Discard

Methods

property :: Discard -> Property

morallyDubiousIOProperty :: Testable prop => IO prop -> Property

Deprecated: Use ioProperty instead

Do I/O inside a property.

ioProperty :: Testable prop => IO prop -> Property

Do I/O inside a property.

Warning: any random values generated inside of the argument to ioProperty will not currently be shrunk. For best results, generate all random values before calling ioProperty.

Exception handling

protect :: (AnException -> a) -> IO a -> IO a

Type Prop

newtype Prop

Constructors

MkProp

Fields

• unProp :: Rose Result

Instances

Testable Prop

Methods

property :: Prop -> Property

type Rose

data Rose a

Constructors

MkRose a [Rose a]

IORose (IO (Rose a))

Instances

Monad Rose

Methods

(>>=) :: Rose a -> (a -> Rose b) -> Rose b

(>>) :: Rose a -> Rose b -> Rose b

return :: a -> Rose a

fail :: String -> Rose a

Functor Rose

Methods

fmap :: (a -> b) -> Rose a -> Rose b

(<$) :: a -> Rose b -> Rose a

Applicative Rose

Methods

pure :: a -> Rose a

(<*>) :: Rose (a -> b) -> Rose a -> Rose b

(*>) :: Rose a -> Rose b -> Rose b

(<*) :: Rose a -> Rose b -> Rose a

ioRose :: IO (Rose Result) -> Rose Result

joinRose :: Rose (Rose a) -> Rose a

reduceRose :: Rose Result -> IO (Rose Result)

Execute the IORose bits of a rose tree, returning a tree constructed by MkRose.

onRose :: (a -> [Rose a] -> Rose a) -> Rose a -> Rose a

Apply a function to the outermost MkRose constructor of a rose tree. The function must be total!

protectRose :: IO (Rose Result) -> IO (Rose Result)

Wrap a rose tree in an exception handler.

protectResults :: Rose Result -> Rose Result

Wrap all the Results in a rose tree in exception handlers.

Result type

data Callback

Different kinds of callbacks

Constructors

PostTest CallbackKind (State -> Result -> IO ())

Called just after a test

PostFinalFailure CallbackKind (State -> Result -> IO ())

Called with the final failing test-case

data CallbackKind

Constructors

Counterexample

Affected by the verbose combinator

NotCounterexample

Not affected by the verbose combinator

data Result

The result of a single test.

Constructors

MkResult

Fields

• ok :: Maybe Bool

  result of the test case; Nothing = discard

• expect :: Bool

  indicates what the expected result of the property is

• reason :: String

  a message indicating what went wrong

• theException :: Maybe AnException

  the exception thrown, if any

• abort :: Bool

  if True, the test should not be repeated

• maybeNumTests :: Maybe Int

  stop after this many tests

• labels :: Map String Int

  all labels used by this property

• stamp :: Set String

  the collected labels for this test case

• callbacks :: [Callback]

  the callbacks for this test case

• testCase :: [String]

  the generated test case

Instances

Testable Result

Methods

property :: Result -> Property

exception :: String -> AnException -> Result

formatException :: String -> AnException -> String

protectResult :: IO Result -> IO Result

succeeded :: Result

failed :: Result

rejected :: Result

Lifting and mapping functions

liftBool :: Bool -> Result

mapResult :: Testable prop => (Result -> Result) -> prop -> Property

mapTotalResult :: Testable prop => (Result -> Result) -> prop -> Property

mapRoseResult :: Testable prop => (Rose Result -> Rose Result) -> prop -> Property

mapProp :: Testable prop => (Prop -> Prop) -> prop -> Property

Property combinators

mapSize :: Testable prop => (Int -> Int) -> prop -> Property

Changes the maximum test case size for a property.

shrinking

Arguments

:: Testable prop

=> (a -> [a])

shrink-like function.

-> a

The original argument

-> (a -> prop)

-> Property

Shrinks the argument to a property if it fails. Shrinking is done automatically for most types. This function is only needed when you want to override the default behavior.

noShrinking :: Testable prop => prop -> Property

Disables shrinking for a property altogether.

callback :: Testable prop => Callback -> prop -> Property

Adds a callback

counterexample :: Testable prop => String -> prop -> Property

Adds the given string to the counterexample if the property fails.

showCounterexample :: String -> IO String

printTestCase :: Testable prop => String -> prop -> Property

Deprecated: Use counterexample instead

Adds the given string to the counterexample if the property fails.

whenFail :: Testable prop => IO () -> prop -> Property

Performs an IO action after the last failure of a property.

whenFail' :: Testable prop => IO () -> prop -> Property

Performs an IO action every time a property fails. Thus, if shrinking is done, this can be used to keep track of the failures along the way.

verbose :: Testable prop => prop -> Property

Prints out the generated testcase every time the property is tested. Only variables quantified over inside the verbose are printed.

expectFailure :: Testable prop => prop -> Property

Indicates that a property is supposed to fail. QuickCheck will report an error if it does not fail.

once :: Testable prop => prop -> Property

Modifies a property so that it only will be tested once. Opposite of again.

again :: Testable prop => prop -> Property

Modifies a property so that it will be tested repeatedly. Opposite of once.

withMaxSuccess :: Testable prop => Int -> prop -> Property

Configures how many times a property will be tested.

For example,

quickCheck (withMaxSuccess 1000 p)

will test p up to 1000 times.

label :: Testable prop => String -> prop -> Property

Attaches a label to a property. This is used for reporting test case distribution.

For example:

prop_reverse_reverse :: [Int] -> Property
prop_reverse_reverse xs =
  label ("length of input is " ++ show (length xs)) $
    reverse (reverse xs) === xs

>>> quickCheck prop_reverse_reverse
+++ OK, passed 100 tests:
7% length of input is 7
6% length of input is 3
5% length of input is 4
4% length of input is 6
...

collect :: (Show a, Testable prop) => a -> prop -> Property

Attaches a label to a property. This is used for reporting test case distribution.

collect x = label (show x)

For example:

prop_reverse_reverse :: [Int] -> Property
prop_reverse_reverse xs =
  collect (length xs) $
    reverse (reverse xs) === xs

>>> quickCheck prop_reverse_reverse
+++ OK, passed 100 tests:
7% 7
6% 3
5% 4
4% 6
...

classify

Arguments

:: Testable prop

=> Bool

True if the test case should be labelled.

-> String

Label.

-> prop

-> Property

Records how many test cases satisfy a given condition.

For example:

prop_sorted_sort :: [Int] -> Property
prop_sorted_sort xs =
  sorted xs ==>
  classify (length xs > 1) "non-trivial" $
  sort xs === xs

>>> quickCheck prop_sorted_sort
+++ OK, passed 100 tests (22% non-trivial).

cover

Arguments

:: Testable prop

=> Bool

True if the test case belongs to the class.

-> Int

The required percentage (0-100) of test cases.

-> String

Label for the test case class.

-> prop

-> Property

Checks that at least the given proportion of successful test cases belong to the given class. Discarded tests (i.e. ones with a false precondition) do not affect coverage.

For example:

prop_sorted_sort :: [Int] -> Property
prop_sorted_sort xs =
  sorted xs ==>
  cover (length xs > 1) 50 "non-trivial" $
  sort xs === xs

>>> quickCheck prop_sorted_sort
*** Insufficient coverage after 100 tests (only 24% non-trivial, not 50%).

(==>) :: Testable prop => Bool -> prop -> Property infixr 0

Implication for properties: The resulting property holds if the first argument is False (in which case the test case is discarded), or if the given property holds.

within :: Testable prop => Int -> prop -> Property

Considers a property failed if it does not complete within the given number of microseconds.

forAll :: (Show a, Testable prop) => Gen a -> (a -> prop) -> Property

Explicit universal quantification: uses an explicitly given test case generator.

forAllShrink :: (Show a, Testable prop) => Gen a -> (a -> [a]) -> (a -> prop) -> Property

Like forAll, but tries to shrink the argument for failing test cases.

(.&.) :: (Testable prop1, Testable prop2) => prop1 -> prop2 -> Property infixr 1

Nondeterministic choice: p1 .&. p2 picks randomly one of p1 and p2 to test. If you test the property 100 times it makes 100 random choices.

(.&&.) :: (Testable prop1, Testable prop2) => prop1 -> prop2 -> Property infixr 1

Conjunction: p1 .&&. p2 passes if both p1 and p2 pass.

conjoin :: Testable prop => [prop] -> Property

Take the conjunction of several properties.

(.||.) :: (Testable prop1, Testable prop2) => prop1 -> prop2 -> Property infixr 1

Disjunction: p1 .||. p2 passes unless p1 and p2 simultaneously fail.

disjoin :: Testable prop => [prop] -> Property

Take the disjunction of several properties.

(===) :: (Eq a, Show a) => a -> a -> Property infix 4

Like ==, but prints a counterexample when it fails.

total :: NFData a => a -> Property

Checks that a value is total, i.e., doesn't crash when evaluated.