Test.WebDriver

This module serves as the top-level interface to the Haskell WebDriver bindings, providing most of the functionality you're likely to want.

WebDriver monad

newtype WD a

A state monad for WebDriver commands.

Constructors

WD (StateT WDSession IO a)

Instances

MonadFix WD

Defined in Test.WebDriver.Monad

Methods

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

MonadIO WD

Defined in Test.WebDriver.Monad

Methods

liftIO :: IO a -> WD a

Applicative WD

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

Defined in Test.WebDriver.Monad

Methods

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

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

Monad WD

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

Defined in Test.WebDriver.Monad

Methods

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

MonadMask WD

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

Defined in Test.WebDriver.Monad

Methods

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

WebDriver WD

Defined in Test.WebDriver.Monad

Methods

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

WDSessionState WD

Defined in Test.WebDriver.Monad

Methods

getSession :: WD WDSession

putSession :: WDSession -> WD ()

MonadBaseControl IO WD

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

Defined in Test.WebDriver.Monad

Methods

liftBase :: IO α -> WD α

type StM WD a

Defined in Test.WebDriver.Monad

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

Running WebDriver commands

runSession :: WebDriverConfig conf => conf -> WD a -> IO a

Executes a WD computation within the IO monad, automatically creating a new session beforehand.

NOTE: session is not automatically closed when complete. If you want this behavior, use finallyClose. Example:

   runSessionThenClose action = runSession myConfig . finallyClose $ action

withSession :: WDSessionStateControl m => WDSession -> m a -> m a

Locally sets a session state for use within the given action. The state of any outside action is unaffected by this function. This function is useful if you need to work with multiple sessions simultaneously.

runWD :: WDSession -> WD a -> IO a

Executes a WD computation within the IO monad, using the given WDSession as state for WebDriver requests.

WebDriver configuration

data WDConfig

WebDriver session configuration

Constructors

WDConfig

Fields

• wdHost :: String

  Host name of the WebDriver server for this session (default 127.0.0.1)

• wdPort :: Int

  Port number of the server (default 4444)

• wdCapabilities :: Capabilities

  Capabilities to use for this session

• wdBasePath :: String

  Base path for all API requests (default "/wd/hub")

• wdRequestHeaders :: RequestHeaders

  Custom request headers to add to every HTTP request.

• wdAuthHeaders :: RequestHeaders

  Custom request headers to add *only* to session creation requests. This is usually done when a WebDriver server requires HTTP auth.

• wdHistoryConfig :: SessionHistoryConfig

  Specifies behavior of HTTP request/response history. By default we use unlimitedHistory.

• wdHTTPManager :: Maybe Manager

  Use the given http-client Manager instead of automatically creating one.

• wdHTTPRetryCount :: Int

  Number of times to retry a HTTP request if it times out (default 0)

Instances

Default WDConfig

Defined in Test.WebDriver.Config

Methods

def :: WDConfig

GetCapabilities WDConfig

Defined in Test.WebDriver.Config

Methods

getCaps :: WDConfig -> Capabilities

SetCapabilities WDConfig

Defined in Test.WebDriver.Config

Methods

setCaps :: Capabilities -> WDConfig -> WDConfig

WebDriverConfig WDConfig

Defined in Test.WebDriver.Config

Methods

mkCaps :: MonadBase IO m => WDConfig -> m Capabilities

mkSession :: MonadBase IO m => WDConfig -> m WDSession

defaultConfig :: WDConfig

A default session config connects to localhost on port 4444, and hasn't been initialized server-side. This value is the same as def but with a less polymorphic type.

Configuration helper functions

Instead of working with the Capabilities record directly, you can use these config modifier functions to specify common options.

useBrowser :: HasCapabilities t => Browser -> t -> t

A helper function for setting the browser capability of a HasCapabilities instance

useProxy :: HasCapabilities t => ProxyType -> t -> t

A helper function for setting the useProxy capability of a HasCapabilities instance

useVersion :: HasCapabilities t => String -> t -> t

A helper function for setting the version capability of a HasCapabilities instance

usePlatform :: HasCapabilities t => Platform -> t -> t

A helper function for setting the platform capability of a HasCapabilities instance

Session history configuration

type SessionHistoryConfig = SessionHistory -> [SessionHistory] -> [SessionHistory]

A function used by wdHistoryConfig to append new entries to session history.

noHistory :: SessionHistoryConfig

No session history is saved.

unlimitedHistory :: SessionHistoryConfig

Keep unlimited history

onlyMostRecentHistory :: SessionHistoryConfig

Saves only the most recent history

HTTP request header utilities

withRequestHeaders :: WDSessionStateControl m => RequestHeaders -> m a -> m a

Set a temporary list of custom RequestHeaders to use within the given action. All previous custom headers are temporarily removed, and then restored at the end.

withAuthHeaders :: WDSessionStateControl m => m a -> m a

Makes all webdriver HTTP requests in the given action use the session's auth headers, typically configured by setting the wdAuthHeaders config. This is useful if you want to temporarily use the same auth headers you used for session creation with other HTTP requests.

WebDriver commands

module Test.WebDriver.Commands

Capabilities (advanced configuration)

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.

Constructors

Capabilities

Fields

• browser :: Browser

  Browser choice and browser specific settings.

• version :: Maybe String

  Browser version to use.

• platform :: Platform

  Platform on which the browser should run.

• proxy :: ProxyType

  Proxy configuration settings.

• javascriptEnabled :: Maybe Bool

  Whether the session supports executing JavaScript via executeJS and asyncJS.

• takesScreenshot :: Maybe Bool

  Whether the session supports taking screenshots of the current page with the screenshot command

• handlesAlerts :: Maybe Bool

  Whether the session can interact with modal popups, such as window.alert and window.confirm via acceptAlerts, dismissAlerts, etc.

• databaseEnabled :: Maybe Bool

  Whether the session can interact with database storage.

• locationContextEnabled :: Maybe Bool

  Whether the session can set and query the browser's location context with setLocation and getLocation.

• applicationCacheEnabled :: Maybe Bool

  Whether the session can interact with the application cache .

• browserConnectionEnabled :: Maybe Bool

  Whether the session can query for the browser's connectivity and disable it if desired

• cssSelectorsEnabled :: Maybe Bool

  Whether the session supports CSS selectors when searching for elements.

• webStorageEnabled :: Maybe Bool

  Whether Web Storage (getKey, setKey, etc) support is enabled

• rotatable :: Maybe Bool

  Whether the session can rotate the current page's current layout between Portrait and Landscape orientations.

• acceptSSLCerts :: Maybe Bool

  Whether the session should accept all SSL certs by default

• nativeEvents :: Maybe Bool

  Whether the session is capable of generating native OS events when simulating user input.

• unexpectedAlertBehavior :: Maybe UnexpectedAlertBehavior

  How the session should handle unexpected alerts.

• additionalCaps :: [Pair]

  A list of (Text, Value) pairs specifying additional non-standard capabilities.

Instances

FromJSON Capabilities

Defined in Test.WebDriver.Capabilities

Methods

parseJSON :: Value -> Parser Capabilities

parseJSONList :: Value -> Parser [Capabilities]

ToJSON Capabilities

Defined in Test.WebDriver.Capabilities

Methods

toJSON :: Capabilities -> Value

toEncoding :: Capabilities -> Encoding

toJSONList :: [Capabilities] -> Value

toEncodingList :: [Capabilities] -> Encoding

Show Capabilities

Defined in Test.WebDriver.Capabilities

Methods

showsPrec :: Int -> Capabilities -> ShowS

show :: Capabilities -> String

showList :: [Capabilities] -> ShowS

Default Capabilities

Defined in Test.WebDriver.Capabilities

Methods

def :: Capabilities

Eq Capabilities

Defined in Test.WebDriver.Capabilities

Methods

(==) :: Capabilities -> Capabilities -> Bool

(/=) :: Capabilities -> Capabilities -> Bool

GetCapabilities Capabilities

Defined in Test.WebDriver.Capabilities

Methods

getCaps :: Capabilities -> Capabilities

defaultCaps :: Capabilities

Default capabilities. This is the same as the Default instance, but with less polymorphism. By default, we use firefox of an unspecified version with default system-wide proxy settings on whatever platform is available . All Maybe capabilities are set to Nothing (no preference).

allCaps :: Capabilities

Same as defaultCaps, but with all Maybe Value capabilities set to Just True.

modifyCaps :: HasCapabilities t => (Capabilities -> Capabilities) -> t -> t

Modifies the wdCapabilities field of a WDConfig by applying the given function. Overloaded to work with any HasCapabilities instance.

data Platform

Represents platform options supported by WebDriver. The value Any represents no preference.

Constructors

Windows

XP

Vista

Mac

Linux

Unix

Any

Instances

FromJSON Platform

Defined in Test.WebDriver.Capabilities

Methods

parseJSON :: Value -> Parser Platform

parseJSONList :: Value -> Parser [Platform]

ToJSON Platform

Defined in Test.WebDriver.Capabilities

Methods

toJSON :: Platform -> Value

toEncoding :: Platform -> Encoding

toJSONList :: [Platform] -> Value

toEncodingList :: [Platform] -> Encoding

Bounded Platform

Defined in Test.WebDriver.Capabilities

Methods

minBound :: Platform

maxBound :: Platform

Enum Platform

Defined in Test.WebDriver.Capabilities

Methods

succ :: Platform -> Platform

pred :: Platform -> Platform

toEnum :: Int -> Platform

fromEnum :: Platform -> Int

enumFrom :: Platform -> [Platform]

enumFromThen :: Platform -> Platform -> [Platform]

enumFromTo :: Platform -> Platform -> [Platform]

enumFromThenTo :: Platform -> Platform -> Platform -> [Platform]

Show Platform

Defined in Test.WebDriver.Capabilities

Methods

showsPrec :: Int -> Platform -> ShowS

show :: Platform -> String

showList :: [Platform] -> ShowS

Eq Platform

Defined in Test.WebDriver.Capabilities

Methods

(==) :: Platform -> Platform -> Bool

(/=) :: Platform -> Platform -> Bool

Ord Platform

Defined in Test.WebDriver.Capabilities

Methods

compare :: Platform -> Platform -> Ordering

(<) :: Platform -> Platform -> Bool

(<=) :: Platform -> Platform -> Bool

(>) :: Platform -> Platform -> Bool

(>=) :: Platform -> Platform -> Bool

max :: Platform -> Platform -> Platform

min :: Platform -> Platform -> Platform

data ProxyType

Available settings for the proxy Capabilities field

Constructors

NoProxy

UseSystemSettings

AutoDetect

PAC

Use a proxy auto-config file specified by URL

Fields

• autoConfigUrl :: String

Manual

Manually specify proxy hosts as hostname:port strings. Note that behavior is undefined for empty strings.

Fields

• ftpProxy :: String
• sslProxy :: String
• httpProxy :: String

Instances

FromJSON ProxyType

Defined in Test.WebDriver.Capabilities

Methods

parseJSON :: Value -> Parser ProxyType

parseJSONList :: Value -> Parser [ProxyType]

ToJSON ProxyType

Defined in Test.WebDriver.Capabilities

Methods

toJSON :: ProxyType -> Value

toEncoding :: ProxyType -> Encoding

toJSONList :: [ProxyType] -> Value

toEncodingList :: [ProxyType] -> Encoding

Show ProxyType

Defined in Test.WebDriver.Capabilities

Methods

showsPrec :: Int -> ProxyType -> ShowS

show :: ProxyType -> String

showList :: [ProxyType] -> ShowS

Eq ProxyType

Defined in Test.WebDriver.Capabilities

Methods

(==) :: ProxyType -> ProxyType -> Bool

(/=) :: ProxyType -> ProxyType -> Bool

Browser-specific capabilities

data Browser

This constructor simultaneously specifies which browser the session will use, while also providing browser-specific configuration. Default configuration is provided for each browser by firefox, chrome, opera, ie, etc.

This library uses firefox as its Default browser configuration, when no browser choice is specified.

Constructors

Firefox

Fields

• ffProfile :: Maybe (PreparedProfile Firefox)

  The firefox profile to use. If Nothing, a default temporary profile is automatically created and used.

• ffLogPref :: LogLevel

  Firefox logging preference

• ffBinary :: Maybe FilePath

  Server-side path to Firefox binary. If Nothing, use a sensible system-based default.

• ffAcceptInsecureCerts :: Maybe Bool

  Available after Firefox 52, and required only for Firefox geckodriver. Indicates whether untrusted and self-signed TLS certificates are implicitly trusted on navigation for the duration of the session.

Chrome

Fields

• chromeDriverVersion :: Maybe String

  Version of the Chrome Webdriver server server to use

  for more information on chromedriver see https://github.com/SeleniumHQ/selenium/wiki/ChromeDriver

• chromeBinary :: Maybe FilePath

  Server-side path to Chrome binary. If Nothing, use a sensible system-based default.

• chromeOptions :: [String]

  A list of command-line options to pass to the Chrome binary.

• chromeExtensions :: [ChromeExtension]

  A list of extensions to use.

• chromeExperimentalOptions :: Object

  Experimental options not yet exposed through a standard API.

IE

Fields

• ieIgnoreProtectedModeSettings :: Bool

  Whether to skip the protected mode check. If set, tests may become flaky, unresponsive, or browsers may hang. If not set, and protected mode settings are not the same for all zones, an exception will be thrown on driver construction.

• ieIgnoreZoomSetting :: Bool

  Indicates whether to skip the check that the browser's zoom level is set to 100%. Value is set to false by default.

• ieInitialBrowserUrl :: Maybe Text

  Allows the user to specify the initial URL loaded when IE starts. Intended to be used with ignoreProtectedModeSettings to allow the user to initialize IE in the proper Protected Mode zone. Using this capability may cause browser instability or flaky and unresponsive code. Only "best effort" support is provided when using this capability.

• ieElementScrollBehavior :: IEElementScrollBehavior

  Allows the user to specify whether elements are scrolled into the viewport for interaction to align with the top or bottom of the viewport. The default value is to align with the top of the viewport.

• ieEnablePersistentHover :: Bool

  Determines whether persistent hovering is enabled (true by default). Persistent hovering is achieved by continuously firing mouse over events at the last location the mouse cursor has been moved to.

• ieEnableElementCacheCleanup :: Bool

  Determines whether the driver should attempt to remove obsolete elements from the element cache on page navigation (true by default). This is to help manage the IE driver's memory footprint , removing references to invalid elements.

• ieRequireWindowFocus :: Bool

  Determines whether to require that the IE window have focus before performing any user interaction operations (mouse or keyboard events). This capability is false by default, but delivers much more accurate native events interactions.

• ieBrowserAttachTimeout :: Integer

  The timeout, in milliseconds, that the driver will attempt to locate and attach to a newly opened instance of Internet Explorer . The default is zero, which indicates waiting indefinitely.

• ieLogFile :: Maybe FilePath

  The path to file where server should write log messages to. By default it writes to stdout.

• ieLogLevel :: IELogLevel

  The log level used by the server. Defaults to IELogFatal

• ieHost :: Maybe Text

  The address of the host adapter on which the server will listen for commands.

• ieExtractPath :: Maybe Text

  The path to the directory used to extract supporting files used by the server. Defaults to the TEMP directory if not specified.

• ieSilent :: Bool

  Suppresses diagnostic output when the server is started.

• ieForceCreateProcess :: Bool

  Forces launching Internet Explorer using the CreateProcess API. If this option is not specified, IE is launched using the IELaunchURL, if it is available. For IE 8 and above, this option requires the TabProcGrowth registry value to be set to 0.

• ieSwitches :: Maybe Text

  Specifies command-line switches with which to launch Internet Explorer. This is only valid when used with the forceCreateProcess.

Opera

Fields

• operaBinary :: Maybe FilePath

  Server-side path to the Opera binary

• operaProduct :: Maybe String

  Which Opera product we're using, e.g. "desktop", "core"

• operaDetach :: Bool

  Whether the Opera instance should stay open after we close the session. If false, closing the session closes the browser.

• operaAutoStart :: Bool

  Whether to auto-start the Opera binary. If false, OperaDriver will wait for a connection from the browser. By default this is True.

• operaIdle :: Bool

  Whether to use Opera's alternative implicit wait implementation. It will use an in-browser heuristic to guess when a page has finished loading. This feature is experimental, and disabled by default.

• operaDisplay :: Maybe Int

  (*nix only) which X display to use.

• operaLauncher :: Maybe FilePath

  Path to the launcher binary to use. The launcher is a gateway between OperaDriver and the Opera browser. If Nothing, OperaDriver will use the launcher supplied with the package.

• operaPort :: Maybe Word16

  The port we should use to connect to Opera. If Just 0 , use a random port. If Nothing, use the default Opera port. The default opera constructor uses Just 0, since Nothing is likely to cause "address already in use" errors.

• operaHost :: Maybe String

  The host Opera should connect to. Unless you're starting Opera manually you won't need this.

• operaOptions :: Maybe String

  Command-line arguments to pass to Opera.

• operaLogFile :: Maybe FilePath

  Where to send the log output. If Nothing, logging is disabled.

• operaLogPref :: LogLevel

  Log level preference. Defaults to LogInfo

Phantomjs

Fields

• phantomjsBinary :: Maybe FilePath
• phantomjsOptions :: [String]

HTMLUnit

IPhone

IPad

Android

Browser Text

some other browser, specified by a string name

Instances

FromJSON Browser

Defined in Test.WebDriver.Capabilities

Methods

parseJSON :: Value -> Parser Browser

parseJSONList :: Value -> Parser [Browser]

ToJSON Browser

Defined in Test.WebDriver.Capabilities

Methods

toJSON :: Browser -> Value

toEncoding :: Browser -> Encoding

toJSONList :: [Browser] -> Value

toEncodingList :: [Browser] -> Encoding

Show Browser

Defined in Test.WebDriver.Capabilities

Methods

showsPrec :: Int -> Browser -> ShowS

show :: Browser -> String

showList :: [Browser] -> ShowS

Default Browser

Defined in Test.WebDriver.Capabilities

Methods

def :: Browser

Eq Browser

Defined in Test.WebDriver.Capabilities

Methods

(==) :: Browser -> Browser -> Bool

(/=) :: Browser -> Browser -> Bool

data LogLevel

Indicates a log verbosity level. Used in Browser and Opera configuration.

Constructors

LogOff

LogSevere

LogWarning

LogInfo

LogConfig

LogFine

LogFiner

LogFinest

LogDebug

LogAll

Instances

FromJSON LogLevel

Defined in Test.WebDriver.Capabilities

Methods

parseJSON :: Value -> Parser LogLevel

parseJSONList :: Value -> Parser [LogLevel]

ToJSON LogLevel

Defined in Test.WebDriver.Capabilities

Methods

toJSON :: LogLevel -> Value

toEncoding :: LogLevel -> Encoding

toJSONList :: [LogLevel] -> Value

toEncodingList :: [LogLevel] -> Encoding

Bounded LogLevel

Defined in Test.WebDriver.Capabilities

Methods

minBound :: LogLevel

maxBound :: LogLevel

Enum LogLevel

Defined in Test.WebDriver.Capabilities

Methods

succ :: LogLevel -> LogLevel

pred :: LogLevel -> LogLevel

toEnum :: Int -> LogLevel

fromEnum :: LogLevel -> Int

enumFrom :: LogLevel -> [LogLevel]

enumFromThen :: LogLevel -> LogLevel -> [LogLevel]

enumFromTo :: LogLevel -> LogLevel -> [LogLevel]

enumFromThenTo :: LogLevel -> LogLevel -> LogLevel -> [LogLevel]

Read LogLevel

Defined in Test.WebDriver.Capabilities

Methods

readsPrec :: Int -> ReadS LogLevel

readList :: ReadS [LogLevel]

readPrec :: ReadPrec LogLevel

readListPrec :: ReadPrec [LogLevel]

Show LogLevel

Defined in Test.WebDriver.Capabilities

Methods

showsPrec :: Int -> LogLevel -> ShowS

show :: LogLevel -> String

showList :: [LogLevel] -> ShowS

Default LogLevel

Defined in Test.WebDriver.Capabilities

Methods

def :: LogLevel

Eq LogLevel

Defined in Test.WebDriver.Capabilities

Methods

(==) :: LogLevel -> LogLevel -> Bool

(/=) :: LogLevel -> LogLevel -> Bool

Ord LogLevel

Defined in Test.WebDriver.Capabilities

Methods

compare :: LogLevel -> LogLevel -> Ordering

(<) :: LogLevel -> LogLevel -> Bool

(<=) :: LogLevel -> LogLevel -> Bool

(>) :: LogLevel -> LogLevel -> Bool

(>=) :: LogLevel -> LogLevel -> Bool

max :: LogLevel -> LogLevel -> LogLevel

min :: LogLevel -> LogLevel -> LogLevel

Browser defaults

firefox :: Browser

Default Firefox settings. All Maybe fields are set to Nothing. ffLogPref is set to LogInfo.

chrome :: Browser

Default Chrome settings. All Maybe fields are set to Nothing, no options are specified, and no extensions are used.

ie :: Browser

Default IE settings. See the IE constructor for more details on individual defaults

opera :: Browser

Default Opera settings. See the Opera constructor for more details on individual defaults.

iPhone :: Browser

iPad :: Browser

android :: Browser

Exception handling

finallyClose :: WebDriver wd => wd a -> wd a

A finalizer ensuring that the session is always closed at the end of the given WD action, regardless of any exceptions.

closeOnException :: WebDriver wd => wd a -> wd a

Exception handler that closes the session when an asynchronous exception is thrown, but otherwise leaves the session open if the action was successful.

module Test.WebDriver.Exceptions

Accessing session history

data SessionHistory

Constructors

SessionHistory

Fields

• histRequest :: Request
• histResponse :: Either SomeException (Response ByteString)
• histRetryCount :: Int

Instances

Show SessionHistory

Defined in Test.WebDriver.Session.History

Methods

showsPrec :: Int -> SessionHistory -> ShowS

show :: SessionHistory -> String

showList :: [SessionHistory] -> ShowS

getSessionHistory :: WDSessionState wd => wd [SessionHistory]

Gets the command history for the current session.

dumpSessionHistory :: WDSessionStateControl wd => wd a -> wd a

Prints a history of API requests to stdout after computing the given action.