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


-- | 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 <a>Html</a>. Returns Either
--   
--   <ul>
--   <li>Left: Query parse error.</li>
--   <li>Right: List of matching Html fragments.</li>
--   </ul>
findBySelector :: Html -> Query -> Either String [String]
type Html = 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

-- | Runs your test suite, using you wai <a>Application</a> and
--   <tt>ConnectionPool</tt> for performing the database queries in your
--   tests.
--   
--   You application may already have your connection pool but you need to
--   pass another one separately here.
--   
--   Look at the examples directory on this package to get an idea of the
--   (small) amount of boilerplate code you'll need to write before calling
--   this.
runTests :: Application -> Pool conn -> SpecsConn conn -> IO ()

-- | Start describing a Tests suite keeping cookies and a reference to the
--   tested <a>Application</a> and <tt>ConnectionPool</tt>
describe :: String -> SpecsConn conn -> SpecsConn conn

-- | Describe a single test that keeps cookies, and a reference to the last
--   response.
it :: String -> OneSpec conn () -> SpecsConn conn

-- | The specs state monad is where <a>describe</a> runs. parameterized by
--   a database connection. You should create type Specs = SpecsConn
--   MyDBConnection
type SpecsConn conn = StateT (SpecsData conn) IO ()

-- | The OneSpec state monad is where <a>it</a> runs.
type OneSpec conn = StateT (OneSpecData conn) IO

-- | Perform a POST request to url, using params
post :: ByteString -> RequestBuilder () -> OneSpec conn ()

-- | Perform a POST request without params
post_ :: ByteString -> OneSpec conn ()

-- | Perform a GET request to url, using params
get :: ByteString -> RequestBuilder () -> OneSpec conn ()

-- | Perform a GET request without params
get_ :: ByteString -> OneSpec conn ()

-- | General interface to performing requests, letting you specify the
--   request method
doRequest :: Method -> ByteString -> RequestBuilder a -> OneSpec conn ()

-- | General interface to performing requests, allowing you to add extra
--   headers as well as letting you specify the request method.
doRequestHeaders :: Method -> ByteString -> [Header] -> RequestBuilder a -> OneSpec conn ()

-- | Add a parameter with the given name and value.
byName :: Text -> Text -> RequestBuilder ()

-- | 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
fileByName :: Text -> FilePath -> Text -> RequestBuilder ()
byLabel :: Text -> Text -> RequestBuilder ()
fileByLabel :: Text -> FilePath -> Text -> RequestBuilder ()

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

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

-- | Run a persistent db query. For asserting on the results of performed
--   actions or setting up pre-conditions. At the moment this part is still
--   very raw.
--   
--   It is intended that you parametize the first argument of this function
--   for your backend runDB = runDBRunnder SqlPersist
runDBRunner :: (MonadBaseControl IO m, MonadIO m) => (poolrunner m a -> Pool conn -> IO a) -> poolrunner m a -> OneSpec conn a

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

-- | Assert the given header key/value pair was returned.
assertHeader :: HoldsResponse a => CI ByteString -> ByteString -> StateT a IO ()

-- | Assert the given header was not included in the response.
assertNoHeader :: HoldsResponse a => CI ByteString -> StateT a IO ()

-- | Assert the last response status is as expected.
statusIs :: HoldsResponse a => Int -> StateT a IO ()

-- | Assert the last response is exactly equal to the given text. This is
--   useful for testing API responses.
bodyEquals :: HoldsResponse a => String -> StateT a IO ()

-- | Assert the last response has the given text. The check is performed
--   using the response body in full text form.
bodyContains :: HoldsResponse a => String -> StateT a IO ()

-- | Queries the html using a css selector, and all matched elements must
--   contain the given string.
htmlAllContain :: HoldsResponse a => Query -> String -> StateT a IO ()

-- | Queries the html using a css selector, and passes if any matched
--   element contains the given string.
--   
--   Since 0.3.5
htmlAnyContain :: HoldsResponse a => Query -> String -> StateT a IO ()

-- | Performs a css query on the last response and asserts the matched
--   elements are as many as expected.
htmlCount :: HoldsResponse a => Query -> Int -> StateT a IO ()

-- | Outputs the last response body to stderr (So it doesn't get captured
--   by HSpec)
printBody :: HoldsResponse a => StateT a IO ()

-- | Performs a CSS query and print the matches to stderr.
printMatches :: HoldsResponse a => Query -> StateT a IO ()

-- | Query the last response using css selectors, returns a list of matched
--   fragments
htmlQuery :: HoldsResponse a => Query -> StateT a IO [Html]

-- | Use HXT to parse a value from an html tag. Check for usage examples in
--   this module's source.
parseHTML :: Html -> Cursor
withResponse :: HoldsResponse a => (SResponse -> StateT a IO b) -> StateT a IO b
instance HoldsResponse RequestBuilderData
instance HoldsResponse (OneSpecData conn)
