git.iko.soy/servant-quickcheck
on bf4efbc help sign in
servant-quickcheck/src/Servant/QuickCheck.hs
99 lines 2.7 kB history raw
1-- | @Servant.QuickCheck@ provides utilities related to using QuickCheck over an API.
2-- Rather than specifying properties that individual handlers must satisfy,
3-- you can state properties that ought to hold true of the entire API.
4--
5-- While the API must be described with @servant@ types, the server being
6-- tested itself need not be implemented with @servant-server@ (or indeed,
7-- written in Haskell).
8--
9-- /N.B./ The examples given here assume the following setup:
10--
11-- > import Servant
12-- > import Servant.QuickCheck
13-- > import Test.Hspec
14-- >
15-- > type API = ReqBody '[JSON] Int :> Post '[JSON] String
16-- >
17-- > api :: Proxy API
18-- > api = Proxy
19module Servant.QuickCheck
20 (
22 -- * Server properties
23 -- | Functions to verify that a server meets certain properties.
24 --
25 -- Example:
26 --
27 -- > server :: Server API
28 -- > server = return . show
29 -- >
30 -- >
31 -- > test :: Spec
32 -- > test = describe "my server" $ do
33 -- >
34 -- > it "never throws a 500 on valid input" $ do
35 -- > withServantServer api server $ \url ->
36 -- > serverSatisfiers api url emptyPredicates never500s 100
37 serverSatisfies
39 -- * Server equality
40 -- | Functions to verify that two servers behave identically.
41 --
42 -- This can be useful when for example rewriting or refactoring an
43 -- application.
44 --
45 -- Example:
46 --
47 -- > server :: Server API
48 -- > server = return . show
49 -- >
50 -- > server2 :: Server API
51 -- > server2 = const $ return "hi"
52 -- >
53 -- > test :: Spec
54 -- > test = describe "my new server" $ do
55 -- >
56 -- > it "behaves like the old one" $ do
57 -- > withServantServer api server $ \url1 ->
58 -- > withServantServer api server2 $ \url2 ->
59 -- > serversEqual api url1 url2 100
60 --
61 , serversEqual
63 -- * Server benchmarking
64 -- | Functions that randomly generate and run benchmarking scripts
65 , serverBenchmark
66 , BenchOptions(..)
67 , defaultBenchOptions
70 -- * Test setup helpers
71 -- | Helpers to setup and teardown @servant@ servers during tests.
72 , withServantServer
74 -- * Predicates
75 -- | Predicates (functions with signatures @a -> Bool@) are used to filter
76 -- out QuickCheck-generated values (so as to specify that requests must
77 -- possess certain properties) and to check that the response specifies the
78 -- expected properties.
79 , Predicates
80 , emptyPredicates
81 , addPredicate
82 , addPolyPredicate
84 -- ** Predicate convenience functions
85 , addRightPredicate
86 , addLeftPredicate
88 -- ** Useful predicates
89 , never500s
90 , onlyJsonObjects
92 -- ** Re-exports
93 , BaseUrl(..)
94 , Scheme(..)
96 ) where
98import Servant.QuickCheck.Internal
99import Servant.Client (BaseUrl(..), Scheme(..))