Hackage :: [Package]

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

[ bsd3, library, servant, web ] [ Propose Tags ] [ Report a vulnerability ]

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

[Skip to Readme]

Modules

[Index] [Quick Jump]

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees

Candidates

Versions [RSS] 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]
Tested with ghc ==8.8.4, ghc ==8.10.7, ghc ==9.0.2, ghc ==9.2.4, ghc ==9.2.8, ghc ==9.4.2, ghc ==9.4.5, ghc ==9.6.1, ghc ==9.6.7, ghc ==9.8.2, ghc ==9.10.2, ghc ==9.12.2
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-10T09:00:46Z
Distributions
Downloads 4 total (4 in the last 30 days)
Rating (no votes yet) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs uploaded by user
Build status unknown [no reports yet]

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:

  • 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.