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


-- | A library for testing with Hspec and the Snap Web Framework
--   
--   A library for testing with Hspec and the Snap Web Framework
@package hspec-snap
@version 0.3.2.2

module Test.Hspec.Snap

-- | The way to run a block of <a>SnapHspecM</a> tests within an
--   <a>hspec</a> test suite. This takes both the top level handler
--   (usually `route routes`, where <tt>routes</tt> are all the routes for
--   your site) and the site initializer (often named <tt>app</tt>), and a
--   block of tests. A test suite can have multiple calls to <a>snap</a>,
--   though each one will cause the site initializer to run, which is often
--   a slow operation (and will slow down test suites).
snap :: Handler b b () -> SnapletInit b b -> SpecWith (SnapHspecState b) -> Spec

-- | This allows you to change the default handler you are running requests
--   against within a block. This is most likely useful for setting request
--   state (for example, logging a user in).
modifySite :: (Handler b b () -> Handler b b ()) -> SpecWith (SnapHspecState b) -> SpecWith (SnapHspecState b)

-- | This performs a similar operation to <a>modifySite</a> but in the
--   context of <a>SnapHspecM</a> (which is needed if you need to
--   <a>eval</a>, produce values, and hand them somewhere else (so they
--   can't be created within <tt>f</tt>).
modifySite' :: (Handler b b () -> Handler b b ()) -> SnapHspecM b a -> SnapHspecM b a

-- | Evaluate a Handler action after each test.
afterEval :: Handler b b () -> SpecWith (SnapHspecState b) -> SpecWith (SnapHspecState b)

-- | Evaluate a Handler action before each test.
beforeEval :: Handler b b () -> SpecWith (SnapHspecState b) -> SpecWith (SnapHspecState b)

-- | The result of making requests against your application. Most
--   assertions act against these types (for example, <a>should200</a>,
--   <a>shouldHaveSelector</a>, etc).
data TestResponse
Html :: Text -> TestResponse
Json :: ByteString -> TestResponse
NotFound :: TestResponse
Redirect :: Int -> Text -> TestResponse
Other :: Int -> TestResponse
Empty :: TestResponse

-- | The main monad that tests run inside of. This allows both access to
--   the application (via requests and <a>eval</a>) and to running
--   assertions (like <a>should404</a> or <a>shouldHaveText</a>).
type SnapHspecM b = StateT (SnapHspecState b) IO

-- | Factory instances allow you to easily generate test data.
--   
--   Essentially, you specify a default way of constructing a data type,
--   and allow certain parts of it to be modified (via the <a>fields</a>
--   data structure).
--   
--   An example follows:
--   
--   <pre>
--   data Foo = Foo Int
--   newtype FooFields = FooFields (IO Int)
--   instance Factory App Foo FooFields where
--     fields = FooFields randomIO
--     save f = liftIO f &gt;&gt;= saveFoo . Foo1
--   
--   main = do create id :: SnapHspecM App Foo
--             create (const $ FooFields (return 1)) :: SnapHspecM App Foo
--   </pre>
class Factory b a d | a -> b, a -> d, d -> a where create transform = save $ transform fields reload = return
fields :: Factory b a d => d
save :: Factory b a d => d -> SnapHspecM b a
create :: Factory b a d => (d -> d) -> SnapHspecM b a
reload :: Factory b a d => a -> SnapHspecM b a

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

-- | Runs a GET request, with a set of parameters.
get' :: Text -> Params -> SnapHspecM b TestResponse

-- | Creates a new POST request, with a set of parameters.
post :: Text -> Params -> SnapHspecM b TestResponse

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

-- | Restricts a response to matches for a given CSS selector. Does nothing
--   to non-Html responses.
restrictResponse :: Text -> TestResponse -> TestResponse
recordSession :: HasSession b => SnapHspecM b a -> SnapHspecM b a
class HasSession b
getSessionLens :: HasSession b => SnapletLens b SessionManager
sessionShouldContain :: Text -> SnapHspecM b ()
sessionShouldNotContain :: Text -> SnapHspecM b ()

-- | Runs an arbitrary stateful action from your application.
eval :: Handler b b a -> SnapHspecM b a

-- | Asserts that a given stateful action will produce a specific different
--   result after an action has been run.
shouldChange :: (Show a, Eq a) => (a -> a) -> (Handler b b a) -> SnapHspecM b c -> SnapHspecM b ()

-- | Asserts that two values are equal.
shouldEqual :: (Show a, Eq a) => a -> a -> SnapHspecM b ()

-- | Asserts that two values are not equal.
shouldNotEqual :: (Show a, Eq a) => a -> a -> SnapHspecM b ()

-- | Asserts that the value is True.
shouldBeTrue :: Bool -> SnapHspecM b ()

-- | Asserts that the value is not True (otherwise known as False).
shouldNotBeTrue :: Bool -> SnapHspecM b ()

-- | Asserts that the response is a success (either Html, or Other with
--   status 200).
should200 :: TestResponse -> SnapHspecM b ()

-- | Asserts that the response is not a normal 200.
shouldNot200 :: TestResponse -> SnapHspecM b ()

-- | Asserts that the response is a NotFound.
should404 :: TestResponse -> SnapHspecM b ()

-- | Asserts that the response is not a NotFound.
shouldNot404 :: TestResponse -> SnapHspecM b ()

-- | Asserts that the response is a redirect.
should300 :: TestResponse -> SnapHspecM b ()

-- | Asserts that the response is not a redirect.
shouldNot300 :: TestResponse -> SnapHspecM b ()

-- | Asserts that the response is a redirect, and thet the url it redirects
--   to starts with the given path.
should300To :: Text -> TestResponse -> SnapHspecM b ()

-- | Asserts that the response is not a redirect to a given path. Note that
--   it can still be a redirect for this assertion to succeed, the path it
--   redirects to just can't start with the given path.
shouldNot300To :: Text -> TestResponse -> SnapHspecM b ()

-- | Assert that a response (which should be Html) has a given selector.
shouldHaveSelector :: Text -> TestResponse -> SnapHspecM b ()

-- | Assert that a response (which should be Html) doesn't have a given
--   selector.
shouldNotHaveSelector :: Text -> TestResponse -> SnapHspecM b ()

-- | Asserts that the response (which should be Html) contains the given
--   text.
shouldHaveText :: Text -> TestResponse -> SnapHspecM b ()

-- | Asserts that the response (which should be Html) does not contain the
--   given text.
shouldNotHaveText :: Text -> TestResponse -> SnapHspecM 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
Predicate :: (a -> Bool) -> FormExpectations a

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

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

-- | Internal state used to share site initialization across tests, and to
--   propogate failures. Understanding it is completely unnecessary to use
--   the library.
--   
--   The fields it contains, in order, are:
--   
--   <pre>
--   Result
--   Main handler
--   Startup state
--   Startup state
--   Session state
--   Before handler (runs before each eval)
--   After handler (runs after each eval).
--   </pre>
data SnapHspecState b
SnapHspecState :: Result -> (Handler b b ()) -> (Snaplet b) -> (InitializerState b) -> (MVar [(Text, Text)]) -> (Handler b b ()) -> (Handler b b ()) -> SnapHspecState b

-- | Records a test Success or Fail. Only the first Fail will be recorded
--   (and will cause the whole block to Fail).
setResult :: Result -> SnapHspecM b ()

-- | Runs a request (built with helpers from Snap.Test), resulting in a
--   response.
runRequest :: RequestBuilder IO () -> SnapHspecM b TestResponse

-- | Runs a request against a given handler (often the whole site), with
--   the given state. Returns any triggered exception, or the response.
runHandlerSafe :: RequestBuilder IO () -> Handler b b v -> Snaplet b -> InitializerState b -> IO (Either Text Response)

-- | Evaluates a given handler with the given state. Returns any triggered
--   exception, or the value produced.
evalHandlerSafe :: Handler b b v -> Snaplet b -> InitializerState b -> IO (Either Text v)
instance Show TestResponse
instance Eq TestResponse
instance Example (SnapHspecM b ())