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


-- | A library for BDD-style testing with the Snap Web Framework
--   
--   A library for BDD-style testing with the Snap Web Framework
@package snap-testing
@version 0.6.0.0

module Snap.Test.BDD

-- | The main type for this library, where <tt>b</tt> is your application
--   state, often called <tt>App</tt>. This is a State monad on top of IO,
--   where the State carries your application (or, more specifically, a
--   top-level handler), and stream of test results to be reported as
--   passing or failing.
type SnapTesting b a = StateT (Handler b b (), (Snaplet b, InitializerState b), OutputStream TestResult) IO a

-- | TestResult is a a flattened tree structure that reflects the structure
--   of your tests, and is the data that is passed to report generators.
data TestResult
NameStart :: Text -> TestResult
NameEnd :: TestResult
TestPass :: (Sentiment Text) -> TestResult
TestFail :: (Sentiment Text) -> TestResult
TestError :: Text -> TestResult

-- | Tests have messages that are agnostic to whether the result should
--   hold or should not hold. The sentiment is attached to them to indicate
--   that positive/negative statement. This allows the same message to be
--   used for tests asserted with <a>should</a> and <a>shouldNot</a>.
data Sentiment a
Positive :: a -> Sentiment a
Negative :: a -> Sentiment a

-- | A TestResponse is the result of making a request. Many predicates
--   operate on these types of responses, and custom predicates can be
--   written against them.
data TestResponse
Html :: Text -> TestResponse
NotFound :: TestResponse
Redirect :: Int -> Text -> TestResponse
Other :: Int -> TestResponse
Empty :: TestResponse

-- | The configuration that is passed to the test runner, currently just a
--   list of report generators, that are each passed a stream of results,
--   and can do any side effecting thing with them.
data SnapTestingConfig
SnapTestingConfig :: [InputStream TestResult -> IO ()] -> SnapTestingConfig
reportGenerators :: SnapTestingConfig -> [InputStream TestResult -> IO ()]

-- | The default configuration just prints results to the console, using
--   the <a>consoleReport</a>.
defaultConfig :: SnapTestingConfig

-- | Run a set of tests, putting the results through the specified report
--   generators
runSnapTests :: SnapTestingConfig -> Handler b b () -> SnapletInit b b -> SnapTesting b () -> IO ()

-- | Prints test results to the console. For example:
--   
--   <pre>
--   /auth/new_user
--    success PASSED
--    creates a new account PASSED
--   </pre>
consoleReport :: InputStream TestResult -> IO ()

-- | Sends the test results to desktop notifications on linux. Prints how
--   many tests passed and failed.
linuxDesktopReport :: InputStream TestResult -> IO ()

-- | Labels a block of tests with a descriptive name, to be used in report
--   generation.
name :: Text -> SnapTesting b () -> SnapTesting b ()

-- | This takes a TestResult and writes it to the test log, so it is
--   processed by the report generators.
should :: SnapTesting b TestResult -> SnapTesting b ()

-- | This is similar to <a>should</a>, but it asserts that the test should
--   fail, and inverts the corresponding message sentiment.
shouldNot :: SnapTesting b TestResult -> SnapTesting b ()

-- | Constructor for CSS selectors
css :: Applicative m => Text -> m CssSelector

-- | A constructor for pure values (this is just a synonym for <a>pure</a>
--   from <a>Applicative</a>).
val :: Applicative m => a -> m a

-- | Runs a GET request
get :: Text -> SnapTesting b TestResponse

-- | Runs a GET request, with a set of parameters.
get' :: Text -> Map ByteString [ByteString] -> SnapTesting b TestResponse

-- | Creates a new POST request, with a set of parameters.
post :: Text -> Map ByteString [ByteString] -> SnapTesting b TestResponse

-- | A helper to construct parameters.
params :: [(ByteString, ByteString)] -> Map ByteString [ByteString]

-- | Checks that the handler evaluates to the given value.
equal :: (Show a, Eq a) => a -> a -> TestResult

-- | Helper to bring the results of other tests into the test suite.
beTrue :: Bool -> TestResult

-- | Checks that the given request results in a success (200) code.
succeed :: TestResponse -> TestResult

-- | Checks that the given request results in a not found (404) code.
notfound :: TestResponse -> TestResult

-- | Checks that the given request results in a redirect (3**) code.
redirect :: TestResponse -> TestResult

-- | Checks that the given request results in a redirect to a specific url.
redirectTo :: TestResponse -> Text -> TestResult

-- | Asserts that a response (which should be Html) has given text.
haveText :: TestResponse -> Text -> TestResult

-- | Assert that a response (which should be Html) has a given selector.
haveSelector :: TestResponse -> CssSelector -> TestResult

-- | Checks that the monadic value given changes by the function specified
--   after the given test block is run.
--   
--   For example, if you wanted to make sure that account creation was
--   creating new accounts:
--   
--   <pre>
--   changes (+1) countAccounts (post "/auth/new_user" $ params
--                               [ ("new_user.name", "Jane")
--                               , ("new_user.email", "jdoe@c.com")
--                               , ("new_user.password", "foobar")])
--   </pre>
changes :: (Show a, Eq a) => (a -> a) -> Handler b b a -> SnapTesting b c -> SnapTesting b ()

-- | A data type for tests against forms.
data FormExpectations a

-- | The value the form should take (and should be valid)
Value :: a -> FormExpectations a

-- | The error paths that should be populated
ErrorPaths :: [Text] -> FormExpectations a

-- | Test against digestive-functors forms.
form :: (Eq a, Show a) => FormExpectations a -> Form Text (Handler b b) a -> Map Text Text -> SnapTesting b ()

-- | Runs an action after a block of tests, usually used to remove database
--   state.
cleanup :: Handler b b () -> SnapTesting b () -> SnapTesting b ()

-- | Evaluate arbitrary actions
eval :: Handler b b a -> SnapTesting b a

-- | Given a site to site function (like, generating a random user and
--   logging in), run the given block of test with the modified state.
modifySite :: (Handler b b () -> Handler b b ()) -> SnapTesting b a -> SnapTesting b a

-- | Allows you to run a quickcheck test. All 100 test passing counts as a
--   pass, any failure a failure. Currently the reporting is really bad
--   (you don't see what the failing example is).
quickCheck :: Testable prop => prop -> SnapTesting b ()
instance Show a => Show (Sentiment a)
instance Show TestResult