Introduce withNumTests and deprecate withMaxSuccess

changelog

@@ -1,3 +1,6 @@
+UNRELEASED
+	* Deprecate `withMaxSuccess` in favour of the renamed `withNumTests`
+
 QuickCheck 2.14.3 (released 2023-05-31)
 	* Add shrinkBoundedEnum (thanks to Jonathan Knowles)
 	* Add discardAfter for discarding tests on timeout (thanks to Justus Sagemüller)

src/Test/QuickCheck.hs

@@ -19,9 +19,9 @@ You can then use QuickCheck to test @prop_reverse@ on 100 random lists:
 >>> quickCheck prop_reverse
 +++ OK, passed 100 tests.
 
-To run more tests you can use the 'withMaxSuccess' combinator:
+To run more tests you can use the 'withNumTests' combinator:
 
->>> quickCheck (withMaxSuccess 10000 prop_reverse)
+>>> quickCheck (withNumTests 10000 prop_reverse)
 +++ OK, passed 10000 tests.
 
 To use QuickCheck on your own data types you will need to write 'Arbitrary'
@@ -268,6 +268,7 @@ module Test.QuickCheck
   , verbose
   , verboseShrinking
   , noShrinking
+  , withNumTests
   , withMaxSuccess
   , within
   , discardAfter

src/Test/QuickCheck/Property.hs

@@ -466,9 +466,20 @@ again = mapTotalResult (\res -> res{ abort = False })
 -- > quickCheck (withMaxSuccess 1000 p)
 --
 -- will test @p@ up to 1000 times.
+{-# DEPRECATED withMaxSuccess "Use withNumTests instead" #-}
 withMaxSuccess :: Testable prop => Int -> prop -> Property
 withMaxSuccess n = n `seq` mapTotalResult (\res -> res{ maybeNumTests = Just n })
 
+-- | Configures how many times a property will be tested.
+--
+-- For example,
+--
+-- > quickCheck (withNumTests 1000 p)
+--
+-- will test @p@ up to 1000 times.
+withNumTests :: Testable prop => Int -> prop -> Property
+withNumTests n = n `seq` mapTotalResult (\res -> res{ maybeNumTests = Just n })
+
 -- | Check that all coverage requirements defined by 'cover' and 'coverTable'
 -- are met, using a statistically sound test, and fail if they are not met.
 --

src/Test/QuickCheck/Test.hs

@@ -174,7 +174,7 @@ stdArgs = Args
 -- | Tests a property and prints the results to 'stdout'.
 --
 -- By default up to 100 tests are performed, which may not be enough
--- to find all bugs. To run more tests, use 'withMaxSuccess'.
+-- to find all bugs. To run more tests, use 'withNumTests'.
 --
 -- If you want to get the counterexample as a Haskell value,
 -- rather than just printing it, try the

tests/GCoArbitraryExample.hs

@@ -17,7 +17,7 @@ instance (Show a, Read a) => Function (D a) where
 
 prop_coarbitrary (Fun _ f) =
   expectFailure $
-  withMaxSuccess 1000 $
+  withNumTests 1000 $
   f (C1 (2::Int)) `elem` [0, 1 :: Int]
 
 return []

tests/Generators.hs

@@ -29,7 +29,7 @@ path :: (a -> Bool) -> Path a -> Bool
 path p (Path xs) = all p xs
 
 somePath :: (a -> Bool) -> Path a -> Property
-somePath p = expectFailure . withMaxSuccess 1000 . path (not . p)
+somePath p = expectFailure . withNumTests 1000 . path (not . p)
 
 newtype Extremal a = Extremal { getExtremal :: a } deriving (Show, Eq, Ord, Num, Enum, Real, Integral)
 
@@ -139,7 +139,7 @@ prop_nonpositive_bound = somePathInt True getNonPositive (== 0)
 
 reachesBound :: (Bounded a, Integral a, Arbitrary a) =>
   a -> Property
-reachesBound x = withMaxSuccess 1000 (expectFailure (x < 3 * (maxBound `div` 4)))
+reachesBound x = withNumTests 1000 (expectFailure (x < 3 * (maxBound `div` 4)))
 
 prop_reachesBound_Int8 = reachesBound :: Int8 -> Property
 prop_reachesBound_Int16 = reachesBound :: Int16 -> Property

tests/Terminal.hs

@@ -63,7 +63,7 @@ format xs = format1 [] [] xs
 -- * Anything written to stderr (presumably by putTemp) is erased
 prop_terminal :: [Command] -> Property
 prop_terminal cmds =
-  withMaxSuccess 1000 $ ioProperty $
+  withNumTests 1000 $ ioProperty $
   withPipe $ \stdout_read stdout_write ->
   withPipe $ \stderr_read stderr_write -> do
     out <- withHandleTerminal stdout_write (Just stderr_write) $ \tm -> do