Implements stubbing of an HTTP request function

Stubbing is accomplished by holding a list of HttpStub somewhere, which defines how to respond to requests that match. The simplest way to do so is to use the IsString instance:

stubs :: [HttpStub]
stubs =
  [ "https://example.com"
  ]

You can now use,

httpStubbed stubs :: Request -> Response ByteString

Anywhere you need an HTTP requesting function and it will respond 200 with an empty body for any GET requests made to this domain.

Stubbed responses can be modified through lenses:

stubs :: [HttpStub]
stubs =
  [ "https://example.com"
      & statusL .~ status400
      & bodyL .~ "Let's test a Bad Request"
  ]

The string is passed to parseRequest_, so anything valid there is valid here, such as setting the method:

data MyItem = MyItem
  { -- ...
  }
  deriving stock Generic
  deriving anyclass ToJSON

stubs :: [HttpStub]
stubs =
  [ "POST https://example.com/items"
      & json [MyItem]
      -- ^ Now matches requests with JSON in the Accept Header only
      --   Responds with Content-Type JSON
      --   Responds with a body of the JSON-encoded items
  ]

MonadHttp

Once we have the stubs, we can set up a MonadHttp context that uses it:

data TestApp = TestApp
  { appHttpStubs :: [HttpStubs]
  }

-- Assume TestAppT is a ReaderT TestApp
instance MonadHttp (TestAppT m a) where
  httpLbs req = do
    stubs <- asks appHttpStubs
    pure $ httpStubbed stubs req

Additionally, there are tools for DerivingVia or running things in a concrete HttpStubsT stack.

Handling Un-stubbed Requests

When no stubs match a given request, we call error -- this seems uncouth, but is actually the best possible behavior for the intended use-case in (e.g.) HSpec:

One other reasonable behavior would be to respond 404 to any un-matched requests. This can be accomplished by adding a "match anything" stub at the end:

stubs :: [HttpStub]
stubs =
  [ -- ...
  , -- ...
  , httpStub "Anything" MatchAnything
      & statusL .~ status404
      & bodyL .~ "Not found"
  ]