1{-|
2The <http://www.cse.chalmers.se/~rjmh/QuickCheck/manual.html QuickCheck manual>
3gives detailed information about using QuickCheck effectively.
4You can also try <https://begriffs.com/posts/2017-01-14-design-use-quickcheck.html>,
5a tutorial written by a user of QuickCheck.
6
7To start using QuickCheck, write down your property as a function returning @Bool@.
8For example, to check that reversing a list twice gives back the same list you can write:
9
10@
11import Test.QuickCheck
12
13prop_reverse :: [Int] -> Bool
14prop_reverse xs = reverse (reverse xs) == xs
15@
16
17You can then use QuickCheck to test @prop_reverse@ on 100 random lists:
18
19>>> quickCheck prop_reverse
20+++ OK, passed 100 tests.
21
22To run more tests you can use the 'withMaxSuccess' combinator:
23
24>>> quickCheck (withMaxSuccess 10000 prop_reverse)
25+++ OK, passed 10000 tests.
26
27To use QuickCheck on your own data types you will need to write 'Arbitrary'
28instances for those types. See the
29<http://www.cse.chalmers.se/~rjmh/QuickCheck/manual.html QuickCheck manual> for
30details about how to do that.
31-}
32{-# LANGUAGE CPP #-}
33#ifndef NO_SAFE_HASKELL
34{-# LANGUAGE Safe #-}
35#endif
36#if defined(__GLASGOW_HASKELL__) && __GLASGOW_HASKELL__ >= 708
37{-# LANGUAGE PatternSynonyms #-}
38#endif
39module Test.QuickCheck
40  (
41    -- * Running tests
42    quickCheck
43  , Args(..), Result(..)
44  , stdArgs
45  , quickCheckWith
46  , quickCheckWithResult
47  , quickCheckResult
48  , isSuccess
49    -- ** Running tests verbosely
50  , verboseCheck
51  , verboseCheckWith
52  , verboseCheckWithResult
53  , verboseCheckResult
54#ifndef NO_TEMPLATE_HASKELL
55    -- ** Testing all properties in a module
56
57    -- | These functions test all properties in the current module, using
58    -- Template Haskell. You need to have a @{-\# LANGUAGE TemplateHaskell \#-}@
59    -- pragma in your module for any of these to work.
60  , quickCheckAll
61  , verboseCheckAll
62  , forAllProperties
63  , allProperties
64    -- ** Testing polymorphic properties
65  , polyQuickCheck
66  , polyVerboseCheck
67  , monomorphic
68#endif
69
70    -- * The 'Arbitrary' typeclass: generation of random values
71  , Arbitrary(..)
72    -- ** Helper functions for implementing 'shrink'
73#ifndef NO_GENERICS
74  , genericShrink
75  , subterms
76  , recursivelyShrink
77#endif
78  , shrinkNothing
79  , shrinkList
80  , shrinkMap
81  , shrinkMapBy
82  , shrinkIntegral
83  , shrinkRealFrac
84  , shrinkDecimal
85
86    -- ** Lifting of 'Arbitrary' to unary and binary type constructors
87  , Arbitrary1(..)
88  , arbitrary1
89  , shrink1
90  , Arbitrary2(..)
91  , arbitrary2
92  , shrink2
93
94    -- * The 'Gen' monad: combinators for building random generators
95  , Gen
96    -- ** Generator combinators
97  , choose
98  , chooseInt
99  , chooseInteger
100  , chooseBoundedIntegral
101  , chooseEnum
102  , chooseAny
103  , oneof
104  , frequency
105  , elements
106  , growingElements
107  , sized
108  , getSize
109  , resize
110  , scale
111  , suchThat
112  , suchThatMap
113  , suchThatMaybe
114  , applyArbitrary2
115  , applyArbitrary3
116  , applyArbitrary4
117    -- ** Generators for lists
118  , listOf
119  , listOf1
120  , vectorOf
121  , vector
122  , infiniteListOf
123  , infiniteList
124  , shuffle
125  , sublistOf
126  , orderedList
127    -- ** Generators for particular types
128  , arbitrarySizedIntegral
129  , arbitrarySizedNatural
130  , arbitrarySizedFractional
131  , arbitrarySizedBoundedIntegral
132  , arbitraryBoundedIntegral
133  , arbitraryBoundedRandom
134  , arbitraryBoundedEnum
135  , arbitraryUnicodeChar
136  , arbitraryASCIIChar
137  , arbitraryPrintableChar
138    -- ** Running generators
139  , generate
140    -- ** Debugging generators
141  , sample
142  , sample'
143
144#ifndef NO_GADTS
145    -- * The 'Function' typeclass: generation of random shrinkable, showable functions
146
147    -- | Example of use:
148    --
149    -- >>> :{
150    -- >>> let prop :: Fun String Integer -> Bool
151    -- >>>     prop (Fun _ f) = f "monkey" == f "banana" || f "banana" == f "elephant"
152    -- >>> :}
153    -- >>> quickCheck prop
154    -- *** Failed! Falsified (after 3 tests and 134 shrinks):
155    -- {"elephant"->1, "monkey"->1, _->0}
156    --
157    -- To generate random values of type @'Fun' a b@,
158    -- you must have an instance @'Function' a@.
159    -- If your type has a 'Show' instance, you can use 'functionShow' to write the instance; otherwise,
160    -- use 'functionMap' to give a bijection between your type and a type that is already an instance of 'Function'.
161    -- See the @'Function' [a]@ instance for an example of the latter.
162    --
163    -- For more information, see the paper \"Shrinking and showing functions\" by Koen Claessen.
164  , Fun (..)
165  , applyFun
166  , applyFun2
167  , applyFun3
168#if defined(__GLASGOW_HASKELL__) && __GLASGOW_HASKELL__ >= 708
169  , pattern Fn
170  , pattern Fn2
171  , pattern Fn3
172#endif
173  , Function (..)
174  , functionMap
175  , functionShow
176  , functionIntegral
177  , functionRealFrac
178  , functionBoundedEnum
179  , functionVoid
180#endif
181
182    -- * The 'CoArbitrary' typeclass: generation of functions the old-fashioned way
183  , CoArbitrary(..)
184#ifndef NO_GENERICS
185  , genericCoarbitrary
186#endif
187  , variant
188  , coarbitraryIntegral
189  , coarbitraryReal
190  , coarbitraryShow
191  , coarbitraryEnum
192  , (><)
193
194    -- * Type-level modifiers for changing generator behavior
195
196    -- | These types do things such as restricting the kind of test data that can be generated.
197    -- They can be pattern-matched on in properties as a stylistic
198    -- alternative to using explicit quantification.
199    --
200    -- Examples:
201    --
202    -- @
203    -- -- Functions cannot be shown (but see 'Function')
204    -- prop_TakeDropWhile ('Blind' p) (xs :: ['A']) =
205    --   takeWhile p xs ++ dropWhile p xs == xs
206    -- @
207    --
208    -- @
209    -- prop_TakeDrop ('NonNegative' n) (xs :: ['A']) =
210    --   take n xs ++ drop n xs == xs
211    -- @
212    --
213    -- @
214    -- -- cycle does not work for empty lists
215    -- prop_Cycle ('NonNegative' n) ('NonEmpty' (xs :: ['A'])) =
216    --   take n (cycle xs) == take n (xs ++ cycle xs)
217    -- @
218    --
219    -- @
220    -- -- Instead of 'forAll' 'orderedList'
221    -- prop_Sort ('Ordered' (xs :: ['OrdA'])) =
222    --   sort xs == xs
223    -- @
224  , Blind(..)
225  , Fixed(..)
226  , OrderedList(..)
227  , NonEmptyList(..)
228  , InfiniteList(..)
229  , SortedList(..)
230  , Positive(..)
231  , Negative(..)
232  , NonZero(..)
233  , NonNegative(..)
234  , NonPositive(..)
235  , Large(..)
236  , Small(..)
237  , Smart(..)
238  , Shrink2(..)
239#ifndef NO_MULTI_PARAM_TYPE_CLASSES
240  , Shrinking(..)
241  , ShrinkState(..)
242#endif
243  , ASCIIString(..)
244  , UnicodeString(..)
245  , PrintableString(..)
246
247    -- * Property combinators
248  , Property, Testable(..)
249  , forAll
250  , forAllShrink
251  , forAllShow
252  , forAllShrinkShow
253  , forAllBlind
254  , forAllShrinkBlind
255  , shrinking
256  , (==>)
257  , Discard(..)
258  , discard
259  , (===)
260  , (=/=)
261#ifndef NO_DEEPSEQ
262  , total
263#endif
264  , ioProperty
265  , idempotentIOProperty
266    -- ** Controlling property execution
267  , verbose
268  , verboseShrinking
269  , noShrinking
270  , withMaxSuccess
271  , within
272  , once
273  , again
274  , mapSize
275    -- ** Conjunction and disjunction
276  , (.&.)
277  , (.&&.)
278  , conjoin
279  , (.||.)
280  , disjoin
281    -- ** What to do on failure
282  , counterexample
283  , printTestCase
284  , whenFail
285  , whenFail'
286  , expectFailure
287    -- * Analysing test case distribution
288  , label
289  , collect
290  , classify
291  , tabulate
292    -- ** Checking test case distribution
293  , cover
294  , coverTable
295  , checkCoverage
296  , checkCoverageWith
297  , Confidence(..)
298  , stdConfidence
299    -- ** Generating example test cases
300  , labelledExamples
301  , labelledExamplesWith
302  , labelledExamplesWithResult
303  , labelledExamplesResult
304  )
305 where
306
307--------------------------------------------------------------------------
308-- imports
309
310import Test.QuickCheck.Gen
311import Test.QuickCheck.Arbitrary
312import Test.QuickCheck.Modifiers
313import Test.QuickCheck.Property hiding ( Result(..) )
314import Test.QuickCheck.Test
315import Test.QuickCheck.Exception
316#ifndef NO_GADTS
317import Test.QuickCheck.Function
318#endif
319import Test.QuickCheck.Features
320import Test.QuickCheck.State
321#ifndef NO_TEMPLATE_HASKELL
322import Test.QuickCheck.All
323#endif
324
325--------------------------------------------------------------------------
326-- the end.
327