Safe Haskell	Safe-Inferred
Language	Haskell2010

Test.Tasty.Silver

Description

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

Note about filenames

They 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 stack test), 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).

Note about 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. When using ByteString, 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 version control 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-silver` 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 e.g. stack install your-package --tests, the tests will be broken.

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

Synopsis

goldenVsFile :: TestName -> FilePath -> FilePath -> IO () -> TestTree
goldenVsProg :: TestName -> FilePath -> FilePath -> [String] -> Text -> TestTree
goldenVsAction :: TestName -> FilePath -> IO a -> (a -> Text) -> TestTree
printProcResult :: (ExitCode, Text, Text) -> Text
findByExtension :: [FilePath] -> FilePath -> IO [FilePath]

Documentation

goldenVsFile Source #

Arguments

:: TestName	test name
-> FilePath	path to the «golden» file (the file that contains correct output)
-> FilePath	path to the output file
-> IO ()	action that creates the output file
-> TestTree	the test verifies that the output file contents is the same as the golden file contents

Compare a given file contents against the golden file contents. Assumes that both text files are utf8 encoded.

goldenVsProg Source #

Arguments

:: TestName	test name
-> FilePath	path to the golden file
-> FilePath	executable to run.
-> [String]	arguments to pass.
-> Text	stdin
-> TestTree

Compares a given file with the output (exit code, stdout, stderr) of a program. Assumes that the program output is utf8 encoded.

goldenVsAction Source #

Arguments

:: TestName	test name
-> FilePath	path to the «golden» file (the file that contains correct output)
-> IO a	action that returns a text-like value.
-> (a -> Text)	Converts a value to it's textual representation.
-> TestTree	the test verifies that the returned textual representation is the same as the golden file contents

Compare something text-like against the golden file contents. For the conversion of inputs to text you may want to use the Data.Text.Encoding or/and System.Process.Text modules.

printProcResult :: (ExitCode, Text, Text) -> Text Source #

Converts the output of a process produced by e.g. System.Process.Text to a textual representation. Stdout/stderr are written seperately, any ordering relation between the two streams is lost in the translation.

findByExtension Source #

Arguments

:: [FilePath]	extensions
-> FilePath	directory
-> IO [FilePath]	paths

Find all files in the given directory and its subdirectories that have the given extensions. It is typically used to find all test files and produce a golden test per test file.

The returned paths use forward slashes (/) to separate path components, even on Windows. Thus if the file name ends up in a golden file, it will not differ when run on another platform.

The semantics of extensions is the same as in takeExtension. In particular, non-empty extensions should have the form ".ext".

This function may throw any exception that getDirectoryContents may throw.

It doesn't do anything special to handle symlinks (in particular, it probably won't work on symlink loops). Nor is it optimized to work with huge directory trees (you'd probably want to use some form of coroutines for that).