ModuleQuickCheck-2.15.0.1Haskell2010

Test.QuickCheck.Monadic

Allows testing of monadic values. Will generally follow this form:

prop_monadic a b = monadicIO $ do
  a' <- run (f a)
  b' <- run (f b)
  -- ...
  assert someBoolean

Example using the FACTOR(1) command-line utility:

import System.Process
import Test.QuickCheck
import Test.QuickCheck.Monadic

-- $ factor 16
-- 16: 2 2 2 2
factor :: Integer -> IO [Integer]
factor n = parse `fmap` System.Process.readProcess "factor" [show n] "" where

  parse :: String -> [Integer]
  parse = map read . tail . words

prop_factor :: Positive Integer -> Property
prop_factor (Positive n) = monadicIO $ do
  factors <- run (factor n)

  assert (product factors == n)

Example1 expression

>>> quickCheck prop_factor+++ OK, passed 100 tests.

See the paper "Testing Monadic Code with QuickCheck".

1 type
18 values

PackageQuickCheck-2.15.0.1
Exports19
LanguageHaskell2010
LicenceBSD-3-Clause
SourceMonadic.hs

Property monad

1 declaration

newtypenewtype PropertyM (m :: Type -> Type) a

The property monad is really a monad transformer that can contain monadic computations in the monad m it is parameterized by:

m - the m-computations that may be performed within PropertyM

Elements of PropertyM m a may mix property operations and m-computations.

Constructors

MkPropertyM
- unPropertyM :: (a -> Gen (m Property)) -> Gen (m Property)

Instances6MonadTrans, Monad, Functor, MonadFail, Applicative, MonadIO

MonadTrans PropertyMDefined in QuickCheck-2.15.0.1 · Test.QuickCheck.Monadic
Monad m => Monad (PropertyM m)Defined in QuickCheck-2.15.0.1 · Test.QuickCheck.Monadic
Functor (PropertyM m)Defined in QuickCheck-2.15.0.1 · Test.QuickCheck.Monadic
Monad m => MonadFail (PropertyM m)Defined in QuickCheck-2.15.0.1 · Test.QuickCheck.Monadic
Applicative (PropertyM m)Defined in QuickCheck-2.15.0.1 · Test.QuickCheck.Monadic
MonadIO m => MonadIO (PropertyM m)Defined in QuickCheck-2.15.0.1 · Test.QuickCheck.Monadic

Monadic specification combinators

9 declarations

valuerun :: Monad m => m a -> PropertyM m a

The lifting operation of the property monad. Allows embedding monadic/IO-actions in properties:

log :: Int -> IO ()

prop_foo n = monadicIO $ do
  run (log n)
  -- ...

valueassert :: Monad m => Bool -> PropertyM m ()

Allows embedding non-monadic properties into monadic ones.

valueassertWith :: Monad m => Bool -> String -> PropertyM m ()

Like assert but allows caller to specify an explicit message to show on failure.

Example:

do
  assertWith True  "My first predicate."
  assertWith False "My other predicate."
  ...

Assertion failed (after 2 tests):
    Passed: My first predicate
    Failed: My other predicate

valuepre :: Monad m => Bool -> PropertyM m ()

Tests preconditions. Unlike assert this does not cause the property to fail, rather it discards them just like using the implication combinator ==>.

This allows representing the Hoare triple

{p} x ← e{q}

pre p
x <- run e
assert q

valuewp :: Monad m => m a -> (a -> PropertyM m b) -> PropertyM m b

The weakest precondition

wp(x ← e, p)

can be expressed as in code as wp e (\x -> p).

valuepick :: (Monad m, Show a) => Gen a -> PropertyM m a

Quantification in a monadic property, fits better with do-notation than forAllM. Note: values generated by pick do not shrink.

valueforAllM

:: (Monad m, Show a)
=> Gen a
-> a -> PropertyM m b
-> PropertyM m b

Quantification in monadic properties to pick, with a notation similar to forAll. Note: values generated by forAllM do not shrink.

valuemonitor :: Monad m => (Property -> Property) -> PropertyM m ()

Allows making observations about the test data:

monitor (collect e)

collects the distribution of value of e.

monitor (counterexample "Failure!")

Adds "Failure!" to the counterexamples.

valuestop :: (Testable prop, Monad m) => prop -> PropertyM m a

Run functions

5 declarations

valuemonadic

:: (Testable a, Monad m)
=> m Property -> Property
-> PropertyM m a
-> Property

valuemonadic' :: (Testable a, Monad m) => PropertyM m a -> Gen (m Property)

valuemonadicIO :: Testable a => PropertyM IO a -> Property

Runs the property monad for IO-computations.

prop_cat msg = monadicIO $ do
  (exitCode, stdout, _) <- run (System.Process.readProcessWithExitCode "cat" [] msg)

  pre (ExitSuccess == exitCode)

  assert (stdout == msg)

Example1 expression

>>> quickCheck prop_cat+++ OK, passed 100 tests.

valuemonadicST :: Testable a => (forall s. PropertyM (ST s) a) -> Property

Runs the property monad for ST-computations.

-- Your mutable sorting algorithm here
sortST :: Ord a => [a] -> ST s (MVector s a)
sortST = Data.Vector.thaw . Data.Vector.fromList . sort

prop_sortST xs = monadicST $ do
  sorted  <- run (Data.Vector.freeze =<< sortST xs)
  assert (Data.Vector.toList sorted == sort xs)

Example1 expression

>>> quickCheck prop_sortST+++ OK, passed 100 tests.

valuerunSTGen :: (forall s. Gen (ST s a)) -> Gen a

Exceptions

4 declarations

valueassertException

:: Exception exc
=> (exc -> Bool)
Return True if that is the exception that was expected
-> a
Value that should result in an exception, when evaluated to WHNF
-> Property

Evaluate the value to Weak Head Normal Form (WHNF) and fail if it does not result in an expected exception being thrown.

valueassertExceptionIO

:: Exception exc
=> (exc -> Bool)
Return True if that is the exception that was expected
-> IO a
An action that should throw the expected exception
-> Property

Make sure that a specific exception is thrown during an IO action. The result is evaluated to WHNF.

valueassertDeepException

:: (NFData a, Exception exc)
=> (exc -> Bool)
Return True if that is the exception that was expected
-> a
Value that should result in an exception, when fully evaluated to NF
-> Property

Same as assertException, but evaluate the value to Normal Form (NF) and fail if it does not result in an expected exception being thrown.

valueassertDeepExceptionIO

:: (NFData a, Exception exc)
=> (exc -> Bool)
Return True if that is the exception that was expected
-> IO a
An action that should throw the expected exception
-> Property

Make sure that a specific exception is thrown during an IO action. The result is evaluated to NF.