webdriver-0.8.2: a Haskell client for the Selenium WebDriver protocol

Safe HaskellNone




WebDriver sessions

data WDSession Source

The local state of a WebDriver session. This structure is passed implicitly through all WD computations




wdSessHost :: ByteString
wdSessPort :: Int
wdSessBasePath :: ByteString
wdSessId :: Maybe SessionId

An opaque reference identifying the session to use with WD commands. A value of Nothing indicates that a session hasn't been created yet. Sessions can be created within WD via createSession, or created automatically with runSession

wdSessHist :: [SessionHistory]

The complete history of HTTP requests and responses, most recent first.

wdSessHistUpdate :: SessionHistoryConfig

Update function used to append new entries to session history

wdSessHTTPManager :: Manager

HTTP Manager used for connection pooling by the http-client library.

wdSessHTTPRetryCount :: Int

Number of times to retry a HTTP request if it times out

wdSessRequestHeaders :: RequestHeaders

Custom request headers to add to every HTTP request.

wdSessAuthHeaders :: RequestHeaders

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

newtype SessionId Source

An opaque identifier for a WebDriver session. These handles are produced by the server on session creation, and act to identify a session in progress.


SessionId Text 

WebDriver configuration

data WDConfig Source

WebDriver session configuration




wdHost :: String

Host name of the WebDriver server for this session (default

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)

defaultConfig :: WDConfig Source

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.

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

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


data Capabilities Source

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.




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.

defaultCaps :: Capabilities Source

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 Source

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

data Platform Source

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



data ProxyType Source

Available settings for the proxy Capabilities field



Use a proxy auto-config file specified by URL


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

Browser-specific capabilities

data Browser Source

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.




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.



chromeDriverVersion :: Maybe String

Version of the Chrome Webdriver server server to use

for more information on chromedriver see http://code.google.com/p/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.



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.



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

Browser Text

some other browser, specified by a string name

Default settings for browsers

firefox :: Browser Source

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

chrome :: Browser Source

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

ie :: Browser Source

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

opera :: Browser Source

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

WebDriver objects and command-specific types

newtype Element Source

An opaque identifier for a web page element.


Element Text 

currentWindow :: WindowHandle Source

A special WindowHandle that always refers to the currently focused window. This is also used by the Default instance.

data Selector Source

Specifies element(s) within a DOM tree using various selection methods.


ById Text 
ByName Text 
ByClass Text

(Note: multiple classes are not allowed. For more control, use ByCSS)

ByTag Text 
ByLinkText Text 
ByPartialLinkText Text 
ByCSS Text 
ByXPath Text 

data JSArg Source

An existential wrapper for any ToJSON instance. This allows us to pass parameters of many different types to Javascript code.


forall a . ToJSON a => JSArg a 


data FrameSelector Source

Specifies the frame used by focusFrame


WithIndex Integer 
WithName Text

focus on a frame by name or ID

WithElement Element

focus on a frame Element


focus on the first frame, or the main document if iframes are used.

data Cookie Source

Cookies are delicious delicacies. When sending cookies to the server, a value of Nothing indicates that the server should use a default value. When receiving cookies from the server, a value of Nothing indicates that the server is unable to specify the value.




cookName :: Text
cookValue :: Text
cookPath :: Maybe Text

path of this cookie. if Nothing, defaults to /

cookDomain :: Maybe Text

domain of this cookie. if Nothing, the current pages domain is used

cookSecure :: Maybe Bool

Is this cookie secure?

cookExpiry :: Maybe Integer

Expiry date expressed as seconds since the Unix epoch Nothing indicates that the cookie never expires

mkCookie :: Text -> Text -> Cookie Source

Creates a Cookie with only a name and value specified. All other fields are set to Nothing, which tells the server to use default values.

data LogEntry Source

A record that represents a single log entry.




logTime :: Integer

timestamp for the log entry. The standard does not specify the epoch or the unit of time.

logLevel :: LogLevel

log verbosity level

logMsg :: Text


newtype InvalidURL Source

An invalid URL was given


InvalidURL String 

newtype NoSessionId Source

A command requiring a session ID was attempted when no session ID was available.


NoSessionId String 

newtype BadJSON Source

An error occured when parsing a JSON value.


BadJSON String 

data HTTPStatusUnknown Source

An unexpected HTTP status was sent by the server.

newtype UnknownCommand Source

A command was sent to the WebDriver server that it didn't recognize.


UnknownCommand String 

newtype ServerError Source

A server-side exception occured


ServerError String 

data FailedCommand Source

This exception encapsulates a broad variety of exceptions that can occur when a command fails.

data FailedCommandInfo Source

Detailed information about the failed command provided by the server.




errMsg :: String

The error message.

errSess :: Maybe WDSession

The session associated with the exception.

errScreen :: Maybe ByteString

A screen shot of the focused window when the exception occured, if provided.

errClass :: Maybe String

The "class" in which the exception was raised, if provided.

errStack :: [StackFrame]

A stack trace of the exception.


Show FailedCommandInfo Source

Provides a readable printout of the error information, useful for logging.

FromJSON FailedCommandInfo Source 

data StackFrame Source

An individual stack frame from the stack trace provided by the server during a FailedCommand.

mkFailedCommandInfo :: WDSessionState s => String -> s FailedCommandInfo Source

Constructs a FailedCommandInfo from only an error message.

failedCommand :: WDSessionStateIO s => FailedCommandType -> String -> s a Source

Convenience function to throw a FailedCommand locally with no server-side info present.