Hackage :: [Package]

servant-routes-golden: Golden test your Servant APIs using `servant-routes`

This is a package candidate release! Here you can preview how this package release will appear once published to the main package index (which can be accomplished via the 'maintain' link below). Please note that once a package has been published to the main package index it cannot be undone! Please consult the package uploading documentation for more information.

[maintain] [Publish]

See the documentation of Servant.API.Routes.Golden.

[Skip to Readme]

Properties

Versions 0.1.0.0, 0.1.0.0
Change log CHANGELOG.md
Dependencies aeson (>=2.0 && <2.3), aeson-pretty (>=0.8.8 && <0.9), base (>=4.13 && <5), hspec-core (>=2.10.0 && <2.12), hspec-golden (>=0.2 && <0.3), servant-routes (>=0.1.0.0 && <0.2), text (>=1.2 && <2.2) [details]
License BSD-3-Clause
Copyright Copyright(c) Frederick Pringle 2025
Author Frederick Pringle
Maintainer freddyjepringle@gmail.com
Category Servant, Web
Home page https://github.com/fpringle/servant-routes
Bug tracker https://github.com/fpringle/servant-routes/issues
Source repo head: git clone https://github.com/fpringle/servant-routes(servant-routes-golden)
Uploaded by fpringle at 2025-06-10T07:54:23Z

Modules

[Index] [Quick Jump]

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees

Readme for servant-routes-golden-0.1.0.0

[back to package description]

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: