-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/

-- | Golden tests support for tasty
--   
--   This package provides support for «golden testing». A golden test is
--   an IO action that writes its result to a file. To pass the test, this
--   output file should be identical to the corresponding «golden» file,
--   which contains the correct result for the test. To get started with
--   golden testing and this library, see Introduction to golden
--   testing.
@package tasty-golden
@version 2.3.5

module Test.Tasty.Golden.Advanced

-- | A very general testing function.
goldenTest :: TestName -> IO a -> IO a -> (a -> a -> IO (Maybe String)) -> (a -> IO ()) -> TestTree

-- | A variant of goldenTest that also provides for deleting the
--   output file. The DeleteOuputFile option controls the
--   circumstances in which the output file is to be deleted.
goldenTest2 :: TestName -> IO a -> IO a -> (a -> a -> IO (Maybe String)) -> (a -> IO ()) -> IO () -> TestTree

-- | 
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
--   Process for further details or
--   https://github.com/haskell/process/pull/168 for even more.
module Test.Tasty.Golden

-- | Compare the output file's contents against the golden file's contents
--   after the given action has created the output file.
goldenVsFile :: TestName -> FilePath -> FilePath -> IO () -> TestTree

-- | Compare a given string against the golden file's contents.
goldenVsString :: TestName -> FilePath -> IO ByteString -> TestTree

-- | Same as goldenVsFile, but invokes an external diff command.
--   
--   See the notes at the top of this module regarding linking with
--   -threaded and Windows-specific issues.
goldenVsFileDiff :: TestName -> (FilePath -> FilePath -> [String]) -> FilePath -> FilePath -> IO () -> TestTree

-- | Same as goldenVsString, but invokes an external diff command.
--   
--   See the notes at the top of this module regarding linking with
--   -threaded and Windows-specific issues.
goldenVsStringDiff :: TestName -> (FilePath -> FilePath -> [String]) -> FilePath -> IO ByteString -> TestTree

-- | The size, in bytes, such that the (incorrect) test output is not
--   displayed when it exceeds this size. Numeric underscores are accepted
--   for readability.
--   
--   The default value is 1000 (i.e. 1Kb).
newtype SizeCutoff
SizeCutoff :: Int64 -> SizeCutoff
[getSizeCutoff] :: SizeCutoff -> Int64

-- | When / whether to delete the test output file, when there is a golden
--   file
data DeleteOutputFile

-- | Never delete the output file (default)
Never :: DeleteOutputFile

-- | Delete the output file if the test passes
OnPass :: DeleteOutputFile

-- | Always delete the output file. (May not be commonly used, but provided
--   for completeness.)
Always :: DeleteOutputFile

-- | Like writeFile, but uses binary mode. (Needed only when you
--   work with String.)
writeBinaryFile :: FilePath -> String -> IO ()

-- | 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).
findByExtension :: [FilePath] -> FilePath -> IO [FilePath]

-- | Like writeFile, but also create parent directories if they are
--   missing.
createDirectoriesAndWriteFile :: FilePath -> ByteString -> IO ()

-- | Previously, accepting tests (by the --accept flag) was done
--   by this module, and there was an ingredient to handle that mode.
--   
--   Now it's done as part of a normal test run. When the `--accept` flag
--   is given, it makes golden tests to update the files whenever there is
--   a mismatch. So you no longer need this module. It remains only for
--   backwards compatibility.
module Test.Tasty.Golden.Manage

-- | This exists only for backwards compatibility. Use defaultMain
--   instead.
defaultMain :: TestTree -> IO ()

-- | This exists only for backwards compatibility. You don't need to
--   include this anymore.
acceptingTests :: Ingredient

-- | This option, when set to True, specifies that we should run in
--   the «accept tests» mode
newtype AcceptTests
AcceptTests :: Bool -> AcceptTests
