Servant.Mock

Automatically derive a mock webserver that implements some API type, just from the said API type's definition.

Using this module couldn't be simpler. Given some API type, like:

type API = "user" :> Get '[JSON] User

that describes your web application, all you have to do is define a Proxy to it:

myAPI :: Proxy API
myAPI = Proxy

and call mock, which has the following type:

mock :: HasMock api => Proxy api -> Server api

What this says is, given some API type api that it knows it can "mock", mock hands you an implementation of the API type. It does so by having each request handler generate a random value of the appropriate type (User in our case). All you need for this to work is to provide Arbitrary instances for the data types returned as response bodies, hence appearing next to Delete, Get, Patch, Post and Put.

To put this all to work and run the mock server, just call serve on the result of mock to get an Application that you can then run with warp.

main :: IO ()
main = Network.Wai.Handler.Warp.run 8080 $
  serve myAPI (mock myAPI)

Documentation

class HasServer api => HasMock api where

HasMock defines an interpretation of API types than turns them into random-response-generating request handlers, hence providing an instance for all the combinators of the core servant library.

Methods

mock :: Proxy api -> Server api

Calling this method creates request handlers of the right type to implement the API described by api that just generate random response values of the right type. E.g:

  type API = "user" :> Get '[JSON] User
        :| "book" :> Get '[JSON] Book

  api :: Proxy API
  api = Proxy

  -- let's say we will start with the frontend,
  -- and hence need a placeholder server
  server :: Server API
  server = mock api
  

What happens here is that Server API actually "means" 2 request handlers, of the following types:

  getUser :: EitherT ServantErr IO User
  getBook :: EitherT ServantErr IO Book
  

So under the hood, mock uses the IO bit to generate random values of type User and Book every time these endpoints are requested.

Instances

HasMock Raw

(HasMock a, HasMock b) => HasMock ((:<|>) a b)

(Arbitrary a, AllCTRender ctypes a) => HasMock (Get ctypes a)

(Arbitrary a, AllCTRender ctypes a) => HasMock (Post ctypes a)

(Arbitrary a, AllCTRender ctypes a) => HasMock (Delete ctypes a)

(Arbitrary a, AllCTRender ctypes a) => HasMock (Put ctypes a)

(Arbitrary a, AllCTRender ctypes a) => HasMock (Patch ctypes a)

(KnownSymbol s, FromText a, HasMock rest) => HasMock ((:>) * * (Capture * s a) rest)

(KnownSymbol h, FromText a, HasMock rest) => HasMock ((:>) * * (Header h a) rest)

(KnownSymbol s, FromText a, HasMock rest) => HasMock ((:>) * * (QueryParam * s a) rest)

(KnownSymbol s, FromText a, HasMock rest) => HasMock ((:>) * * (QueryParams * s a) rest)

(KnownSymbol s, HasMock rest) => HasMock ((:>) * * (QueryFlag s) rest)

(AllCTUnrender ctypes a, HasMock rest) => HasMock ((:>) * * (ReqBody * ctypes a) rest)

(KnownSymbol s, FromText a, HasMock rest) => HasMock ((:>) * * (MatrixParam * s a) rest)

(KnownSymbol s, FromText a, HasMock rest) => HasMock ((:>) * * (MatrixParams * s a) rest)

(KnownSymbol s, HasMock rest) => HasMock ((:>) * * (MatrixFlag s) rest)

(KnownSymbol path, HasMock rest) => HasMock ((:>) Symbol * path rest)