Test.Extrapolate

Extrapolate is a property-based testing library capable of reporting generalized counter-examples.

Consider the following faulty implementation of sort:

sort :: Ord a => [a] -> [a]
sort []      =  []
sort (x:xs)  =  sort (filter (< x) xs)
             ++ [x]
             ++ sort (filter (> x) xs)

When tests pass, Extrapolate works like a regular property-based testing library. See:

> check $ \xs -> sort (sort xs :: [Int]) == sort xs
+++ OK, passed 360 tests.

When tests fail, Extrapolate reports a fully defined counter-example and a generalization of failing inputs. See:

> > check $ \xs -> length (sort xs :: [Int]) == length xs
*** Failed! Falsifiable (after 3 tests):
[0,0]

Generalization:
x:x:_

The property fails for any integer x and for any list _ at the tail.

Checking properties

check :: Testable a => a -> IO ()

Checks a property printing results on stdout

> check $ \xs -> sort (sort xs) == sort (xs::[Int])
+++ OK, passed 360 tests.

> check $ \xs ys -> xs `union` ys == ys `union` (xs::[Int])
*** Failed! Falsifiable (after 4 tests):
[] [0,0]

Generalization:
[] (x:x:_)

checkResult :: Testable a => a -> IO Bool

Check a property printing results on stdout and returning True on success.

There is no option to silence this function: for silence, you should use holds.

for :: Testable a => (WithOption a -> b) -> Int -> a -> b

Use for to configure the number of tests performed by check.

> check `for` 10080 $ \xs -> sort (sort xs) == sort (xs :: [Int])
+++ OK, passed 10080 tests.

Don't forget the dollar ($)!

withBackground :: Testable a => (WithOption a -> b) -> [Expr] -> a -> b

Use withBackground to provide additional functions to appear in side-conditions.

check `withBackground` [constant "isSpace" isSpace] $ \xs -> unwords (words xs) == xs
*** Failed! Falsifiable (after 4 tests):
" "

Generalization:
' ':_

Conditional Generalization:
c:_  when  isSpace c

withConditionSize :: Testable a => (WithOption a -> b) -> Int -> a -> b

Use withConditionSize to configure the maximum condition size allowed.

Generalizable types

class (Listable a, Typeable a, Show a) => Generalizable a where

Extrapolate can generalize counter-examples of any types that are Generalizable.

The core (and only required functions) of the generalizable typeclass are the expr and instances functions.

The following example shows a datatype and its instance:

data Stack a = Stack a (Stack a) | Empty

instance Generalizable a => Generalizable (Stack a) where
name _ = "s"
expr s@(Stack x y) = constant "Stack" (Stack ->>: s) :$ expr x :$ expr y
expr s@Empty       = constant "Empty" (Empty   -: s)
instances s = this s $ instances (argTy1of1 s)

To declare instances and expr it may be useful to use:

• LeanCheck's Test.LeanCheck.Utils.TypeBinding operators: -:, ->:, ->>:, ...;
• Extrapolate's Test.Extrapolate.TypeBinding operators: argTy1of1, argTy1of2, argTy2of2, ....

Minimal complete definition

expr, instances

Methods

expr :: a -> Expr

Transforms a value into an manipulable expression tree. See constant and :$.

name :: a -> String

Common name for a variable, defaults to "x".

background :: a -> [Expr]

List of symbols allowed to appear in side-conditions. Defaults to []. See constant.

instances :: a -> Instances -> Instances

Computes a list of reified instances. See this.

Instances

Generalizable Bool

Methods

expr :: Bool -> Expr

name :: Bool -> String

background :: Bool -> [Expr]

instances :: Bool -> Instances -> Instances

Generalizable Char

Methods

expr :: Char -> Expr

name :: Char -> String

background :: Char -> [Expr]

instances :: Char -> Instances -> Instances

Generalizable Int

Methods

expr :: Int -> Expr

name :: Int -> String

background :: Int -> [Expr]

instances :: Int -> Instances -> Instances

Generalizable Integer

Methods

expr :: Integer -> Expr

name :: Integer -> String

background :: Integer -> [Expr]

instances :: Integer -> Instances -> Instances

Generalizable Ordering

Methods

expr :: Ordering -> Expr

name :: Ordering -> String

background :: Ordering -> [Expr]

instances :: Ordering -> Instances -> Instances

Generalizable ()

Methods

expr :: () -> Expr

name :: () -> String

background :: () -> [Expr]

instances :: () -> Instances -> Instances

Generalizable a => Generalizable [a]

Methods

expr :: [a] -> Expr

name :: [a] -> String

background :: [a] -> [Expr]

instances :: [a] -> Instances -> Instances

Generalizable a => Generalizable (Maybe a)

Methods

expr :: Maybe a -> Expr

name :: Maybe a -> String

background :: Maybe a -> [Expr]

instances :: Maybe a -> Instances -> Instances

(Generalizable a, Generalizable b) => Generalizable (Either a b)

Methods

expr :: Either a b -> Expr

name :: Either a b -> String

background :: Either a b -> [Expr]

instances :: Either a b -> Instances -> Instances

(Generalizable a, Generalizable b) => Generalizable (a, b)

Methods

expr :: (a, b) -> Expr

name :: (a, b) -> String

background :: (a, b) -> [Expr]

instances :: (a, b) -> Instances -> Instances

(Generalizable a, Generalizable b, Generalizable c) => Generalizable (a, b, c)

Methods

expr :: (a, b, c) -> Expr

name :: (a, b, c) -> String

background :: (a, b, c) -> [Expr]

instances :: (a, b, c) -> Instances -> Instances

this :: Generalizable a => a -> (Instances -> Instances) -> Instances -> Instances

data Expr :: *

An encoded Haskell functional-application expression for use by Speculate.

Constructors

Constant String Dynamic

Var String TypeRep

Expr :$ Expr

Instances

Eq Expr

Methods

(==) :: Expr -> Expr -> Bool

(/=) :: Expr -> Expr -> Bool

Ord Expr

Methods

compare :: Expr -> Expr -> Ordering

(<) :: Expr -> Expr -> Bool

(<=) :: Expr -> Expr -> Bool

(>) :: Expr -> Expr -> Bool

(>=) :: Expr -> Expr -> Bool

max :: Expr -> Expr -> Expr

min :: Expr -> Expr -> Expr

Show Expr

Methods

showsPrec :: Int -> Expr -> ShowS

show :: Expr -> String

showList :: [Expr] -> ShowS

constant :: Typeable * a => String -> a -> Expr

Encode a constant Haskell expression for use by Speculate. It takes a string representation of a value and a value, returning an Expr. Examples:

constant "0" 0
constant "'a'" 'a'
constant "True" True
constant "id" (id :: Int -> Int)
constant "(+)" ((+) :: Int -> Int -> Int)
constant "sort" (sort :: [Bool] -> [Bool])

showConstant :: (Typeable * a, Show a) => a -> Expr

A shorthand for constant to be used on values that are Show instances. Examples:

showConstant 0     =  constant "0" 0
showConstant 'a'   =  constant "'a'" 'a' 
showConstant True  =  constant "True" True

bgEq :: (Eq a, Generalizable a) => a -> [Expr]

bgOrd :: (Ord a, Generalizable a) => a -> [Expr]

Testable properties

class Testable a

Minimal complete definition

resultiers, ($-|), tinstances

Instances

Testable Bool

Methods

resultiers :: Bool -> [[([Expr], Bool)]]

($-|) :: Bool -> [Expr] -> Bool

tinstances :: Bool -> Instances

options :: Bool -> Options

Testable a => Testable (WithOption a)

Methods

resultiers :: WithOption a -> [[([Expr], Bool)]]

($-|) :: WithOption a -> [Expr] -> Bool

tinstances :: WithOption a -> Instances

options :: WithOption a -> Options

(Testable b, Generalizable a, Listable a) => Testable (a -> b)

Methods

resultiers :: (a -> b) -> [[([Expr], Bool)]]

($-|) :: (a -> b) -> [Expr] -> Bool

tinstances :: (a -> b) -> Instances

options :: (a -> b) -> Options

Automatically deriving Generalizable instances

deriveGeneralizable :: Name -> DecsQ

Derives a Generalizable instance for a given type Name.

Consider the following Stack datatype:

data Stack a = Stack a (Stack a) | Empty

Writing

deriveGeneralizable ''Stack

will automatically derive the following Generalizable instance:

instance Generalizable a => Generalizable (Stack a) where
  expr s@(Stack x y) = constant "Stack" (Stack ->>: s) :$ expr x :$ expr y
  expr s@Empty       = constant "Empty" (Empty   -: s)
  instances s = this "s" s
              $ let Stack x y = Stack undefined undefined `asTypeOf` s
                in instances x
                 . instances y

This function needs the TemplateHaskell extension.

deriveGeneralizableIfNeeded :: Name -> DecsQ

Same as deriveGeneralizable but does not warn when instance already exists (deriveGeneralizable is preferable).

deriveGeneralizableCascading :: Name -> DecsQ

Derives a Generalizable instance for a given type Name cascading derivation of type arguments as well.

Other useful modules

module Test.Extrapolate.TypeBinding

module Test.LeanCheck

module Test.LeanCheck.Utils.TypeBinding

ordering :: Ordering