QuickCheck-2.8.2: Automatic testing of Haskell programs

Safe Haskell | Safe
Language | Haskell98

Test.QuickCheck.Property

Contents

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

Description

Combinators for constructing properties.

Synopsis

- newtype Property = MkProperty {
  - unProperty :: Gen Prop
  }
- class Testable prop where
- data Discard = Discard
- morallyDubiousIOProperty :: Testable prop => IO prop -> Property
- ioProperty :: 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
  - theException :: Maybe AnException
  - abort :: Bool
  - labels :: Map String Int
  - stamp :: Set String
  - callbacks :: [Callback]
  }
- 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
- counterexample :: Testable prop => String -> 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
- (===) :: (Eq a, Show a) => a -> a -> Property

# Property and Testable types

newtype Property #

The type of properties.

Backwards combatibility note: in older versions of QuickCheck `Property` was a type synonym for ``Gen` `Prop``, so you could mix and match property combinators and `Gen` monad operations. Code that does this will no longer typecheck. However, it is easy to fix: because of the `Testable` typeclass, any combinator that expects a `Property` will also accept a ``Gen` `Property``. If you have a `Property` where you need a ``Gen` `a``, simply wrap the property combinator inside a `return` to get a ``Gen` `Property``, and all should be well.

Constructors

MkProperty |
Fields unProperty :: Gen Prop

Instances

Testable Property # |
Methods property :: Property -> Property # exhaustive :: Property -> Bool #

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 #

Convert the thing to a property.

exhaustive :: prop -> Bool #

If true, the property will only be tested once. However, if used inside a quantifier, it will be tested normally.

Instances

Testable Bool # |
Methods property :: Bool -> Property # exhaustive :: Bool -> Bool #
Testable Result # |
Methods property :: Result -> Property # exhaustive :: Result -> Bool #
Testable Prop # |
Methods property :: Prop -> Property # exhaustive :: Prop -> Bool #
Testable Discard # |
Methods property :: Discard -> Property # exhaustive :: Discard -> Bool #
Testable Property # |
Methods property :: Property -> Property # exhaustive :: Property -> Bool #
Testable prop => Testable (Gen prop) # |
Methods property :: Gen prop -> Property # exhaustive :: Gen prop -> Bool #
(Arbitrary a, Show a, Testable prop) => Testable (a -> prop) # |
Methods property :: (a -> prop) -> Property # exhaustive :: (a -> prop) -> Bool #

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 # exhaustive :: Discard -> Bool #

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

Deprecated: Use ioProperty instead

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

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

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

For more advanced monadic testing you may want to look at Test.QuickCheck.Monadic.

## 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 # exhaustive :: Prop -> Bool #

## 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 # liftA2 :: (a -> b -> c) -> Rose a -> Rose b -> Rose c # (*>) :: 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 labels :: Map String Int all labels used by this property stamp :: Set String the collected values for this test case callbacks :: [Callback] the callbacks for this test case

Instances

Testable Result # |
Methods property :: Result -> Property # exhaustive :: Result -> Bool #

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

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

Adds the given string to the counterexample.

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

Deprecated: Use counterexample instead

Adds the given string to 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. 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.

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 successful test cases belong to the given class. Discarded tests (i.e. ones with a false precondition) do not affect coverage.

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