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


-- | integration testing for WAI/Yesod Applications
--   
--   Behaviour Oriented integration Testing for Yesod Applications
@package yesod-test
@version 1.2.0


-- | 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 Show Selector
instance Eq Selector
instance Show SelectorGroup
instance Eq SelectorGroup


-- | 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>. It's 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, were your forms may have field names generated by the
--   framework or a randomly generated <tt>_nonce</tt> field.
--   
--   Your database is also directly available so you can use runDBRunner 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] ()

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

-- | 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 url, using params
get :: (Yesod site, RedirectUrl site url) => url -> YesodExample site ()

-- | Perform a POST request to url
post :: (Yesod site, RedirectUrl site url) => url -> YesodExample site ()

-- | General interface to performing requests, allowing you to add extra
--   headers as well as letting you specify the request method.
request :: Yesod site => RequestBuilder site () -> YesodExample site ()
addRequestHeader :: Header -> RequestBuilder site ()
setMethod :: Method -> RequestBuilder site ()

-- | Add a parameter with the given name and value.
addPostParam :: Text -> Text -> RequestBuilder site ()
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
addFile :: Text -> FilePath -> Text -> RequestBuilder site ()

-- | The RequestBuilder state monad constructs an url encoded string of
--   arguments to send with your requests. Some of the functions that run
--   on it use the current response to analize the forms that the server is
--   expecting to receive.
type RequestBuilder site = StateT (RequestBuilderData site) IO
setUrl :: (Yesod site, RedirectUrl site url) => url -> RequestBuilder site ()
byLabel :: Text -> Text -> RequestBuilder site ()
fileByLabel :: Text -> FilePath -> Text -> RequestBuilder site ()

-- | For responses that display a single form, just lookup the only nonce
--   available.
addNonce :: RequestBuilder site ()

-- | Lookup a _nonce form field and add it's value to the params. Receives
--   a CSS selector that should resolve to the form element containing the
--   nonce.
addNonce_ :: Query -> 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 ()

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

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