@@ -5,6 +5,49 @@
5{-# LANGUAGE FlexibleContexts #-}
5{-# LANGUAGE FlexibleContexts #-}
6{-# LANGUAGE FlexibleInstances #-}
6{-# LANGUAGE FlexibleInstances #-}
7{-# LANGUAGE ScopedTypeVariables #-}
7{-# LANGUAGE ScopedTypeVariables #-}
9+-- Module : Servant.Mock
10+-- Copyright : 2015 Alp Mestanogullari
13+-- Maintainer : Alp Mestanogullari <alpmestan@gmail.com>
14+-- Stability : experimental
15+-- Portability : portable
17+-- Automatically derive a mock webserver that implements some API type,
18+-- just from the said API type's definition.
20+-- Using this module couldn't be simpler. Given some API type, like:
22+-- > type API = "user" :> Get '[JSON] User
24+-- that describes your web application, all you have to do is define
27+-- > myAPI :: Proxy API
30+-- and call 'mock', which has the following type:
33+-- 'mock' :: 'HasMock' api => 'Proxy' api -> 'Server' api
36+-- What this says is, given some API type @api@ that it knows it can
37+-- "mock", 'mock' hands you an implementation of the API type. It does so
38+-- by having each request handler generate a random value of the
39+-- appropriate type (@User@ in our case). All you need for this to work is
40+-- to provide 'Arbitrary' instances for the data types returned as response
41+-- bodies, hence appearing next to 'Delete', 'Get', 'Patch', 'Post' and 'Put'.
43+-- To put this all to work and run the mock server, just call 'serve' on the
44+-- result of 'mock' to get an 'Application' that you can then run with warp.
48+-- main = Network.Wai.Handler.Warp.run 8080 $
49+-- 'serve' myAPI ('mock' myAPI)
8module Servant.Mock ( HasMock(..) ) where
51module Servant.Mock ( HasMock(..) ) where
10#if !MIN_VERSION_base(4,8,0)
53#if !MIN_VERSION_base(4,8,0)
@@ -21,7 +64,40 @@ import Servant.API.ContentTypes
21import Test.QuickCheck.Arbitrary (Arbitrary(..), vector)
64import Test.QuickCheck.Arbitrary (Arbitrary(..), vector)
22import Test.QuickCheck.Gen (Gen, generate)
65import Test.QuickCheck.Gen (Gen, generate)
67+-- | 'HasMock' defines an interpretation of API types
68+-- than turns them into random-response-generating
69+-- request handlers, hence providing an instance for
70+-- all the combinators of the core /servant/ library.
24class HasServer api => HasMock api where
71class HasServer api => HasMock api where
72+ -- | Calling this method creates request handlers of
73+ -- the right type to implement the API described by
74+ -- @api@ that just generate random response values of
75+ -- the right type. E.g:
78+ -- type API = "user" :> Get '[JSON] User
79+ -- :<|> "book" :> Get '[JSON] Book
84+ -- -- let's say we will start with the frontend,
85+ -- -- and hence need a placeholder server
86+ -- server :: Server API
90+ -- What happens here is that @'Server' API@
91+ -- actually "means" 2 request handlers, of the following types:
94+ -- getUser :: EitherT ServantErr IO User
95+ -- getBook :: EitherT ServantErr IO Book
98+ -- So under the hood, 'mock' uses the 'IO' bit to generate
99+ -- random values of type 'User' and 'Book' every time these
100+ -- endpoints are requested.
25 mock :: Proxy api -> Server api
101 mock :: Proxy api -> Server api
27instance (HasMock a, HasMock b) => HasMock (a :<|> b) where
103instance (HasMock a, HasMock b) => HasMock (a :<|> b) where