@@ -5,6 +5,49 @@
55{-# LANGUAGE FlexibleContexts #-}
66{-# LANGUAGE FlexibleInstances #-}
77{-# LANGUAGE ScopedTypeVariables #-}
8+-- |
9+-- Module : Servant.Mock
10+-- Copyright : 2015 Alp Mestanogullari
11+-- License : BSD3
12+--
13+-- Maintainer : Alp Mestanogullari <alpmestan@gmail.com>
14+-- Stability : experimental
15+-- Portability : portable
16+--
17+-- Automatically derive a mock webserver that implements some API type,
18+-- just from the said API type's definition.
19+--
20+-- Using this module couldn't be simpler. Given some API type, like:
21+--
22+-- > type API = "user" :> Get '[JSON] User
23+--
24+-- that describes your web application, all you have to do is define
25+-- a 'Proxy' to it:
26+--
27+-- > myAPI :: Proxy API
28+-- > myAPI = Proxy
29+--
30+-- and call 'mock', which has the following type:
31+--
32+-- @
33+-- 'mock' :: 'HasMock' api => 'Proxy' api -> 'Server' api
34+-- @
35+--
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'.
42+--
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.
45+--
46+-- @
47+-- main :: IO ()
48+-- main = Network.Wai.Handler.Warp.run 8080 $
49+-- 'serve' myAPI ('mock' myAPI)
50+-- @
851module Servant.Mock ( HasMock(..) ) where
952
1053#if !MIN_VERSION_base(4,8,0)
@@ -21,7 +64,40 @@ import Servant.API.ContentTypes
2164import Test.QuickCheck.Arbitrary (Arbitrary(..), vector)
2265import Test.QuickCheck.Gen (Gen, generate)
2366
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.
2471class 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:
76+ --
77+ -- @
78+ -- type API = "user" :> Get '[JSON] User
79+ -- :<|> "book" :> Get '[JSON] Book
80+ --
81+ -- api :: Proxy API
82+ -- api = Proxy
83+ --
84+ -- -- let's say we will start with the frontend,
85+ -- -- and hence need a placeholder server
86+ -- server :: Server API
87+ -- server = mock api
88+ -- @
89+ --
90+ -- What happens here is that @'Server' API@
91+ -- actually "means" 2 request handlers, of the following types:
92+ --
93+ -- @
94+ -- getUser :: EitherT ServantErr IO User
95+ -- getBook :: EitherT ServantErr IO Book
96+ -- @
97+ --
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.
25101 mock :: Proxy api -> Server api
26102
27103instance (HasMock a, HasMock b) => HasMock (a :<|> b) where