-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Safe reimplementation of QuickCheck's core
--
-- QuickCheck-safe reimplements the quickCheck functionality with a pure
-- interface and a very small trusted base (see
-- Test.QuickCheck.Safe.Trusted).
--
--
-- - uses the existing Arbitrary instances
-- - implemented features: testing, result minimization (i.e.,
-- shrinking)
-- - missing features: expected failures, label frequencies,
-- coverage
--
--
-- The package is targeted at users who want to leverage SafeHaskell for
-- sandboxing.
--
--
-- >>> putStr $ quickCheck (inventQCGen ()) (\x -> length (x :: [()]) < 10)
-- *** Failed! Falsifiable (after 18 tests and 3 shrinks):
-- [(),(),(),(),(),(),(),(),(),(),(),(),(),(),()]
--
@package QuickCheck-safe
@version 0.1.0.5
module Test.QuickCheck.Safe.Trusted
-- | pureEvaluate wraps tryEvaluate in
-- unsafePerformIO. This may look like a dirty hack, but this
-- building block allows us to implement most of QuickCheck's
-- functionality without resorting to IO again.
pureEvaluate :: a -> Either AnException a
type AnException = SomeException
-- | inventQCGen invokes newQCGen via unsafePerformIO.
-- It is useful in connection with the quickCheck family of
-- functions.
inventQCGen :: a -> QCGen
-- | The "standard" QuickCheck random number generator. A wrapper around
-- either TFGen on GHC, or StdGen on other Haskell systems.
data QCGen
-- | This module implements a simplified, pure version of Test.Quickcheck's
-- quickCheck functionality.
module Test.QuickCheck.Safe
-- | Cf. quickCheck. Note that in contrast to QuickCheck's function,
-- this one takes an additional QCGen argument.
--
--
-- >>> putStr $ quickCheck (inventQCGen ()) (\x -> length (x :: [()]) < 10)
-- *** Failed! Falsifiable (after 18 tests and 3 shrinks):
-- [(),(),(),(),(),(),(),(),(),(),(),(),(),(),()]
--
quickCheck :: STestable prop => QCGen -> prop -> String
-- | Cf. quickCheckResult. Note that in contrast to QuickCheck's
-- function, this one takes an additional QCGen argument.
quickCheckResult :: STestable prop => QCGen -> prop -> Result
-- | Cf. quickCheckWith. Note that in contrast to QuickCheck's
-- function, this one takes an additional QCGen argument.
quickCheckWith :: STestable prop => Args -> QCGen -> prop -> String
-- | Cf. quickCheckWithResult. Note that in contrast to QuickCheck's
-- function, this one takes an additional QCGen argument.
quickCheckWithResult :: STestable prop => Args -> QCGen -> prop -> Result
class STestable prop
-- | Implication. Cf. ==>.
(==>) :: STestable prop => Bool -> prop -> SProperty
-- | Disjunction. Cf. .||..
(.||.) :: (STestable prop2, STestable prop1) => prop1 -> prop2 -> SProperty
-- | Conjunction. Cf. .&&..
(.&&.) :: (STestable prop2, STestable prop1) => prop1 -> prop2 -> SProperty
-- | Nondeterministic conjunction. Cf. &..
(.&.) :: (STestable prop2, STestable prop1) => prop1 -> prop2 -> SProperty
-- | Equality test. Cf. ===.
(===) :: (Eq a, Show a) => a -> a -> SProperty
-- | Label tests. Cf. label.
label :: STestable prop => String -> prop -> SProperty
-- | Shrink counterexamples. Cf. shrinking.
shrinking :: STestable prop => (a -> [a]) -> a -> (a -> prop) -> SProperty
-- | Suppress shrinking of counterexamples. Cf. noShrinking.
noShrinking :: STestable prop => prop -> SProperty
-- | Adjust testcase sizes. Cf. mapSize.
mapSize :: STestable prop => (Int -> Int) -> prop -> SProperty
-- | Universal quantification. Cf. forAll.
forAll :: (Show a, STestable prop) => Gen a -> (a -> prop) -> SProperty
-- | Universal quantification with shrinking. Cf. forAllShrink.
forAllShrink :: (Show a, STestable prop) => Gen a -> (a -> [a]) -> (a -> prop) -> SProperty
-- | inventQCGen invokes newQCGen via unsafePerformIO.
-- It is useful in connection with the quickCheck family of
-- functions.
inventQCGen :: a -> QCGen
-- | A variant of labelledExamples that takes test arguments and
-- returns a result.
labelledExamplesWithResult :: Testable prop => Args -> prop -> IO Result
-- | A variant of labelledExamples that returns a result.
labelledExamplesResult :: Testable prop => prop -> IO Result
-- | A variant of labelledExamples that takes test arguments.
labelledExamplesWith :: Testable prop => Args -> prop -> IO ()
-- | Given a property, which must use label, collect,
-- classify or cover to associate labels with test cases,
-- find an example test case for each possible label. The example test
-- cases are minimised using shrinking.
--
-- For example, suppose we test delete x xs and record
-- the number of times that x occurs in xs:
--
--
-- prop_delete :: Int -> [Int] -> Property
-- prop_delete x xs =
-- classify (count x xs == 0) "count x xs == 0" $
-- classify (count x xs == 1) "count x xs == 1" $
-- classify (count x xs >= 2) "count x xs >= 2" $
-- counterexample (show (delete x xs)) $
-- count x (delete x xs) == max 0 (count x xs-1)
-- where count x xs = length (filter (== x) xs)
--
--
-- labelledExamples generates three example test cases, one for
-- each label:
--
--
-- >>> labelledExamples prop_delete
-- *** Found example of count x xs == 0
-- 0
-- []
-- []
--
-- *** Found example of count x xs == 1
-- 0
-- [0]
-- []
--
-- *** Found example of count x xs >= 2
-- 5
-- [5,5]
-- [5]
--
-- +++ OK, passed 100 tests:
-- 78% count x xs == 0
-- 21% count x xs == 1
-- 1% count x xs >= 2
--
labelledExamples :: Testable prop => prop -> IO ()
-- | Test all properties in the current module. This is just a convenience
-- function that combines quickCheckAll and verbose.
--
-- verboseCheckAll has the same issue with scoping as
-- quickCheckAll: see the note there about return [].
verboseCheckAll :: Q Exp
-- | Test all properties in the current module. The name of the property
-- must begin with prop_. Polymorphic properties will be
-- defaulted to Integer. Returns True if all tests
-- succeeded, False otherwise.
--
-- To use quickCheckAll, add a definition to your module along the
-- lines of
--
--
-- return []
-- runTests = $quickCheckAll
--
--
-- and then execute runTests.
--
-- Note: the bizarre return [] in the example above is needed on
-- GHC 7.8 and later; without it, quickCheckAll will not be able
-- to find any of the properties. For the curious, the return []
-- is a Template Haskell splice that makes GHC insert the empty list of
-- declarations at that point in the program; GHC typechecks everything
-- before the return [] before it starts on the rest of the
-- module, which means that the later call to quickCheckAll can
-- see everything that was defined before the return []. Yikes!
quickCheckAll :: Q Exp
-- | List all properties in the current module.
--
-- $allProperties has type [(String,
-- Property)].
--
-- allProperties has the same issue with scoping as
-- quickCheckAll: see the note there about return [].
allProperties :: Q Exp
-- | Test all properties in the current module, using a custom
-- quickCheck function. The same caveats as with
-- quickCheckAll apply.
--
-- $forAllProperties has type (Property ->
-- IO Result) -> IO Bool. An example
-- invocation is $forAllProperties
-- quickCheckResult, which does the same thing as
-- $quickCheckAll.
--
-- forAllProperties has the same issue with scoping as
-- quickCheckAll: see the note there about return [].
forAllProperties :: Q Exp
-- | Monomorphise an arbitrary property by defaulting all type variables to
-- Integer.
--
-- For example, if f has type Ord a => [a] ->
-- [a] then $(monomorphic 'f) has type
-- [Integer] -> [Integer].
--
-- If you want to use monomorphic in the same file where you
-- defined the property, the same scoping problems pop up as in
-- quickCheckAll: see the note there about return [].
monomorphic :: Name -> ExpQ
-- | Test a polymorphic property, defaulting all type variables to
-- Integer. This is just a convenience function that combines
-- verboseCheck and monomorphic.
--
-- If you want to use polyVerboseCheck in the same file where you
-- defined the property, the same scoping problems pop up as in
-- quickCheckAll: see the note there about return [].
polyVerboseCheck :: Name -> ExpQ
-- | Test a polymorphic property, defaulting all type variables to
-- Integer.
--
-- Invoke as $(polyQuickCheck 'prop), where prop
-- is a property. Note that just evaluating quickCheck
-- prop in GHCi will seem to work, but will silently default all
-- type variables to ()!
--
-- $(polyQuickCheck 'prop) means the same as
-- quickCheck $(monomorphic 'prop). If you want to
-- supply custom arguments to polyQuickCheck, you will have to
-- combine quickCheckWith and monomorphic yourself.
--
-- If you want to use polyQuickCheck in the same file where you
-- defined the property, the same scoping problems pop up as in
-- quickCheckAll: see the note there about return [].
polyQuickCheck :: Name -> ExpQ
-- | Tests a property, using test arguments, produces a test result, and
-- prints the results and all test cases generated to stdout.
-- This is just a convenience function that combines
-- quickCheckWithResult and verbose.
verboseCheckWithResult :: Testable prop => Args -> prop -> IO Result
-- | Tests a property, produces a test result, and prints the results and
-- all test cases generated to stdout. This is just a
-- convenience function that combines quickCheckResult and
-- verbose.
verboseCheckResult :: Testable prop => prop -> IO Result
-- | Tests a property, using test arguments, and prints the results and all
-- test cases generated to stdout. This is just a convenience
-- function that combines quickCheckWith and verbose.
verboseCheckWith :: Testable prop => Args -> prop -> IO ()
-- | Tests a property and prints the results and all test cases generated
-- to stdout. This is just a convenience function that means the
-- same as quickCheck . verbose.
verboseCheck :: Testable prop => prop -> IO ()
-- | The default test arguments
stdArgs :: Args
-- | Check if the test run result was a success
isSuccess :: Result -> Bool
-- | Args specifies arguments to the QuickCheck driver
data Args
Args :: Maybe (QCGen, Int) -> Int -> Int -> Int -> Bool -> Int -> Args
-- | Should we replay a previous test? Note: saving a seed from one version
-- of QuickCheck and replaying it in another is not supported. If you
-- want to store a test case permanently you should save the test case
-- itself.
[replay] :: Args -> Maybe (QCGen, Int)
-- | Maximum number of successful tests before succeeding. Testing stops at
-- the first failure. If all tests are passing and you want to run more
-- tests, increase this number.
[maxSuccess] :: Args -> Int
-- | Maximum number of discarded tests per successful test before giving up
[maxDiscardRatio] :: Args -> Int
-- | Size to use for the biggest test cases
[maxSize] :: Args -> Int
-- | Whether to print anything
[chatty] :: Args -> Bool
-- | Maximum number of shrinks to before giving up. Setting this to zero
-- turns shrinking off.
[maxShrinks] :: Args -> Int
-- | Result represents the test result
data Result
-- | A successful test run
Success :: Int -> Int -> !Map [String] Int -> !Map String Int -> !Map String Map String Int -> String -> Result
-- | Number of tests performed
[numTests] :: Result -> Int
-- | Number of tests skipped
[numDiscarded] :: Result -> Int
-- | The number of test cases having each combination of labels (see
-- label)
[labels] :: Result -> !Map [String] Int
-- | The number of test cases having each class (see classify)
[classes] :: Result -> !Map String Int
-- | Data collected by tabulate
[tables] :: Result -> !Map String Map String Int
-- | Printed output
[output] :: Result -> String
-- | Given up
GaveUp :: Int -> Int -> !Map [String] Int -> !Map String Int -> !Map String Map String Int -> String -> Result
-- | Number of tests performed
[numTests] :: Result -> Int
-- | Number of tests skipped
[numDiscarded] :: Result -> Int
-- | The number of test cases having each combination of labels (see
-- label)
[labels] :: Result -> !Map [String] Int
-- | The number of test cases having each class (see classify)
[classes] :: Result -> !Map String Int
-- | Data collected by tabulate
[tables] :: Result -> !Map String Map String Int
-- | Printed output
[output] :: Result -> String
-- | A failed test run
Failure :: Int -> Int -> Int -> Int -> Int -> QCGen -> Int -> String -> Maybe AnException -> String -> [String] -> [String] -> Set String -> Result
-- | Number of tests performed
[numTests] :: Result -> Int
-- | Number of tests skipped
[numDiscarded] :: Result -> Int
-- | Number of successful shrinking steps performed
[numShrinks] :: Result -> Int
-- | Number of unsuccessful shrinking steps performed
[numShrinkTries] :: Result -> Int
-- | Number of unsuccessful shrinking steps performed since last successful
-- shrink
[numShrinkFinal] :: Result -> Int
-- | What seed was used
[usedSeed] :: Result -> QCGen
-- | What was the test size
[usedSize] :: Result -> Int
-- | Why did the property fail
[reason] :: Result -> String
-- | The exception the property threw, if any
[theException] :: Result -> Maybe AnException
-- | Printed output
[output] :: Result -> String
-- | The test case which provoked the failure
[failingTestCase] :: Result -> [String]
-- | The test case's labels (see label)
[failingLabels] :: Result -> [String]
-- | The test case's classes (see classify)
[failingClasses] :: Result -> Set String
-- | A property that should have failed did not
NoExpectedFailure :: Int -> Int -> !Map [String] Int -> !Map String Int -> !Map String Map String Int -> String -> Result
-- | Number of tests performed
[numTests] :: Result -> Int
-- | Number of tests skipped
[numDiscarded] :: Result -> Int
-- | The number of test cases having each combination of labels (see
-- label)
[labels] :: Result -> !Map [String] Int
-- | The number of test cases having each class (see classify)
[classes] :: Result -> !Map String Int
-- | Data collected by tabulate
[tables] :: Result -> !Map String Map String Int
-- | Printed output
[output] :: Result -> String
-- | Checks that a value is total, i.e., doesn't crash when evaluated.
total :: NFData a => a -> Property
-- | Like /=, but prints a counterexample when it fails.
(=/=) :: (Eq a, Show a) => a -> a -> Property
infix 4 =/=
-- | Like forAllShrink, but without printing the generated value.
forAllShrinkBlind :: Testable prop => Gen a -> a -> [a] -> a -> prop -> Property
-- | Like forAllShrink, but with an explicitly given show function.
forAllShrinkShow :: Testable prop => Gen a -> a -> [a] -> a -> String -> a -> prop -> Property
-- | Like forAll, but without printing the generated value.
forAllBlind :: Testable prop => Gen a -> a -> prop -> Property
-- | Like forAll, but with an explicitly given show function.
forAllShow :: Testable prop => Gen a -> a -> String -> a -> prop -> Property
-- | Checks that the values in a given table appear a certain
-- proportion of the time. A call to coverTable table
-- [(x1, p1), ..., (xn, pn)] asserts that of the values in
-- table, x1 should appear at least p1 percent
-- of the time, x2 at least p2 percent of the time, and
-- so on.
--
-- Note: If the coverage check fails, QuickCheck prints out a
-- warning, but the property does not fail. To make the property
-- fail, use checkCoverage.
--
-- Continuing the example from the tabular combinator...
--
--
-- data Command = LogIn | LogOut | SendMessage String deriving (Data, Show)
-- prop_chatroom :: [Command] -> Property
-- prop_chatroom cmds =
-- wellFormed cmds LoggedOut ==>
-- 'tabulate' "Commands" (map (show . 'Data.Data.toConstr') cmds) $
-- ...
--
--
-- ...we can add a coverage requirement as follows, which checks that
-- LogIn, LogOut and SendMessage each occur at
-- least 25% of the time:
--
--
-- prop_chatroom :: [Command] -> Property
-- prop_chatroom cmds =
-- wellFormed cmds LoggedOut ==>
-- coverTable "Commands" [("LogIn", 25), ("LogOut", 25), ("SendMessage", 25)] $
-- 'tabulate' "Commands" (map (show . 'Data.Data.toConstr') cmds) $
-- ... property goes here ...
--
--
--
-- >>> quickCheck prop_chatroom
-- +++ OK, passed 100 tests; 2909 discarded:
-- 56% 0
-- 17% 1
-- 10% 2
-- 6% 3
-- 5% 4
-- 3% 5
-- 3% 7
--
-- Commands (111 in total):
-- 51.4% LogIn
-- 30.6% SendMessage
-- 18.0% LogOut
--
-- Table 'Commands' had only 18.0% LogOut, but expected 25.0%
--
coverTable :: Testable prop => String -> [(String, Double)] -> prop -> Property
-- | Collects information about test case distribution into a table. The
-- arguments to tabulate are the table's name and a list of values
-- associated with the current test case. After testing, QuickCheck
-- prints the frequency of all collected values. The frequencies are
-- expressed as a percentage of the total number of values collected.
--
-- You should prefer tabulate to label when each test case
-- is associated with a varying number of values. Here is a (not terribly
-- useful) example, where the test data is a list of integers and we
-- record all values that occur in the list:
--
--
-- prop_sorted_sort :: [Int] -> Property
-- prop_sorted_sort xs =
-- sorted xs ==>
-- tabulate "List elements" (map show xs) $
-- sort xs === xs
--
--
--
-- >>> quickCheck prop_sorted_sort
-- +++ OK, passed 100 tests; 1684 discarded.
--
-- List elements (109 in total):
-- 3.7% 0
-- 3.7% 17
-- 3.7% 2
-- 3.7% 6
-- 2.8% -6
-- 2.8% -7
--
--
-- Here is a more useful example. We are testing a chatroom, where the
-- user can log in, log out, or send a message:
--
--
-- data Command = LogIn | LogOut | SendMessage String deriving (Data, Show)
-- instance Arbitrary Command where ...
--
--
-- There are some restrictions on command sequences; for example, the
-- user must log in before doing anything else. The function valid ::
-- [Command] -> Bool checks that a command sequence is allowed.
-- Our property then has the form:
--
--
-- prop_chatroom :: [Command] -> Property
-- prop_chatroom cmds =
-- valid cmds ==>
-- ...
--
--
-- The use of ==> may skew test case distribution. We use
-- collect to see the length of the command sequences, and
-- tabulate to get the frequencies of the individual commands:
--
--
-- prop_chatroom :: [Command] -> Property
-- prop_chatroom cmds =
-- wellFormed cmds LoggedOut ==>
-- 'collect' (length cmds) $
-- 'tabulate' "Commands" (map (show . 'Data.Data.toConstr') cmds) $
-- ...
--
--
--
-- >>> quickCheckWith stdArgs{maxDiscardRatio = 1000} prop_chatroom
-- +++ OK, passed 100 tests; 2775 discarded:
-- 60% 0
-- 20% 1
-- 15% 2
-- 3% 3
-- 1% 4
-- 1% 5
--
-- Commands (68 in total):
-- 62% LogIn
-- 22% SendMessage
-- 16% LogOut
--
tabulate :: Testable prop => String -> [String] -> prop -> Property
-- | The standard parameters used by checkCoverage: certainty =
-- 10^9, tolerance = 0.9. See Confidence for the
-- meaning of the parameters.
stdConfidence :: Confidence
-- | Check coverage requirements using a custom confidence level. See
-- stdConfidence.
--
-- An example of making the statistical test less stringent in order to
-- improve performance:
--
--
-- quickCheck (checkCoverageWith stdConfidence{certainty = 10^6} prop_foo)
--
checkCoverageWith :: Testable prop => Confidence -> prop -> Property
-- | Check that all coverage requirements defined by cover and
-- coverTable are met, using a statistically sound test, and fail
-- if they are not met.
--
-- Ordinarily, a failed coverage check does not cause the property to
-- fail. This is because the coverage requirement is not tested in a
-- statistically sound way. If you use cover to express that a
-- certain value must appear 20% of the time, QuickCheck will warn you if
-- the value only appears in 19 out of 100 test cases - but since the
-- coverage varies randomly, you may have just been unlucky, and there
-- may not be any real problem with your test generation.
--
-- When you use checkCoverage, QuickCheck uses a statistical test
-- to account for the role of luck in coverage failures. It will run as
-- many tests as needed until it is sure about whether the coverage
-- requirements are met. If a coverage requirement is not met, the
-- property fails.
--
-- Example:
--
--
-- quickCheck (checkCoverage prop_foo)
--
checkCoverage :: Testable prop => prop -> Property
-- | Configures how many times a property will be tested.
--
-- For example,
--
--
-- quickCheck (withMaxSuccess 1000 p)
--
--
-- will test p up to 1000 times.
withMaxSuccess :: Testable prop => Int -> prop -> Property
-- | Modifies a property so that it will be tested repeatedly. Opposite of
-- once.
again :: Testable prop => prop -> Property
-- | Prints out the generated testcase every time the property fails,
-- including during shrinking. Only variables quantified over
-- inside the verboseShrinking are printed.
verboseShrinking :: Testable prop => prop -> Property
-- | Performs an IO action every time a property fails. Thus, if
-- shrinking is done, this can be used to keep track of the failures
-- along the way.
whenFail' :: Testable prop => IO () -> prop -> Property
-- | Performs an IO action after the last failure of a property.
whenFail :: Testable prop => IO () -> prop -> Property
-- | Do I/O inside a property.
--
-- Warning: during shrinking, the I/O may not always be re-executed.
-- Instead, the I/O may be executed once and then its result retained. If
-- this is not acceptable, use ioProperty instead.
idempotentIOProperty :: Testable prop => IO prop -> Property
-- | Do I/O inside a property.
--
-- Warning: any random values generated inside of the argument to
-- ioProperty will not currently be shrunk. For best results,
-- generate all random values before calling ioProperty, or use
-- idempotentIOProperty if that is safe.
--
-- Note: if your property does no quantification, it will only be tested
-- once. To test it repeatedly, use again.
ioProperty :: Testable prop => IO prop -> Property
-- | If a property returns Discard, the current test case is
-- discarded, the same as if a precondition was false.
--
-- An example is the definition of ==>:
--
--
-- (==>) :: Testable prop => Bool -> prop -> Property
-- False ==> _ = property Discard
-- True ==> p = property p
--
data Discard
Discard :: Discard
-- | The statistical parameters used by checkCoverage.
data Confidence
Confidence :: Integer -> Double -> Confidence
-- | How certain checkCoverage must be before the property fails.
-- If the coverage requirement is met, and the certainty parameter is
-- n, then you should get a false positive at most one in
-- n runs of QuickCheck. The default value is 10^9.
--
-- Lower values will speed up checkCoverage at the cost of false
-- positives.
--
-- If you are using checkCoverage as part of a test suite, you
-- should be careful not to set certainty too low. If you want,
-- say, a 1% chance of a false positive during a project's lifetime, then
-- certainty should be set to at least 100 * m * n,
-- where m is the number of uses of cover in the test
-- suite, and n is the number of times you expect the test suite
-- to be run during the project's lifetime. The default value is chosen
-- to be big enough for most projects.
[certainty] :: Confidence -> Integer
-- | For statistical reasons, checkCoverage will not reject
-- coverage levels that are only slightly below the required levels. If
-- the required level is p then an actual level of tolerance
-- * p will be accepted. The default value is 0.9.
--
-- Lower values will speed up checkCoverage at the cost of not
-- detecting minor coverage violations.
[tolerance] :: Confidence -> Double
-- | Extracts the value of a ternary function. Fn3 is the pattern
-- equivalent of this function.
applyFun3 :: () => Fun (a, b, c) d -> a -> b -> c -> d
-- | Extracts the value of a binary function.
--
-- Fn2 is the pattern equivalent of this function.
--
--
-- prop_zipWith :: Fun (Int, Bool) Char -> [Int] -> [Bool] -> Bool
-- prop_zipWith f xs ys = zipWith (applyFun2 f) xs ys == [ applyFun2 f x y | (x, y) <- zip xs ys]
--
applyFun2 :: () => Fun (a, b) c -> a -> b -> c
-- | Extracts the value of a function.
--
-- Fn is the pattern equivalent of this function.
--
--
-- prop :: Fun String Integer -> Bool
-- prop f = applyFun f "banana" == applyFun f "monkey"
-- || applyFun f "banana" == applyFun f "elephant"
--
applyFun :: () => Fun a b -> a -> b
-- | The basic building block for Function instances. Provides a
-- Function instance by mapping to and from a type that already
-- has a Function instance.
functionMap :: Function b => a -> b -> b -> a -> a -> c -> a :-> c
-- | Provides a Function instance for types with Show and
-- Read.
functionShow :: (Show a, Read a) => a -> c -> a :-> c
-- | Provides a Function instance for types with Integral.
functionIntegral :: Integral a => a -> b -> a :-> b
-- | Provides a Function instance for types with RealFrac.
functionRealFrac :: RealFrac a => a -> b -> a :-> b
-- | Provides a Function instance for types with Bounded and
-- Enum. Use only for small types (i.e. not integers): creates the
-- list ['minBound'..'maxBound']!
functionBoundedEnum :: (Eq a, Bounded a, Enum a) => a -> b -> a :-> b
-- | A modifier for testing functions.
--
--
-- prop :: Fun String Integer -> Bool
-- prop (Fn f) = f "banana" == f "monkey"
-- || f "banana" == f "elephant"
--
-- | A modifier for testing binary functions.
--
--
-- prop_zipWith :: Fun (Int, Bool) Char -> [Int] -> [Bool] -> Bool
-- prop_zipWith (Fn2 f) xs ys = zipWith f xs ys == [ f x y | (x, y) <- zip xs ys]
--
-- | A modifier for testing ternary functions.
-- | The class Function a is used for random generation of
-- showable functions of type a -> b.
--
-- There is a default implementation for function, which you can
-- use if your type has structural equality. Otherwise, you can normally
-- use functionMap or functionShow.
class Function a
function :: Function a => a -> b -> a :-> b
-- | Generation of random shrinkable, showable functions.
--
-- To generate random values of type Fun a b, you must
-- have an instance Function a.
--
-- See also applyFun, and Fn with GHC >= 7.8.
data Fun a b
Fun :: (a :-> b, b, Shrunk) -> a -> b -> Fun a b
-- | Blind x: as x, but x does not have to be in the Show
-- class.
newtype Blind a
Blind :: a -> Blind a
[getBlind] :: Blind a -> a
-- | Fixed x: as x, but will not be shrunk.
newtype Fixed a
Fixed :: a -> Fixed a
[getFixed] :: Fixed a -> a
-- | Ordered xs: guarantees that xs is ordered.
newtype OrderedList a
Ordered :: [a] -> OrderedList a
[getOrdered] :: OrderedList a -> [a]
-- | NonEmpty xs: guarantees that xs is non-empty.
newtype NonEmptyList a
NonEmpty :: [a] -> NonEmptyList a
[getNonEmpty] :: NonEmptyList a -> [a]
-- | InfiniteList xs _: guarantees that xs is an infinite list.
-- When a counterexample is found, only prints the prefix of xs that was
-- used by the program.
--
-- Here is a contrived example property:
--
--
-- prop_take_10 :: InfiniteList Char -> Bool
-- prop_take_10 (InfiniteList xs _) =
-- or [ x == 'a' | x <- take 10 xs ]
--
--
-- In the following counterexample, the list must start with
-- "bbbbbbbbbb" but the remaining (infinite) part can contain
-- anything:
--
--
-- >>> quickCheck prop_take_10
-- *** Failed! Falsifiable (after 1 test and 14 shrinks):
-- "bbbbbbbbbb" ++ ...
--
data InfiniteList a
InfiniteList :: [a] -> InfiniteListInternalData a -> InfiniteList a
[getInfiniteList] :: InfiniteList a -> [a]
[infiniteListInternalData] :: InfiniteList a -> InfiniteListInternalData a
-- | Sorted xs: guarantees that xs is sorted.
newtype SortedList a
Sorted :: [a] -> SortedList a
[getSorted] :: SortedList a -> [a]
-- | Positive x: guarantees that x > 0.
newtype Positive a
Positive :: a -> Positive a
[getPositive] :: Positive a -> a
-- | NonZero x: guarantees that x /= 0.
newtype NonZero a
NonZero :: a -> NonZero a
[getNonZero] :: NonZero a -> a
-- | NonNegative x: guarantees that x >= 0.
newtype NonNegative a
NonNegative :: a -> NonNegative a
[getNonNegative] :: NonNegative a -> a
-- | Large x: by default, QuickCheck generates Ints drawn
-- from a small range. Large Int gives you values drawn from the
-- entire range instead.
newtype Large a
Large :: a -> Large a
[getLarge] :: Large a -> a
-- | Small x: generates values of x drawn from a small
-- range. The opposite of Large.
newtype Small a
Small :: a -> Small a
[getSmall] :: Small a -> a
-- | Shrink2 x: allows 2 shrinking steps at the same time when
-- shrinking x
newtype Shrink2 a
Shrink2 :: a -> Shrink2 a
[getShrink2] :: Shrink2 a -> a
-- | Smart _ x: tries a different order when shrinking.
data Smart a
Smart :: Int -> a -> Smart a
-- | Shrinking _ x: allows for maintaining a state during
-- shrinking.
data Shrinking s a
Shrinking :: s -> a -> Shrinking s a
class ShrinkState s a
shrinkInit :: ShrinkState s a => a -> s
shrinkState :: ShrinkState s a => a -> s -> [(a, s)]
-- | ASCIIString: generates an ASCII string.
newtype ASCIIString
ASCIIString :: String -> ASCIIString
[getASCIIString] :: ASCIIString -> String
-- | UnicodeString: generates a unicode String. The string will
-- not contain surrogate pairs.
newtype UnicodeString
UnicodeString :: String -> UnicodeString
[getUnicodeString] :: UnicodeString -> String
-- | PrintableString: generates a printable unicode String. The
-- string will not contain surrogate pairs.
newtype PrintableString
PrintableString :: String -> PrintableString
[getPrintableString] :: PrintableString -> String
-- | Generates an infinite list.
infiniteList :: Arbitrary a => Gen [a]
-- | Generates an ordered list.
orderedList :: (Ord a, Arbitrary a) => Gen [a]
-- | Generates a list of a given length.
vector :: Arbitrary a => Int -> Gen [a]
-- | A coarbitrary implementation for enums.
coarbitraryEnum :: Enum a => a -> Gen b -> Gen b
-- | coarbitrary helper for lazy people :-).
coarbitraryShow :: Show a => a -> Gen b -> Gen b
-- | A coarbitrary implementation for real numbers.
coarbitraryReal :: Real a => a -> Gen b -> Gen b
-- | A coarbitrary implementation for integral numbers.
coarbitraryIntegral :: Integral a => a -> Gen b -> Gen b
-- | Combine two generator perturbing functions, for example the results of
-- calls to variant or coarbitrary.
(><) :: () => Gen a -> Gen a -> Gen a -> Gen a -> Gen a -> Gen a
-- | Generic CoArbitrary implementation.
genericCoarbitrary :: (Generic a, GCoArbitrary Rep a) => a -> Gen b -> Gen b
-- | Shrink a real number, preferring numbers with shorter decimal
-- representations. See also shrinkRealFrac.
shrinkDecimal :: RealFrac a => a -> [a]
-- | Shrink a fraction, preferring numbers with smaller numerators or
-- denominators. See also shrinkDecimal.
shrinkRealFrac :: RealFrac a => a -> [a]
-- | Shrink an integral number.
shrinkIntegral :: Integral a => a -> [a]
-- | Non-overloaded version of shrinkMap.
shrinkMapBy :: () => a -> b -> b -> a -> a -> [a] -> b -> [b]
-- | Map a shrink function to another domain. This is handy if your data
-- type has special invariants, but is almost isomorphic to some
-- other type.
--
--
-- shrinkOrderedList :: (Ord a, Arbitrary a) => [a] -> [[a]]
-- shrinkOrderedList = shrinkMap sort id
--
-- shrinkSet :: (Ord a, Arbitrary a) => Set a -> Set [a]
-- shrinkSet = shrinkMap fromList toList
--
shrinkMap :: Arbitrary a => a -> b -> b -> a -> b -> [b]
-- | Returns no shrinking alternatives.
shrinkNothing :: () => a -> [a]
-- | Generates a printable Unicode character.
arbitraryPrintableChar :: Gen Char
-- | Generates a random ASCII character (0-127).
arbitraryASCIIChar :: Gen Char
-- | Generates any Unicode character (but not a surrogate)
arbitraryUnicodeChar :: Gen Char
-- | Generates an integral number from a bounded domain. The number is
-- chosen from the entire range of the type, but small numbers are
-- generated more often than big numbers. Inspired by demands from Phil
-- Wadler.
arbitrarySizedBoundedIntegral :: (Bounded a, Integral a) => Gen a
-- | Generates an element of a bounded enumeration.
arbitraryBoundedEnum :: (Bounded a, Enum a) => Gen a
-- | Generates an element of a bounded type. The element is chosen from the
-- entire range of the type.
arbitraryBoundedRandom :: (Bounded a, Random a) => Gen a
-- | Generates an integral number. The number is chosen uniformly from the
-- entire range of the type. You may want to use
-- arbitrarySizedBoundedIntegral instead.
arbitraryBoundedIntegral :: (Bounded a, Integral a) => Gen a
-- | Generates a fractional number. The number can be positive or negative
-- and its maximum absolute value depends on the size parameter.
arbitrarySizedFractional :: Fractional a => Gen a
-- | Generates a natural number. The number's maximum value depends on the
-- size parameter.
arbitrarySizedNatural :: Integral a => Gen a
-- | Generates an integral number. The number can be positive or negative
-- and its maximum absolute value depends on the size parameter.
arbitrarySizedIntegral :: Integral a => Gen a
-- | Apply a function of arity 4 to random arguments.
applyArbitrary4 :: (Arbitrary a, Arbitrary b, Arbitrary c, Arbitrary d) => a -> b -> c -> d -> r -> Gen r
-- | Apply a ternary function to random arguments.
applyArbitrary3 :: (Arbitrary a, Arbitrary b, Arbitrary c) => a -> b -> c -> r -> Gen r
-- | Apply a binary function to random arguments.
applyArbitrary2 :: (Arbitrary a, Arbitrary b) => a -> b -> r -> Gen r
-- | Shrink a list of values given a shrinking function for individual
-- values.
shrinkList :: () => a -> [a] -> [a] -> [[a]]
-- | All immediate subterms of a term.
subterms :: (Generic a, GSubterms Rep a a) => a -> [a]
-- | Recursively shrink all immediate subterms.
recursivelyShrink :: (Generic a, RecursivelyShrink Rep a) => a -> [a]
-- | Shrink a term to any of its immediate subterms, and also recursively
-- shrink all subterms.
genericShrink :: (Generic a, RecursivelyShrink Rep a, GSubterms Rep a a) => a -> [a]
shrink2 :: (Arbitrary2 f, Arbitrary a, Arbitrary b) => f a b -> [f a b]
arbitrary2 :: (Arbitrary2 f, Arbitrary a, Arbitrary b) => Gen f a b
shrink1 :: (Arbitrary1 f, Arbitrary a) => f a -> [f a]
arbitrary1 :: (Arbitrary1 f, Arbitrary a) => Gen f a
-- | Random generation and shrinking of values.
--
-- QuickCheck provides Arbitrary instances for most types in
-- base, except those which incur extra dependencies. For a
-- wider range of Arbitrary instances see the
-- quickcheck-instances package.
class Arbitrary a
-- | A generator for values of the given type.
--
-- It is worth spending time thinking about what sort of test data you
-- want - good generators are often the difference between finding bugs
-- and not finding them. You can use sample, label and
-- classify to check the quality of your test data.
--
-- There is no generic arbitrary implementation included because
-- we don't know how to make a high-quality one. If you want one,
-- consider using the testing-feat or generic-random
-- packages.
--
-- The QuickCheck manual goes into detail on how to write good
-- generators. Make sure to look at it, especially if your type is
-- recursive!
arbitrary :: Arbitrary a => Gen a
-- | Produces a (possibly) empty list of all the possible immediate shrinks
-- of the given value.
--
-- The default implementation returns the empty list, so will not try to
-- shrink the value. If your data type has no special invariants, you can
-- enable shrinking by defining shrink = genericShrink,
-- but by customising the behaviour of shrink you can often get
-- simpler counterexamples.
--
-- Most implementations of shrink should try at least three
-- things:
--
--
-- - Shrink a term to any of its immediate subterms. You can use
-- subterms to do this.
-- - Recursively apply shrink to all immediate subterms. You can
-- use recursivelyShrink to do this.
-- - Type-specific shrinkings such as replacing a constructor by a
-- simpler constructor.
--
--
-- For example, suppose we have the following implementation of binary
-- trees:
--
--
-- data Tree a = Nil | Branch a (Tree a) (Tree a)
--
--
-- We can then define shrink as follows:
--
--
-- shrink Nil = []
-- shrink (Branch x l r) =
-- -- shrink Branch to Nil
-- [Nil] ++
-- -- shrink to subterms
-- [l, r] ++
-- -- recursively shrink subterms
-- [Branch x' l' r' | (x', l', r') <- shrink (x, l, r)]
--
--
-- There are a couple of subtleties here:
--
--
-- - QuickCheck tries the shrinking candidates in the order they appear
-- in the list, so we put more aggressive shrinking steps (such as
-- replacing the whole tree by Nil) before smaller ones (such as
-- recursively shrinking the subtrees).
-- - It is tempting to write the last line as [Branch x' l' r' | x'
-- <- shrink x, l' <- shrink l, r' <- shrink r] but this is
-- the wrong thing! It will force QuickCheck to shrink x,
-- l and r in tandem, and shrinking will stop once
-- one of the three is fully shrunk.
--
--
-- There is a fair bit of boilerplate in the code above. We can avoid it
-- with the help of some generic functions. The function
-- genericShrink tries shrinking a term to all of its subterms
-- and, failing that, recursively shrinks the subterms. Using it, we can
-- define shrink as:
--
--
-- shrink x = shrinkToNil x ++ genericShrink x
-- where
-- shrinkToNil Nil = []
-- shrinkToNil (Branch _ l r) = [Nil]
--
--
-- genericShrink is a combination of subterms, which
-- shrinks a term to any of its subterms, and recursivelyShrink,
-- which shrinks all subterms of a term. These may be useful if you need
-- a bit more control over shrinking than genericShrink gives you.
--
-- A final gotcha: we cannot define shrink as simply
-- shrink x = Nil:genericShrink x as this shrinks
-- Nil to Nil, and shrinking will go into an infinite
-- loop.
--
-- If all this leaves you bewildered, you might try shrink =
-- genericShrink to begin with, after deriving
-- Generic for your type. However, if your data type has any
-- special invariants, you will need to check that genericShrink
-- can't break those invariants.
shrink :: Arbitrary a => a -> [a]
-- | Lifting of the Arbitrary class to unary type constructors.
class Arbitrary1 (f :: * -> *)
liftArbitrary :: Arbitrary1 f => Gen a -> Gen f a
liftShrink :: Arbitrary1 f => a -> [a] -> f a -> [f a]
-- | Lifting of the Arbitrary class to binary type constructors.
class Arbitrary2 (f :: * -> * -> *)
liftArbitrary2 :: Arbitrary2 f => Gen a -> Gen b -> Gen f a b
liftShrink2 :: Arbitrary2 f => a -> [a] -> b -> [b] -> f a b -> [f a b]
-- | Used for random generation of functions. You should consider using
-- Fun instead, which can show the generated functions as strings.
--
-- If you are using a recent GHC, there is a default definition of
-- coarbitrary using genericCoarbitrary, so if your type
-- has a Generic instance it's enough to say
--
--
-- instance CoArbitrary MyType
--
--
-- You should only use genericCoarbitrary for data types where
-- equality is structural, i.e. if you can't have two different
-- representations of the same value. An example where it's not safe is
-- sets implemented using binary search trees: the same set can be
-- represented as several different trees. Here you would have to
-- explicitly define coarbitrary s = coarbitrary (toList s).
class CoArbitrary a
-- | Used to generate a function of type a -> b. The first
-- argument is a value, the second a generator. You should use
-- variant to perturb the random generator; the goal is that
-- different values for the first argument will lead to different calls
-- to variant. An example will help:
--
--
-- instance CoArbitrary a => CoArbitrary [a] where
-- coarbitrary [] = variant 0
-- coarbitrary (x:xs) = variant 1 . coarbitrary (x,xs)
--
coarbitrary :: CoArbitrary a => a -> Gen b -> Gen b
-- | Generates an infinite list.
infiniteListOf :: () => Gen a -> Gen [a]
-- | Generates a list of the given length.
vectorOf :: () => Int -> Gen a -> Gen [a]
-- | Generates a non-empty list of random length. The maximum length
-- depends on the size parameter.
listOf1 :: () => Gen a -> Gen [a]
-- | Generates a list of random length. The maximum length depends on the
-- size parameter.
listOf :: () => Gen a -> Gen [a]
-- | Takes a list of elements of increasing size, and chooses among an
-- initial segment of the list. The size of this initial segment
-- increases with the size parameter. The input list must be non-empty.
growingElements :: () => [a] -> Gen a
-- | Generates a random permutation of the given list.
shuffle :: () => [a] -> Gen [a]
-- | Generates a random subsequence of the given list.
sublistOf :: () => [a] -> Gen [a]
-- | Generates one of the given values. The input list must be non-empty.
elements :: () => [a] -> Gen a
-- | Chooses one of the given generators, with a weighted random
-- distribution. The input list must be non-empty.
frequency :: () => [(Int, Gen a)] -> Gen a
-- | Randomly uses one of the given generators. The input list must be
-- non-empty.
oneof :: () => [Gen a] -> Gen a
-- | Tries to generate a value that satisfies a predicate. If it fails to
-- do so after enough attempts, returns Nothing.
suchThatMaybe :: () => Gen a -> a -> Bool -> Gen Maybe a
-- | Generates a value for which the given function returns a Just,
-- and then applies the function.
suchThatMap :: () => Gen a -> a -> Maybe b -> Gen b
-- | Generates a value that satisfies a predicate.
suchThat :: () => Gen a -> a -> Bool -> Gen a
-- | Generates some example values and prints them to stdout.
sample :: Show a => Gen a -> IO ()
-- | Generates some example values.
sample' :: () => Gen a -> IO [a]
-- | Run a generator. The size passed to the generator is always 30; if you
-- want another size then you should explicitly use resize.
generate :: () => Gen a -> IO a
-- | Generates a random element in the given inclusive range.
choose :: Random a => (a, a) -> Gen a
-- | Adjust the size parameter, by transforming it with the given function.
scale :: () => Int -> Int -> Gen a -> Gen a
-- | Overrides the size parameter. Returns a generator which uses the given
-- size instead of the runtime-size parameter.
resize :: () => Int -> Gen a -> Gen a
-- | Returns the size parameter. Used to construct generators that depend
-- on the size parameter.
--
-- For example, listOf, which uses the size parameter as an upper
-- bound on length of lists it generates, can be defined like this:
--
--
-- listOf :: Gen a -> Gen [a]
-- listOf gen = do
-- n <- getSize
-- k <- choose (0,n)
-- vectorOf k gen
--
--
-- You can also do this using sized.
getSize :: Gen Int
-- | Used to construct generators that depend on the size parameter.
--
-- For example, listOf, which uses the size parameter as an upper
-- bound on length of lists it generates, can be defined like this:
--
--
-- listOf :: Gen a -> Gen [a]
-- listOf gen = sized $ \n ->
-- do k <- choose (0,n)
-- vectorOf k gen
--
--
-- You can also do this using getSize.
sized :: () => Int -> Gen a -> Gen a
-- | Modifies a generator using an integer seed.
variant :: Integral n => n -> Gen a -> Gen a
-- | A generator for values of type a.
--
-- The third-party package QuickCheck-GenT provides a monad
-- transformer version of GenT.
data Gen a
-- | A special error value. If a property evaluates discard, it
-- causes QuickCheck to discard the current test case. This can be useful
-- if you want to discard the current test case, but are somewhere you
-- can't use ==>, such as inside a generator.
discard :: () => a
instance Test.QuickCheck.Safe.STestable Test.QuickCheck.Safe.SProperty
instance Test.QuickCheck.Safe.STestable prop => Test.QuickCheck.Safe.STestable (Test.QuickCheck.Gen.Gen prop)
instance Test.QuickCheck.Safe.STestable GHC.Types.Bool
instance (Test.QuickCheck.Arbitrary.Arbitrary a, GHC.Show.Show a, Test.QuickCheck.Safe.STestable prop) => Test.QuickCheck.Safe.STestable (a -> prop)