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


-- | Write end2end web application tests using webdriver and hspec
--   
--   For end to end testing of web applications from Haskell, the
--   <a>webdriver</a> package is a great tool but just contains the code to
--   communicate with the browser. This package integrates webdriver with
--   <a>hspec</a>.
@package hspec-webdriver
@version 0.2.3


-- | Write hspec tests that are webdriver tests, automatically managing the
--   webdriver sessions.
--   
--   This module re-exports functions from <a>Test.Hspec</a> and
--   <a>Test.WebDriver.Commands</a> and it is intended that you just import
--   <tt>Test.Hspec.WebDriver</tt>. If you need to import
--   <tt>Test.Hspec</tt> or <tt>Test.WebDriver</tt>, you should do so using
--   a qualified import.
--   
--   <pre>
--   {-# LANGUAGE OverloadedStrings #-}
--   module XKCD where
--   
--   import Test.Hspec.WebDriver
--   
--   main :: IO ()
--   main = hspec $
--       describe "XKCD Tests" $ do
--   
--           session "for 327" $ using Firefox $ do
--               it "opens the page" $ runWD $
--                   openPage "http://www.xkcd.com/327/"
--               it "checks hover text" $ runWD $ do
--                   e &lt;- findElem $ ByCSS "div#comic &gt; img"
--                   e `shouldBeTag` "img"
--                   e `shouldHaveAttr` ("title", "Her daughter is named Help I'm trapped in a driver's license factory.")
--   
--           parallel $ session "for 303" $ using [Firefox, Chrome] $ do
--               it "opens the page" $ runWD $
--                   openPage "http://www.xkcd.com/303/"
--               it "checks the title" $ runWD $ do
--                   e &lt;- findElem $ ById "ctitle"
--                   e `shouldBeTag` "div"
--                   e `shouldHaveText` "Compiling"
--   </pre>
--   
--   The above code assumes selenium-server-standalone is running on
--   <tt>127.0.0.1:4444</tt> at path <tt>/wd/hub</tt> (this is the
--   default).
module Test.Hspec.WebDriver

-- | Webdriver expectations consist of a set of browser <a>Capabilities</a>
--   to use and the actual test as a <a>WD</a> monad. The browser
--   capabilities are specified by an enumeration which is an instance of
--   <a>TestCapabilities</a>. The <tt>BrowserDefaults</tt> enumeration
--   provides items that represent the default set of capabilities for each
--   browser (see <a>defaultCaps</a>).
--   
--   To obtain more control over the capabilities (e.g. to test multiple
--   versions of IE or to test Firefrox without javascript), you should
--   <tt>import Test.Hspec.WebDriver hiding (BrowserDefaults)</tt> and then
--   create your own enumeration which is an instance of
--   <a>TestCapabilities</a> and <a>Using</a>.
data BrowserDefaults
Firefox :: BrowserDefaults
Chrome :: BrowserDefaults
IE :: BrowserDefaults
Opera :: BrowserDefaults
IPhone :: BrowserDefaults
IPad :: BrowserDefaults
Android :: BrowserDefaults

-- | Combine the examples nested inside this call into a webdriver session.
--   For each capability in the list, before the first example is executed,
--   a new webdriver session is created using the capabilities. The
--   examples are then executed in depth-first order using this webdriver
--   session (so later examples can rely on the browser state created by
--   earlier examples). Once the final example has executed, the session is
--   closed. If some <a>WDExample</a> fails (throws an exception), all
--   remaining examples in the session will become pending.
--   
--   Note that when using <a>parallel</a>, the examples within a single
--   session will still execute serially. Different sessions (including the
--   multiple sessions created if more than one capability is passed to
--   <a>session</a>) will be executed in parallel.
--   
--   This function uses the default webdriver host (127.0.0.1), port
--   (4444), and basepath (<tt>/wd/hub</tt>).
session :: TestCapabilities cap => String -> ([cap], Spec) -> Spec

-- | A variation of <a>session</a> which allows you to specify the
--   webdriver host, port, and basepath.
sessionOn :: TestCapabilities cap => String -> Word16 -> String -> String -> ([cap], Spec) -> Spec

-- | Create an example from a <a>WD</a> action. This <i>must</i> be nested
--   inside a call to <a>session</a> or <a>sessionOn</a>.
runWD :: WD () -> WDExample

-- | An example that can be passed to <a>it</a> containing a webdriver
--   action. It must be created with <a>runWD</a>.
data WDExample

-- | A typeclass of things which can be converted to a list of
--   capabilities. It's primary purpose is to allow the word <tt>using</tt>
--   to be used with <a>session</a> so that the session description reads
--   like a sentance.
--   
--   <pre>
--   session "for the home page" $ using Firefox $ do
--       it "loads the page" $ runWD $ do
--           ...
--       it "scrolls the carosel" $ runWD $ do
--           ...
--   session "for the users page" $ using [Firefox, Chrome] $ do
--       ...
--   </pre>
class Using a where type family UsingList a
using :: Using a => a -> Spec -> (UsingList a, Spec)

-- | Abort the session without closing the session.
--   
--   Normally, <a>session</a> will automatically close the session either
--   when the tests complete without error or when any of the tests within
--   the session throws an error. When developing the test suite, this can
--   be annoying since closing the session causes the browser window to
--   close. Therefore, while developing the test suite, you can insert a
--   call to <a>inspectSession</a>. This will immedietly halt the session
--   (all later tests will fail) but will not close the session so that the
--   browser window stays open.
inspectSession :: WD ()

-- | <a>shouldBe</a> lifted into the <a>WD</a> monad.
shouldBe :: (Show a, Eq a) => a -> a -> WD ()

-- | Asserts that the given element matches the given tag.
shouldBeTag :: Element -> Text -> WD ()

-- | Asserts that the given element has the given text.
shouldHaveText :: Element -> Text -> WD ()

-- | Asserts that the given elemnt has the attribute given by <tt>(attr
--   name, value)</tt>.
shouldHaveAttr :: Element -> (Text, Text) -> WD ()

-- | Asserts that the action returns the expected result.
shouldReturn :: (Show a, Eq a) => WD a -> a -> WD ()

-- | Asserts that the action throws an exception.
shouldThrow :: (Show e, Eq e, Exception e) => WD a -> e -> WD ()

-- | Provides information about the browser capabilities used for testing.
--   If you want more control over capabilities, you should hide
--   <a>BrowserDefaults</a> and then make an enumeration of all the
--   webdriver capabilities you will be testing with. For example,
--   
--   <pre>
--   data TestCaps = Firefox
--                 | FirefoxWithoutJavascript
--                 | Chrome
--                 | IE8
--                 | IE9
--      deriving (Show, Eq, Bounded, Enum)
--   </pre>
--   
--   <tt>TestCaps</tt> must then be made an instance of
--   <tt>TestCapabilities</tt>. Also, instances of <tt>Using</tt> should be
--   created.
class Show c => TestCapabilities c
newCaps :: TestCapabilities c => c -> WD Capabilities

-- | Run given spec and write a report to <a>stdout</a>. Exit with
--   <a>exitFailure</a> if at least one spec item fails.
hspec :: Spec -> IO ()
type Spec = SpecM ()

-- | Combine a list of specs into a larger spec.
describe :: String -> Spec -> Spec

-- | Create a spec item.
--   
--   A spec item consists of:
--   
--   <ul>
--   <li>a textual description of a desired behavior</li>
--   <li>an example for that behavior</li>
--   </ul>
--   
--   <pre>
--   describe "absolute" $ do
--     it "returns a positive number when given a negative number" $
--       absolute (-1) == 1
--   </pre>
it :: Example a => String -> a -> Spec

-- | An alias for <a>describe</a>.
context :: String -> Spec -> Spec

-- | Run examples of given spec in parallel.
parallel :: Spec -> Spec

-- | Specifies a pending example.
--   
--   If you want to textually specify a behavior but do not have an example
--   yet, use this:
--   
--   <pre>
--   describe "fancyFormatter" $ do
--     it "can format text in a way that everyone likes" $
--       pending
--   </pre>
pending :: Expectation

-- | Specifies a pending example with a reason for why it's pending.
--   
--   <pre>
--   describe "fancyFormatter" $ do
--     it "can format text in a way that everyone likes" $
--       pendingWith "waiting for clarification from the designers"
--   </pre>
pendingWith :: String -> Expectation

-- | A monadic interface to the WebDriver server. This monad is simply a
--   state monad transformer over <a>IO</a>, threading session information
--   between sequential webdriver commands
data WD a :: * -> *

-- | Lift a computation from the <a>IO</a> monad.
liftIO :: MonadIO m => forall a. IO a -> m a
instance Typeable WdState
instance Typeable PrevHasError
instance Eq BrowserDefaults
instance Show BrowserDefaults
instance Enum BrowserDefaults
instance Bounded BrowserDefaults
instance Show PrevHasError
instance Example WDExample
instance Exception PrevHasError
instance Using [BrowserDefaults]
instance Using BrowserDefaults
instance TestCapabilities BrowserDefaults