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


-- | integration testing for WAI/Yesod Applications
--   
--   API docs and the README are available at
--   <a>http://www.stackage.org/package/yesod-test</a>
@package yesod-test
@version 1.6.19


-- | Parsing CSS selectors into queries.
module Yesod.Test.CssQuery
data SelectorGroup
DirectChildren :: [Selector] -> SelectorGroup
DeepChildren :: [Selector] -> SelectorGroup
data Selector
ById :: Text -> Selector
ByClass :: Text -> Selector
ByTagName :: Text -> Selector
ByAttrExists :: Text -> Selector
ByAttrEquals :: Text -> Text -> Selector
ByAttrContains :: Text -> Text -> Selector
ByAttrStarts :: Text -> Text -> Selector
ByAttrEnds :: Text -> Text -> Selector

-- | Parses a query into an intermediate format which is easy to feed to
--   HXT
--   
--   <ul>
--   <li>The top-level lists represent the top level comma separated
--   queries.</li>
--   <li>SelectorGroup is a group of qualifiers which are separated with
--   spaces or &gt; like these three: <i>table.main.odd tr.even &gt;
--   td.big</i></li>
--   <li>A SelectorGroup as a list of Selector items, following the above
--   example the selectors in the group are: <i>table</i>, <i>.main</i> and
--   <i>.odd</i></li>
--   </ul>
parseQuery :: Text -> Either String [[SelectorGroup]]
instance GHC.Classes.Eq Yesod.Test.CssQuery.Selector
instance GHC.Classes.Eq Yesod.Test.CssQuery.SelectorGroup
instance GHC.Internal.Show.Show Yesod.Test.CssQuery.Selector
instance GHC.Internal.Show.Show Yesod.Test.CssQuery.SelectorGroup


-- | This module exposes functions that are used internally by yesod-test.
--   The functions exposed here are _not_ a stable API—they may be changed
--   or removed without any major version bump.
--   
--   That said, you may find them useful if your application can accept API
--   breakage.
module Yesod.Test.Internal

-- | Helper function to get the first 1024 characters of the body, assuming
--   it is UTF-8. This function is used to preview the body in case of an
--   assertion failure.
getBodyTextPreview :: ByteString -> Text

-- | Helper function to determine if we can print a body as plain text, for
--   debugging purposes.
contentTypeHeaderIsUtf8 :: ByteString -> Bool

-- | List of Content-Types that are assumed to be UTF-8 (e.g. JSON).
assumedUTF8ContentTypes :: Set ByteString


-- | The <a>SIO</a> type is used by <a>Yesod.Test</a> to provide
--   exception-safe environment between requests and assertions.
--   
--   This module is internal. Breaking changes to this module will not be
--   reflected in the major version of this package.
module Yesod.Test.Internal.SIO

-- | State + IO
newtype SIO s a
SIO :: ReaderT (IORef s) IO a -> SIO s a

-- | Retrieve the current state in the <a>SIO</a> type.
--   
--   Equivalent to <a>get</a>
getSIO :: SIO s s

-- | Put the given <tt>s</tt> into the <a>SIO</a> state for later
--   retrieval.
--   
--   Equivalent to <a>put</a>, but the value is evaluated to weak head
--   normal form.
putSIO :: s -> SIO s ()

-- | Modify the underlying <tt>s</tt> state.
--   
--   This is strict in the function used, and is equivalent to
--   <a>modify'</a>.
modifySIO :: (s -> s) -> SIO s ()

-- | Run an <a>SIO</a> action with the intial state <tt>s</tt> provided,
--   returning the result, and discard the final state.
evalSIO :: SIO s a -> s -> IO a

-- | Run an <a>SIO</a> action with the initial state <tt>s</tt> provided,
--   returning the final state, and discarding the result.
execSIO :: SIO s () -> s -> IO s

-- | Run an <a>SIO</a> action with the initial state provided, returning
--   both the result of the computation as well as the final state.
runSIO :: SIO s a -> s -> IO (s, a)
instance GHC.Internal.Base.Applicative (Yesod.Test.Internal.SIO.SIO s)
instance GHC.Internal.Base.Functor (Yesod.Test.Internal.SIO.SIO s)
instance Control.Monad.IO.Class.MonadIO (Yesod.Test.Internal.SIO.SIO s)
instance GHC.Internal.Base.Monad (Yesod.Test.Internal.SIO.SIO s)
instance Control.Monad.State.Class.MonadState s (Yesod.Test.Internal.SIO.SIO s)
instance Control.Monad.Catch.MonadThrow (Yesod.Test.Internal.SIO.SIO s)
instance Control.Monad.IO.Unlift.MonadUnliftIO (Yesod.Test.Internal.SIO.SIO s)


-- | This module uses HXT to transverse an HTML document using CSS
--   selectors.
--   
--   The most important function here is <a>findBySelector</a>, it takes a
--   CSS query and a string containing the HTML to look into, and it
--   returns a list of the HTML fragments that matched the given query.
--   
--   Only a subset of the CSS spec is currently supported:
--   
--   <ul>
--   <li>By tag name: <i>table td a</i></li>
--   <li>By class names: <i>.container .content</i></li>
--   <li>By Id: <i>#oneId</i></li>
--   <li>By attribute: <i>[hasIt]</i>, <i>[exact=match]</i>,
--   <i>[contains*=text]</i>, <i>[starts^=with]</i>,
--   <i>[ends$=with]</i></li>
--   <li>Union: <i>a, span, p</i></li>
--   <li>Immediate children: <i>div &gt; p</i></li>
--   <li>Get jiggy with it: <i>div[data-attr=yeah] &gt; .mon, .foo.bar div,
--   #oneThing</i></li>
--   </ul>
module Yesod.Test.TransversingCSS

-- | Perform a css <a>Query</a> on <tt>Html</tt>. Returns Either
--   
--   <ul>
--   <li>Left: Query parse error.</li>
--   <li>Right: List of matching Html fragments.</li>
--   </ul>
findBySelector :: HtmlLBS -> Query -> Either String [String]

-- | Perform a css <a>Query</a> on <tt>Html</tt>. Returns Either
--   
--   <ul>
--   <li>Left: Query parse error.</li>
--   <li>Right: List of matching Cursors</li>
--   </ul>
findAttributeBySelector :: HtmlLBS -> Query -> Text -> Either String [[Text]]
type HtmlLBS = ByteString
type Query = Text

-- | Parses a query into an intermediate format which is easy to feed to
--   HXT
--   
--   <ul>
--   <li>The top-level lists represent the top level comma separated
--   queries.</li>
--   <li>SelectorGroup is a group of qualifiers which are separated with
--   spaces or &gt; like these three: <i>table.main.odd tr.even &gt;
--   td.big</i></li>
--   <li>A SelectorGroup as a list of Selector items, following the above
--   example the selectors in the group are: <i>table</i>, <i>.main</i> and
--   <i>.odd</i></li>
--   </ul>
parseQuery :: Text -> Either String [[SelectorGroup]]
runQuery :: Cursor -> [[SelectorGroup]] -> [Cursor]
data Selector
ById :: Text -> Selector
ByClass :: Text -> Selector
ByTagName :: Text -> Selector
ByAttrExists :: Text -> Selector
ByAttrEquals :: Text -> Text -> Selector
ByAttrContains :: Text -> Text -> Selector
ByAttrStarts :: Text -> Text -> Selector
ByAttrEnds :: Text -> Text -> Selector
data SelectorGroup
DirectChildren :: [Selector] -> SelectorGroup
DeepChildren :: [Selector] -> SelectorGroup


-- | Yesod.Test is a pragmatic framework for testing web applications built
--   using wai.
--   
--   By pragmatic I may also mean <tt>dirty</tt>. Its main goal is to
--   encourage integration and system testing of web applications by making
--   everything <i>easy to test</i>.
--   
--   Your tests are like browser sessions that keep track of cookies and
--   the last visited page. You can perform assertions on the content of
--   HTML responses, using CSS selectors to explore the document more
--   easily.
--   
--   You can also easily build requests using forms present in the current
--   page. This is very useful for testing web applications built in yesod,
--   for example, where your forms may have field names generated by the
--   framework or a randomly generated CSRF token input.
--   
--   <h3>Example project</h3>
--   
--   The best way to see an example project using yesod-test is to create a
--   scaffolded Yesod project:
--   
--   <pre>
--   stack new projectname yesod-sqlite
--   </pre>
--   
--   (See
--   <a>https://github.com/commercialhaskell/stack-templates/wiki#yesod</a>
--   for the full list of Yesod templates)
--   
--   The scaffolded project makes your database directly available in
--   tests, so you can use <tt>runDB</tt> to set up backend pre-conditions,
--   or to assert that your session is having the desired effect. It also
--   handles wiping your database between each test.
--   
--   <h3>Example code</h3>
--   
--   The code below should give you a high-level idea of yesod-test's
--   capabilities. Note that it uses helper functions like <tt>withApp</tt>
--   and <tt>runDB</tt> from the scaffolded project; these aren't provided
--   by yesod-test.
--   
--   <pre>
--   spec :: Spec
--   spec = withApp $ do
--     describe "Homepage" $ do
--       it "loads the homepage with a valid status code" $ do
--         <a>get</a> HomeR
--         <a>statusIs</a> 200
--     describe "Login Form" $ do
--       it "Only allows dashboard access after logging in" $ do
--         <a>get</a> DashboardR
--         <a>statusIs</a> 401
--   
--         <a>get</a> HomeR
--         -- Assert a &lt;p&gt; tag exists on the page
--         <a>htmlAnyContain</a> "p" "Login"
--   
--         -- yesod-test provides a <a>RequestBuilder</a> monad for building up HTTP requests
--         <a>request</a> $ do
--           -- Lookup the HTML &lt;label&gt; with the text Username, and set a POST parameter for that field with the value Felipe
--           <a>byLabelExact</a> "Username" "Felipe"
--           <a>byLabelExact</a> "Password" "pass"
--           <a>setMethod</a> "POST"
--           <a>setUrl</a> SignupR
--         <a>statusIs</a> 200
--   
--         -- The previous request will have stored a session cookie, so we can access the dashboard now
--         <a>get</a> DashboardR
--         <a>statusIs</a> 200
--   
--         -- Assert a user with the name Felipe was added to the database
--         [Entity userId user] &lt;- runDB $ selectList [] []
--         <a>assertEq</a> "A single user named Felipe is created" (userUsername user) "Felipe"
--     describe "JSON" $ do
--       it "Can make requests using JSON, and parse JSON responses" $ do
--         -- Precondition: Create a user with the name "George"
--         runDB $ insert_ $ User "George" "pass"
--   
--         <a>request</a> $ do
--           -- Use the Aeson library to send JSON to the server
--           <a>setRequestBody</a> (<a>encode</a> $ LoginRequest "George" "pass")
--           <a>addRequestHeader</a> ("Accept", "application/json")
--           <a>addRequestHeader</a> ("Content-Type", "application/json")
--           <a>setUrl</a> LoginR
--         <a>statusIs</a> 200
--   
--         -- Parse the request's response as JSON
--         (signupResponse :: SignupResponse) &lt;- <a>requireJSONResponse</a>
--   </pre>
--   
--   <h3>HUnit / HSpec integration</h3>
--   
--   yesod-test is built on top of hspec, which is itself built on top of
--   HUnit. You can use existing assertion functions from those libraries,
--   but you'll need to use <a>liftIO</a> with them:
--   
--   <pre>
--   liftIO $ actualTimesCalled `<a>shouldBe'</a> expectedTimesCalled -- hspec assertion
--   </pre>
--   
--   <pre>
--   liftIO $ <a>assertBool</a> "a is greater than b" (a &gt; b) -- HUnit assertion
--   </pre>
--   
--   yesod-test provides a handful of assertion functions that are already
--   lifted, such as <a>assertEq</a>, as well.
module Yesod.Test
yesodSpec :: YesodDispatch site => site -> YesodSpec site -> Spec

-- | Corresponds to hspec's <tt>Spec</tt>.
--   
--   Since 1.2.0
type YesodSpec site = Writer [YesodSpecTree site] ()

-- | Same as yesodSpec, but instead of taking already built site it takes
--   an action which produces site for each test.
yesodSpecWithSiteGenerator :: YesodDispatch site => IO site -> YesodSpec site -> Spec

-- | Same as yesodSpecWithSiteGenerator, but also takes an argument to
--   build the site and makes that argument available to the tests.
yesodSpecWithSiteGeneratorAndArgument :: YesodDispatch site => (a -> IO site) -> YesodSpec site -> SpecWith a

-- | Same as yesodSpec, but instead of taking a site it takes an action
--   which produces the <a>Application</a> for each test. This lets you use
--   your middleware from makeApplication
yesodSpecApp :: YesodDispatch site => site -> IO Application -> YesodSpec site -> Spec

-- | A single test case, to be run with <a>yit</a>.
--   
--   Since 1.2.0
type YesodExample site = SIO YesodExampleData site

-- | The state used in a single test case defined using <a>yit</a>
--   
--   Since 1.2.4
data YesodExampleData site
YesodExampleData :: !Application -> !site -> !Cookies -> !Maybe SResponse -> YesodExampleData site
[yedApp] :: YesodExampleData site -> !Application
[yedSite] :: YesodExampleData site -> !site
[yedCookies] :: YesodExampleData site -> !Cookies
[yedResponse] :: YesodExampleData site -> !Maybe SResponse
type TestApp site = (site, Middleware)
type YSpec site = SpecWith TestApp site
testApp :: site -> Middleware -> TestApp site

-- | Internal data structure, corresponding to hspec's <a>SpecTree</a>.
--   
--   Since 1.2.0
data YesodSpecTree site
YesodSpecGroup :: String -> [YesodSpecTree site] -> YesodSpecTree site
YesodSpecItem :: String -> YesodExample site () -> YesodSpecTree site

-- | Start describing a Tests suite keeping cookies and a reference to the
--   tested <a>Application</a> and <tt>ConnectionPool</tt>
ydescribe :: String -> YesodSpec site -> YesodSpec site

-- | Describe a single test that keeps cookies, and a reference to the last
--   response.
yit :: String -> YesodExample site () -> YesodSpec site

-- | Modifies the site (<a>yedSite</a>) of the test, and creates a new WAI
--   app (<a>yedApp</a>) for it.
--   
--   yesod-test allows sending requests to your application to test that it
--   handles them correctly. In rare cases, you may wish to modify that
--   application in the middle of a test. This may be useful if you wish
--   to, for example, test your application under a certain configuration,
--   then change that configuration to see if your app responds
--   differently.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   post SendEmailR
--   -- Assert email not created in database
--   testModifySite (\site -&gt; pure (site { siteSettingsStoreEmail = True }, id))
--   post SendEmailR
--   -- Assert email created in database
--   </pre>
--   
--   <pre>
--   testModifySite (\site -&gt; do
--     middleware &lt;- makeLogware site
--     pure (site { appRedisConnection = Nothing }, middleware)
--   )
--   </pre>
testModifySite :: YesodDispatch site => (site -> IO (site, Middleware)) -> YesodExample site ()

-- | Sets a cookie
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   import qualified Web.Cookie as Cookie
--   :set -XOverloadedStrings
--   testSetCookie Cookie.defaultSetCookie { Cookie.setCookieName = "name" }
--   </pre>
testSetCookie :: SetCookie -> YesodExample site ()

-- | Deletes the cookie of the given name
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   :set -XOverloadedStrings
--   testDeleteCookie "name"
--   </pre>
testDeleteCookie :: ByteString -> YesodExample site ()

-- | Modify the current cookies with the given mapping function
testModifyCookies :: (Cookies -> Cookies) -> YesodExample site ()

-- | Clears the current cookies
testClearCookies :: YesodExample site ()

-- | Perform a GET request to <tt>url</tt>.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   get HomeR
--   </pre>
--   
--   <pre>
--   get ("http://google.com" :: Text)
--   </pre>
get :: (Yesod site, RedirectUrl site url) => url -> YesodExample site ()

-- | Perform a POST request to <tt>url</tt>.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   post HomeR
--   </pre>
post :: (Yesod site, RedirectUrl site url) => url -> YesodExample site ()

-- | Perform a POST request to <tt>url</tt> with the given body.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   postBody HomeR "foobar"
--   </pre>
--   
--   <pre>
--   import Data.Aeson
--   postBody HomeR (encode $ object ["age" .= (1 :: Integer)])
--   </pre>
postBody :: (Yesod site, RedirectUrl site url) => url -> ByteString -> YesodExample site ()

-- | Perform a request using a given method to <tt>url</tt>.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   performMethod "DELETE" HomeR
--   </pre>
performMethod :: (Yesod site, RedirectUrl site url) => ByteString -> url -> YesodExample site ()

-- | Follow a redirect, if the last response was a redirect. (We consider a
--   request a redirect if the status is 301, 302, 303, 307 or 308, and the
--   Location header is set.)
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   get HomeR
--   followRedirect
--   </pre>
followRedirect :: Yesod site => YesodExample site (Either Text Text)

-- | Parse the Location header of the last response.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   post ResourcesR
--   (Right (ResourceR resourceId)) &lt;- getLocation
--   </pre>
getLocation :: ParseRoute site => YesodExample site (Either Text (Route site))

-- | The general interface for performing requests. <a>request</a> takes a
--   <a>RequestBuilder</a>, constructs a request, and executes it.
--   
--   The <a>RequestBuilder</a> allows you to build up attributes of the
--   request, like the headers, parameters, and URL of the request.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   request $ do
--     addToken
--     byLabel "First Name" "Felipe"
--     setMethod "PUT"
--     setUrl NameR
--   </pre>
request :: RequestBuilder site () -> YesodExample site ()

-- | Adds the given header to the request; see
--   <a>Network.HTTP.Types.Header</a> for creating <a>Header</a>s.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   import Network.HTTP.Types.Header
--   request $ do
--     addRequestHeader (hUserAgent, "Chrome/41.0.2228.0")
--   </pre>
addRequestHeader :: Header -> RequestBuilder site ()

-- | Adds a header for <a>HTTP Basic Authentication</a> to the request
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   request $ do
--     addBasicAuthHeader "Aladdin" "OpenSesame"
--   </pre>
addBasicAuthHeader :: CI ByteString -> CI ByteString -> RequestBuilder site ()

-- | Sets the HTTP method used by the request.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   request $ do
--     setMethod "POST"
--   </pre>
--   
--   <pre>
--   import Network.HTTP.Types.Method
--   request $ do
--     setMethod methodPut
--   </pre>
setMethod :: Method -> RequestBuilder site ()

-- | Add a parameter with the given name and value to the request body.
--   This function can be called multiple times to add multiple parameters,
--   and be mixed with calls to <a>addFile</a>.
--   
--   "Post parameter" is an informal description of what is submitted by
--   making an HTTP POST with an HTML <tt>&lt;form&gt;</tt>. Like HTML
--   <tt>&lt;form&gt;</tt>s, yesod-test will default to a
--   <tt>Content-Type</tt> of <tt>application/x-www-form-urlencoded</tt> if
--   no files are added, and switch to <tt>multipart/form-data</tt> if
--   files are added.
--   
--   Calling this function after using <a>setRequestBody</a> will raise an
--   error.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   {-# LANGUAGE OverloadedStrings #-}
--   post $ do
--     addPostParam "key" "value"
--   </pre>
addPostParam :: Text -> Text -> RequestBuilder site ()

-- | Add a parameter with the given name and value to the query string.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   {-# LANGUAGE OverloadedStrings #-}
--   request $ do
--     addGetParam "key" "value" -- Adds ?key=value to the URL
--   </pre>
addGetParam :: Text -> Text -> RequestBuilder site ()

-- | Add a bare parameter with the given name and no value to the query
--   string. The parameter is added without an <tt>=</tt> sign.
--   
--   You can specify the entire query string literally by adding a single
--   bare parameter and no other parameters.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   {-# LANGUAGE OverloadedStrings #-}
--   request $ do
--     addBareGetParam "key" -- Adds ?key to the URL
--   </pre>
addBareGetParam :: Text -> RequestBuilder site ()

-- | Add a file to be posted with the current request.
--   
--   Adding a file will automatically change your request content-type to
--   be multipart/form-data.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   request $ do
--     addFile "profile_picture" "static/img/picture.png" "img/png"
--   </pre>
addFile :: Text -> FilePath -> Text -> RequestBuilder site ()

-- | Simple way to set HTTP request body
--   
--   <h4><b> Examples</b></h4>
--   
--   <pre>
--   request $ do
--     setRequestBody "foobar"
--   </pre>
--   
--   <pre>
--   import Data.Aeson
--   request $ do
--     setRequestBody $ encode $ object ["age" .= (1 :: Integer)]
--   </pre>
setRequestBody :: ByteString -> RequestBuilder site ()

-- | The <a>RequestBuilder</a> state monad constructs a URL encoded string
--   of arguments to send with your requests. Some of the functions that
--   run on it use the current response to analyze the forms that the
--   server is expecting to receive.
type RequestBuilder site = SIO RequestBuilderData site

-- | State + IO
data SIO s a

-- | Sets the URL used by the request.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   request $ do
--     setUrl HomeR
--   </pre>
--   
--   <pre>
--   request $ do
--     setUrl ("http://google.com/" :: Text)
--   </pre>
setUrl :: (Yesod site, RedirectUrl site url) => url -> RequestBuilder site ()

-- | Click on a link defined by a CSS query
--   
--   <h4><b> Examples</b></h4>
--   
--   <pre>
--   get "/foobar"
--   clickOn "a#idofthelink"
--   </pre>
clickOn :: (HasCallStack, Yesod site) => Query -> YesodExample site ()

-- | Finds the <tt>&lt;label&gt;</tt> with the given value, finds its
--   corresponding <tt>&lt;input&gt;</tt>, then adds a parameter for that
--   input to the request body.
--   
--   <h4><b>Examples</b></h4>
--   
--   Given this HTML, we want to submit <tt>f1=Michael</tt> to the server:
--   
--   <pre>
--   &lt;form method="POST"&gt;
--     &lt;label for="user"&gt;Username&lt;/label&gt;
--     &lt;input id="user" name="f1" /&gt;
--   &lt;/form&gt;
--   </pre>
--   
--   You can set this parameter like so:
--   
--   <pre>
--   request $ do
--     byLabel "Username" "Michael"
--   </pre>
--   
--   This function also supports the implicit label syntax, in which the
--   <tt>&lt;input&gt;</tt> is nested inside the <tt>&lt;label&gt;</tt>
--   rather than specified with <tt>for</tt>:
--   
--   <pre>
--   &lt;form method="POST"&gt;
--     &lt;label&gt;Username &lt;input name="f1"&gt; &lt;/label&gt;
--   &lt;/form&gt;
--   </pre>
--   
--   Warning: This function looks for any label that contains the provided
--   text. If multiple labels contain that text, this function will throw
--   an error, as in the example below:
--   
--   <pre>
--   &lt;form method="POST"&gt;
--     &lt;label for="nickname"&gt;Nickname&lt;/label&gt;
--     &lt;input id="nickname" name="f1" /&gt;
--   </pre>
--   
--   <pre>
--     &lt;label for="nickname2"&gt;Nickname2&lt;/label&gt;
--     &lt;input id="nickname2" name="f2" /&gt;
--   &lt;/form&gt;
--   </pre>
--   
--   <pre>
--   request $ do
--     byLabel "Nickname" "Snoyberger"
--   </pre>
--   
--   Then, it throws "More than one label contained" error.
--   
--   Therefore, this function is deprecated. Please consider using
--   <a>byLabelExact</a>, which performs the exact match over the provided
--   text.

-- | <i>Deprecated: This function seems to have multiple bugs (ref:
--   <a>https://github.com/yesodweb/yesod/pull/1459)</a>. Use byLabelExact,
--   byLabelContain, byLabelPrefix or byLabelSuffix instead</i>
byLabel :: Text -> Text -> RequestBuilder site ()

-- | Finds the <tt>&lt;label&gt;</tt> with the given value, finds its
--   corresponding <tt>&lt;input&gt;</tt>, then adds a parameter for that
--   input to the request body.
--   
--   <h4><b>Examples</b></h4>
--   
--   Given this HTML, we want to submit <tt>f1=Michael</tt> to the server:
--   
--   <pre>
--   &lt;form method="POST"&gt;
--     &lt;label for="user"&gt;Username&lt;/label&gt;
--     &lt;input id="user" name="f1" /&gt;
--   &lt;/form&gt;
--   </pre>
--   
--   You can set this parameter like so:
--   
--   <pre>
--   request $ do
--     byLabel "Username" "Michael"
--   </pre>
--   
--   This function also supports the implicit label syntax, in which the
--   <tt>&lt;input&gt;</tt> is nested inside the <tt>&lt;label&gt;</tt>
--   rather than specified with <tt>for</tt>:
--   
--   <pre>
--   &lt;form method="POST"&gt;
--     &lt;label&gt;Username &lt;input name="f1"&gt; &lt;/label&gt;
--   &lt;/form&gt;
--   </pre>
byLabelExact :: Text -> Text -> RequestBuilder site ()

-- | Contain version of <a>byLabelExact</a>
--   
--   Note: Just like <a>byLabel</a>, this function throws an error if it
--   finds multiple labels
byLabelContain :: Text -> Text -> RequestBuilder site ()

-- | Prefix version of <a>byLabelExact</a>
--   
--   Note: Just like <a>byLabel</a>, this function throws an error if it
--   finds multiple labels
byLabelPrefix :: Text -> Text -> RequestBuilder site ()

-- | Suffix version of <a>byLabelExact</a>
--   
--   Note: Just like <a>byLabel</a>, this function throws an error if it
--   finds multiple labels
byLabelSuffix :: Text -> Text -> RequestBuilder site ()

-- | Note: This function throws an error if it finds multiple labels or if
--   the CSS selector fails to parse, doesn't match any fragment, or
--   matches multiple fragments.
bySelectorLabelContain :: Text -> Text -> Text -> RequestBuilder site ()

-- | Finds the <tt>&lt;label&gt;</tt> with the given value, finds its
--   corresponding <tt>&lt;input&gt;</tt>, then adds a file for that input
--   to the request body.
--   
--   <h4><b>Examples</b></h4>
--   
--   Given this HTML, we want to submit a file with the parameter name
--   <tt>f1</tt> to the server:
--   
--   <pre>
--   &lt;form method="POST"&gt;
--     &lt;label for="imageInput"&gt;Please submit an image&lt;/label&gt;
--     &lt;input id="imageInput" type="file" name="f1" accept="image/*"&gt;
--   &lt;/form&gt;
--   </pre>
--   
--   You can set this parameter like so:
--   
--   <pre>
--   request $ do
--     fileByLabel "Please submit an image" "static/img/picture.png" "img/png"
--   </pre>
--   
--   This function also supports the implicit label syntax, in which the
--   <tt>&lt;input&gt;</tt> is nested inside the <tt>&lt;label&gt;</tt>
--   rather than specified with <tt>for</tt>:
--   
--   <pre>
--   &lt;form method="POST"&gt;
--     &lt;label&gt;Please submit an image &lt;input type="file" name="f1"&gt; &lt;/label&gt;
--   &lt;/form&gt;
--   </pre>
--   
--   Warning: This function has the same issue as <a>byLabel</a>. Please
--   use <a>fileByLabelExact</a> instead.

-- | <i>Deprecated: This function seems to have multiple bugs (ref:
--   <a>https://github.com/yesodweb/yesod/pull/1459)</a>. Use
--   fileByLabelExact, fileByLabelContain, fileByLabelPrefix or
--   fileByLabelSuffix instead</i>
fileByLabel :: Text -> FilePath -> Text -> RequestBuilder site ()

-- | Finds the <tt>&lt;label&gt;</tt> with the given value, finds its
--   corresponding <tt>&lt;input&gt;</tt>, then adds a file for that input
--   to the request body.
--   
--   <h4><b>Examples</b></h4>
--   
--   Given this HTML, we want to submit a file with the parameter name
--   <tt>f1</tt> to the server:
--   
--   <pre>
--   &lt;form method="POST"&gt;
--     &lt;label for="imageInput"&gt;Please submit an image&lt;/label&gt;
--     &lt;input id="imageInput" type="file" name="f1" accept="image/*"&gt;
--   &lt;/form&gt;
--   </pre>
--   
--   You can set this parameter like so:
--   
--   <pre>
--   request $ do
--     fileByLabel "Please submit an image" "static/img/picture.png" "img/png"
--   </pre>
--   
--   This function also supports the implicit label syntax, in which the
--   <tt>&lt;input&gt;</tt> is nested inside the <tt>&lt;label&gt;</tt>
--   rather than specified with <tt>for</tt>:
--   
--   <pre>
--   &lt;form method="POST"&gt;
--     &lt;label&gt;Please submit an image &lt;input type="file" name="f1"&gt; &lt;/label&gt;
--   &lt;/form&gt;
--   </pre>
fileByLabelExact :: Text -> FilePath -> Text -> RequestBuilder site ()

-- | Contain version of <a>fileByLabelExact</a>
--   
--   Note: Just like <a>fileByLabel</a>, this function throws an error if
--   it finds multiple labels
fileByLabelContain :: Text -> FilePath -> Text -> RequestBuilder site ()

-- | Prefix version of <a>fileByLabelExact</a>
--   
--   Note: Just like <a>fileByLabel</a>, this function throws an error if
--   it finds multiple labels
fileByLabelPrefix :: Text -> FilePath -> Text -> RequestBuilder site ()

-- | Suffix version of <a>fileByLabelExact</a>
--   
--   Note: Just like <a>fileByLabel</a>, this function throws an error if
--   it finds multiple labels
fileByLabelSuffix :: Text -> FilePath -> Text -> RequestBuilder site ()

-- | Finds the <tt>&lt;label&gt;</tt> with the given value, finds its
--   corresponding <tt>&lt;input&gt;</tt>, then make this input checked. It
--   is assumed the <tt>&lt;input&gt;</tt> has <tt>type=radio</tt>.
--   
--   <h4><b>Examples</b></h4>
--   
--   Given this HTML, we want to submit <tt>f1=2</tt> (i.e. radio button
--   with <a>Blue</a> label) to the server:
--   
--   <pre>
--   &lt;form method="POST"&gt;
--     &lt;label for="hident2"&gt;Color&lt;/label&gt;
--     &lt;div id="hident2"&gt;
--       &lt;div class="radio"&gt;
--         &lt;input id="hident2-none" type="radio" name="f1" value="none" checked&gt;
--         &lt;label for="hident2-none"&gt;&amp;lt;None&amp;gt;&lt;/label&gt;
--       &lt;/div&gt;
--       &lt;div class="radio"&gt;
--         &lt;input id="hident2-1" type="radio" name="f1" value="1"&gt;
--         &lt;label for="hident2-1"&gt;Red&lt;/label&gt;
--       &lt;/div&gt;
--       &lt;div class="radio"&gt;
--         &lt;input id="hident2-2" type="radio" name="f1" value="2"&gt;
--         &lt;label for="hident2-2"&gt;Blue&lt;/label&gt;
--       &lt;/div&gt;
--       &lt;div class="radio"&gt;
--         &lt;input id="hident2-3" type="radio" name="f1" value="3"&gt;
--         &lt;label for="hident2-3"&gt;Gray&lt;/label&gt;
--       &lt;/div&gt;
--       &lt;div class="radio"&gt;
--         &lt;input id="hident2-4" type="radio" name="f1" value="4"&gt;
--         &lt;label for="hident2-4"&gt;Black&lt;/label&gt;
--       &lt;/div&gt;
--     &lt;/div&gt;
--   &lt;/form&gt;
--   </pre>
--   
--   You can set this parameter like so:
--   
--   <pre>
--   request $ do
--     chooseByLabel "Blue"
--   </pre>
chooseByLabel :: Text -> RequestBuilder site ()

-- | Finds the <tt>&lt;label&gt;</tt> with the given value, finds its
--   corresponding <tt>&lt;input&gt;</tt>, then make this input checked. It
--   is assumed the <tt>&lt;input&gt;</tt> has <tt>type=checkbox</tt>.
--   
--   <h4><b>Examples</b></h4>
--   
--   Given this HTML, we want to submit <tt>f1=2</tt> and <tt>f1=4</tt>
--   (i.e. checked checkboxes are <a>Blue</a> and <a>Black</a>) to the
--   server:
--   
--   <pre>
--   &lt;form method="POST"&gt;
--     &lt;label for="hident2"&gt;Colors&lt;/label&gt;
--     &lt;span id="hident2"&gt;
--       &lt;input id="hident2-1" type="checkbox" name="f1" value="1"&gt;
--       &lt;label for="hident2-1"&gt;Red&lt;/label&gt;
--       &lt;input id="hident2-2" type="checkbox" name="f1" value="2" checked&gt;
--       &lt;label for="hident2-2"&gt;Blue&lt;/label&gt;
--       &lt;input id="hident2-3" type="checkbox" name="f1" value="3"&gt;
--       &lt;label for="hident2-3"&gt;Gray&lt;/label&gt;
--       &lt;input id="hident2-4" type="checkbox" name="f1" value="4" checked&gt;
--       &lt;label for="hident2-4"&gt;Black&lt;/label&gt;
--     &lt;/span&gt;
--   &lt;/form&gt;
--   </pre>
--   
--   You can set this parameter like so:
--   
--   <pre>
--   request $ do
--     checkByLabel "Blue"
--     checkByLabel "Black"
--   </pre>
checkByLabel :: Text -> RequestBuilder site ()

-- | Finds the <tt>&lt;label&gt;</tt> with the given value, finds its
--   corresponding <tt>&lt;select&gt;</tt>, then finds corresponding
--   <tt>&lt;option&gt;</tt> and make this options selected.
--   
--   <h4><b>Examples</b></h4>
--   
--   Given this HTML, we want to submit <tt>f1=2</tt> (i.e. selected option
--   is <a>Blue</a>) to the server:
--   
--   <pre>
--   &lt;form method="post" action="labels-select"&gt;
--     &lt;label for="hident2"&gt;Selection List&lt;/label&gt;
--     &lt;select id="hident2" name="f1"&gt;
--       &lt;option value="1"&gt;Red&lt;/option&gt;
--       &lt;option value="2"&gt;Blue&lt;/option&gt;
--       &lt;option value="3"&gt;Gray&lt;/option&gt;
--       &lt;option value="4"&gt;Black&lt;/option&gt;
--     &lt;/select&gt;
--   &lt;/form&gt;
--   </pre>
--   
--   You can set this parameter like so:
--   
--   <pre>
--   request $ do
--     setMethod "POST"
--     selectByLabel "Selection List" "Blue"
--   </pre>
selectByLabel :: Text -> Text -> RequestBuilder site ()

-- | For responses that display a single form, just lookup the only CSRF
--   token available.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   request $ do
--     addToken
--   </pre>
addToken :: HasCallStack => RequestBuilder site ()

-- | Lookups the hidden input named "_token" and adds its value to the
--   params. Receives a CSS selector that should resolve to the form
--   element containing the token.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   request $ do
--     addToken_ "#formID"
--   </pre>
addToken_ :: HasCallStack => Query -> RequestBuilder site ()

-- | Calls <a>addTokenFromCookieNamedToHeaderNamed</a> with the
--   <a>defaultCsrfCookieName</a> and <a>defaultCsrfHeaderName</a>.
--   
--   Use this function if you're using the CSRF middleware from
--   <a>Yesod.Core</a> and haven't customized the cookie or header name.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   request $ do
--     addTokenFromCookie
--   </pre>
--   
--   Since 1.4.3.2
addTokenFromCookie :: HasCallStack => RequestBuilder site ()

-- | Looks up the CSRF token stored in the cookie with the given name and
--   adds it to the request headers. An error is thrown if the cookie can't
--   be found.
--   
--   Use this function if you're using the CSRF middleware from
--   <a>Yesod.Core</a> and have customized the cookie or header name.
--   
--   See <a>Yesod.Core.Handler</a> for details on this approach to CSRF
--   protection.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   import Data.CaseInsensitive (CI)
--   request $ do
--     addTokenFromCookieNamedToHeaderNamed "cookieName" (CI "headerName")
--   </pre>
--   
--   Since 1.4.3.2
addTokenFromCookieNamedToHeaderNamed :: HasCallStack => ByteString -> CI ByteString -> RequestBuilder site ()

-- | <i>Deprecated: Use assertEq instead</i>
assertEqual :: (HasCallStack, Eq a) => String -> a -> a -> YesodExample site ()

-- | Asserts that the two given values are not equal.
--   
--   In case they are equal, the error message includes the values.
assertNotEq :: (HasCallStack, Eq a, Show a) => String -> a -> a -> YesodExample site ()

-- | Asserts that the two given values are equal.
assertEqualNoShow :: (HasCallStack, Eq a) => String -> a -> a -> YesodExample site ()

-- | Asserts that the two given values are equal.
--   
--   In case they are not equal, the error message includes the two values.
assertEq :: (HasCallStack, Eq a, Show a) => String -> a -> a -> YesodExample site ()

-- | Assert the given header key/value pair was returned.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   {-# LANGUAGE OverloadedStrings #-}
--   get HomeR
--   assertHeader "key" "value"
--   </pre>
--   
--   <pre>
--   import qualified Data.CaseInsensitive as CI
--   import qualified Data.ByteString.Char8 as BS8
--   getHomeR
--   assertHeader (CI.mk (BS8.pack "key")) (BS8.pack "value")
--   </pre>
assertHeader :: HasCallStack => CI ByteString -> ByteString -> YesodExample site ()

-- | Assert the given header was not included in the response.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   {-# LANGUAGE OverloadedStrings #-}
--   get HomeR
--   assertNoHeader "key"
--   </pre>
--   
--   <pre>
--   import qualified Data.CaseInsensitive as CI
--   import qualified Data.ByteString.Char8 as BS8
--   getHomeR
--   assertNoHeader (CI.mk (BS8.pack "key"))
--   </pre>
assertNoHeader :: HasCallStack => CI ByteString -> YesodExample site ()

-- | Assert the last response status is as expected. If the status code
--   doesn't match, a portion of the body is also printed to aid in
--   debugging.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   get HomeR
--   statusIs 200
--   </pre>
statusIs :: HasCallStack => Int -> YesodExample site ()

-- | Assert the last response is exactly equal to the given text. This is
--   useful for testing API responses.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   get HomeR
--   bodyEquals "&lt;html&gt;&lt;body&gt;&lt;h1&gt;Hello, World&lt;/h1&gt;&lt;/body&gt;&lt;/html&gt;"
--   </pre>
bodyEquals :: HasCallStack => String -> YesodExample site ()

-- | Assert the last response has the given text. The check is performed
--   using the response body in full text form.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   get HomeR
--   bodyContains "&lt;h1&gt;Foo&lt;/h1&gt;"
--   </pre>
bodyContains :: HasCallStack => String -> YesodExample site ()

-- | Assert the last response doesn't have the given text. The check is
--   performed using the response body in full text form.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   get HomeR
--   bodyNotContains "&lt;h1&gt;Foo&lt;/h1&gt;
--   </pre>
bodyNotContains :: HasCallStack => String -> YesodExample site ()

-- | Queries the HTML using a CSS selector, and all matched elements must
--   contain the given string.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   {-# LANGUAGE OverloadedStrings #-}
--   get HomeR
--   htmlAllContain "p" "Hello" -- Every &lt;p&gt; tag contains the string "Hello"
--   </pre>
--   
--   <pre>
--   import qualified Data.Text as T
--   get HomeR
--   htmlAllContain (T.pack "h1#mainTitle") "Sign Up Now!" -- All &lt;h1&gt; tags with the ID mainTitle contain the string "Sign Up Now!"
--   </pre>
htmlAllContain :: HasCallStack => Query -> String -> YesodExample site ()

-- | Queries the HTML using a CSS selector, and passes if any matched
--   element contains the given string.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   {-# LANGUAGE OverloadedStrings #-}
--   get HomeR
--   htmlAnyContain "p" "Hello" -- At least one &lt;p&gt; tag contains the string "Hello"
--   </pre>
--   
--   Since 0.3.5
htmlAnyContain :: HasCallStack => Query -> String -> YesodExample site ()

-- | Queries the HTML using a CSS selector, and fails if any matched
--   element contains the given string (in other words, it is the logical
--   inverse of htmlAnyContain).
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   {-# LANGUAGE OverloadedStrings #-}
--   get HomeR
--   htmlNoneContain ".my-class" "Hello" -- No tags with the class "my-class" contain the string "Hello"
--   </pre>
--   
--   Since 1.2.2
htmlNoneContain :: HasCallStack => Query -> String -> YesodExample site ()

-- | Performs a CSS query on the last response and asserts the matched
--   elements are as many as expected.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   {-# LANGUAGE OverloadedStrings #-}
--   get HomeR
--   htmlCount "p" 3 -- There are exactly 3 &lt;p&gt; tags in the response
--   </pre>
htmlCount :: HasCallStack => Query -> Int -> YesodExample site ()

-- | Parses the response body from JSON into a Haskell value, throwing an
--   error if parsing fails.
--   
--   This function also checks that the <tt>Content-Type</tt> of the
--   response is <tt>application/json</tt>.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   get CommentR
--   (comment :: Comment) &lt;- requireJSONResponse
--   </pre>
--   
--   <pre>
--   post UserR
--   (json :: Value) &lt;- requireJSONResponse
--   </pre>
requireJSONResponse :: (HasCallStack, FromJSON a) => YesodExample site a

-- | Get the foundation value used for the current test.
--   
--   Since 1.2.0
getTestYesod :: YesodExample site site

-- | Get the most recently provided response value, if available.
--   
--   Since 1.2.0
getResponse :: YesodExample site (Maybe SResponse)

-- | Returns the <a>Cookies</a> from the most recent request. If a request
--   hasn't been made, an error is raised.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   request $ do
--     cookies &lt;- getRequestCookies
--     liftIO $ putStrLn $ "Cookies are: " ++ show cookies
--   </pre>
--   
--   Since 1.4.3.2
getRequestCookies :: HasCallStack => RequestBuilder site Cookies

-- | Outputs the last response body to stderr (So it doesn't get captured
--   by HSpec). Useful for debugging.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   get HomeR
--   printBody
--   </pre>
printBody :: YesodExample site ()

-- | Performs a CSS query and print the matches to stderr.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   {-# LANGUAGE OverloadedStrings #-}
--   get HomeR
--   printMatches "h1" -- Prints all h1 tags
--   </pre>
printMatches :: HasCallStack => Query -> YesodExample site ()

-- | Query the last response using CSS selectors, returns a list of matched
--   fragments
htmlQuery :: HasCallStack => Query -> YesodExample site [HtmlLBS]

-- | Use HXT to parse a value from an HTML tag. Check for usage examples in
--   this module's source.
parseHTML :: HtmlLBS -> Cursor

-- | Performs a given action using the last response. Use this to create
--   response-level assertions
withResponse :: HasCallStack => (SResponse -> YesodExample site a) -> YesodExample site a
instance Yesod.Core.Class.Dispatch.YesodDispatch site => Test.Hspec.Core.Example.Example (Yesod.Test.Internal.SIO.SIO (Yesod.Test.YesodExampleData site) a)
