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


-- | A Formatter for hspec that provides Github Actions Annotations
--   
--   Please see the README on GitHub at
--   <a>https://github.com/MercuryTechnologies/hspec-formatter-github#readme</a>
@package hspec-formatter-github
@version 0.1.0.0


-- | This module is internal! Use at your own risk. Breaking changes to
--   this module will not necessarily be reflected in PVP versions.
module Test.Hspec.Formatters.GithubAction.Internal

-- | This option enhances a given <a>Formatter</a> with annotations that
--   will show up on the correct test item failure. This allows you to use
--   the test output you want, and additionally get Github Action
--   annotations.
withGithubActionFormatter :: Formatter -> Formatter

-- | A representation of the Github Actions error format.
data ErrorCommand
ErrorCommand :: Maybe String -> Maybe String -> Maybe Int -> Maybe Int -> String -> ErrorCommand
[title] :: ErrorCommand -> Maybe String
[file] :: ErrorCommand -> Maybe String
[line] :: ErrorCommand -> Maybe Int
[col] :: ErrorCommand -> Maybe Int
[message] :: ErrorCommand -> String

-- | Make a suitable error annotation from an hspec failure.
--   
--   Not clear what to do with the Maybe Location here: do we use the one
--   from the Item, or this one? What if both or neither are available?
--   Also not clear whether to use itemInfo.
errorCommandFor :: Path -> Item -> Maybe Location -> FailureReason -> ErrorCommand

-- | The github actions command format.
formatErrorCommand :: ErrorCommand -> String
escapeData :: String -> String
escapeProperty :: String -> String

-- | If you want to extend
emitGithubActionAnnotation :: Path -> Item -> FormatM ()


-- | This module provides a utility to allow you to have annotations on
--   test failures in GitHub Actions.
--   
--   To use this, you'll call <a>registerGithubActionsAnnotations</a> with
--   a <a>Formatter</a> of your choice.
--   
--   <pre>
--   main :: IO ()
--   main = do
--       let hspecConfig =
--               <a>registerGithubActionsAnnotations</a> <a>checks</a> <tt>defaultConfig</tt>
--       <tt>hspecWith</tt> hspecConfig spec
--   </pre>
--   
--   This will make the <tt>github</tt> formatter available.
--   
--   Then, to actually use the formatter, you can provide the argument
--   <tt>--format=github</tt> on the command line or in a <tt>.hspec</tt>
--   file, or the <tt>HSPEC_FORMAT=github</tt> environment variable.
--   
--   To do this locally with <tt>cabal</tt>, you must use <tt>cabal
--   run</tt>, as <tt>cabal test</tt> evidently does not allow you to pass
--   <tt>--test-arguments</tt> anymore?
--   
--   <pre>
--   $ cabal run $(test-target-name) -- --format=github
--   </pre>
--   
--   The environment variable is easier to set in CI, probably.
--   
--   <pre>
--   $ HSPEC_FORMAT=github cabal test
--   </pre>
--   
--   And you can use a file, if you really want to, for some reason.
--   
--   <pre>
--   $ echo "--format=github" &gt;&gt; .hspec
--   $ cabal test
--   </pre>
module Test.Hspec.Formatters.GithubAction

-- | This function adds the GitHub Annotations to the underlying
--   <a>Formatter</a>
registerGithubActionsAnnotations :: Formatter -> Config -> Config

-- | This option enhances a given <a>Formatter</a> with annotations that
--   will show up on the correct test item failure. This allows you to use
--   the test output you want, and additionally get Github Action
--   annotations.
withGithubActionFormatter :: Formatter -> Formatter
silent :: Formatter
checks :: Formatter