Test.QuickCheck.Classes

This library provides lists of properties that should hold for common typeclasses. All of these take a Proxy argument that is used to nail down the type for which the typeclass dictionaries should be tested. For example, at GHCi:

>>> lawsCheck (monoidLaws (Proxy :: Proxy Ordering))
Monoid: Associative +++ OK, passed 100 tests.
Monoid: Left Identity +++ OK, passed 100 tests.
Monoid: Right Identity +++ OK, passed 100 tests.

Assuming that the Arbitrary instance for Ordering is good, we now have confidence that the Monoid instance for Ordering satisfies the monoid laws. We can check multiple typeclasses with:

>>> foldMap (lawsCheck . ($ (Proxy :: Proxy Word))) [jsonLaws,showReadLaws]
ToJSON/FromJSON: Encoding Equals Value +++ OK, passed 100 tests.
ToJSON/FromJSON: Partial Isomorphism +++ OK, passed 100 tests.
Show/Read: Partial Isomorphism +++ OK, passed 100 tests.

Running

lawsCheck :: Laws -> IO ()

A convenience function for working testing properties in GHCi. See the test suite of this library for an example of how to integrate multiple properties into larger test suite.

lawsCheckMany

Arguments

:: [(String, [Laws])]

Element is type name paired with typeclass laws

-> IO ()

A convenience function for checking multiple typeclass instances of multiple types.

Properties

Ground Types

commutativeMonoidLaws :: (Monoid a, Eq a, Arbitrary a, Show a) => Proxy a -> Laws

Tests everything from monoidProps plus the following:

Commutative

mappend a b ≡ mappend b a

eqLaws :: (Eq a, Arbitrary a, Show a) => Proxy a -> Laws

Tests the following properties:

Transitive

a == b ∧ b == c ⇒ a == c

Symmetric

a == b ⇒ b == a

Reflexive

a == a

Some of these properties involve implication. In the case that the left hand side of the implication arrow does not hold, we do not retry. Consequently, these properties only end up being useful when the data type has a small number of inhabitants.

ordLaws :: (Ord a, Arbitrary a, Show a) => Proxy a -> Laws

Tests the following properties:

Antisymmetry

@a ≤ b ∧ b ≤ a ⇒ a = b

Transitivity

a ≤ b ∧ b ≤ c ⇒ a ≤ c

Totality

a ≤ b ∨ a > b

showReadLaws :: (Show a, Read a, Eq a, Arbitrary a) => Proxy a -> Laws

jsonLaws :: (ToJSON a, FromJSON a, Show a, Arbitrary a, Eq a) => Proxy a -> Laws

Tests the following properties:

Partial Isomorphism

decode . encode ≡ Just

Encoding Equals Value

decode . encode ≡ Just . toJSON

Note that in the second propertiy, the type of decode is ByteString -> Value, not ByteString -> a

integralLaws :: (Integral a, Arbitrary a, Show a) => Proxy a -> Laws

Tests the following properties:

Quotient Remainder

(quot x y) * y + (rem x y) ≡ x

Division Modulus

(div x y) * y + (mod x y) ≡ x

Integer Roundtrip

fromInteger (toInteger x) ≡ x

monoidLaws :: (Monoid a, Eq a, Arbitrary a, Show a) => Proxy a -> Laws

Tests the following properties:

Associative

mappend a (mappend b c) ≡ mappend (mappend a b) c

Left Identity

mappend mempty a ≡ a

Right Identity

mappend a mempty ≡ a

ordLaws :: (Ord a, Arbitrary a, Show a) => Proxy a -> Laws

Tests the following properties:

Antisymmetry

@a ≤ b ∧ b ≤ a ⇒ a = b

Transitivity

a ≤ b ∧ b ≤ c ⇒ a ≤ c

Totality

a ≤ b ∨ a > b

primLaws :: (Prim a, Eq a, Arbitrary a, Show a) => Proxy a -> Laws

Test that a Prim instance obey the several laws.

semigroupLaws :: (Semigroup a, Eq a, Arbitrary a, Show a) => Proxy a -> Laws

Tests the following properties:

Associative

a <> (b <> c) ≡ (a <> b) <> c

showReadLaws :: (Show a, Read a, Eq a, Arbitrary a) => Proxy a -> Laws

storableLaws :: (Storable a, Eq a, Arbitrary a, Show a) => Proxy a -> Laws

integralLaws :: (Integral a, Arbitrary a, Show a) => Proxy a -> Laws

Tests the following properties:

Quotient Remainder

(quot x y) * y + (rem x y) ≡ x

Division Modulus

(div x y) * y + (mod x y) ≡ x

Integer Roundtrip

fromInteger (toInteger x) ≡ x

bitsLaws :: (FiniteBits a, Arbitrary a, Show a) => Proxy a -> Laws

Tests the following properties:

Conjunction Idempotence

n .&. n ≡ n

Disjunction Idempotence

n .|. n ≡ n

Double Complement

complement (complement n) ≡ n

Set Bit

setBit n i ≡ n .|. bit i

Clear Bit

clearBit n i ≡ n .&. complement (bit i)

Complement Bit

complementBit n i ≡ xor n (bit i)

Clear Zero

clearBit zeroBits i ≡ zeroBits

Set Zero

setBit zeroBits i ≡ bit i

Test Zero

testBit zeroBits i ≡ False

Pop Zero

popCount zeroBits ≡ 0

Count Leading Zeros of Zero

countLeadingZeros zeroBits ≡ finiteBitSize ⊥

Count Trailing Zeros of Zero

countTrailingZeros zeroBits ≡ finiteBitSize ⊥

All of the useful instances of the Bits typeclass also have FiniteBits instances, so these property tests actually require that instance as well.

Note: This property test is only available when using base-4.7 or newer.

isListLaws :: (IsList a, Show a, Show (Item a), Arbitrary a, Arbitrary (Item a), Eq a) => Proxy a -> Laws

Tests the following properties:

Partial Isomorphism

fromList . toList ≡ id

Length Preservation

fromList xs ≡ fromListN (length xs) xs

Note: This property test is only available when using base-4.7 or newer.

Higher-Kinded Types

altLaws :: (Alt f, Eq1 f, Show1 f, Arbitrary1 f) => proxy f -> Laws

Tests the following alt properties:

Associativity

(a <!> b) <!> c ≡ a <!> (b <!> c)

Left Distributivity

@f <$> (a <!> b) = (f <$> a) <!> (f <$> b)

alternativeLaws :: (Alternative f, Eq1 f, Show1 f, Arbitrary1 f) => proxy f -> Laws

Tests the following alternative properties:

Identity

empty <|> x ≡ x x <|> empty ≡ x

Associativity

a <|> (b <|> c) ≡ (a <|> b) <|> c)

applicativeLaws :: (Applicative f, Eq1 f, Show1 f, Arbitrary1 f) => proxy f -> Laws

Tests the following applicative properties:

Identity

pure id <*> v ≡ v

Composition

pure (.) <*> u <*> v <*> w ≡ u <*> (v <*> w)

Homomorphism

pure f <*> pure x ≡ pure (f x)

Interchange

u <*> pure y ≡ pure ($ y) <*> u

LiftA2 (1)

(<*>) ≡ liftA2 id

foldableLaws :: (Foldable f, Eq1 f, Show1 f, Arbitrary1 f) => proxy f -> Laws

Tests the following Foldable properties:

fold

fold ≡ foldMap id

foldMap

foldMap f ≡ foldr (mappend . f) mempty

foldr

foldr f z t ≡ appEndo (foldMap (Endo . f) t ) z

foldr'

foldr' f z0 xs = let f' k x z = k $! f x z in foldl f' id xs z0

foldr1

foldr1 f t ≡ let Just (xs,x) = unsnoc (toList t) in foldr f x xs

foldl

foldl f z t ≡ appEndo (getDual (foldMap (Dual . Endo . flip f) t)) z

foldl'

foldl' f z0 xs ≡ let f' x k z = k $! f z x in foldr f' id xs z0

foldl1

foldl1 f t ≡ let x : xs = toList t in foldl f x xs

toList

toList ≡ foldr (:) []

null

null ≡ foldr (const (const False)) True

length

length ≡ getSum . foldMap (const (Sum 1))

Note that this checks to ensure that foldl' and foldr' are suitably strict.

traversableLaws :: (Traversable f, Eq1 f, Show1 f, Arbitrary1 f) => proxy f -> Laws

Tests the following Traversable properties:

Naturality

t . traverse f = traverse (t . f) for every applicative transformation t

Identity

traverse Identity = Identity

Composition

traverse (Compose . fmap g . f) = Compose . fmap (traverse g) . traverse f

Sequence Naturality

t . sequenceA = sequenceA . fmap t for every applicative transformation t

Sequence Identity

sequenceA . fmap Identity = Identity

Sequence Composition

sequenceA . fmap Compose = Compose . fmap sequenceA . sequenceA

foldMap

foldMap = foldMapDefault

fmap

fmap = fmapDefault

Where an applicative transformation is a function

t :: (Applicative f, Applicative g) => f a -> g a

preserving the Applicative operations, i.e.

• Identity: t (pure x) = pure x
• Distributivity: t (x <*> y) = t x <*> t y

functorLaws :: (Functor f, Eq1 f, Show1 f, Arbitrary1 f) => proxy f -> Laws

Tests the following functor properties:

Identity

fmap id ≡ id

Composition

fmap (f . g) ≡ fmap f . fmap g

Const

(<$) ≡ fmap const

monadLaws :: (Monad f, Applicative f, Eq1 f, Show1 f, Arbitrary1 f) => proxy f -> Laws

Tests the following monadic properties:

Left Identity

return a >>= k ≡ k a

Right Identity

m >>= return ≡ m

Associativity

m >>= (\x -> k x >>= h) ≡ (m >>= k) >>= h

Return

pure ≡ return

Ap

(<*>) ≡ ap

bifunctorLaws :: (Bifunctor f, Eq2 f, Show2 f, Arbitrary2 f) => proxy f -> Laws

Tests the following Bifunctor properties:

Identity

bimap id id ≡ id

First Identity

first id ≡ id

Second Identity

second id ≡ id

Bifunctor Composition

bimap f g ≡ first f . second g

Note: This property test is only available when this package is built with base-4.9+ or transformers-0.5+.

Types

data Laws

A set of laws associated with a typeclass.

Constructors

Laws

Fields

• lawsTypeclass :: String

  Name of the typeclass whose laws are tested

• lawsProperties :: [(String, Property)]

  Pairs of law name and property