leancheck: Cholesterol-free property-based testing

[ bsd3, library, testing ] [ Propose Tags ]

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]

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees

Candidates

  • No Candidates
Versions [RSS] 0.3.0, 0.4.0, 0.4.1, 0.5.0, 0.6.0, 0.6.1, 0.6.2, 0.6.3, 0.6.4, 0.6.5, 0.6.6, 0.6.7, 0.7.0, 0.7.1, 0.7.2, 0.7.3, 0.7.4, 0.7.5, 0.7.6, 0.7.7, 0.8.0, 0.9.0, 0.9.1, 0.9.2, 0.9.3, 0.9.4, 0.9.6, 0.9.8, 0.9.10, 0.9.12, 1.0.0, 1.0.2
Dependencies base (>=4 && <5), template-haskell [details]
License BSD-3-Clause
Author Rudy Matela <rudy@matela.com.br>
Maintainer Rudy Matela <rudy@matela.com.br>
Category Testing
Home page https://github.com/rudymatela/leancheck#readme
Source repo head: git clone https://github.com/rudymatela/leancheck
this: git clone https://github.com/rudymatela/leancheck(tag v0.6.2)
Uploaded by rudymatela at 2017-03-28T15:53:03Z
Distributions Arch:1.0.2, LTSHaskell:1.0.2, NixOS:1.0.2, Stackage:1.0.2
Reverse Dependencies 11 direct, 33 indirect [details]
Downloads 19713 total (135 in the last 30 days)
Rating 2.25 (votes: 2) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs uploaded by user
Build status unknown [no reports yet]

Readme for leancheck-0.6.2

[back to package description]

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).