Golden tests store the expected output in a separated file. Each time a golden test is executed the output of the subject under test (SUT) is compared with the expected output. If the output of the SUT changes then the test will fail until the expected output is updated.
hspec-golden
allows you to write golden tests using the popular hspec
.
You can write golden tests using defaultGolden
helper:
describe "myFunc" $
it "generates the right output with the right params" $
let output = show $ myFunc params
in defaultGolden "myFunc" output
The first parameter of defaultGolden
is the golden file name. I recommend you to use
show
and 'functionName
(enable TemplateHaskellQuotes
for the quote) to
always have a unique name for your file. Example: show 'myFunc == MyModule.myFunc
.
Although, you can name it as you like.
You can write golden tests using golden
helper:
describe "myFunc" $
golden "generates the right output with the right params" $
let output = show $ myFunc params
in return output
In case your output isn't a String
you can define your own Golden
test
using the Golden
data type:
{-# LANGUAGE TemplateHaskellQuotes #-}
import Test.Hspec
import Test.Hspec.Golden
import Data.Text (Text)
import qualified Data.Text.IO as T
myGoldenTest :: String -> Text -> Golden Text
myGoldenTest name actualOutput =
Golden {
output = actualOutput,
encodePretty = prettyText,
writeToFile = T.writeFile,
readFromFile = T.readFile,
goldenFile = name,
actualFile = Just (name </> "-actual"),
failFirstTime = False
}
spec :: Spec
spec =
describe "myTextFunc" $
it "generates the right output with the right params" $
let textOutput = myTextFunc params
in myGoldenTest (show 'myTextFunc) textOutput
You can install the hspec-golden
command line interface (CLI) with stack
:
$ stack install hspec-golden
or cabal
:
$ cabal install hspec-golden
The CLI is called hgold
:
$ hgold -h
Update your golden files
Usage: hgold [-u|--update [DIR]] [-v|--version]
Available options:
-u,--update [DIR] The testing directory where you're dumping your
results. (default: ".golden")
-v,--version Show version
-h,--help Show this help text
Update the golden tests under .golden
directory:
$ hgold
Update the golden tests under .myGoldenTest
directory:
$ hgold -u .myGoldenTest
Thanks goes to these wonderful people (emoji key):
Cristhian Motoche 💻 |
Christian Wünsche (ehem Heyn) 💻 |
Bit Connor 💻 |
Diego Balseiro 💻 |
Jorge Guerra Landázuri 💻 |
Phil Hazelden 💻 |
Alexander Vieth 💻 |
Guillaume Bouchard 💻 |
Stefani Castellanos 💻 |
|||||
Add your contributions |
This project follows the all-contributors specification. Contributions of any kind welcome!
MIT, see the LICENSE file.
Do you want to contribute to this project? Please take a look at our contributing guideline to know how you can help us build it.