-- 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.5.0.1


-- | 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.SelectorGroup
instance GHC.Show.Show Yesod.Test.CssQuery.SelectorGroup
instance GHC.Classes.Eq Yesod.Test.CssQuery.Selector
instance GHC.Show.Show Yesod.Test.CssQuery.Selector


-- | 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]
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 and persistent.
--   
--   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.
--   
--   Your database is also directly available so you can use <tt>runDB</tt>
--   to set up backend pre-conditions, or to assert that your session is
--   having the desired effect.
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 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 = StateT (YesodExampleData site) IO

-- | 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>YesodSpecTree</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

-- | 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 ()

-- | 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 :: Yesod site => 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 ()

-- | 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.
addPostParam :: Text -> Text -> RequestBuilder site ()

-- | Add a parameter with the given name and value to the query string.
addGetParam :: Text -> 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 :: (Yesod site) => 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 = StateT (RequestBuilderData site) IO

-- | 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 ()

-- | 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>
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 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>
fileByLabel :: Text -> FilePath -> 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 :: 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_ :: 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 :: 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 :: ByteString -> CI ByteString -> RequestBuilder site ()

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

-- | Assert the given header key/value pair was returned.
assertHeader :: CI ByteString -> ByteString -> YesodExample site ()

-- | Assert the given header was not included in the response.
assertNoHeader :: CI ByteString -> YesodExample site ()

-- | Assert the last response status is as expected.
statusIs :: Int -> YesodExample site ()

-- | Assert the last response is exactly equal to the given text. This is
--   useful for testing API responses.
bodyEquals :: String -> YesodExample site ()

-- | Assert the last response has the given text. The check is performed
--   using the response body in full text form.
bodyContains :: String -> YesodExample site ()

-- | Queries the HTML using a CSS selector, and all matched elements must
--   contain the given string.
htmlAllContain :: Query -> String -> YesodExample site ()

-- | Queries the HTML using a CSS selector, and passes if any matched
--   element contains the given string.
--   
--   Since 0.3.5
htmlAnyContain :: 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 htmlAnyContains).
--   
--   Since 1.2.2
htmlNoneContain :: Query -> String -> YesodExample site ()

-- | Performs a CSS query on the last response and asserts the matched
--   elements are as many as expected.
htmlCount :: Query -> Int -> YesodExample site ()

-- | 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 :: RequestBuilder site Cookies

-- | Outputs the last response body to stderr (So it doesn't get captured
--   by HSpec)
printBody :: YesodExample site ()

-- | Performs a CSS query and print the matches to stderr.
printMatches :: Query -> YesodExample site ()

-- | Query the last response using CSS selectors, returns a list of matched
--   fragments
htmlQuery :: 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 :: (SResponse -> YesodExample site a) -> YesodExample site a
instance Yesod.Core.Class.Dispatch.YesodDispatch site => Test.Hspec.Core.Example.Example (Control.Monad.Trans.State.Lazy.StateT (Yesod.Test.YesodExampleData site) GHC.Types.IO a)
