-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | A property-based testing library
--   
--   SmallCheck is a testing library that allows to verify properties for
--   all test cases up to some depth. The test cases are generated
--   automatically by SmallCheck.
@package smallcheck
@version 0.6


-- | Generation of test data.
module Test.SmallCheck.Series

-- | Maximum depth of generated test values
--   
--   For data values, it is the depth of nested constructor applications.
--   
--   For functional values, it is both the depth of nested case analysis
--   and the depth of results.
type Depth = Int

-- | <a>Series</a> is a function from the depth to a finite list of values.
type Series a = Depth -> [a]
class Serial a
series :: Serial a => Series a
coseries :: Serial a => Series b -> Series (a -> b)
cons0 :: a -> Series a
cons1 :: Serial a => (a -> b) -> Series b
cons2 :: (Serial a, Serial b) => (a -> b -> c) -> Series c
cons3 :: (Serial a, Serial b, Serial c) => (a -> b -> c -> d) -> Series d
cons4 :: (Serial a, Serial b, Serial c, Serial d) => (a -> b -> c -> d -> e) -> Series e
alts0 :: Series a -> Series a
alts1 :: Serial a => Series b -> Series (a -> b)
alts2 :: (Serial a, Serial b) => Series c -> Series (a -> b -> c)
alts3 :: (Serial a, Serial b, Serial c) => Series d -> Series (a -> b -> c -> d)
alts4 :: (Serial a, Serial b, Serial c, Serial d) => Series e -> Series (a -> b -> c -> d -> e)

-- | Sum (union) of series
(\/) :: Series a -> Series a -> Series a

-- | Product of series
(><) :: Series a -> Series b -> Series (a, b)

-- | <a>N</a> is a wrapper for <a>Integral</a> types that causes only
--   non-negative values to be generated. Generated functions of type <tt>N
--   a -&gt; b</tt> do not distinguish different negative values of
--   <tt>a</tt>.
--   
--   See also <a>Nat</a> and <a>Natural</a>.
newtype N a
N :: a -> N a
type Nat = N Int
type Natural = N Integer

-- | For customising the depth measure. Use with care!
depth :: Depth -> Depth -> Depth
instance Eq a => Eq (N a)
instance Ord a => Ord (N a)
instance (Serial a, Show a, Show b) => Show (a -> b)
instance (Serial a, Serial b) => Serial (a -> b)
instance Serial a => Serial [a]
instance (Serial a, Serial b) => Serial (Either a b)
instance Serial a => Serial (Maybe a)
instance Serial Bool
instance (Serial a, Serial b, Serial c, Serial d) => Serial (a, b, c, d)
instance (Serial a, Serial b, Serial c) => Serial (a, b, c)
instance (Serial a, Serial b) => Serial (a, b)
instance Serial Char
instance Serial Double
instance Serial Float
instance (Integral a, Serial a) => Serial (N a)
instance Show a => Show (N a)
instance Serial Integer
instance Serial Int
instance Serial ()
instance GSerial f => GSerialSum (C1 c f)
instance (GSerialSum a, GSerialSum b) => GSerialSum (a :+: b)
instance (GSerialSum a, GSerialSum b) => GSerial (a :+: b)
instance (GSerial a, GSerial b) => GSerial (a :*: b)
instance GSerial U1
instance Serial c => GSerial (K1 i c)
instance GSerial f => GSerial (M1 i c f)


-- | Properties and tools to construct them.
module Test.SmallCheck.Property
data TestCase
TestCase :: TestResult -> [String] -> TestCase
result :: TestCase -> TestResult
arguments :: TestCase -> [String]
data TestResult
Pass :: TestResult
Fail :: TestResult

-- | <a>Inappropriate</a> means that the precondition of <a>==&gt;</a> was
--   not satisfied
Inappropriate :: TestResult

-- | Return <a>False</a> iff the result is <a>Fail</a>
resultIsOk :: TestResult -> Bool

-- | Wrapper type for <a>Testable</a>s
data Property

-- | Maximum depth of generated test values
--   
--   For data values, it is the depth of nested constructor applications.
--   
--   For functional values, it is both the depth of nested case analysis
--   and the depth of results.
type Depth = Int

-- | Anything of a <a>Testable</a> type can be regarded as a "test"
class Testable a
test :: Testable a => a -> Depth -> [TestCase]

-- | Wrap a <a>Testable</a> into a <a>Property</a>
property :: Testable a => a -> Property

-- | A lower-level way to create properties. Use <a>property</a> if
--   possible.
--   
--   The argument is a function that produces the list of results given the
--   depth of testing.
mkProperty :: (Depth -> [TestCase]) -> Property

-- | The <a>==&gt;</a> operator can be used to express a restricting
--   condition under which a property should hold. For example, testing a
--   propositional-logic module (see examples/logical), we might define:
--   
--   <pre>
--   prop_tautEval :: Proposition -&gt; Environment -&gt; Property
--   prop_tautEval p e =
--     tautology p ==&gt; eval p e
--   </pre>
--   
--   But here is an alternative definition:
--   
--   <pre>
--   prop_tautEval :: Proposition -&gt; Property
--   prop_taut p =
--     tautology p ==&gt; \e -&gt; eval p e
--   </pre>
--   
--   The first definition generates p and e for each test, whereas the
--   second only generates e if the tautology p holds.
--   
--   The second definition is far better as the test-space is reduced from
--   PE to T'+TE where P, T, T' and E are the numbers of propositions,
--   tautologies, non-tautologies and environments.
(==>) :: Testable a => Bool -> a -> Property

-- | <tt><a>exists</a> p</tt> holds iff it is possible to find an argument
--   <tt>a</tt> (within the depth constraints!) satisfying the predicate
--   <tt>p</tt>
exists :: (Show a, Serial a, Testable b) => (a -> b) -> Property

-- | The default testing of existentials is bounded by the same depth as
--   their context. This rule has important consequences. Just as a
--   universal property may be satisfied when the depth bound is shallow
--   but fail when it is deeper, so the reverse may be true for an
--   existential property. So when testing properties involving
--   existentials it may be appropriate to try deeper testing after a
--   shallow failure. However, sometimes the default same-depth-bound
--   interpretation of existential properties can make testing of a valid
--   property fail at all depths. Here is a contrived but illustrative
--   example:
--   
--   <pre>
--   prop_append1 :: [Bool] -&gt; [Bool] -&gt; Property
--   prop_append1 xs ys = exists $ \zs -&gt; zs == xs++ys
--   </pre>
--   
--   <a>existsDeeperBy</a> transforms the depth bound by a given
--   <tt><a>Depth</a> -&gt; <a>Depth</a></tt> function:
--   
--   <pre>
--   prop_append2 :: [Bool] -&gt; [Bool] -&gt; Property
--   prop_append2 xs ys = existsDeeperBy (*2) $ \zs -&gt; zs == xs++ys
--   </pre>
existsDeeperBy :: (Show a, Serial a, Testable b) => (Depth -> Depth) -> (a -> b) -> Property

-- | Like <a>exists</a>, but additionally require the uniqueness of the
--   argument satisfying the predicate
exists1 :: (Show a, Serial a, Testable b) => (a -> b) -> Property

-- | Like <a>existsDeeperBy</a>, but additionally require the uniqueness of
--   the argument satisfying the predicate
exists1DeeperBy :: (Show a, Serial a, Testable b) => (Depth -> Depth) -> (a -> b) -> Property
forAll :: (Show a, Testable b) => Series a -> (a -> b) -> Property
forAllElem :: (Show a, Testable b) => [a] -> (a -> b) -> Property
thereExists :: (Show a, Testable b) => Series a -> (a -> b) -> Property
thereExistsElem :: (Show a, Testable b) => [a] -> (a -> b) -> Property
thereExists1 :: (Show a, Testable b) => Series a -> (a -> b) -> Property
thereExists1Elem :: (Show a, Testable b) => [a] -> (a -> b) -> Property
instance Testable Property
instance (Serial a, Show a, Testable b) => Testable (a -> b)
instance Testable Bool


-- | Functions to run SmallCheck tests.
module Test.SmallCheck.Drivers

-- | Run series of tests using depth bounds 0..d, stopping if any test
--   fails, and print a summary report or a counter-example.
smallCheck :: Testable a => Depth -> a -> IO ()

-- | Interactive variant, asking the user whether testing should
--   continue/go deeper after a failure/completed iteration.
--   
--   Example session:
--   
--   <pre>
--   haskell&gt; smallCheckI prop_append1
--   Depth 0:
--     Completed 1 test(s) without failure.
--     Deeper? y
--   Depth 1:
--     Failed test no. 5. Test values follow.
--     [True]
--     [True]
--     Continue? n
--     Deeper? n
--   haskell&gt;
--   </pre>
smallCheckI :: Testable a => a -> IO ()

-- | Same as <a>smallCheck</a>, but test for values of depth d only
depthCheck :: Testable a => Depth -> a -> IO ()


-- | This module exports the main pieces of SmallCheck functionality.
--   
--   For pointers to other sources of information about SmallCheck, please
--   refer to the README at
--   <a>https://github.com/feuerbach/smallcheck/blob/master/README.md</a>
module Test.SmallCheck

-- | Anything of a <a>Testable</a> type can be regarded as a "test"
class Testable a

-- | Wrapper type for <a>Testable</a>s
data Property

-- | Wrap a <a>Testable</a> into a <a>Property</a>
property :: Testable a => a -> Property

-- | <tt><a>exists</a> p</tt> holds iff it is possible to find an argument
--   <tt>a</tt> (within the depth constraints!) satisfying the predicate
--   <tt>p</tt>
exists :: (Show a, Serial a, Testable b) => (a -> b) -> Property

-- | Like <a>exists</a>, but additionally require the uniqueness of the
--   argument satisfying the predicate
exists1 :: (Show a, Serial a, Testable b) => (a -> b) -> Property

-- | The default testing of existentials is bounded by the same depth as
--   their context. This rule has important consequences. Just as a
--   universal property may be satisfied when the depth bound is shallow
--   but fail when it is deeper, so the reverse may be true for an
--   existential property. So when testing properties involving
--   existentials it may be appropriate to try deeper testing after a
--   shallow failure. However, sometimes the default same-depth-bound
--   interpretation of existential properties can make testing of a valid
--   property fail at all depths. Here is a contrived but illustrative
--   example:
--   
--   <pre>
--   prop_append1 :: [Bool] -&gt; [Bool] -&gt; Property
--   prop_append1 xs ys = exists $ \zs -&gt; zs == xs++ys
--   </pre>
--   
--   <a>existsDeeperBy</a> transforms the depth bound by a given
--   <tt><a>Depth</a> -&gt; <a>Depth</a></tt> function:
--   
--   <pre>
--   prop_append2 :: [Bool] -&gt; [Bool] -&gt; Property
--   prop_append2 xs ys = existsDeeperBy (*2) $ \zs -&gt; zs == xs++ys
--   </pre>
existsDeeperBy :: (Show a, Serial a, Testable b) => (Depth -> Depth) -> (a -> b) -> Property

-- | Like <a>existsDeeperBy</a>, but additionally require the uniqueness of
--   the argument satisfying the predicate
exists1DeeperBy :: (Show a, Serial a, Testable b) => (Depth -> Depth) -> (a -> b) -> Property

-- | The <a>==&gt;</a> operator can be used to express a restricting
--   condition under which a property should hold. For example, testing a
--   propositional-logic module (see examples/logical), we might define:
--   
--   <pre>
--   prop_tautEval :: Proposition -&gt; Environment -&gt; Property
--   prop_tautEval p e =
--     tautology p ==&gt; eval p e
--   </pre>
--   
--   But here is an alternative definition:
--   
--   <pre>
--   prop_tautEval :: Proposition -&gt; Property
--   prop_taut p =
--     tautology p ==&gt; \e -&gt; eval p e
--   </pre>
--   
--   The first definition generates p and e for each test, whereas the
--   second only generates e if the tautology p holds.
--   
--   The second definition is far better as the test-space is reduced from
--   PE to T'+TE where P, T, T' and E are the numbers of propositions,
--   tautologies, non-tautologies and environments.
(==>) :: Testable a => Bool -> a -> Property

-- | Run series of tests using depth bounds 0..d, stopping if any test
--   fails, and print a summary report or a counter-example.
smallCheck :: Testable a => Depth -> a -> IO ()

-- | Same as <a>smallCheck</a>, but test for values of depth d only
depthCheck :: Testable a => Depth -> a -> IO ()

-- | Interactive variant, asking the user whether testing should
--   continue/go deeper after a failure/completed iteration.
--   
--   Example session:
--   
--   <pre>
--   haskell&gt; smallCheckI prop_append1
--   Depth 0:
--     Completed 1 test(s) without failure.
--     Deeper? y
--   Depth 1:
--     Failed test no. 5. Test values follow.
--     [True]
--     [True]
--     Continue? n
--     Deeper? n
--   haskell&gt;
--   </pre>
smallCheckI :: Testable a => a -> IO ()

-- | Maximum depth of generated test values
--   
--   For data values, it is the depth of nested constructor applications.
--   
--   For functional values, it is both the depth of nested case analysis
--   and the depth of results.
type Depth = Int