# hspec-golden [![Build and Test](https://github.com/stackbuilders/hspec-golden/actions/workflows/build-and-test.yml/badge.svg?branch=main)](https://github.com/stackbuilders/hspec-golden/actions/workflows/build-and-test.yml) [![Hackage](https://img.shields.io/hackage/v/hspec-golden.svg)](http://hackage.haskell.org/package/hspec-golden) ## Description 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`. ## Usage You can write golden tests using `defaultGolden` helper: ```haskell 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: ```haskell 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: ```haskell {-# 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 ``` ## Install CLI 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 ``` ## Contributors ✨ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/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](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome! ## License MIT, see the [LICENSE file](./LICENSE). ## Contributing Do you want to contribute to this project? Please take a look at our [contributing guideline](/docs/CONTRIBUTING.md) to know how you can help us build it. --- Stack Builders

[Check out our libraries](https://github.com/stackbuilders/) | [Join our team](https://www.stackbuilders.com/join-us/)