QuickCheck-2.6: Automatic testing of Haskell programs

Safe Haskell | Safe-Inferred
Language | Haskell98

Test.QuickCheck.Property

Contents

- Property and Testable types
  - Exception handling
  - Type Prop
  - type Rose
  - Result type
  - Lifting and mapping functions
  - Property combinators

Synopsis

- type Property = Gen Prop
- class Testable prop where
  - property :: prop -> Property
  - exhaustive :: prop -> Bool
- morallyDubiousIOProperty :: Testable prop => IO prop -> Property
- protect :: (AnException -> a) -> IO a -> IO a
- newtype Prop = MkProp {
  - unProp :: Rose Result
  }
- data Rose a
  - = MkRose a [Rose a]
  - | IORose (IO (Rose a))
- ioRose :: IO (Rose Result) -> Rose Result
- joinRose :: Rose (Rose a) -> Rose a
- reduceRose :: Rose Result -> IO (Rose Result)
- onRose :: (a -> [Rose a] -> Rose a) -> Rose a -> Rose a
- protectRose :: IO (Rose Result) -> IO (Rose Result)
- protectResults :: Rose Result -> Rose Result
- data Callback
  - = PostTest CallbackKind (State -> Result -> IO ())
  - | PostFinalFailure CallbackKind (State -> Result -> IO ())
- data CallbackKind
  - = Counterexample
  - | NotCounterexample
- data Result = MkResult {
  - ok :: Maybe Bool
  - expect :: Bool
  - reason :: String
  - interrupted :: Bool
  - abort :: Bool
  - stamp :: [(String, Int)]
  - callbacks :: [Callback]
  }
- result :: Result
- exception :: String -> AnException -> Result
- formatException :: String -> AnException -> String
- protectResult :: IO Result -> IO Result
- succeeded :: Result
- failed :: Result
- rejected :: Result
- 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
- mapSize :: Testable prop => (Int -> Int) -> prop -> Property
- shrinking :: Testable prop => (a -> [a]) -> a -> (a -> prop) -> Property
- noShrinking :: Testable prop => prop -> Property
- callback :: Testable prop => Callback -> prop -> Property
- printTestCase :: Testable prop => String -> prop -> Property
- whenFail :: Testable prop => IO () -> prop -> Property
- whenFail' :: Testable prop => IO () -> prop -> Property
- verbose :: Testable prop => prop -> Property
- expectFailure :: Testable prop => prop -> Property
- once :: Testable prop => prop -> Property
- label :: Testable prop => String -> prop -> Property
- collect :: (Show a, Testable prop) => a -> prop -> Property
- classify :: Testable prop => Bool -> String -> prop -> Property
- cover :: Testable prop => Bool -> Int -> String -> prop -> Property
- (==>) :: Testable prop => Bool -> prop -> Property
- within :: Testable prop => Int -> prop -> Property
- forAll :: (Show a, Testable prop) => Gen a -> (a -> prop) -> Property
- forAllShrink :: (Show a, Testable prop) => Gen a -> (a -> [a]) -> (a -> prop) -> Property
- (.&.) :: (Testable prop1, Testable prop2) => prop1 -> prop2 -> Property
- (.&&.) :: (Testable prop1, Testable prop2) => prop1 -> prop2 -> Property
- conjoin :: Testable prop => [prop] -> Property
- (.||.) :: (Testable prop1, Testable prop2) => prop1 -> prop2 -> Property
- disjoin :: Testable prop => [prop] -> Property

# Property and Testable types

type Property = Gen Prop

class Testable prop where

The class of things which can be tested, i.e. turned into a property.

Minimal complete definition

property

Methods

property :: prop -> Property

exhaustive :: prop -> Bool

Instances

Testable Bool |
Testable Result |
Testable Prop |
Testable prop => Testable (Gen prop) |
(Arbitrary a, Show a, Testable prop) => Testable (a -> prop) |

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

Do I/O inside a property. This can obviously lead to unrepeatable testcases, so use with care.

## Exception handling

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

## Type Prop

newtype Prop

Constructors

MkProp |

Fields

unProp :: Rose Result

Instances

Testable Prop |

## type Rose

data Rose a

Constructors

MkRose a [Rose a] |
IORose (IO (Rose a)) |

Instances

Monad Rose |
Functor Rose |

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

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

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

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

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

protectResults :: Rose Result -> Rose Result

## 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

interrupted :: Bool

  indicates if the test case was cancelled by pressing ^C

abort :: Bool

  if True, the test should not be repeated

stamp :: [(String, Int)]

  the collected values for this test case

callbacks :: [Callback]

  the callbacks for this test case

Instances

Testable Result |

result :: Result

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 property if it fails. Shrinking is done automatically for most types. This 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

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

Prints a message to the terminal as part of the counterexample.

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, like `verboseCheck` from QuickCheck 1. Only variables quantified over inside the `verbose` are printed.

expectFailure :: Testable prop => prop -> Property

Modifies a property so that it is expected to fail for some test cases.

once :: Testable prop => prop -> Property

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

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

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

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

Labels a property with a value:

    collect x = label (show x)

classify

Arguments

:: Testable prop |
=> Bool | `True` if the test case should be labelled.
-> String | Label.
-> prop |
-> Property |

Conditionally labels test case.

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 the test cases belong to the given class.

(==>) :: 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.