The leancheck package

This is a package candidate release! Here you can preview how this package release will appear once published to the main package index (which can be accomplished via the 'maintain' link below). Please note that once a package has been published to the main package index it cannot be undone! Please consult the package uploading documentation for more information.

[maintain]

LeanCheck is a simple enumerative property-based testing library.

Properties are defined as Haskell functions returning a boolean value which should be true for all possible choices of argument values. LeanCheck applies enumerated argument values to these properties in search for a counterexample. Properties can be viewed as parameterized unit tests.

LeanCheck works by producing tiers of test values: a possibly infinite list of finite sublists of same-and-increasingly-sized values.

LeanCheck has lean core with only 180 lines of Haskell code.


[Skip to ReadMe]

Properties

Versions0.3.0, 0.4.0, 0.4.1, 0.5.0, 0.6.0, 0.6.1, 0.6.2, 0.6.2
Change logNone available
Dependenciesbase (==4.*), template-haskell [details]
LicenseBSD3
AuthorRudy Matela <rudy@matela.com.br>
MaintainerRudy Matela <rudy@matela.com.br>
CategoryTesting
Home pagehttps://github.com/rudymatela/leancheck#readme
Source repositoryhead: git clone https://github.com/rudymatela/leancheck
this: git clone https://github.com/rudymatela/leancheck(tag v0.6.2)
UploadedTue Mar 28 15:52:15 UTC 2017 by rudymatela

Modules

[Index]

Downloads

Maintainers' corner

For package maintainers and hackage trustees

Readme for leancheck-0.6.2

LeanCheck

Build Status Hackage version

LeanCheck is a simple enumerative property-based testing library. Properties are defined as Haskell functions returning a boolean value which should be True for all possible choices of argument values. LeanCheck applies enumerated argument values to these properties in search for a counterexample. Properties can be viewed as parameterized unit tests.

LeanCheck works by producing tiers of test values: a possibly infinite list of finite sublists of same-and-increasingly-sized values. This enumeration is similar to Feat's. However, the ranking and ordering of values are defined differently. The interface is also different.

In this README, lines ending with -- > indicate expected return values.

Installing

To install the latest LeanCheck version from Hackage, just run:

$ cabal update
$ cabal install leancheck

Checking if properties are True

To check if properties are True, just use the function holds :: Testable a => Int -> a -> Bool. It takes two arguments: the number of values to test and a property (function returning Bool), then, it returns a boolean indicating whether the property holds. See (ghci):

import Test.LeanCheck
import Data.List
holds 100 $ \xs -> sort (sort xs) == sort (xs::[Int])  -- > True
holds 100 $ \xs -> [] `union` xs == (xs::[Int])        -- > False

Finding counter examples

To find counter examples to properties, you can use the function counterExample :: Testable a => Int -> a -> Maybe [String]. It takes two arguments: the number of values to test and a property (function returning Bool). Then, it returns Nothing if no results are found or Just a list of Strings representing the offending arguments to the property. See (ghci):

import Test.LeanCheck
import Data.List

counterExample 100 $ \xs -> sort (sort xs) == sort (xs::[Int])
-- > Nothing

counterExample 100 $ \xs -> [] `union` xs == (xs::[Int])
-- > Just ["[0,0]"]

counterExample 100 $ \xs ys -> xs `union` ys == ys `union` (xs::[Int])
-- > Just ["[]","[0,0]"]

Checking properties like in SmallCheck/QuickCheck

To "check" properties like in SmallCheck and QuickCheck automatically printing results on standard output, you can use the function check :: Testable a => a -> IO ().

import Test.LeanCheck
import Data.List

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

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

The function check tests for a maximum of 200 tests. To check for a maximum of n tests, use checkFor n. To get a boolean result wrapped in IO, use checkResult or checkResultFor. There is no "quiet" option, just use holds or counterExample in that case.

Testing user-defined types

LeanCheck works on properties with Listable argument types. Listable instances are declared similarly to SmallCheck:

data MyType = MyConsA
            | MyConsB Int
            | MyConsC Int Char
            | MyConsD String

instance Listable MyType where
  tiers = cons0 MyConsA
       \/ cons1 MyConsB
       \/ cons2 MyConsC
       \/ cons1 MyConsD

The tiers function return a potentially infinite list of finite sub-lists (tiers). Each successive tier has values of increasing size.

tiers :: Listable a => [[a]]

For convenience, the function list returns a potentially infinite list of values of the bound type:

list :: Listable a => [a]

So, for example:

take 5 (list :: [(Int,Int)]) -- > [(0,0),(0,1),(1,0),(0,-1),(1,1)]

The list function can be used to debug your custom instances.

Listable class instances are more customizable than what is described here: check source comments or haddock documentation for details.

Further reading

For a detailed documentation of each function, see LeanCheck's Haddock documentation.

For an introduction to property-based testing and a step-by-step guide to LeanCheck, see the tutorial on property-based testing with LeanCheck (doc/tutorial.md in the source repository).