-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Generate Main module with QuickCheck tests -- @package quickpull @version 0.4.0.0 -- | This module is necessary to maintain compatibility with both -- QuickCheck 2.6 and QuickCheck 2.7. This module is used for newer -- versions of QuickCheck (after version 2.7). module Quickpull.EqShow -- | Like ==, but prints a counterexample when it fails. (===) :: (Eq a, Show a) => a -> a -> Property module Quickpull.Formatting indentAmt :: Int indent :: Int -> String -> String (<+>) :: String -> String -> String module Quickpull.Types -- | A tree of tests. This allows you to group tests for convenient -- display; it also allows you to write computations that return entire -- groups of tests. data TestTree TestTree :: String -> Node -> TestTree label :: TestTree -> String payload :: TestTree -> Node data Node -- | A group of tests. Contains a list of TestTree, each of which -- might be a Test or another Group. Group :: [TestTree] -> Node -- | A QuickCheck test to run. Test :: a -> Node -- | A single property or tree to test. data Article Single :: a -> Article Multi :: TestTree -> Article -- | Metadata about a particular test or group. data Meta Meta :: ModDesc -> Int -> String -> Meta -- | Name of file providing this test or group. modDesc :: Meta -> ModDesc -- | Line number of the test or group. linenum :: Meta -> Int -- | The name of the test or group, such as prop_mytest or -- proptree_mytest. qName :: Meta -> String -- | Description of a single property or tree to test from a file. Unlike -- Item, this does not contain the actual item; this is for use -- when parsing a test input module. data Qual QTree :: Qual QProp :: Qual -- | Description of a module. data ModDesc ModDesc :: String -> [String] -> ModDesc -- | Path to the module modPath :: ModDesc -> String -- | Each part of the hierarchical name modName :: ModDesc -> [String] -- | Creates a ModDesc. makeModDesc :: FilePath -> [FilePath] -> FilePath -> ModDesc -- | Specifies a single item to test, along with metadata about that item. data Decree Decree :: Meta -> Article -> Decree meta :: Decree -> Meta item :: Decree -> Article -- | Summary of all QuickCheck results. data Summary Summary :: !Int -> !Int -> !Int -> !Int -> Summary success :: Summary -> !Int gaveUp :: Summary -> !Int failure :: Summary -> !Int noExpectedFailure :: Summary -> !Int -- | Create a new Group of tests. group :: String -> [TestTree] -> TestTree -- | Create a new Test. test :: Testable a => String -> a -> TestTree instance Eq Qual instance Ord Qual instance Show Qual instance Eq ModDesc instance Ord ModDesc instance Show ModDesc instance Eq Meta instance Ord Meta instance Show Meta instance Show TestTree module Quickpull.Files -- | Takes a stack of directories and a directory where reading was -- started; returns a single path to the relevant directory. concatDirs :: FilePath -> [FilePath] -> FilePath isInterestingFile :: FilePath -> Bool isInterestingDir :: FilePath -> Bool -- | Pulls all modules from a given directory. modsInDirectory :: [FilePath] -> FilePath -> IO [ModDesc] -- | Pulls all modules from the given directory. A module is any file that -- begins with a capital letter and ends in .hs. allModules :: FilePath -> IO [ModDesc] -- | Pulls all properties from the text of a file. Properties that are -- Testable must begin with prop_. Properties that are -- a TestTree must begin with proptree_. -- -- Steps in this computation: -- -- getQuals :: ModDesc -> String -> [(Meta, Qual)] -- | Given a ModDesc, reads the module from disk and parses it. readAndParse :: ModDesc -> IO [(Meta, Qual)] -- | Functions to build TestTree that test properties of -- typeclasses, such as the functor laws, monad laws, and monoid laws. -- These functions are rough; for example, they do not shrink on failure, -- they are monomorphic, and they do not show the counterexamples of -- failing functions. But they are sufficient to help verify the -- lawfulness of your types. module Quickpull.Laws -- | Tests the monad laws: -- -- Left identity: -- -- 
--   return a >>= f == f a
--
-- -- Right identity: -- -- 
--   m >>= return == m
--
-- -- Associativity: -- -- 
--   (m >>= f) >>= g == m >>= (\x -> f x >>= g)
--
monad :: (Eq b, Show b, Monad m) => Gen (m Int) -> Gen (Int -> m Int) -> Gen (m Int -> b) -> TestTree -- | Tests the functor laws: -- -- 
--   fmap id == id
--
-- -- 
--   fmap (f . g) == fmap f . fmap g
--
functor :: (Eq b, Show b, Functor f) => Gen (f Int) -> Gen (f Int -> b) -> TestTree -- | Tests the Applicative laws: -- -- -- -- 
--   pure id <*> v == v
--
-- -- -- -- 
--   pure (.) <*> u <*> v <*> w == u <*> (v <*> w)
--
-- -- -- -- 
--   pure f <*> pure x = pure (f x)
--
-- -- -- -- 
--   u <*> pure y = pure ($ y) <*> u
--
applicative :: (Eq b, Show b, Applicative f) => Gen (f Int) -> Gen (f (Int -> Int)) -> Gen (f Int -> b) -> TestTree -- | Tests the monoid laws: -- -- 
--   mappend mempty x = x
--
-- -- 
--   mappend x mempty = x
--
-- -- 
--   mappend x (mappend y z) = mappend (mappend x y) z
--
-- -- 
--   mconcat = foldr mappend mempty
--
monoid :: (Eq b, Show b, Monoid a) => Gen a -> Gen (a -> b) -> TestTree -- | Tests whether a particular operation is associative, that is: -- -- 
--   a `f` (b `f` c) == (a `f` b) `f` c
--
associative :: (Eq b, Show b) => Gen (a -> a -> a) -> Gen (a -> b) -> Gen a -> Gen Property -- | Tests whether a particular operation is commutative, that is: -- -- 
--   a `f` b == b `f` a
--
commutative :: (Eq b, Show b) => Gen (a -> a -> a) -> Gen (a -> b) -> Gen a -> Gen Property -- | Tests whether a particular value is the left identity, that is: -- -- 
--   z `f` a == a
--
leftIdentity :: (Eq b, Show b) => Gen (a -> a -> a) -> Gen (a -> b) -> Gen a -> Gen a -> Gen Property -- | Tests whether a particular value is the right identity, that is: -- -- 
--   a `f` z == a
--
rightIdentity :: (Eq b, Show b) => Gen (a -> a -> a) -> Gen (a -> b) -> Gen a -> Gen a -> Gen Property module Quickpull.Render metaQual :: Char -> (Meta, Qual) -> String metaQuals :: [(Meta, Qual)] -> String imports :: [ModDesc] -> String -- | Summarizes a Meta in a single line. metaLine :: Meta -> String topComments :: String testModule :: String -> [(Meta, Qual)] -> String summary :: Summary -> String -- | Running tests. To check a TestTree in a REPL, use -- quickCheckTree; to check a QuickCheck Testable, just use -- quickCheck and the similar functions in Test.QuickCheck. -- The other functions in this module will be more useful for checking -- from within a compiled test program. -- -- The QuickCheck docs in Test.QuickCheck contain warnings about -- how type defaulting in GHCi can cause types to silently default to -- (); all those warnings also apply to use of the functions in -- this module. Although QuickCheck has some Template Haskell to help -- with this, Quickpull currently does not. You don't have to worry about -- this in non-interactive use, as the defaulting rules are more strict -- and, with warnings on, GHC will warn you when it defaults a type. module Quickpull.Runners -- | Checks a TestTree and prints the result to standard output. -- Intended for use in a REPL; however, the QuickCheck docs in -- Test.QuickCheck contain warnings about how type defaulting in -- GHCi can cause types to silently default to (); all those -- warnings also apply to use of this function. quickCheckTree :: TestTree -> IO () -- | Checks a TestTree and prints the result to standard output in -- addition to returning it as a list of Result. Each -- Decree returns a list of Result (a Single returns -- a single Result, while a Multi returns a Result -- for each test in the tree.) treeWithResult :: (forall a. Testable a => a -> IO Result) -> TestTree -> IO [Result] -- | Tests a Decree and prints the result to standard output in -- addition to returning a list of Result. Each Decree -- returns a list of Result (a Single returns a single -- Result, while a Multi returns a Result for each -- test in the tree.) decreeWithResult :: (forall a. Testable a => a -> IO Result) -> Decree -> IO [Result] -- | Tests each Decree using a custom function that you specify; -- this allows you to vary the test depending on what's in the -- Decree. Each Decree returns a list of Result (a -- Single returns a single Result, while a Multi -- returns a Result for each test in the tree.) The tests are -- printed to standard output as they run, in addition to returning the -- Result. seeDecree :: (Decree -> forall a. Testable a => a -> IO Result) -> [Decree] -> IO [[Result]] -- | Tests each Decree and prints the results to standard output. -- Exits successfully if all tests succeeded; otherwise, exits -- unsuccessfully. -- -- Not recommended for REPL use as this function will either kill your -- REPL when it's done or, in the case of recent GHC versions, issue an -- exception. defaultMain :: [Decree] -> IO () -- | Like defaultMain but allows you to pass arguments to the -- QuickCheck driver. -- -- Not recommended for REPL use as this function will either kill your -- REPL when it's done or, in the case of recent GHC versions, issue an -- exception. defaultMainWith :: Args -> [Decree] -> IO () -- | Tallies up the Results. summarize :: [Result] -> Summary -- | Exit successfully if there were no failures, give-ups, or -- no-expected-failures; otherwise, exit unsuccessfully. exitCode :: Summary -> ExitCode -- | Quickpull - a simple testing framework to reduce boilerplating -- -- Quickpull is a testing framework that helps you test multiple -- QuickCheck properties with a minimum of boilerplating and redundancy. -- It consists of two parts: first, an executable file which reads -- Haskell modules and extracts properties from them; and second, this -- library, which runs the tests. -- -- The executable, named quickpull by default, is a -- preprocessor. You have to run this executable to get the QuickCheck -- properties from your modules. It fetches single properties, which are -- values that have type Testable a, as well as trees -- of properties, which have type TestTree. For example, to get -- your properties if they are in modules in a directory named -- tests, run this from your project's root directory: -- -- 
--   $ quickpull tests
--
-- -- The results will be printed to standard output. Inspect this output, -- then redirect the output to a module named Decrees. -- -- quickpull does not know or parse Haskell. It simply reads the -- file and, following a few simple rules, copies the names of properties -- and trees, along with metadata about them. All single properties must -- be named beginning with prop_, and trees must be named -- beginning with proptree_. The name of the property or tree -- must be the first thing on the line, not preceded by spaces on the -- line (which is probably how you write modules anyway if you are using -- layout.) -- -- One problem with this method is that code that is commented out using -- the block commenting (with braces) will still be read; at present a -- simple workaround is to comment out blocks of code using per-line -- commenting instead. -- -- quickpull only gets tests from files ending in .hs, -- and the property name must be the very first thing on the line; -- therefore, literate Haskell files won't work. -- -- You then need a program that actually runs your tests. To get started, -- you need just a short simple program, like this: -- -- 
--   module Main where
--   
--   import Decrees
--   import Quickpull
--   
--   main = defaultMain decrees
--
-- -- When run, this program will run the tests, print the results to -- standard output, and exit with an appropriate error code. -- -- If your needs are more complicated, study the Quickpull.Types -- and Quickpull.Runners modules. For example, you can: -- -- -- -- There is also the Quickpull.Laws module, which helps you test -- common laws, such as the Monad laws and the Monoid laws. -- -- Advantages of Quickpull: -- -- -- -- Disadvantages: -- -- -- -- For examples of usage, see the tests that are bundled with Quickpull -- in the tests/ directory. These tests use Quickpull to test -- some common laws, such as the Monad and Monoid laws, on types that -- come in the standard library. There is a similar test for the -- QuickCheck Gen monad in the quickcheck-tests/ -- directory; interestingly enough, Gen does not satisfy the monad laws. -- To compile and run the tests/ tests, run cabal with the -- --enable-tests option; it will produce a binary named -- quickpull-tests. For the quickcheck-tests/ -- directory, run Cabal with the -fbuild-test-gen option; it -- will produce a binary named quickpull-test-gen. -- -- To see how to integrate Quickpull into a development workflow, see the -- Quickpull source on Github at -- -- http://www.github.com/massysett/quickpull -- -- It has a generate script that runs the quickpull -- binary to generate the appropriate Decrees modules; after -- that, cabal can be used as usual to build the package, -- executables, and distribution tarball. That way, although your test -- suite will need Quickpull listed as a build dependency so the tests -- will build, your users will not need to do any preprocessing to run -- the tests. module Quickpull -- | A tree of tests. This allows you to group tests for convenient -- display; it also allows you to write computations that return entire -- groups of tests. data TestTree -- | Create a new Group of tests. group :: String -> [TestTree] -> TestTree -- | Create a new Test. test :: Testable a => String -> a -> TestTree -- | Description of a module. data ModDesc ModDesc :: String -> [String] -> ModDesc -- | Path to the module modPath :: ModDesc -> String -- | Each part of the hierarchical name modName :: ModDesc -> [String] -- | Metadata about a particular test or group. data Meta Meta :: ModDesc -> Int -> String -> Meta -- | Name of file providing this test or group. modDesc :: Meta -> ModDesc -- | Line number of the test or group. linenum :: Meta -> Int -- | The name of the test or group, such as prop_mytest or -- proptree_mytest. qName :: Meta -> String -- | A single property or tree to test. data Article Single :: a -> Article Multi :: TestTree -> Article -- | Specifies a single item to test, along with metadata about that item. data Decree Decree :: Meta -> Article -> Decree meta :: Decree -> Meta item :: Decree -> Article -- | Checks a TestTree and prints the result to standard output. -- Intended for use in a REPL; however, the QuickCheck docs in -- Test.QuickCheck contain warnings about how type defaulting in -- GHCi can cause types to silently default to (); all those -- warnings also apply to use of this function. quickCheckTree :: TestTree -> IO () -- | Tests each Decree and prints the results to standard output. -- Exits successfully if all tests succeeded; otherwise, exits -- unsuccessfully. -- -- Not recommended for REPL use as this function will either kill your -- REPL when it's done or, in the case of recent GHC versions, issue an -- exception. defaultMain :: [Decree] -> IO () -- | Like defaultMain but allows you to pass arguments to the -- QuickCheck driver. -- -- Not recommended for REPL use as this function will either kill your -- REPL when it's done or, in the case of recent GHC versions, issue an -- exception. defaultMainWith :: Args -> [Decree] -> IO ()