@hackage / servant-routes-golden

Golden test your Servant APIs using `servant-routes`

Latest0.1.0.0

About

Metadata

  • Last updated , by fpringle
  • License BSD-3-Clause
  • Categories Web Development

  • Maintained by: freddyjepringle@gmail.com

  • Lottery factor: 1

Links

Installation

Tested Compilers

  1. 9.12.2
  2. 9.10.2
  3. 9.8.2
  4. 9.6.7
  5. 9.6.1
  6. 9.4.5
  7. 9.4.2
  8. 9.2.8
  9. 9.2.4
  10. 9.0.2
  11. 8.10.7
  12. 8.8.4

Readme

servant-routes-golden

This package lets us define Golden tests using the HasRoutes class from servant-routes and the hspec-golden library.

See Servant.API.Routes.Golden for reference documentation.

Example

-- file src/API.hs
module API where

import Servant.API

type UserAPI =
  "users"
    :> ( "list" :> Get '[JSON] [User]
          :<|> "create" :> ReqBody '[JSON] UserCreateData :> Post '[JSON] UserID
          :<|> "detail" :> QueryParam' '[Required] "id" UserID :> Get '[JSON] User
       )

-- file test/APISpec.hs

module APISpec where

import API
import Servant.API.Routes.Golden
import Hspec

spec :: Spec
spec =
  it "UserAPI" $ goldenRoutes @UserAPI (show ''UserAPI)

We can run cabal test to generate the starting "golden file":

$ cabal test
API
  UserAPI [✔]
    First time execution. Golden file created.

Of course, if we run the test again, it should pass:

$ cabal test
API
  UserAPI [✔]
    Golden and Actual output didn't change

But let's say we change the API definition slightly:

type UserAPI =
  "users"
    :> ( "list" :> Get '[JSON] [User]
-          :<|> "create" :> ReqBody '[JSON] UserCreateData :> Post '[JSON] UserID
+          :<|> "create-new" :> ReqBody '[JSON] UserCreateData :> Post '[JSON] UserID
          :<|> "detail" :> QueryParam' '[Required] "id" UserID :> Get '[JSON] User
       )

Then when we run the tests again:

$ cabal test
API
  UserAPI [✘]
    Files golden and actual not match

Failures:

  test/APISpec.hs:9:3: 
  1) Servant.API.Routes.Golden UserAPI
       expected: {
                     "/users/create": {
                         "POST": {
                             "auths": [],
                             "description": null,
                             "method": "POST",
                             "params": [],
                             "path": "/users/create",
                             "request_body": "UserCreateData",
                             "request_headers": [],
                             "response": {
                 @@ 45 lines omitted @@
                 
        but got: {
                     "/users/create-new": {
                         "POST": {
                             "auths": [],
                             "description": null,
                             "method": "POST",
                             "params": [],
                             "path": "/users/create-new",
                             "request_body": "UserCreateData",
                             "request_headers": [],
                             "response": {
                 @@ 45 lines omitted @@

This forces us to either:

  • acknowledge that the golden files should be updated, and do so by running the hgold CLI, or
  • realise that our changes resulted in a change to the API which we didn't anticipate, so we have to fix them.