hspec-webdriver-1.2.2: Write end2end web application tests using webdriver and hspec
Safe HaskellSafe-Inferred
LanguageHaskell98

Test.Hspec.WebDriver

Description

Write hspec tests that are webdriver tests, automatically managing the webdriver sessions.

This module re-exports functions from Test.Hspec and Test.WebDriver.Commands and it is intended that you just import Test.Hspec.WebDriver. If you need to import Test.Hspec or Test.WebDriver, you should do so using a qualified import.

{-# LANGUAGE OverloadedStrings #-}
module XKCD where

import Test.Hspec.WebDriver

allBrowsers :: [Capabilities]
allBrowsers = [firefoxCaps, chromeCaps, ieCaps]

browsersExceptIE :: [Capabilities]
browsersExceptIE = [firefoxCaps, chromeCaps]

main :: IO ()
main = hspec $
    describe "XKCD Tests" $ do

        session "for 327" $ using allBrowsers $ do
            it "opens the page" $ runWD $
                openPage "http://www.xkcd.com/327/"
            it "checks hover text" $ runWD $ do
                e <- findElem $ ByCSS "div#comic > 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 browsersExceptIE $ do
            it "opens the page" $ runWD $
                openPage "http://www.xkcd.com/303/"
            it "checks the title" $ runWD $ do
                e <- findElem $ ById "ctitle"
                e `shouldBeTag` "div"
                e `shouldHaveText` "Compiling"

The above code assumes selenium-server-standalone is running on 127.0.0.1:4444 at path /wd/hub (this is the default).

Synopsis

Webdriver Example

data WdExample multi Source #

A webdriver example.

The webdriver action of type WD () should interact with the webpage using commands from Test.WebDriver.Commands (which is re-exported from this module) and then use the expectations in this module. It is possible to split up the spec of a single page into multiple examples where later examples start with the web browser state from the end of the previous example. This is helpful to keep each individual example small and allows the entire spec to be described at the beginning with pending examples.

The way this works is that you combine examples into a session using session or sessionWith. A webdriver session is then threaded through all examples in a session so that a later example in the session can rely on the webbrowser state as set up by the previous example. The type system enforces that every webdriver example must be located within a call to session or sessionWith. Indeed, a WdExample produces a SpecWith (WdTestSession multi) which can only be converted to Spec using session or sessionWith. The reason for the WdPending constructor is so that a pending example can be specified with type SpecWith (WdTestSession multi) so it can compose with the other webdriver examples.

The type multi is used when testing multiple sessions at once (e.g. to test multiple interacting users), otherwise it is (). Values of this type are used to determine which browser session the example should be executed against. A new session is created every time a new value of type multi is seen. Note that the type system enforces that every example within the session has the same type multi.

Constructors

WdExample multi WdOptions (WD ()) 
WdPending (Maybe String) 

Instances

Instances details
Eq multi => Example (WdExample multi) Source # 
Instance details

Defined in Test.Hspec.WebDriver

Associated Types

type Arg (WdExample multi) #

Methods

evaluateExample :: WdExample multi -> Params -> (ActionWith (Arg (WdExample multi)) -> IO ()) -> ProgressCallback -> IO Result #

type Arg (WdExample multi) Source # 
Instance details

Defined in Test.Hspec.WebDriver

type Arg (WdExample multi) = WdTestSession multi

data WdOptions Source #

Optional options that can be passed to runWDOptions.

Constructors

WdOptions 

Fields

Instances

Instances details
Default WdOptions Source # 
Instance details

Defined in Test.Hspec.WebDriver

Methods

def :: WdOptions #

runWD :: WD () -> WdExample () Source #

A shorthand for constructing a WdExample from a webdriver action when you are only testing a single browser session at once. See the XKCD example at the top of the page.

runWDOptions :: WdOptions -> WD () -> WdExample () Source #

A version of runWD that accepts some custom options

runWDWith :: multi -> WD () -> WdExample multi Source #

Create a webdriver example, specifying which of the multiple sessions the example should be executed against. I suggest you create an enumeration for multi, for example:

data TestUser = Gandolf | Bilbo | Legolas
    deriving (Show, Eq, Enum, Bounded)

runUser :: TestUser -> WD () -> WDExample TestUser
runUser = runWDWith

spec :: Spec
spec = session "tests some page" $ using [firefoxCaps] $ do
    it "does something with Gandolf" $ runUser Gandolf $ do
        openPage ...
    it "does something with Bilbo" $ runUser Bilbo $ do
        openPage ...
    it "goes back to the Gandolf session" $ runUser Gandolf $ do
        e <- findElem ....
        ...

In the above code, two sessions are created and the examples will go back and forth between the two sessions. Note that a session for Legolas will only be created the first time he shows up in a call to runUser, which might be never. To share information between the sessions (e.g. some data that Gandolf creates that Bilbo should expect), the best way I have found is to use IORefs created with runIO (wrapped in a utility module).

runWDWithOptions :: multi -> WdOptions -> WD () -> WdExample multi Source #

A version of runWDWith that accepts some custom options

pending :: WdExample multi Source #

A pending example.

pendingWith :: String -> WdExample multi Source #

A pending example with a message.

example :: Default multi => Expectation -> WdExample multi Source #

A version of example which lifts an IO () to a webdriver example (so it can be composed with other webdriver examples). In the case of multiple sessions, it doesn't really matter which session the expectation is executed against, so a default value is used. In the case of single sessions, the type is WdExample ().

Webdriver Sessions

session :: String -> ([Capabilities], SpecWith (WdTestSession multi)) -> Spec Source #

Combine the examples nested inside this call into a webdriver session or multiple sessions. For each of the capabilities in the list, the examples are executed one at a time in depth-first order and so later examples can rely on the browser state created by earlier examples. These passes through the examples are independent for different capabilities. Note that when using parallel, the examples within a single pass still execute serially. Different passes through the examples will be executed in parallel. The sessions are managed as follows:

  • In the simplest case when multi is (), before the first example is executed a new webdriver session with the given capabilities is created. The examples are then executed in depth-first order, and the session is then closed when either an exception occurs or the examples complete. (The session can be left open with inspectSession).
  • More generally, as the examples are executed, each time a new value of type multi is seen, a new webdriver session with the capabilities is automatically created. Later examples will continue with the session matching their value of multi.

This function uses the default webdriver host (127.0.0.1), port (4444), and basepath (/wd/hub).

sessionWith :: WDConfig -> String -> ([(Capabilities, String)], SpecWith (WdTestSession multi)) -> Spec Source #

A variation of session which allows you to specify the webdriver configuration. Note that the capabilities in the WDConfig will be ignored, instead the capabilities will come from the list of Capabilities passed to sessionWith.

In addition, each capability is paired with a descriptive string which is passed to hspec to describe the example. By default, session uses the browser name as the description. sessionWith supports a more detailed description so that in the hspec output you can distinguish between capabilities that share the same browser but differ in the details, for example capabilities with and without javascript.

inspectSession :: WD () Source #

Abort the session without closing the session.

Normally, session 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 inspectSession. This will immedietly halt the session (all later tests will fail) but will not close the session so that the browser window stays open.

using :: [caps] -> SpecWith (WdTestSession multi) -> ([caps], SpecWith (WdTestSession multi)) Source #

A synonym for constructing pairs that allows the word using to be used with session so that the session description reads like a sentance.

allBrowsers :: [Capabilities]
allBrowsers = [firefoxCaps, chromeCaps, ieCaps]

browsersExceptIE :: [Capabilities]
browsersExceptIE = [firefoxCaps, chromeCaps]

mobileBrowsers :: [Capabilities]
mobileBrowsers = [iphoneCaps, ipadCaps, androidCaps]

myspec :: Spec
myspec = do
  session "for the home page" $ using allBrowsers $ do
    it "loads the page" $ runWD $ do
        ...
    it "scrolls the carosel" $ runWD $ do
        ...
  session "for the users page" $ using browsersExceptIE $ do
    ...

data WdTestSession multi Source #

Internal state for webdriver test sessions.

Default Capabilities

firefoxCaps :: Capabilities Source #

Default capabilities which can be used in the list passed to using. I suggest creating a top-level definition such as allBrowsers and browsersWithoutIE such as in the XKCD example at the top of the page, so that you do not specify the browsers in the individual spec.

chromeCaps :: Capabilities Source #

Default capabilities which can be used in the list passed to using. I suggest creating a top-level definition such as allBrowsers and browsersWithoutIE such as in the XKCD example at the top of the page, so that you do not specify the browsers in the individual spec.

ieCaps :: Capabilities Source #

Default capabilities which can be used in the list passed to using. I suggest creating a top-level definition such as allBrowsers and browsersWithoutIE such as in the XKCD example at the top of the page, so that you do not specify the browsers in the individual spec.

operaCaps :: Capabilities Source #

Default capabilities which can be used in the list passed to using. I suggest creating a top-level definition such as allBrowsers and browsersWithoutIE such as in the XKCD example at the top of the page, so that you do not specify the browsers in the individual spec.

iphoneCaps :: Capabilities Source #

Default capabilities which can be used in the list passed to using. I suggest creating a top-level definition such as allBrowsers and browsersWithoutIE such as in the XKCD example at the top of the page, so that you do not specify the browsers in the individual spec.

ipadCaps :: Capabilities Source #

Default capabilities which can be used in the list passed to using. I suggest creating a top-level definition such as allBrowsers and browsersWithoutIE such as in the XKCD example at the top of the page, so that you do not specify the browsers in the individual spec.

androidCaps :: Capabilities Source #

Default capabilities which can be used in the list passed to using. I suggest creating a top-level definition such as allBrowsers and browsersWithoutIE such as in the XKCD example at the top of the page, so that you do not specify the browsers in the individual spec.

Expectations

shouldBe :: (Show a, Eq a) => a -> a -> WD () Source #

shouldBe lifted into the WD monad.

shouldBeTag :: Element -> Text -> WD () Source #

Asserts that the given element matches the given tag.

shouldHaveText :: Element -> Text -> WD () Source #

Asserts that the given element has the given text.

shouldHaveAttr :: Element -> (Text, Text) -> WD () Source #

Asserts that the given elemnt has the attribute given by (attr name, value).

shouldReturn :: (Show a, Eq a) => WD a -> a -> WD () Source #

Asserts that the action returns the expected result.

shouldThrow :: (Show e, Eq e, Exception e) => WD a -> e -> WD () Source #

Asserts that the action throws an exception.

Re-exports from Test.Hspec

hspec :: Spec -> IO () #

Run a given spec and write a report to stdout. Exit with exitFailure if at least one spec item fails.

Note: hspec handles command-line options and reads config files. This is not always desirable. Use evalSpec and runSpecForest if you need more control over these aspects.

type Spec = SpecWith () #

type SpecWith a = SpecM a () #

describe :: HasCallStack => String -> SpecWith a -> SpecWith a #

The describe function combines a list of specs into a larger spec.

context :: HasCallStack => String -> SpecWith a -> SpecWith a #

context is an alias for describe.

it :: (HasCallStack, Example a) => String -> a -> SpecWith (Arg a) #

The it function creates a spec item.

A spec item consists of:

  • a textual description of a desired behavior
  • an example for that behavior
describe "absolute" $ do
  it "returns a positive number when given a negative number" $
    absolute (-1) == 1

specify :: (HasCallStack, Example a) => String -> a -> SpecWith (Arg a) #

specify is an alias for it.

parallel :: SpecWith a -> SpecWith a #

parallel marks all spec items of the given spec to be safe for parallel evaluation.

runIO :: IO r -> SpecM a r #

Run an IO action while constructing the spec tree.

SpecM is a monad to construct a spec tree, without executing any spec items. runIO allows you to run IO actions during this construction phase. The IO action is always run when the spec tree is constructed (e.g. even when --dry-run is specified). If you do not need the result of the IO action to construct the spec tree, beforeAll may be more suitable for your use case.

Re-exports from Test.WebDriver

data WD a #

A state monad for WebDriver commands.

Instances

Instances details
MonadFix WD 
Instance details

Defined in Test.WebDriver.Monad

Methods

mfix :: (a -> WD a) -> WD a #

MonadIO WD 
Instance details

Defined in Test.WebDriver.Monad

Methods

liftIO :: IO a -> WD a #

Applicative WD 
Instance details

Defined in Test.WebDriver.Monad

Methods

pure :: a -> WD a #

(<*>) :: WD (a -> b) -> WD a -> WD b #

liftA2 :: (a -> b -> c) -> WD a -> WD b -> WD c #

(*>) :: WD a -> WD b -> WD b #

(<*) :: WD a -> WD b -> WD a #

Functor WD 
Instance details

Defined in Test.WebDriver.Monad

Methods

fmap :: (a -> b) -> WD a -> WD b #

(<$) :: a -> WD b -> WD a #

Monad WD 
Instance details

Defined in Test.WebDriver.Monad

Methods

(>>=) :: WD a -> (a -> WD b) -> WD b #

(>>) :: WD a -> WD b -> WD b #

return :: a -> WD a #

MonadCatch WD 
Instance details

Defined in Test.WebDriver.Monad

Methods

catch :: Exception e => WD a -> (e -> WD a) -> WD a #

MonadMask WD 
Instance details

Defined in Test.WebDriver.Monad

Methods

mask :: ((forall a. WD a -> WD a) -> WD b) -> WD b #

uninterruptibleMask :: ((forall a. WD a -> WD a) -> WD b) -> WD b #

generalBracket :: WD a -> (a -> ExitCase b -> WD c) -> (a -> WD b) -> WD (b, c) #

MonadThrow WD 
Instance details

Defined in Test.WebDriver.Monad

Methods

throwM :: Exception e => e -> WD a #

WebDriver WD 
Instance details

Defined in Test.WebDriver.Monad

Methods

doCommand :: (HasCallStack, ToJSON a, FromJSON b) => Method -> Text -> a -> WD b #

WDSessionState WD 
Instance details

Defined in Test.WebDriver.Monad

MonadBaseControl IO WD 
Instance details

Defined in Test.WebDriver.Monad

Associated Types

type StM WD a #

Methods

liftBaseWith :: (RunInBase WD IO -> IO a) -> WD a #

restoreM :: StM WD a -> WD a #

MonadBase IO WD 
Instance details

Defined in Test.WebDriver.Monad

Methods

liftBase :: IO α -> WD α #

type StM WD a 
Instance details

Defined in Test.WebDriver.Monad

type StM WD a = StM (StateT WDSession IO) a

data Capabilities #

A structure describing the capabilities of a session. This record serves dual roles.

  • It's used to specify the desired capabilities for a session before it's created. In this usage, fields that are set to Nothing indicate that we have no preference for that capability.
  • When received from the server , it's used to describe the actual capabilities given to us by the WebDriver server. Here a value of Nothing indicates that the server doesn't support the capability. Thus, for Maybe Bool fields, both Nothing and Just False indicate a lack of support for the desired capability.