webdriver-0.11.0.0: a Haskell client for the Selenium WebDriver protocol
Safe HaskellSafe-Inferred
LanguageHaskell2010

Test.WebDriver.Commands

Description

This module exports basic WD actions that can be used to interact with a browser session.

Synopsis

Sessions

createSession :: (HasCallStack, WebDriver wd) => Capabilities -> wd WDSession Source #

Create a new session with the given Capabilities. The returned session becomes the "current session" for this action.

Note: if you're using runSession to run your WebDriver commands, you don't need to call this explicitly.

closeSession :: (HasCallStack, WebDriver wd) => wd () Source #

Close the current session and the browser associated with it.

sessions :: (HasCallStack, WebDriver wd) => wd [(SessionId, Capabilities)] Source #

Retrieve a list of active sessions and their Capabilities.

getActualCaps :: (HasCallStack, WebDriver wd) => wd Capabilities Source #

Get the actual server-side Capabilities of the current session.

Browser interaction

Web navigation

openPage :: (HasCallStack, WebDriver wd) => String -> wd () Source #

Opens a new page by the given URL.

forward :: (HasCallStack, WebDriver wd) => wd () Source #

Navigate forward in the browser history.

back :: (HasCallStack, WebDriver wd) => wd () Source #

Navigate backward in the browser history.

refresh :: (HasCallStack, WebDriver wd) => wd () Source #

Refresh the current page

Page info

getCurrentURL :: (HasCallStack, WebDriver wd) => wd String Source #

Gets the URL of the current page.

getSource :: (HasCallStack, WebDriver wd) => wd Text Source #

Get the current page source

getTitle :: (HasCallStack, WebDriver wd) => wd Text Source #

Get the title of the current page.

saveScreenshot :: (HasCallStack, WebDriver wd) => FilePath -> wd () Source #

Save a screenshot to a particular location

screenshot :: (HasCallStack, WebDriver wd) => wd ByteString Source #

Grab a screenshot of the current page as a PNG image

screenshotBase64 :: (HasCallStack, WebDriver wd) => wd ByteString Source #

Grab a screenshot as a base-64 encoded PNG image. This is the protocol-defined format.

Timeouts

setImplicitWait :: (HasCallStack, WebDriver wd) => Integer -> wd () Source #

Sets the amount of time (ms) we implicitly wait when searching for elements.

setScriptTimeout :: (HasCallStack, WebDriver wd) => Integer -> wd () Source #

Sets the amount of time (ms) we wait for an asynchronous script to return a result.

setPageLoadTimeout :: (HasCallStack, WebDriver wd) => Integer -> wd () Source #

Sets the amount of time (ms) to wait for a page to finish loading before throwing a Timeout exception.

Web elements

newtype Element Source #

An opaque identifier for a web page element.

Constructors

Element Text 

data Selector Source #

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

Constructors

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 

Searching for elements

findElem :: (HasCallStack, WebDriver wd) => Selector -> wd Element Source #

Find an element on the page using the given element selector.

findElems :: (HasCallStack, WebDriver wd) => Selector -> wd [Element] Source #

Find all elements on the page matching the given selector.

findElemFrom :: (HasCallStack, WebDriver wd) => Element -> Selector -> wd Element Source #

Search for an element using the given element as root.

findElemsFrom :: (HasCallStack, WebDriver wd) => Element -> Selector -> wd [Element] Source #

Find all elements matching a selector, using the given element as root.

Interacting with elements

click :: (HasCallStack, WebDriver wd) => Element -> wd () Source #

Click on an element.

submit :: (HasCallStack, WebDriver wd) => Element -> wd () Source #

Submit a form element. This may be applied to descendents of a form element as well.

getText :: (HasCallStack, WebDriver wd) => Element -> wd Text Source #

Get all visible text within this element.

Sending key inputs to elements

sendKeys :: (HasCallStack, WebDriver wd) => Text -> Element -> wd () Source #

Send a sequence of keystrokes to an element. All modifier keys are released at the end of the function. Named constants for special modifier keys can be found in Test.WebDriver.Common.Keys

sendRawKeys :: (HasCallStack, WebDriver wd) => Text -> wd () Source #

Similar to sendKeys, but doesn't implicitly release modifier keys afterwards. This allows you to combine modifiers with mouse clicks.

clearInput :: (HasCallStack, WebDriver wd) => Element -> wd () Source #

Clear a textarea or text input element's value.

Element information

attr :: (HasCallStack, WebDriver wd) => Element -> Text -> wd (Maybe Text) Source #

Retrieve the value of an element's attribute

cssProp :: (HasCallStack, WebDriver wd) => Element -> Text -> wd (Maybe Text) Source #

Retrieve the value of an element's computed CSS property

elemPos :: (HasCallStack, WebDriver wd) => Element -> wd (Float, Float) Source #

Retrieve an element's current position.

elemSize :: (HasCallStack, WebDriver wd) => Element -> wd (Float, Float) Source #

Retrieve an element's current size.

isSelected :: (HasCallStack, WebDriver wd) => Element -> wd Bool Source #

Determine if the element is selected.

isEnabled :: (HasCallStack, WebDriver wd) => Element -> wd Bool Source #

Determine if the element is enabled.

isDisplayed :: (HasCallStack, WebDriver wd) => Element -> wd Bool Source #

Determine if the element is displayed.

tagName :: (HasCallStack, WebDriver wd) => Element -> wd Text Source #

Return the tag name of the given element.

activeElem :: (HasCallStack, WebDriver wd) => wd Element Source #

Return the element that currently has focus.

elemInfo :: (HasCallStack, WebDriver wd) => Element -> wd Value Source #

Deprecated: This command does not work with Marionette (Firefox) driver, and is likely to be completely removed in Selenium 4

Describe the element. Returns a JSON object whose meaning is currently undefined by the WebDriver protocol.

Element equality

(<==>) :: (HasCallStack, WebDriver wd) => Element -> Element -> wd Bool infix 4 Source #

Determines if two element identifiers refer to the same element.

(</=>) :: (HasCallStack, WebDriver wd) => Element -> Element -> wd Bool infix 4 Source #

Determines if two element identifiers refer to different elements.

Javascript

executeJS :: (Foldable f, FromJSON a, WebDriver wd) => f JSArg -> Text -> wd a Source #

Inject a snippet of Javascript into the page for execution in the context of the currently selected frame. The executed script is assumed to be synchronous and the result of evaluating the script is returned and converted to an instance of FromJSON.

The first parameter defines a sequence of arguments to pass to the javascript function. Arguments of type Element will be converted to the corresponding DOM element. Likewise, any elements in the script result will be returned to the client as Elements.

The second parameter defines the script itself in the form of a function body. The value returned by that function will be returned to the client. The function will be invoked with the provided argument list and the values may be accessed via the arguments object in the order specified.

When using executeJS, GHC might complain about an ambiguous type in situations where the result of the executeJS call is ignored/discard. Consider the following example:

	jsExample = do
		e <- findElem (ById "foo")
		executeJS [] "someAction()"
		return e

Because the result of the executeJS is discarded, GHC cannot resolve which instance of the fromJSON class to use when parsing the Selenium server response. In such cases, we can use the ignoreReturn helper function located in Test.WebDriver.JSON. ignoreReturn has no runtime effect; it simply helps the type system by expicitly providing a fromJSON instance to use.

	import Test.WebDriver.JSON (ignoreReturn)
	jsExample = do
		e <- findElem (ById "foo")
		ignoreReturn $ executeJS [] "someAction()"
		return e

asyncJS :: (HasCallStack, Foldable f, FromJSON a, WebDriver wd) => f JSArg -> Text -> wd (Maybe a) Source #

Executes a snippet of Javascript code asynchronously. This function works similarly to executeJS, except that the Javascript is passed a callback function as its final argument. The script should call this function to signal that it has finished executing, passing to it a value that will be returned as the result of asyncJS. A result of Nothing indicates that the Javascript function timed out (see setScriptTimeout)

data JSArg Source #

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

Constructors

forall a.ToJSON a => JSArg a 

Instances

Instances details
ToJSON JSArg Source # 
Instance details

Defined in Test.WebDriver.Commands

Windows

newtype WindowHandle Source #

An opaque identifier for a browser window

Constructors

WindowHandle Text 

Instances

Instances details
FromJSON WindowHandle Source # 
Instance details

Defined in Test.WebDriver.Commands.Internal

ToJSON WindowHandle Source # 
Instance details

Defined in Test.WebDriver.Commands.Internal

Read WindowHandle Source # 
Instance details

Defined in Test.WebDriver.Commands.Internal

Show WindowHandle Source # 
Instance details

Defined in Test.WebDriver.Commands.Internal

Default WindowHandle Source # 
Instance details

Defined in Test.WebDriver.Commands.Internal

Methods

def :: WindowHandle #

Eq WindowHandle Source # 
Instance details

Defined in Test.WebDriver.Commands.Internal

Ord WindowHandle Source # 
Instance details

Defined in Test.WebDriver.Commands.Internal

currentWindow :: WindowHandle Source #

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

getCurrentWindow :: (HasCallStack, WebDriver wd) => wd WindowHandle Source #

Returns a handle to the currently focused window

closeWindow :: (HasCallStack, WebDriver wd) => WindowHandle -> wd () Source #

Closes the given window

windows :: (HasCallStack, WebDriver wd) => wd [WindowHandle] Source #

Returns a list of all windows available to the session

maximize :: (HasCallStack, WebDriver wd) => wd () Source #

Maximizes the current window if not already maximized

getWindowSize :: (HasCallStack, WebDriver wd) => wd (Word, Word) Source #

Get the dimensions of the current window.

setWindowSize :: (HasCallStack, WebDriver wd) => (Word, Word) -> wd () Source #

Set the dimensions of the current window.

getWindowPos :: (HasCallStack, WebDriver wd) => wd (Int, Int) Source #

Get the coordinates of the current window.

setWindowPos :: (HasCallStack, WebDriver wd) => (Int, Int) -> wd () Source #

Set the coordinates of the current window.

Focusing on frames

focusFrame :: (HasCallStack, WebDriver wd) => FrameSelector -> wd () Source #

Switch focus to the frame specified by the FrameSelector.

data FrameSelector Source #

Specifies the frame used by focusFrame

Constructors

WithIndex Integer 
WithName Text

focus on a frame by name or ID

WithElement Element

focus on a frame Element

DefaultFrame

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

Cookies

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.

Constructors

Cookie 

Fields

Instances

Instances details
FromJSON Cookie Source # 
Instance details

Defined in Test.WebDriver.Cookies

ToJSON Cookie Source # 
Instance details

Defined in Test.WebDriver.Cookies

Generic Cookie Source # 
Instance details

Defined in Test.WebDriver.Cookies

Associated Types

type Rep Cookie :: Type -> Type #

Methods

from :: Cookie -> Rep Cookie x #

to :: Rep Cookie x -> Cookie #

Show Cookie Source # 
Instance details

Defined in Test.WebDriver.Cookies

Eq Cookie Source # 
Instance details

Defined in Test.WebDriver.Cookies

Methods

(==) :: Cookie -> Cookie -> Bool #

(/=) :: Cookie -> Cookie -> Bool #

type Rep Cookie Source # 
Instance details

Defined in Test.WebDriver.Cookies

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.

cookies :: (HasCallStack, WebDriver wd) => wd [Cookie] Source #

Retrieve all cookies visible to the current page.

setCookie :: (HasCallStack, WebDriver wd) => Cookie -> wd () Source #

Set a cookie. If the cookie path is not specified, it will default to "/". Likewise, if the domain is omitted, it will default to the current page's domain

deleteCookie :: (HasCallStack, WebDriver wd) => Cookie -> wd () Source #

Delete a cookie. This will do nothing is the cookie isn't visible to the current page.

deleteVisibleCookies :: (HasCallStack, WebDriver wd) => wd () Source #

Delete all visible cookies on the current page.

Alerts

getAlertText :: (HasCallStack, WebDriver wd) => wd Text Source #

Get the text of an alert dialog.

replyToAlert :: (HasCallStack, WebDriver wd) => Text -> wd () Source #

Sends keystrokes to Javascript prompt() dialog.

acceptAlert :: (HasCallStack, WebDriver wd) => wd () Source #

Accepts the currently displayed alert dialog.

dismissAlert :: (HasCallStack, WebDriver wd) => wd () Source #

Dismisses the currently displayed alert dialog.

Mouse gestures

moveTo :: (HasCallStack, WebDriver wd) => (Int, Int) -> wd () Source #

Moves the mouse to the given position relative to the active element.

moveToCenter :: (HasCallStack, WebDriver wd) => Element -> wd () Source #

Moves the mouse to the center of a given element.

moveToFrom :: (HasCallStack, WebDriver wd) => (Int, Int) -> Element -> wd () Source #

Moves the mouse to the given position relative to the given element.

clickWith :: (HasCallStack, WebDriver wd) => MouseButton -> wd () Source #

Click at the current mouse position with the given mouse button.

data MouseButton Source #

A mouse button

Instances

Instances details
FromJSON MouseButton Source # 
Instance details

Defined in Test.WebDriver.Commands

ToJSON MouseButton Source # 
Instance details

Defined in Test.WebDriver.Commands

Bounded MouseButton Source # 
Instance details

Defined in Test.WebDriver.Commands

Enum MouseButton Source # 
Instance details

Defined in Test.WebDriver.Commands

Show MouseButton Source # 
Instance details

Defined in Test.WebDriver.Commands

Eq MouseButton Source # 
Instance details

Defined in Test.WebDriver.Commands

Ord MouseButton Source # 
Instance details

Defined in Test.WebDriver.Commands

mouseDown :: (HasCallStack, WebDriver wd) => wd () Source #

Press and hold the left mouse button down. Note that undefined behavior occurs if the next mouse command is not mouseUp.

mouseUp :: (HasCallStack, WebDriver wd) => wd () Source #

Release the left mouse button.

withMouseDown :: (HasCallStack, WebDriver wd) => wd a -> wd a Source #

Perform the given action with the left mouse button held down. The mouse is automatically released afterwards.

doubleClick :: (HasCallStack, WebDriver wd) => wd () Source #

Double click at the current mouse location.

HTML 5 Web Storage

data WebStorageType Source #

An HTML 5 storage type

Instances

Instances details
Bounded WebStorageType Source # 
Instance details

Defined in Test.WebDriver.Commands

Enum WebStorageType Source # 
Instance details

Defined in Test.WebDriver.Commands

Show WebStorageType Source # 
Instance details

Defined in Test.WebDriver.Commands

Eq WebStorageType Source # 
Instance details

Defined in Test.WebDriver.Commands

Ord WebStorageType Source # 
Instance details

Defined in Test.WebDriver.Commands

storageSize :: (HasCallStack, WebDriver wd) => WebStorageType -> wd Integer Source #

Get the current number of keys in a web storage area.

getAllKeys :: (HasCallStack, WebDriver wd) => WebStorageType -> wd [Text] Source #

Get a list of all keys from a web storage area.

deleteAllKeys :: (HasCallStack, WebDriver wd) => WebStorageType -> wd () Source #

Delete all keys within a given web storage area.

getKey :: (HasCallStack, WebDriver wd) => WebStorageType -> Text -> wd Text Source #

Get the value associated with a key in the given web storage area. Unset keys result in empty strings, since the Web Storage spec makes no distinction between the empty string and an undefined value.

setKey :: (HasCallStack, WebDriver wd) => WebStorageType -> Text -> Text -> wd Text Source #

Set a key in the given web storage area.

deleteKey :: (HasCallStack, WebDriver wd) => WebStorageType -> Text -> wd () Source #

Delete a key in the given web storage area.

HTML 5 Application Cache

data ApplicationCacheStatus Source #

Instances

Instances details
FromJSON ApplicationCacheStatus Source # 
Instance details

Defined in Test.WebDriver.Commands

Bounded ApplicationCacheStatus Source # 
Instance details

Defined in Test.WebDriver.Commands

Enum ApplicationCacheStatus Source # 
Instance details

Defined in Test.WebDriver.Commands

Read ApplicationCacheStatus Source # 
Instance details

Defined in Test.WebDriver.Commands

Show ApplicationCacheStatus Source # 
Instance details

Defined in Test.WebDriver.Commands

Eq ApplicationCacheStatus Source # 
Instance details

Defined in Test.WebDriver.Commands

Ord ApplicationCacheStatus Source # 
Instance details

Defined in Test.WebDriver.Commands

Mobile device support

Screen orientation

data Orientation Source #

A screen orientation

Constructors

Landscape 
Portrait 

Instances

Instances details
FromJSON Orientation Source # 
Instance details

Defined in Test.WebDriver.Commands

ToJSON Orientation Source # 
Instance details

Defined in Test.WebDriver.Commands

Bounded Orientation Source # 
Instance details

Defined in Test.WebDriver.Commands

Enum Orientation Source # 
Instance details

Defined in Test.WebDriver.Commands

Show Orientation Source # 
Instance details

Defined in Test.WebDriver.Commands

Eq Orientation Source # 
Instance details

Defined in Test.WebDriver.Commands

Ord Orientation Source # 
Instance details

Defined in Test.WebDriver.Commands

getOrientation :: (HasCallStack, WebDriver wd) => wd Orientation Source #

Get the current screen orientation for rotatable display devices.

setOrientation :: (HasCallStack, WebDriver wd) => Orientation -> wd () Source #

Set the current screen orientation for rotatable display devices.

Geo-location

getLocation :: (HasCallStack, WebDriver wd) => wd (Int, Int, Int) Source #

Get the current geographical location of the device.

setLocation :: (HasCallStack, WebDriver wd) => (Int, Int, Int) -> wd () Source #

Set the current geographical location of the device.

Touch gestures

touchClick :: (HasCallStack, WebDriver wd) => Element -> wd () Source #

Single tap on the touch screen at the given element's location.

touchDown :: (HasCallStack, WebDriver wd) => (Int, Int) -> wd () Source #

Emulates pressing a finger down on the screen at the given location.

touchUp :: (HasCallStack, WebDriver wd) => (Int, Int) -> wd () Source #

Emulates removing a finger from the screen at the given location.

touchMove :: (HasCallStack, WebDriver wd) => (Int, Int) -> wd () Source #

Emulates moving a finger on the screen to the given location.

touchScroll :: (HasCallStack, WebDriver wd) => (Int, Int) -> wd () Source #

Emulate finger-based touch scroll. Use this function if you don't care where the scroll begins

touchScrollFrom :: (HasCallStack, WebDriver wd) => (Int, Int) -> Element -> wd () Source #

Emulate finger-based touch scroll, starting from the given location relative to the given element.

touchDoubleClick :: (HasCallStack, WebDriver wd) => Element -> wd () Source #

Emulate a double click on a touch device.

touchLongClick :: (HasCallStack, WebDriver wd) => Element -> wd () Source #

Emulate a long click on a touch device.

touchFlick :: (HasCallStack, WebDriver wd) => (Int, Int) -> wd () Source #

Emulate a flick on the touch screen. The coordinates indicate x and y velocity, respectively. Use this function if you don't care where the flick starts.

touchFlickFrom Source #

Arguments

:: (HasCallStack, WebDriver wd) 
=> Int

flick velocity

-> (Int, Int)

a location relative to the given element

-> Element

the given element

-> wd () 

Emulate a flick on the touch screen.

IME support

Uploading files to remote server

These functions allow you to upload a file to a remote server. Note that this operation isn't supported by all WebDriver servers, and the location where the file is stored is not standardized.

uploadFile :: (HasCallStack, WebDriver wd) => FilePath -> wd () Source #

Uploads a file from the local filesystem by its file path.

uploadRawFile Source #

Arguments

:: (HasCallStack, WebDriver wd) 
=> FilePath

File path to use with this bytestring.

-> Integer

Modification time (in seconds since Unix epoch).

-> ByteString

The file contents as a lazy ByteString

-> wd () 

Uploads a raw bytestring with associated file info.

uploadZipEntry :: (HasCallStack, WebDriver wd) => Entry -> wd () Source #

Lowest level interface to the file uploading mechanism. This allows you to specify the exact details of the zip entry sent across network.

Server information and logs

serverStatus :: WebDriver wd => wd Value Source #

Get information from the server as a JSON Value. For more information about this object see https://github.com/SeleniumHQ/selenium/wiki/JsonWireProtocol#status

getLogs :: (HasCallStack, WebDriver wd) => LogType -> wd [LogEntry] Source #

Retrieve the log buffer for a given log type. The server-side log buffer is reset after each request.

Which log types are available is server defined, but the wire protocol lists these as common log types: client, driver, browser, server

getLogTypes :: (HasCallStack, WebDriver wd) => wd [LogType] Source #

Get a list of available log types.

data LogEntry Source #

A record that represents a single log entry.

Constructors

LogEntry 

Fields

data LogLevel Source #

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

Instances

Instances details
FromJSON LogLevel Source # 
Instance details

Defined in Test.WebDriver.Capabilities

ToJSON LogLevel Source # 
Instance details

Defined in Test.WebDriver.Capabilities

Bounded LogLevel Source # 
Instance details

Defined in Test.WebDriver.Capabilities

Enum LogLevel Source # 
Instance details

Defined in Test.WebDriver.Capabilities

Read LogLevel Source # 
Instance details

Defined in Test.WebDriver.Capabilities

Show LogLevel Source # 
Instance details

Defined in Test.WebDriver.Capabilities

Default LogLevel Source # 
Instance details

Defined in Test.WebDriver.Capabilities

Methods

def :: LogLevel #

Eq LogLevel Source # 
Instance details

Defined in Test.WebDriver.Capabilities

Ord LogLevel Source # 
Instance details

Defined in Test.WebDriver.Capabilities