Test.Tasty.Golden

Getting Started

To get started with golden testing and this library, see Introduction to golden testing.

This module provides a simplified interface. If you want more, see Test.Tasty.Golden.Advanced.

Filenames

Filenames are looked up in the usual way, Thus relative names are relative to the processes current working directory. It is common to run tests from the package's root directory (via cabal test or cabal install --enable-tests), so if your test files are under the tests/ subdirectory, your relative file names should start with tests/ (even if your test.hs is itself under tests/, too).

Line endings

The best way to avoid headaches with line endings (when running tests both on UNIX and Windows) is to treat your golden files as binary, even when they are actually textual.

This means:

• When writing output files from Haskell code, open them in binary mode (see openBinaryFile, withBinaryFile and hSetBinaryMode). This will disable automatic \n -> \r\n conversion on Windows. For convenience, this module exports writeBinaryFile which is just like writeFile but opens the file in binary mode. When using ByteStrings note that Data.ByteString and Data.ByteString.Lazy use binary mode for writeFile, while Data.ByteString.Char8 and Data.ByteString.Lazy.Char8 use text mode.

• Tell your VCS not to do any newline conversion for golden files. For git check in a .gitattributes file with the following contents (assuming your golden files have .golden extension):

*.golden	-text

On its side, tasty-golden reads and writes files in binary mode, too.

Why not let Haskell/git do automatic conversion on Windows? Well, for instance, tar will not do the conversion for you when unpacking a release tarball, so when you run cabal install your-package --enable-tests, the tests will be broken.

As a last resort, you can strip all \rs from both arguments in your comparison function when necessary. But most of the time treating the files as binary does the job.

Linking

The test suite should be compiled with -threaded if you want to avoid blocking any other threads while goldenVsFileDiff and similar functions wait for the result of the diff command.

Windows limitations

When using goldenVsFileDiff or goldenVsStringDiff under Windows the exit code from the diff program that you specify will not be captured correctly if that program uses exec.

More specifically, you will get the exit code of the original child (which always exits with code 0, since it called exec), not the exit code of the process which carried on with execution after exec. This is different from the behavior prescribed by POSIX but is the best approximation that can be realised under the restrictions of the Windows process model. See System.Process for further details or https://github.com/haskell/process/pull/168 for even more.