-- 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 <a>Introduction to golden
--   testing</a>.
@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 <a>goldenTest</a> that also provides for deleting the
--   output file. The <a>DeleteOuputFile</a> 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


-- | <h2>Getting Started</h2>
--   
--   To get started with golden testing and this library, see
--   <a>Introduction to golden testing</a>.
--   
--   This module provides a simplified interface. If you want more, see
--   <a>Test.Tasty.Golden.Advanced</a>.
--   
--   <h2>Filenames</h2>
--   
--   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 <tt>cabal test</tt>
--   or <tt>cabal install --enable-tests</tt>), so if your test files are
--   under the <tt>tests/</tt> subdirectory, your relative file names
--   should start with <tt>tests/</tt> (even if your <tt>test.hs</tt> is
--   itself under <tt>tests/</tt>, too).
--   
--   <h2>Line endings</h2>
--   
--   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:
--   
--   <ul>
--   <li>When writing output files from Haskell code, open them in binary
--   mode (see <a>openBinaryFile</a>, <a>withBinaryFile</a> and
--   <a>hSetBinaryMode</a>). This will disable automatic <tt>\n -&gt;
--   \r\n</tt> conversion on Windows. For convenience, this module exports
--   <a>writeBinaryFile</a> which is just like <a>writeFile</a> but opens
--   the file in binary mode. When using <tt>ByteString</tt>s note that
--   <a>Data.ByteString</a> and <a>Data.ByteString.Lazy</a> use binary mode
--   for <tt>writeFile</tt>, while <a>Data.ByteString.Char8</a> and
--   <a>Data.ByteString.Lazy.Char8</a> use text mode.</li>
--   <li>Tell your VCS not to do any newline conversion for golden files.
--   For git check in a <tt>.gitattributes</tt> file with the following
--   contents (assuming your golden files have <tt>.golden</tt>
--   extension):</li>
--   </ul>
--   
--   <pre>
--   *.golden	-text
--   </pre>
--   
--   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, <tt>tar</tt> will not do the conversion for you when
--   unpacking a release tarball, so when you run <tt>cabal install
--   your-package --enable-tests</tt>, the tests will be broken.
--   
--   As a last resort, you can strip all <tt>\r</tt>s from both arguments
--   in your comparison function when necessary. But most of the time
--   treating the files as binary does the job.
--   
--   <h2>Linking</h2>
--   
--   The test suite should be compiled with <tt>-threaded</tt> if you want
--   to avoid blocking any other threads while <a>goldenVsFileDiff</a> and
--   similar functions wait for the result of the diff command.
--   
--   <h2>Windows limitations</h2>
--   
--   When using <a>goldenVsFileDiff</a> or <a>goldenVsStringDiff</a> under
--   Windows the exit code from the diff program that you specify will not
--   be captured correctly if that program uses <tt>exec</tt>.
--   
--   More specifically, you will get the exit code of the <i>original
--   child</i> (which always exits with code 0, since it called
--   <tt>exec</tt>), not the exit code of the process which carried on with
--   execution after <tt>exec</tt>. 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
--   <a>Process</a> for further details or
--   <a>https://github.com/haskell/process/pull/168</a> 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 <a>goldenVsFile</a>, but invokes an external diff command.
--   
--   See the notes at the top of this module regarding linking with
--   <tt>-threaded</tt> and Windows-specific issues.
goldenVsFileDiff :: TestName -> (FilePath -> FilePath -> [String]) -> FilePath -> FilePath -> IO () -> TestTree

-- | Same as <a>goldenVsString</a>, but invokes an external diff command.
--   
--   See the notes at the top of this module regarding linking with
--   <tt>-threaded</tt> 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 <a>writeFile</a>, but uses binary mode. (Needed only when you
--   work with <a>String</a>.)
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 <a>takeExtension</a>. In
--   particular, non-empty extensions should have the form <tt>".ext"</tt>.
--   
--   This function may throw any exception that <a>getDirectoryContents</a>
--   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 <a>writeFile</a>, but also create parent directories if they are
--   missing.
createDirectoriesAndWriteFile :: FilePath -> ByteString -> IO ()


-- | Previously, accepting tests (by the <tt>--accept</tt> 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 <a>defaultMain</a>
--   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 <a>True</a>, specifies that we should run in
--   the «accept tests» mode
newtype AcceptTests
AcceptTests :: Bool -> AcceptTests
