diff --git a/ChangeLog.md b/ChangeLog.md --- a/ChangeLog.md +++ b/ChangeLog.md @@ -1,4 +1,25 @@ # Changelog for hspec-golden +## 0.2.2.0 +#### Add +* `golden` helper to write tests + +## 0.2.1.1 +#### Add +* Add colors to hspec-golden CLI tool. + +## 0.2.1.0 +#### Add +* Instance for IO Golden type. Kudos to @dbalseiro + +## 0.2.0.1 +#### Add +* Update docs. + +## 0.2.0.0 +#### Add +* More flexible file locations +* Contributed by: @bitc and @christianheyn + ## 0.1.0.2 #### Add * Lowerbound for `hspec-core` in `hspec-golden` library diff --git a/LICENSE b/LICENSE --- a/LICENSE +++ b/LICENSE @@ -1,30 +1,21 @@ -Copyright Stack Builders (c) 2019-2020 - -All rights reserved. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are met: +MIT License - * Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. +Copyright (c) 2022 Stack Builders Inc. - * Redistributions in binary form must reproduce the above - copyright notice, this list of conditions and the following - disclaimer in the documentation and/or other materials provided - with the distribution. +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: - * Neither the name of Author name here nor the names of other - contributors may be used to endorse or promote products derived - from this software without specific prior written permission. +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@ # hspec-golden -[![Build Status](https://travis-ci.org/stackbuilders/hspec-golden.svg?branch=master)](https://travis-ci.org/stackbuilders/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 @@ -9,7 +9,7 @@ `hspec-golden` allows you to write golden tests using the popular `hspec`. -## Getting started +## Usage You can write golden tests using `defaultGolden` helper: @@ -25,6 +25,15 @@ 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: @@ -43,18 +52,20 @@ encodePretty = prettyText, writeToFile = T.writeFile, readFromFile = T.readFile, - testName = name, - directory = ".myGoldenTestDir", + goldenFile = name, + actualFile = Just (name "-actual"), failFirstTime = False } -describe "myTextFunc" $ - it "generates the right output with the right params" $ - let textOutput = myTextFunc params - in myGoldenTest (show 'myTextFunc) textOutput +spec :: Spec +spec = + describe "myTextFunc" $ + it "generates the right output with the right params" $ + let textOutput = myTextFunc params + in myGoldenTest (show 'myTextFunc) textOutput ``` -## Installing CLI +## Install CLI You can install the `hspec-golden` command line interface (CLI) with `stack`: @@ -97,11 +108,55 @@ $ hgold -u .myGoldenTest ``` -## Licensing +## Contributors ✨ +Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)): + + + + + + + + + + + + + + + + + + + + + + + + + +
Cristhian Motoche
Cristhian Motoche
💻		Christian Wünsche (ehem Heyn)
Christian Wünsche (ehem Heyn)
💻		Bit Connor
Bit Connor
💻		Diego Balseiro
Diego Balseiro
💻		Jorge Guerra Landázuri
Jorge Guerra Landázuri
💻		Phil Hazelden
Phil Hazelden
💻		Alexander Vieth
Alexander Vieth
💻
Guillaume Bouchard
Guillaume Bouchard
💻		Stefani Castellanos
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 -Pull requests for modifications to this program are welcome! Fork and open a PR. -If you're looking for a place to start, you may want to check the [open issue](https://github.com/stackbuilders/hspec-golden/issues). +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/) diff --git a/app/Main.hs b/app/Main.hs --- a/app/Main.hs +++ b/app/Main.hs @@ -1,27 +1,25 @@ module Main where +import System.Console.ANSI import Control.Monad (forM_, when) import Data.Version (showVersion) import Paths_hspec_golden (version) import Options.Applicative import Data.Monoid ((<>)) +import GHC.IO (catch) import System.Directory (doesDirectoryExist, doesFileExist, listDirectory, renameFile) import qualified Test.Hspec.Golden as G defaultDirGoldenTest :: FilePath -defaultDirGoldenTest = G.directory (G.defaultGolden "" "") +defaultDirGoldenTest = ".golden" -- CLI Params -data Params = - Params - { updateDir :: FilePath - -- , shouldUpdate :: Bool - } deriving Show - +newtype Params = Params { updateDir :: FilePath } deriving Show + params :: Parser Params -params = Params +params = Params <$> strOption (long "update" <> short 'u' @@ -31,18 +29,28 @@ <> help "The testing directory where you're dumping your results.") versionOpt :: Parser (a->a) -versionOpt = infoOption (showVersion version) +versionOpt = infoOption (showVersion version) (long "version" - <> short 'v' + <> short 'v' <> help "Show version") - ---Update Files +withColor :: Color -> IO () -> IO () +withColor color action = do + setSGR [SetColor Foreground Dull color] + action + setSGR [Reset] + +success, warning, failure :: IO () -> IO () +success = withColor Green +warning = withColor Yellow +failure = withColor Red + +-- Update golden files in the given directory updateGolden :: FilePath -> IO () updateGolden dir = do - putStrLn "Replacing golden with actual..." + putStrLn "Replacing golden with actual:" go dir - putStrLn "Finish..." + success $ putStrLn "Finished!" where go dir = do entries <- listDirectory dir @@ -59,9 +67,16 @@ goldenFilePath = testPath ++ "/golden" in do actualFileExist <- doesFileExist actualFilePath - when actualFileExist (do - putStrLn $ " Replacing file: " ++ goldenFilePath ++ " with: " ++ actualFilePath - renameFile actualFilePath goldenFilePath) + when actualFileExist $ do + putStr " Replacing file: " + warning $ putStr goldenFilePath + putStr " with: " + success $ putStrLn actualFilePath + renameFile actualFilePath goldenFilePath `catch` handleErr + where + handleErr :: IOError -> IO () + handleErr e = + failure $ putStr $ "Warning: Could not replace file due to error: " ++ show e -- Main diff --git a/hspec-golden.cabal b/hspec-golden.cabal --- a/hspec-golden.cabal +++ b/hspec-golden.cabal @@ -1,24 +1,38 @@ cabal-version: 1.12 --- This file has been generated from package.yaml by hpack version 0.33.1. +-- This file has been generated from package.yaml by hpack version 0.36.0. -- -- see: https://github.com/sol/hpack --- --- hash: 34c8c9ac8723c74e1b8dfdf2b6153ad8f1d4c677cbdf667841dc84bda2db22d4 name: hspec-golden -version: 0.1.0.3 +version: 0.2.2.0 synopsis: Golden tests for hspec -description: Please see the README on GitHub at +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@. + . + > describe "myFunc" $ + > it "generates the right output with the right params" $ + > let output = show $ myFunc params + > in defaultGolden "myFunc" output + . + Please see the + for more information. category: Testing homepage: https://github.com/stackbuilders/hspec-golden#readme bug-reports: https://github.com/stackbuilders/hspec-golden/issues author: Stack Builders -maintainer: cmotoche@stackbuilders.com -copyright: 2019-2020 Stack Builders Inc +maintainer: Cristhian Motoche +copyright: 2019-Present Stack Builders Inc license: MIT license-file: LICENSE build-type: Simple +tested-with: + GHC==8.8, GHC==8.10, GHC==9.0 extra-source-files: README.md ChangeLog.md @@ -36,8 +50,9 @@ src build-depends: base >=4.6 && <5 - , directory - , hspec-core >=2.5 && <3.0 + , directory >=1.3.6 && <1.4 + , filepath >=1.0 && <2.0 + , hspec-core >=2.10 && <3.0 default-language: Haskell2010 executable hgold @@ -48,10 +63,11 @@ app ghc-options: -threaded -rtsopts -with-rtsopts=-N build-depends: - base >=4.6 && <5 + ansi-terminal >=1.0 && <2.0 + , base >=4.6 && <5 , directory >=1.2.5.0 , hspec-golden - , optparse-applicative + , optparse-applicative >=0.18.1 && <0.19 default-language: Haskell2010 test-suite hspec-golden-test @@ -63,6 +79,8 @@ hs-source-dirs: test ghc-options: -threaded -rtsopts -with-rtsopts=-N + build-tool-depends: + hspec-discover:hspec-discover >=2.0 && <3.0 build-depends: base >=4.6 && <5 , directory diff --git a/src/Test/Hspec/Golden.hs b/src/Test/Hspec/Golden.hs --- a/src/Test/Hspec/Golden.hs +++ b/src/Test/Hspec/Golden.hs @@ -21,13 +21,19 @@ module Test.Hspec.Golden ( Golden(..) , defaultGolden + , golden ) where +import Control.Monad.IO.Class (MonadIO (liftIO)) import Data.IORef -import System.Directory (createDirectoryIfMissing, doesFileExist) -import Test.Hspec.Core.Spec (Example (..), FailureReason (..), - Result (..), ResultStatus (..)) +import Data.List (intercalate) +import System.Directory (createDirectoryIfMissing, + doesFileExist) +import System.FilePath (takeDirectory, ()) +import Test.Hspec.Core.Spec (Example (..), FailureReason (..), + Result (..), ResultStatus (..), Spec, + SpecWith, getSpecDescriptionPath, it) -- | Golden tests parameters @@ -43,8 +49,8 @@ -- encodePretty = prettyText, -- writeToFile = T.writeFile, -- readFromFile = T.readFile, --- testName = name, --- directory = ".specific-golden-dir", +-- goldenFile = ".specific-golden-dir" name "golden", +-- actualFile = Just (".specific-golden-dir" name "actual"), -- failFirstTime = False -- } -- @@ -59,8 +65,8 @@ encodePretty :: str -> String, -- ^ Makes the comparison pretty when the test fails writeToFile :: FilePath -> str -> IO (), -- ^ How to write into the golden file the file readFromFile :: FilePath -> IO str, -- ^ How to read the file, - testName :: String, -- ^ Test name (make sure it's unique otherwise it could be override) - directory :: FilePath, -- ^ Directory where you write your tests + goldenFile :: FilePath, -- ^ Where to read/write the golden file for this test. + actualFile :: Maybe FilePath, -- ^ Where to save the actual file for this test. If it is @Nothing@ then no file is written. failFirstTime :: Bool -- ^ Whether to record a failure the first time this test is run } @@ -68,6 +74,19 @@ type Arg (Golden str) = () evaluateExample e = evaluateExample (\() -> e) +instance Eq str => Example (IO (Golden str)) where + type Arg (IO (Golden str)) = () + evaluateExample e = evaluateExample (\() -> e) + +instance Eq str => Example (arg -> IO (Golden str)) where + type Arg (arg -> IO (Golden str)) = arg + evaluateExample golden _ action _ = do + ref <- newIORef (Result "" Success) + action $ \arg -> do + r <- runGolden =<< golden arg + writeIORef ref (fromGoldenResult r) + readIORef ref + instance Eq str => Example (arg -> Golden str) where type Arg (arg -> Golden str) = arg evaluateExample golden _ action _ = do @@ -80,12 +99,12 @@ -- | Transform a GoldenResult into a Result from Hspec fromGoldenResult :: GoldenResult -> Result -fromGoldenResult SameOutput = Result "Golden and Actual output hasn't changed" Success +fromGoldenResult SameOutput = Result "Golden and Actual output didn't change" Success fromGoldenResult FirstExecutionSucceed = Result "First time execution. Golden file created." Success fromGoldenResult FirstExecutionFail = Result "First time execution. Golden file created." - (Failure Nothing (Reason "failFirstTime is set to True")) -fromGoldenResult (MissmatchOutput expected actual) = + (Failure Nothing (Reason "Golden file did not exist and was created. Failed because failFirstTime is set to True")) +fromGoldenResult (MismatchOutput expected actual) = Result "Files golden and actual not match" (Failure Nothing (ExpectedButGot Nothing expected actual)) @@ -103,17 +122,17 @@ Golden { output = output_, encodePretty = show, - testName = name, writeToFile = writeFile, readFromFile = readFile, - directory = ".golden", + goldenFile = ".golden" name "golden", + actualFile = Just (".golden" name "actual"), failFirstTime = False } -- | Possible results from a golden test execution data GoldenResult = - MissmatchOutput String String + MismatchOutput String String | SameOutput | FirstExecutionSucceed | FirstExecutionFail @@ -122,26 +141,47 @@ runGolden :: Eq str => Golden str -> IO GoldenResult runGolden Golden{..} = - let goldenTestDir = directory ++ "/" ++ testName - goldenFilePath = goldenTestDir ++ "/" ++ "golden" - actualFilePath = goldenTestDir ++ "/" ++ "actual" + let goldenTestDir = takeDirectory goldenFile in do createDirectoryIfMissing True goldenTestDir - goldenFileExist <- doesFileExist goldenFilePath + goldenFileExist <- doesFileExist goldenFile - -- the actual file is always written, this way, hgold will always - -- upgrade based on the latest run - writeToFile actualFilePath output + case actualFile of + Nothing -> return () + Just actual -> do + -- It is recommended to always write the actual file, this way, + -- hgold will always upgrade based on the latest run + let actualDir = takeDirectory actual + createDirectoryIfMissing True actualDir + writeToFile actual output if not goldenFileExist then do - writeToFile goldenFilePath output + writeToFile goldenFile output return $ if failFirstTime then FirstExecutionFail else FirstExecutionSucceed else do - contentGolden <- readFromFile goldenFilePath + contentGolden <- readFromFile goldenFile if contentGolden == output then return SameOutput - else return $ MissmatchOutput (encodePretty contentGolden) (encodePretty output) + else return $ MismatchOutput (encodePretty contentGolden) (encodePretty output) + + +-- | A helper function to create a golden test. +-- +-- @ +-- describe "function" $ +-- golden "some name" $ +-- return content +-- @ + +golden + :: String -- ^ Test description + -> IO String -- ^ Content (@return content@ for pure functions) + -> Spec +golden description runAction = do + path <- (++ words description) <$> getSpecDescriptionPath + it description $ + defaultGolden (intercalate "-" path) <$> runAction diff --git a/test/Test/Hspec/GoldenSpec.hs b/test/Test/Hspec/GoldenSpec.hs --- a/test/Test/Hspec/GoldenSpec.hs +++ b/test/Test/Hspec/GoldenSpec.hs @@ -1,6 +1,6 @@ module Test.Hspec.GoldenSpec (spec) where -import Control.Monad (void) +import Control.Monad (void, when) import Test.Hspec import qualified Test.Hspec.Core.Runner as H @@ -17,19 +17,27 @@ fixtureContent = "simple text" fixtureTestName = "id" -goldenTestDir, goldenFile, actualFile :: FilePath -goldenTestDir = directory (defaultGolden "" "") ++ "/" ++ "id" -goldenFile = goldenTestDir ++ "/" ++ "golden" -actualFile = goldenTestDir ++ "/" ++ "actual" +goldenTestDir, goldenFilePath, actualFilePath :: FilePath +goldenTestDir = ".golden" ++ "/" ++ "id" +goldenFilePath = goldenTestDir ++ "/" ++ "golden" +actualFilePath = goldenTestDir ++ "/" ++ "actual" fixtureTest :: String -> H.Spec fixtureTest content = - H.describe "id" $ - H.it "should work" $ + describe "id" $ + it "should work" $ defaultGolden fixtureTestName content +fixtureGoldenTest :: String -> H.Spec +fixtureGoldenTest content = + describe "id" $ + golden "golden sample file" $ + return content + removeFixtures :: IO () -removeFixtures = removeDirectoryRecursive goldenTestDir +removeFixtures = do + exists <- doesDirectoryExist ".golden" + when exists $ removeDirectoryRecursive ".golden" runSpec :: H.Spec -> IO [String] runSpec = captureLines . H.hspecResult @@ -43,12 +51,12 @@ context "when the test is executed for the first time" $ do it "should create a `golden` file" $ do void $ runSpec $ fixtureTest fixtureContent - goldenFileContent <- readFile goldenFile + goldenFileContent <- readFile goldenFilePath goldenFileContent `shouldBe` fixtureContent it "should create a `actual` file" $ do void $ runSpec $ fixtureTest fixtureContent - actualFileContent <- readFile goldenFile + actualFileContent <- readFile goldenFilePath actualFileContent `shouldBe` fixtureContent context "when the output is updated" $ @@ -56,20 +64,32 @@ it "should create the `actual` output file" $ do void $ runSpec $ fixtureTest fixtureContent void $ runSpec $ fixtureTest fixtureUpdatedContent - actualFileContent <- readFile actualFile + actualFileContent <- readFile actualFilePath actualFileContent `shouldBe` fixtureUpdatedContent - it "shouldn't overide the `golden` file" $ do + it "shouldn't override the `golden` file" $ do void $ runSpec $ fixtureTest fixtureContent void $ runSpec $ fixtureTest fixtureUpdatedContent - goldenFileContent <- readFile goldenFile + goldenFileContent <- readFile goldenFilePath goldenFileContent `shouldBe` fixtureContent + context "when IO actions are needed in the test case" $ + it "enables `defaultGolden` to be accessible from the test case" $ do + void $ runSpec $ fixtureTest fixtureContent + result <- readFile goldenFilePath + pure $ defaultGolden "io-test" result context "when the output is not updated" $ context "when the test is executed a second time" $ it "shouldn't change the `golden` file content" $ do void $ runSpec $ fixtureTest fixtureContent void $ runSpec $ fixtureTest fixtureContent - goldenFileContent <- readFile goldenFile + goldenFileContent <- readFile goldenFilePath goldenFileContent `shouldBe` fixtureContent + + describe "golden" $ + context "given some input" $ + it "creates file with separated dashes" $ do + void $ runSpec $ fixtureGoldenTest fixtureContent + goldenFile <- readFile ".golden/id-golden-sample-file/golden" + goldenFile `shouldBe` fixtureContent