WebDriver UDF

Introduction

The WebDriver UDF will allow you to interact with any browser that supports the W3C WebDriver specifications. Supporting multiple browsers via the same code base is now possible with just a few configuration settings.

Requirements

User Defined Functions

  • JSON UDF
  • WinHTTP UDF
  • HtmlTable2Array UDF (optional)
  • WinHttp_WebSocket UDF (optional; needed for websocket CDP functionality)

WebDriver for desired browser

  • Chrome
  • FireFox
  • Edge
  • Opera

Source Code

You will always be able to find the latest version in the GitHub Repo

Version

0.9.1


WebDriver UDF Library

Below is a complete list of the functions available in this library. Click on a function name for a detailed description.

Function | Description
_WD_CreateSession | Request new session from web driver.
_WD_DeleteSession | Delete existing session.
_WD_Status | Get current web driver state.
_WD_GetSession | Get details on existing session.
_WD_Timeouts | Set or retrieve the session timeout parameters.
_WD_Navigate | Navigate to the designated URL.
_WD_Action | Perform various interactions with the web driver session.
_WD_Window | Perform interactions related to the current window.
_WD_FindElement | Find element(s) by designated strategy.
_WD_ElementAction | Perform action on designated element.
_WD_ExecuteScript | Execute Javascipt commands.
_WD_Alert | Respond to user prompt.
_WD_GetSource | Get page source.
_WD_Cookies | Gets, sets, or deletes the session's cookies.
_WD_Option | Sets and get options for the web driver UDF.
_WD_Startup | Launch the designated web driver console app.
_WD_Shutdown | Kill the web driver console app.
_WD_LastHTTPResult | Return the result of the last WinHTTP request.
_WD_LastHTTPResponse | Return the response of the last WinHTTP request.
_WD_NewTab | Create new tab in current browser session.
_WD_Attach | Attach to existing browser tab.
_WD_LinkClickByText | Simulate a mouse click on a link with text matching the provided string.
_WD_WaitElement | Wait for an element in the current tab before returning.
_WD_GetMouseElement | Retrieves reference to element below mouse pointer.
_WD_GetElementFromPoint | Retrieves reference to element at specified point.
_WD_GetFrameCount | Returns the number of frames/iframes in the current document context.
_WD_IsWindowTop | Returns a boolean of the session being at the top level, or in a frame(s).
_WD_FrameEnter | Enter the specified frame.
_WD_FrameLeave | Leave the current frame, to its parent.
_WD_HighlightElement | Highlights the specified element. [Deprecated]
_WD_HighlightElements | Highlights the specified elements.
_WD_LoadWait | Wait for a browser page load to complete before returning.
_WD_Screenshot | Takes a screenshot of the Window or Element.
_WD_PrintToPDF | Print the current tab in paginated PDF format.
_WD_jQuerify | Inject jQuery library into current session.
_WD_ElementOptionSelect | Find and click on an option from a Select element.
_WD_ElementSelectAction | Perform action on designated <select> element.
_WD_ConsoleVisible | Control visibility of the webdriver console app.
_WD_GetShadowRoot | Retrieves the shadow root of an element.
_WD_SelectFiles | Select files for uploading to a website.
_WD_IsLatestRelease | Compares local UDF version to latest release on Github.
_WD_UpdateDriver | Replace web driver with newer version, if available.
_WD_GetBrowserVersion | Get version number of specified browser.
_WD_GetBrowserPath | Retrieve path to browser executable from registry
_WD_GetWebDriverVersion | Get version number of specifed webdriver.
_WD_DownloadFile | Download file and save to disk.
_WD_SetTimeouts | User friendly function to set webdriver session timeouts.
_WD_GetElementById | Locate element by id.
_WD_GetElementByName | Locate element by name.
_WD_SetElementValue | Set value of designated element.
_WD_ElementActionEx | Perform advanced action on designated element.
_WD_GetTable | Return all elements of a table.
_WD_IsFullScreen | Return a boolean indicating if the session is in full screen mode.
_WD_GetDevicePixelRatio | Returns an integer indicating the DevicePixelRatio
_WD_CheckContext | Check if browser context is still valid.
_WD_JsonActionKey | Formats keyboard "action" strings for use in _WD_Action
_WD_JsonActionPointer | Formats pointer "action" strings for use in _WD_Action
_WD_JsonActionPause | Formats pause "action" strings for use in _WD_Action
_WD_JsonCookie | Formats "cookie" strings for use in _WD_Cookies
_WD_CDPExecuteCommand | Execute CDP command.
_WD_CDPGetSettings | Retrieve CDP related settings from the browser.


Function _WD_Option

Function Reference

_WD_Option

Sets and get options for the web driver UDF.

_WD_Option($sOption[, $vValue = Default])

Parameters

$sOption One of the following options:

BASEURL - IP address used for web driver communication
BINARYFORMAT - Format used to store binary data
CONSOLE - Destination for console output
CONSOLESUFFIX - Suffix for console output
DEBUGTRIM - Length of response text written to the debug cocnsole
DEFAULTTIMEOUT - Default timeout (in miliseconds) used by other functions if no other value is supplied
DRIVER - Full path name to web driver executable
DRIVERCLOSE - Close prior driver instances before launching new one (Boolean)
DRIVERDETECT - Use existing driver instance if it exists (Boolean)
DRIVERPARAMS - Parameters to pass to web driver executable
ERRORMSGBOX - Enable/Disable reporting errors to MsgBox() (Boolean)
OUTPUTDEBUG - Enable/Disable reporting errors to OutputDebugString (Boolean)
HTTPTIMEOUTS - Set WinHTTP timeouts on each Get, Post, Delete request (Boolean)
PORT - Port used for web driver communication
SLEEP - Function to be called when UDF pauses the script execution
VERSION - Version number of UDF library (read only)
$vValue [optional] if no value is given, the current value is returned (default = "")

Return Value

Success: | 1 or current value.
Failure: | 0 or "" (empty string) and sets @error to $_WD_ERROR_InvalidDataType


Function _WD_Shutdown

Function Reference

_WD_Shutdown

Kill the web driver console app.

_WD_Shutdown([$vDriver = Default])

Parameters

$vDriver [optional] The name or PID of Web driver console to shutdown

Return Value

Success: | None
Failure: | None.

Related

_WD_Startup


Function _WD_Startup

Function Reference

_WD_Startup

Launch the designated web driver console app.

_WD_Startup()

Parameters

None.

Return Value

Success: | PID for the WD console.
Failure: | 0 and sets @error to one of the following values: - $_WD_ERROR_GeneralError - $_WD_ERROR_InvalidValue - $_WD_ERROR_FileIssue

Related

_WD_Shutdown


Function _WD_Status

Function Reference

_WD_Status

Get current web driver state.

_WD_Status()

Parameters

None.

Return Value

Success: | Dictionary object with "message" and "ready" properties.
Failure: | "" (empty string) and sets @error to $_WD_ERROR_Exception

Related

_WD_LastHTTPResult


Function _WD_Action

Function Reference

_WD_Action

Perform various interactions with the web driver session.

_WD_Action($sSession, $sCommand[, $sOption = Default])

Parameters

$sSession | Session ID from _WD_CreateSession
$sCommand | One of the following actions: ACTIONS - Performs the action specified in $sOption. If $sOption = "" then all the keys and pointer buttons that are currently depressed will be released. This causes events to be fired as if the state was released by an explicit series of actions BACK - Causes the browser to traverse one step backward in the joint session history of the current top-level browsing context FORWARD - Causes the browser to traverse one step forwards in the joint session history of the current top-level browsing context REFRESH - Causes the browser to reload the page in current top-level browsing context TITLE - Returns the document title of the current top-level browsing context URL - Protocol binding to load the URL of the browser. If a baseUrl is specified in the config, it will be prepended to the url parameter. Calling this function with the same url as last time will trigger a page reload
$sOption | [optional] a JSON string of actions to perform. Default is ""

Return Value

Success: | Return value from web driver (could be an empty string).
Failure: | "" (empty string) and sets @error to one of the following values: - $_WD_ERROR_Exception - $_WD_ERROR_InvalidDataType

Related

_WD_LastHTTPResult


Function _WD_Alert

Function Reference

_WD_Alert

Respond to user prompt.

_WD_Alert($sSession, $sCommand[, $sOption = Default])

Parameters

$sSession | Session ID from _WD_CreateSession
$sCommand | One of the following actions: ACCEPT - Accept the current user prompt as if the user would have clicked the OK button DISMISS - Dismiss the current user prompt as if the user would have clicked the Cancel or OK button, whichever is present, in that order GETTEXT - Return the text message associated with the current user prompt or null SENDTEXT - Set the text field of the current user prompt to the given value STATUS - Return logical value indicating the presence or absence of an alert
$sOption | [optional] a string value. Default is ""

Return Value

Success: | Requested data returned by web driver.
Failure: | "" (empty string) and sets @error to one of the following values: - $_WD_ERROR_NoAlert - $_WD_ERROR_InvalidDataType

Related

_WD_LastHTTPResult


Function _WD_CheckContext

Function Reference

_WD_CheckContext

Check if browser context is still valid.

_WD_CheckContext($sSession[, $bReconnect = Default[, $vTarget = Default]])

Parameters

$sSession | Session ID from _WD_CreateSession
$bReconnect | [optional] Auto reconnect? Default is True
$vTarget | [optional] Tab to target in reconnect attempt. Default is $_WD_TARGET_FirstTab. This can be the handle for an existing tab if known

Return Value

Success: | Returns one of the following values: $_WD_STATUS_Valid (1) - Current browser context is valid $_WD_STATUS_Reconnect (2) - Context was invalid; Successfully reconnected to existing tab
Failure: | $_WD_STATUS_Invalid (0) and sets @error to $_WD_ERROR_Exception

Related

_WD_Action, _WD_Window, _WD_LastHTTPResult


Function _WD_Cookies

Function Reference

_WD_Cookies

Gets, sets, or deletes the session's cookies.

_WD_Cookies($sSession, $sCommand[, $sOption = Default])

Parameters

$sSession | Session ID from _WD_CreateSession
$sCommand | One of the following actions: ADD - Create a new cookie. $sOption has to be a JSON string DELETE - Delete a single cookie. The name of the cookie to delete is specified in $sOption DELETEALL - Delete all cookies GET - Retrieve the value of a single cookie. The name of the cookie to retrieve has to be specified in $sOption GETALL - Retrieve the values of all cookies
$sOption | [optional] a string value. Default is ""

Return Value

Success: | Requested data returned by web driver.
Failure: | "" (empty string) and sets @error to one of the following values: - $_WD_ERROR_Exception - $_WD_ERROR_InvalidDataType - $_WD_ERROR_InvalidArgue

Remarks

Please have a look at wd_demo.au3 > DemoCookies function for how to add a new cookie.

Related

_WD_JsonCookie, _WD_LastHTTPResult


Function _WD_CreateSession

Function Reference

_WD_CreateSession

Request new session from web driver.

_WD_CreateSession([$sCapabilities = Default])

Parameters

$sCapabilities [optional] Requested features in JSON format. Default is "{}"

Return Value

Success: | Session ID to be used in future requests to web driver session.
Failure: | "" (empty string) and sets @error to $_WD_ERROR_Exception.

Related

_WD_DeleteSession, _WD_LastHTTPResult


Function _WD_DeleteSession

Function Reference

_WD_DeleteSession

Delete existing session.

_WD_DeleteSession($sSession)

Parameters

$sSession Session ID from _WD_CreateSession

Return Value

Success: | 1
Failure: | 0 and sets @error to $_WD_ERROR_Exception

Related

_WD_CreateSession, _WD_LastHTTPResult


Function _WD_DownloadFile

Function Reference

_WD_DownloadFile

Download file and save to disk.

_WD_DownloadFile($sURL, $sDest[, $iOptions = Default])

Parameters

$sURL | URL representing file to be downloaded
$sDest | Full path, including filename, of destination file
$iOptions | [optional] Download options

Return Value

Success: | True (Download succeeded).
Failure: | False (Download failed) and sets @error to one of the following values: - $_WD_ERROR_NotFound - $_WD_ERROR_FileIssue - $_WD_ERROR_Timeout - $_WD_ERROR_GeneralError - $_WD_ERROR_UserAbort


Function _WD_ExecuteScript

Function Reference

_WD_ExecuteScript

Execute Javascipt commands.

_WD_ExecuteScript($sSession, $sScript[, $sArguments = Default[, $bAsync = Default[, $vSubNode = Default]]])

Parameters

$sSession | Session ID from _WD_CreateSession
$sScript | Javascript command(s) to run
$sArguments | [optional] String of arguments in JSON format
$bAsync | [optional] Perform request asyncronously? Default is False
$vSubNode | [optional] Return the designated JSON node instead of the entire JSON string. Default is "" (entire response is returned)

Return Value

Success: | Response from web driver in JSON format or value requested by given $vSubNode
Failure: | Response from web driver in JSON format and sets @error to value returned from __WD_Post() If script is executed successfully but $vSubNode isn't found, then "" (empty string) and sets @error to $_WD_ERROR_RetValue If $vSubNode isn't valid, then "" (empty string) and sets @error to _WD_ERROR_InvalidArgue

Related

_WD_LastHTTPResult


Function _WD_GetSession

Function Reference

_WD_GetSession

Get details on existing session.

_WD_GetSession($sSession)

Parameters

$sSession Session ID from _WD_CreateSession

Return Value

Success: | Dictionary object with "sessionId" and "capabilities" items.
Failure: | "" (empty string) and sets @error to $_WD_ERROR_Exception

Remarks

The Get Session functionality was added and then removed from the W3C draft spec, so the code is commented
until they determine how this should function. See w3c/webdriver@35df53a for details. Meanwhile, I temporarily
changed the code to return the information that is available

Related

_WD_CreateSession, _WD_LastHTTPResult


Function _WD_GetSource

Function Reference

_WD_GetSource

Get page source.

_WD_GetSource($sSession)

Parameters

$sSession Session ID from _WD_CreateSession

Return Value

Success: | HTML source code from page.
Failure: | "" (empty string) and sets @error to one of the following values: - $_WD_ERROR_Exception

Related

_WD_LastHTTPResult


Function _WD_jQuerify

Function Reference

_WD_jQuerify

Inject jQuery library into current session.

_WD_jQuerify($sSession[, $sjQueryFile = Default[, $iTimeout = Default]])

Parameters

$sSession | Session ID from _WD_CreateSession
$sjQueryFile | [optional] Path or URL to jQuery source file
$iTimeout | [optional] Period of time (in milliseconds) to wait before exiting function

Return Value

Success: | None.
Failure: | None and sets @error to one of the following values: - $_WD_ERROR_Timeout - $_WD_ERROR_GeneralError

Related

_WD_ExecuteScript, _WD_LastHTTPResult


Function _WD_LoadWait

Function Reference

_WD_LoadWait

Wait for a browser page load to complete before returning.

_WD_LoadWait($sSession[, $iDelay = Default[, $iTimeout = Default[, $sElement = Default]]])

Parameters

$sSession | Session ID from _WD_CreateSession
$iDelay | [optional] Milliseconds to wait before initially checking status
$iTimeout | [optional] Period of time (in milliseconds) to wait before exiting function
$sElement | [optional] Element ID to confirm DOM invalidation

Return Value

Success: | 1.
Failure: | 0 and sets @error to $_WD_ERROR_Timeout

Related

_WD_LastHTTPResult


Function _WD_Navigate

Function Reference

_WD_Navigate

Navigate to the designated URL.

_WD_Navigate($sSession, $sURL)

Parameters

$sSession | Session ID from _WD_CreateSession
$sURL | Destination URL

Return Value

Success: | 1.
Failure: | 0 and sets @error to one of the following values: - $_WD_ERROR_Exception - $_WD_ERROR_Timeout

Related

_WD_LastHTTPResult


Function _WD_SetTimeouts

Function Reference

_WD_SetTimeouts

User friendly function to set webdriver session timeouts.

_WD_SetTimeouts($sSession[, $iPageLoad = Default[, $iScript = Default[, $iImplicitWait = Default]]])

Parameters

$sSession | Session ID from _WD_CreateSession
$iPageLoad | [optional] Page load timeout in milliseconds
$iScript | [optional] Script timeout in milliseconds
$iImplicitWait | [optional] Implicit wait timeout in milliseconds

Return Value

Success: | Return value from web driver in JSON format.
Failure: | 0 and sets @error to one of the following values: - $_WD_ERROR_InvalidArgue - $_WD_ERROR_Exception - $_WD_ERROR_InvalidDataType

Remarks

$iScript parameter can be null, implies that scripts should never be interrupted, but instead run indefinitely
When setting page load timeout, WinHTTP receive timeout is automatically adjusted as well

Related

_WD_Timeouts, _WD_LastHTTPResult


Function _WD_Timeouts

Function Reference

_WD_Timeouts

Set or retrieve the session timeout parameters.

_WD_Timeouts($sSession[, $sTimeouts = Default])

Parameters

$sSession | Session ID from _WD_CreateSession
$sTimeouts | [optional] Requested timouts in JSON format. Default is ""

Return Value

Success: | Return value from web driver in JSON format.
Failure: | 0 and sets @error to $_WD_ERROR_Exception

Remarks

Separate timeouts can be set for "script", "pageLoad", and "implicit".

Related

_WD_LastHTTPResult


Function _WD_ElementAction

Function Reference

_WD_ElementAction

Perform action on designated element.

_WD_ElementAction($sSession, $sElement, $sCommand[, $sOption = Default])

Parameters

$sSession | Session ID from _WD_CreateSession
$sElement | Element ID from _WD_FindElement
$sCommand | One of the following actions: ACTIVE - Get active element ATTRIBUTE - Get element's attribute CLEAR - Clear element's value CLICK - Click element COMPUTEDLABEL - Get element's computed label COMPUTEDROLE - Get element's computed role CSS - Get element's CSS value DISPLAYED - Get element's visibility ENABLED - Get element's enabled status NAME - Get element's tag name PROPERTY - Get element's property RECT - Get element's dimensions / coordinates SCREENSHOT - Take element screenshot SELECTED - Get element's selected status SHADOW - Get element's shadow root TEXT - Get element's rendered text VALUE - Get or set element's value. If $sOption = "" the value of the element is returned, else set
$sOption | [optional] a string value. Default is ""

Return Value

Success: | Requested data returned by web driver.
Failure: | "" (empty string) and sets @error to one of the following values: - $_WD_ERROR_NoMatch - $_WD_ERROR_Exception - $_WD_ERROR_InvalidDataType - $_WD_ERROR_InvalidExpression

Related

_WD_LastHTTPResult


Function _WD_ElementActionEx

Function Reference

_WD_ElementActionEx

Perform advanced action on designated element.

_WD_ElementActionEx($sSession, $sElement, $sCommand[, $iXOffset = Default[, $iYOffset = Default[, $iButton = Default[, $iHoldDelay = Default[, $sModifier = Default]]]]])

Parameters

$sSession | Session ID from _WD_CreateSession
$sElement | Element ID from _WD_FindElement
$sCommand | one of the following actions: CHECK - Checks a checkbox input element CHILDCOUNT - Returns the number of child elements CLICK - Clicks on the target element CLICKANDHOLD - Clicks on the target element and holds the button down for the designated timeframe ($iHoldDelay) DOUBLECLICK - Do a double click on the selected element HIDE - Change the element's style to 'display: none' to hide the element HOVER - Move the mouse pointer so that it is located above the target element MODIFIERCLICK - Holds down a modifier key on the keyboard before clicking on the target element. This can be used to perform advanced actions such as shift-clicking an element RIGHTCLICK - Do a rightclick on the selected element SHOW - Change the element's style to 'display: normal' to unhide/show the element UNCHECK - Unchecks a checkbox input element
$iXOffset | [optional] X Offset. Default is 0
$iYOffset | [optional] Y Offset. Default is 0
$iButton | [optional] Mouse button. Default is $_WD_BUTTON_Left
$iHoldDelay | [optional] Hold time in ms. Default is 1000
$sModifier | [optional] Modifier key. Default is "\uE008" (shift key)

Return Value

Success: | Return value from web driver (could be an empty string)
Failure: | "" (empty string) and sets @error to one of the following values: - $_WD_ERROR_Exception - $_WD_ERROR_InvalidDataType

Remarks

Moving the mouse pointer above the target element is the first thing to occur for every $sCommand before it gets executed.
There are examples in DemoElements() function in wd_demo.au3

Related

_WD_ElementAction, _WD_Action, _WD_LastHTTPResult


Function _WD_ElementOptionSelect

Function Reference

_WD_ElementOptionSelect

Find and click on an option from a Select element.

_WD_ElementOptionSelect($sSession, $sStrategy, $sSelector[, $sStartElement = Default])

Parameters

$sSession | Session ID from _WD_CreateSession
$sStrategy | Locator strategy. See defined constant $_WD_LOCATOR_* for allowed values
$sSelector | Indicates how the WebDriver should traverse through the HTML DOM to locate the desired element(s). Should point to <option> in element of type '<select>'
$sStartElement | [optional] Element ID of element to use as starting point

Return Value

Success: | None.
Failure: | None and sets @error to one of the following values: - $_WD_ERROR_Exception - $_WD_ERROR_NoMatch - $_WD_ERROR_InvalidDataType - $_WD_ERROR_InvalidExpression

Related

_WD_FindElement, _WD_ElementAction, _WD_LastHTTPResult


Function _WD_ElementSelectAction

Function Reference

_WD_ElementSelectAction

Perform action on designated <select> element.

_WD_ElementSelectAction($sSession, $sSelectElement, $sCommand[, $aParameters = Default])

Parameters

$sSession | Session ID from _WD_CreateSession
$sSelectElement | Element ID of <select> element from _WD_FindElement
$sCommand | Action to be performed. Can be one of the following: DESELECTALL - Clear all selections MULTISELECT - Select <option> elements given in 1D array of labels OPTIONS - Retrieves all <option> elements as 2D array containing 4 columns (value, label, index and selected status) SELECTALL - Select all <option> elements SELECTEDINDEX - Retrieves 0-based index of the first selected <option> element SELECTEDLABELS - Retrieves labels of selected <option> elements as 1D array SELECTEDOPTIONS- Retrieves selected <option> elements as 2D array containing 4 columns (value, label, index and selected status) VALUE - Retrieves value of the first selected <option> element
$aParameters | [optional] List of parameters (depending on chosen $sCommand)

Return Value

Success: | Requested data returned by web driver.
Failure: | "" (empty string) and sets @error to one of the following values: - $_WD_ERROR_NoMatch - $_WD_ERROR_Exception - $_WD_ERROR_InvalidDataType - $_WD_ERROR_InvalidExpression - $_WD_ERROR_InvalidArgue

Remarks

If no option is selected, SELECTEDINDEX will return -1

Related

_WD_FindElement, _WD_ExecuteScript


Function _WD_FindElement

Function Reference

_WD_FindElement

Find element(s) by designated strategy.

_WD_FindElement($sSession, $sStrategy, $sSelector[, $sStartNodeID = Default[, $bMultiple = Default[, $bShadowRoot = Default]]])

Parameters

$sSession | Session ID from _WD_CreateSession
$sStrategy | Locator strategy. See defined constant $_WD_LOCATOR_* for allowed values
$sSelector | Value to find
$sStartNodeID | [optional] Element ID to use as starting node. Default is ""
$bMultiple | [optional] Return multiple matching elements? Default is False
$bShadowRoot | [optional] Starting node is a shadow root? Default is False

Return Value

Success: | Element ID(s) returned by web driver.
Failure: | "" (empty string) and sets @error to one of the following values: - $_WD_ERROR_Exception - $_WD_ERROR_NoMatch - $_WD_ERROR_InvalidExpression

Remarks

An array of matching elements is returned when $bMultiple is True.

Related

_WD_LastHTTPResult


Function _WD_GetElementById

Function Reference

_WD_GetElementById

Locate element by id.

_WD_GetElementById($sSession, $sID)

Parameters

$sSession | Session ID from _WD_CreateSession
$sID | ID of desired element

Return Value

Success: | Element ID returned by web driver.
Failure: | "" (empty string) and sets @error to one of the following values: - $_WD_ERROR_Exception - $_WD_ERROR_NoMatch

Related

_WD_FindElement, _WD_LastHTTPResult


Function _WD_GetElementByName

Function Reference

_WD_GetElementByName

Locate element by name.

_WD_GetElementByName($sSession, $sName)

Parameters

$sSession | Session ID from _WD_CreateSession
$sName | Name of desired element

Return Value

Success: | Element ID returned by web driver
Failure: | "" (empty string) and sets @error to one of the following values: - $_WD_ERROR_Exception - $_WD_ERROR_NoMatch

Related

_WD_FindElement, _WD_LastHTTPResult


Function _WD_GetElementFromPoint

Function Reference

_WD_GetElementFromPoint

Retrieves reference to element at specified point.

_WD_GetElementFromPoint($sSession, $iX, $iY)

Parameters

$sSession | Session ID from _WD_CreateSession
$iX | an integer value
$iY | an integer value

Return Value

Success: | Element ID returned by web driver.
Failure: | "" (empty string) and @error is set to $_WD_ERROR_RetValue

Remarks

@extended is set to 1 if the browsing context changed during the function call

Related

_WD_ExecuteScript, _WD_LastHTTPResult


Function _WD_GetMouseElement

Function Reference

_WD_GetMouseElement

Retrieves reference to element below mouse pointer.

_WD_GetMouseElement($sSession)

Parameters

$sSession Session ID from _WD_CreateSession

Return Value

Success: | Element ID returned by web driver.
Failure: | Response from web driver and sets @error returned from _WD_ExecuteScript()

Related

_WD_ExecuteScript, _WD_LastHTTPResult


Function _WD_GetShadowRoot

Function Reference

_WD_GetShadowRoot

Retrieves the shadow root of an element.

_WD_GetShadowRoot($sSession, $sStrategy, $sSelector[, $sStartElement = Default])

Parameters

$sSession | Session ID from _WD_CreateSession
$sStrategy | Locator strategy. See defined constant $_WD_LOCATOR_* for allowed values
$sSelector | Indicates how the WebDriver should traverse through the HTML DOM to locate the desired element(s).
$sStartElement | [optional] a string value. Default is ""

Return Value

Success: | Element ID returned by web driver.
Failure: | "" (empty string) and sets @error to one of the following values: - $_WD_ERROR_Exception - $_WD_ERROR_NoMatch

Related

_WD_FindElement, _WD_ElementAction, _WD_LastHTTPResult


Function _WD_GetTable

Function Reference

_WD_GetTable

Return all elements of a table.

_WD_GetTable($sSession, $sBaseElement)

Parameters

$sSession | Session ID from _WD_CreateSession
$sBaseElement | XPath of the table to return

Return Value

Success: | 2D array.
Failure: | "" (empty string) and sets @error to one of the following values: - $_WD_ERROR_Exception - $_WD_ERROR_NoMatch

Related

_WD_FindElement, _WD_ElementAction, _WD_LastHTTPResult


Function _WD_HighlightElements

Function Reference

_WD_HighlightElements

Highlights the specified elements.

_WD_HighlightElements($sSession, $vElements[, $iMethod = Default])

Parameters

$sSession | Session ID from _WD_CreateSession
$vElements | Element ID from _WD_FindElement (single element as string; multiple elements as array)
$iMethod | [optional] an integer value to set the style (default = 1) 0 - Remove highlight 1 - Highlight border dotted red 2 - Highlight yellow rounded box 3 - Highlight yellow rounded box + border dotted red

Return Value

Success: | True
Failure: | False and sets @error to _WD_ERROR_InvalidArgue or the error code from _WD_ExecuteScript()

Related

_WD_LastHTTPResult


Function _WD_LinkClickByText

Function Reference

_WD_LinkClickByText

Simulate a mouse click on a link with text matching the provided string.

_WD_LinkClickByText($sSession, $sText[, $bPartial = Default])

Parameters

$sSession | Session ID from _WD_CreateSession
$sText | Text to find in link
$bPartial | [optional] Search by partial text? Default is True

Return Value

Success: | None.
Failure: | "" (empty string) and sets @error to one of the following values: - $_WD_ERROR_Exception - $_WD_ERROR_NoMatch

Related

_WD_FindElement, _WD_ElementAction, _WD_LastHTTPResult


Function _WD_SelectFiles

Function Reference

_WD_SelectFiles

Select files for uploading to a website.

_WD_SelectFiles($sSession, $sStrategy, $sSelector, $sFilename)

Parameters

$sSession | Session ID from _WD_CreateSession
$sStrategy | Locator strategy. See defined constant $_WD_LOCATOR_* for allowed values
$sSelector | Indicates how the WebDriver should traverse through the HTML DOM to locate the desired element(s). Should point to element of type '< input type="file" >'.
$sFilename | Full path of file(s) to upload (use newline character [@LF] to separate files)

Return Value

Success: | Number of selected files.
Failure: | "0" and sets @error to one of the following values: - $_WD_ERROR_Exception - $_WD_ERROR_NoMatch

Remarks

If $sFilename is empty, then prior selection is cleared.

Related

_WD_FindElement, _WD_ElementAction, _WD_LastHTTPResult


Function _WD_SetElementValue

Function Reference

_WD_SetElementValue

Set value of designated element.

_WD_SetElementValue($sSession, $sElement, $sValue[, $iStyle = Default])

Parameters

$sSession | Session ID from _WD_CreateSession
$sElement | Element ID from _WD_FindElement
$sValue | New value for element
$iStyle | [optional] Update style. Default is $_WD_OPTION_Standard $_WD_OPTION_Standard (0) = Set value using _WD_ElementAction $_WD_OPTION_Advanced (1) = Set value using _WD_ExecuteScript

Return Value

Success: | Requested data returned by web driver
Failure: | "" (empty string) and sets @error to one of the following values: - $_WD_ERROR_NoMatch - $_WD_ERROR_Exception - $_WD_ERROR_InvalidDataType - $_WD_ERROR_InvalidExpression

Related

_WD_ElementAction, _WD_LastHTTPResult


Function _WD_WaitElement

Function Reference

_WD_WaitElement

Wait for an element in the current tab before returning.

_WD_WaitElement($sSession, $sStrategy, $sSelector[, $iDelay = Default[, $iTimeout = Default[, $iOptions = Default]]])

Parameters

$sSession | Session ID from _WD_CreateSession
$sStrategy | Locator strategy. See defined constant $_WD_LOCATOR_* for allowed values
$sSelector | Indicates how the WebDriver should traverse through the HTML DOM to locate the desired element(s).
$iDelay | [optional] Milliseconds to wait before initially checking status
$iTimeout | [optional] Period of time (in milliseconds) to wait before exiting function
$iOptions | [optional] Binary flags to perform additional actions: $_WD_OPTION_None (0) = No optional feature processing $_WD_OPTION_Visible (1) = Confirm element is visible $_WD_OPTION_Enabled (2) = Confirm element is enabled $_WD_OPTION_NoMatch (8) = Confirm element not found

Return Value

Success: | Element ID returned by web driver.
Failure: | "" (empty string) and sets @error to one of the following values: - $_WD_ERROR_Timeout - $_WD_ERROR_InvalidArgue - $_WD_ERROR_UserAbort

Related

_WD_FindElement, _WD_ElementAction, _WD_LastHTTPResult


Function _WD_Window

Function Reference

_WD_Window

Perform interactions related to the current window.

_WD_Window($sSession, $sCommand[, $sOption = Default])

Parameters

$sSession | Session ID from _WD_CreateSession
$sCommand | One of the following actions: CLOSE - Close current tab FRAME - Switch to frame FULLSCREEN - Set window to fullscreen HANDLES - Get all window handles MAXIMIZE - Maximize window MINIMIZE - Minimize window NEW - Create a new window PARENT - Switch to parent frame PRINT - Generate PDF representation of the paginated document RECT - Get or set the window's size & position SCREENSHOT - Take screenshot of window SWITCH - Switch to designated tab WINDOW - Get or set the current window
$sOption | [optional] a string value. Default is ""

Return Value

Success: | Return value from web driver (could be an empty string).
Failure: | "" (empty string) and sets @error to one of the following values: - $_WD_ERROR_Exception - $_WD_ERROR_InvalidDataType

Related

_WD_LastHTTPResult


Function _WD_Attach

Function Reference

_WD_Attach

Attach to existing browser tab.

_WD_Attach($sSession, $sString[, $sMode = Default])

Parameters

$sSession | Session ID from _WD_CreateSession
$sString | String to search for
$sMode | [optional] One of the following search modes: Title (default) URL HTML

Return Value

Success: | String representing handle of matching tab.
Failure: | "" (empty string) and sets @error to one of the following values: - $_WD_ERROR_InvalidDataType - $_WD_ERROR_NoMatch - $_WD_ERROR_GeneralError

Related

_WD_Window, _WD_LastHTTPResult


Function _WD_NewTab

Function Reference

_WD_NewTab

Create new tab in current browser session.

_WD_NewTab($sSession[, $bSwitch = Default[, $iTimeout = Default[, $sURL = Default[, $sFeatures = Default]]]])

Parameters

$sSession | Session ID from _WD_CreateSession
$bSwitch | [optional] Switch session context to new tab? Default is True
$iTimeout | [optional] Period of time (in milliseconds) to wait before exiting function
$sURL | [optional] URL to be loaded in new tab
$sFeatures | [optional] Comma-separated list of requested features of the new tab

Return Value

Success: | String representing handle of new tab.
Failure: | "" (empty string) and sets @error to one of the following values: - $_WD_ERROR_Exception - $_WD_ERROR_Timeout

Remarks

Specifying any features other than noopener or noreferrer, also has the effect of requesting a popup.
See the link below for further details and a list of available features.

Related

_WD_Window, _WD_LastHTTPResult


Function _WD_PrintToPDF

Function Reference

_WD_PrintToPDF

Print the current tab in paginated PDF format.

_WD_PrintToPDF($sSession[, $sOptions = Default]])

Parameters

$sSession | Session ID from _WD_CreateSession
$sOptions | [optional] JSON string of formatting directives

Return Value

Success: | String containing PDF contents.
Failure: | "" (empty string) and sets @error to one of the following values: - $_WD_ERROR_Exception - $_WD_ERROR_InvalidDataType

Remarks

Chromedriver currently requires headless mode (https://bugs.chromium.org/p/chromedriver/issues/detail?id=3517).

Related

_WD_Window, _WD_LastHTTPResult


Function _WD_Screenshot

Function Reference

_WD_Screenshot

Takes a screenshot of the Window or Element.

_WD_Screenshot($sSession[, $sElement = Default[, $iOutputType = Default]])

Parameters

$sSession | Session ID from _WD_CreateSession
$sElement | [optional] Element ID from _WD_FindElement
$iOutputType | [optional] One of the following output types: 1 - String (Default) 2 - Binary 3 - Base64

Return Value

Success: | Output of specified type (PNG format).
Failure: | "" (empty string) and sets @error to one of the following values: - $_WD_ERROR_NoMatch - $_WD_ERROR_Exception - $_WD_ERROR_GeneralError - $_WD_ERROR_InvalidDataType - $_WD_ERROR_InvalidExpression

Related

_WD_Window, _WD_ElementAction, _WD_LastHTTPResult


Function _WD_IsFullScreen

Function Reference

_WD_IsFullScreen

Return a boolean indicating if the session is in full screen mode.

_WD_IsFullScreen($sSession)

Parameters

$sSession Session ID from _WD_CreateSession

Return Value

Success: | True or False.
Failure: | Response from webdriver and sets @error returned from _WD_ExecuteScript()

Related

_WD_LastHTTPResult


Function _WD_IsWindowTop

Function Reference

_WD_IsWindowTop

Returns a boolean of the session being at the top level, or in a frame(s).

_WD_IsWindowTop($sSession)

Parameters

$sSession Session ID from _WD_CreateSession

Return Value

Success: | Boolean response.
Failure: | Response from webdriver and sets @error returned from _WD_ExecuteScript()

Related

_WD_ExecuteScript, _WD_LastHTTPResult


Function _WD_FrameEnter

Function Reference

_WD_FrameEnter

Enter the specified frame.

_WD_FrameEnter($sSession, $vIdentifier)

Parameters

$sSession | Session ID from _WD_CreateSession
$vIdentifier | Index (as 0-based Integer) or Element ID (as String) or Null (Keyword)

Return Value

Success: | True.
Failure: | WD Response error message (E.g. "no such frame") and sets @error to $_WD_ERROR_Exception

Remarks

You can drill-down into nested frames by calling this function repeatedly with the correct parameters.

Related

_WD_Window, _WD_LastHTTPResult


Function _WD_FrameLeave

Function Reference

_WD_FrameLeave

Leave the current frame, to its parent.

_WD_FrameLeave($sSession)

Parameters

$sSession Session ID from _WD_CreateSession

Return Value

Success: | True.
Failure: | WD Response error message (E.g. "chrome not reachable") and sets @error to $_WD_ERROR_Exception

Remarks

ChromeDriver and GeckoDriver respond differently for a successful operation

Related

_WD_Window, _WD_LastHTTPResult


Function _WD_GetFrameCount

Function Reference

_WD_GetFrameCount

Returns the number of frames/iframes in the current document context.

_WD_GetFrameCount($sSession)

Parameters

$sSession Session ID from _WD_CreateSession

Return Value

Success: | Number of frames
Failure: | 0 and sets @error to $_WD_ERROR_Exception

Remarks

Nested frames are not included in the frame count

Related

_WD_ExecuteScript, _WD_LastHTTPResult


Function _WD_CDPExecuteCommand

Function Reference

_WD_CDPExecuteCommand

Execute CDP command.

_WD_CDPExecuteCommand($sSession, $sCommand, $oParams[, $sWebSocketURL = Default])

Parameters

$sSession | Session ID from _WD_CreateSession
$sCommand | Name of the command
$oParams | Parameters of the command as an object
$sWebSocketURL | [optional] Websocket URL

Return Value

Success: | Raw return value from web driver in JSON format.
Failure: | "" (empty string) and sets @error to $_WD_ERROR_Exception

Remarks

The original version of this function is specific to ChromeDriver, you can execute "Chrome DevTools Protocol"
commands by using this function, for all available commands see: https://chromedevtools.github.io/devtools-protocol/tot/

The revised version uses websockets to provide CDP access for all compatible browsers. However, it
will only with an OS that natively supports WebSockets (Windows 8, Windows Server 2012, or newer)

Related

_WD_LastHTTPResult


Function _WD_CDPGetSettings

Function Reference

_WD_CDPGetSettings

Retrieve CDP related settings from the browser.

_WD_CDPGetSettings($sSession, $sOption)

Parameters

$sSession | Session ID from _WD_CreateSession
$sOption | one of the following: DEBUGGER - Returns the Websocket target originally returned by _WD_CreateSession LIST - Lists websocket targets VERSION - Reurns an array containing version metadata

Return Value

Success: | The returned value depends on the selected $sOption. DEBUGGER: Websocket target originally returned by _WD_CreateSession LIST: Array containing websocket targets VERSION: Array containing version metadata
Failure: | "" (empty string) and sets @error to one of the following values: - $_WD_ERROR_Exception - $_WD_ERROR_GeneralError

Related

_WD_LastHTTPResult


Function _WD_UpdateDriver

Function Reference

_WD_UpdateDriver

Replace web driver with newer version, if available.

_WD_UpdateDriver($sBrowser[, $sInstallDir = Default[, $bFlag64 = Default[, $bForce = Default]]])

Parameters

$sBrowser | Browser name or full path to browser executable
$sInstallDir | [optional] Install directory. Default is @ScriptDir
$bFlag64 | [optional] Install 64bit version? Default is current driver architecture or False
$bForce | [optional] Force update? Default is False

Return Value

Success: | True (Driver was updated).
Failure: | False (Driver was not updated) and sets @error to one of the following values: - $_WD_ERROR_InvalidValue - $_WD_ERROR_GeneralError - $_WD_ERROR_NotFound - $_WD_ERROR_FileIssue - $_WD_ERROR_UserAbort - $_WD_ERROR_NotSupported

Remarks

When $bForce = Null, then the function will check for an updated webdriver without actually performing the update.
In this scenario, the return value indicates if an update is available.

Related

_WD_GetBrowserVersion, _WD_GetWebDriverVersion


Function _WD_ConsoleVisible

Function Reference

_WD_ConsoleVisible

Control visibility of the webdriver console app.

_WD_ConsoleVisible([$bVisible = Default])

Parameters

$bVisible [optional] Set to true to show the console. Default is False.

Return Value

Success: | None
Failure: | None


Function _WD_LastHTTPResult

Function Reference

_WD_LastHTTPResult

Return the result of the last WinHTTP request.

_WD_LastHTTPResult()

Parameters

None.

Return Value

Success: | Result of last WinHTTP request
Failure: | None.


Function _WD_LastHTTPResponse

Function Reference

_WD_LastHTTPResponse

Return the response of the last WinHTTP request.

_WD_LastHTTPResponse()

Parameters

None.

Return Value

Success: | Response of last WinHTTP request
Failure: | None.


Function _WD_GetBrowserVersion

Function Reference

_WD_GetBrowserVersion

Get version number of specified browser.

_WD_GetBrowserVersion($sBrowser)

Parameters

$sBrowser Browser name or full path to browser executable

Return Value

Success: | Version number ("#.#.#.#" format) returned by FileGetVersion for the browser exe
Failure: | "0" and sets @error to one of the following values: - $_WD_ERROR_FileIssue - $_WD_ERROR_NotSupported - $_WD_ERROR_NotFound

Related

_WD_GetBrowserPath, _WD_UpdateDriver


Function _WD_GetBrowserPath

Function Reference

_WD_GetBrowserPath

Retrieve path to browser executable from registry

_WD_GetBrowserPath($sBrowser)

Parameters

$sBrowser Name of browser

Return Value

Success: | Full path to browser executable and sets @extended to index of $_WD_SupportedBrowsers
Failure: | "" and sets @error to one of the following values: - $_WD_ERROR_InvalidValue - $_WD_ERROR_NotSupported - $_WD_ERROR_NotFound

Remarks

Browser names are defined in $_WD_SupportedBrowsers

Related

_WD_GetBrowserVersion, _WD_UpdateDriver


Function _WD_GetWebDriverVersion

Function Reference

_WD_GetWebDriverVersion

Get version number of specifed webdriver.

_WD_GetWebDriverVersion($sInstallDir, $sDriverEXE)

Parameters

$sInstallDir | a string value. Directory where $sDriverEXE is located
$sDriverEXE | a string value. File name of "WebDriver.exe"

Return Value

Success: | The value you get when you call WebDriver with the --version parameter
Failure: | "0" and sets @error to one of the following values: - $_WD_ERROR_NotFound - $_WD_ERROR_GeneralError

Related

_WD_UpdateDriver


Function _WD_IsLatestRelease

Function Reference

_WD_IsLatestRelease

Compares local UDF version to latest release on Github.

_WD_IsLatestRelease()

Parameters

None.

Return Value

Success: | True if the local UDF version is the latest, otherwise False
Failure: | Null and sets @error to one of the following values: - $_WD_ERROR_Exception - $_WD_ERROR_GeneralError


Function _WD_GetDevicePixelRatio

Function Reference

_WD_GetDevicePixelRatio

Returns an integer indicating the DevicePixelRatio

_WD_GetDevicePixelRatio($sSession)

Parameters

$sSession Session ID from _WD_CreateSession

Return Value

Success: | DevicePixelRatio
Failure: | Response from webdriver and sets @error returned from _WD_ExecuteScript()

Related

_WD_LastHTTPResult


Function _WD_JsonActionKey

Function Reference

_WD_JsonActionKey

Formats keyboard "action" strings for use in _WD_Action

_WD_JsonActionKey($sType, $sKey[, $iSuffix = 1])

Parameters

$sType | Type of action (Ex: keyDown, keyUp)
$sKey | Keystroke to simulate
$iSuffix | [optional] Value to append to the "id" property. Default is 1.

Return Value

Success: | Requested JSON string
Failure: | None.

Related

_WD_Action


Function _WD_JsonActionPause

Function Reference

_WD_JsonActionPause

Formats pause "action" strings for use in _WD_Action

_WD_JsonActionPause($iDuration)

Parameters

$iDuration length of time to pause in ticks

Return Value

Success: | Requested JSON string
Failure: | None.

Related

_WD_Action


Function _WD_JsonActionPointer

Function Reference

_WD_JsonActionPointer

Formats pointer "action" strings for use in _WD_Action

_WD_JsonActionPointer($sType[, $iButton = Default[, $sOrigin = Default[, $iXOffset = Default[, $iYOffset = Default[, $iDuration = Default]]]]])

Parameters

$sType | Type of action (Ex: pointerDown, pointerUp, pointerMove)
$iButton | [optional] Mouse button to simulate. Default is $_WD_BUTTON_Left.
$sOrigin | [optional] Starting location. ('pointer', 'viewport', or Element ID). Default is 'viewport'.
$iXOffset | [optional] X offset. Default is 0.
$iYOffset | [optional] Y offset. Default is 0.
$iDuration | [optional] Duration in ticks. Default is 100.

Return Value

Success: | Requested JSON string
Failure: | None.

Related

_WD_Action


WebDriver UDF

Additional Resources

Webdriver Wiki

Discussion Threads on Autoit Forums

  • WebDriver UDF Help & Support part 1
  • WebDriver UDF Help & Support part 2
  • WebDriver UDF Help & Support part 3


Function _WD_HighlightElement

Function Reference

_WD_HighlightElement

Highlights the specified element. [Deprecated]

_WD_HighlightElement($sSession, $sElement[, $iMethod = Default])

Parameters

$sSession | Session ID from _WD_CreateSession
$sElement | Element ID from _WD_FindElement
$iMethod | [optional] an integer value to set the style (default = 1) 0 - Remove highlight 1 - Highlight border dotted red 2 - Highlight yellow rounded box 3 - Highlight yellow rounded box + border dotted red

Return Value

Success: | True.
Failure: | False and sets @error returned from _WD_ExecuteScript()

Remarks

This function will be removed in a future release. Update your code to use _WD_HighlightElements instead.

Related

_WD_HighlightElements, _WD_LastHTTPResult


Function _WD_JsonCookie

Function Reference

_WD_JsonCookie

Formats "cookie" strings for use in _WD_Cookies

_WD_JsonCookie($sName, $sValue[, $sPath = Default[, $sDomain = Default[, $bSecure = Default [, $bHTTPOnly = Default[, $iExpiryTime = Default[, $sSameSite = Default]]]]]])

Parameters

$sName | The name of the cookie.
$sValue | The cookie value.
$sPath | [optional] This defines the cookie path.
$sDomain | [optional] This defines the domain the cookie is visible to.
$bSecure | [optional] This defines whether the cookie is a secure cookie.
$bHTTPOnly | [optional] This defines whether the cookie is an HTTP only cookie.
$iExpiryTime | [optional] This defines when the cookie expires, specified in seconds since Unix Epoch.
$sSameSite | [optional] This defines whether the cookie applies to a SameSite policy. One of the following modes can be used: None Lax Strict

Return Value

Success: | Cookie as formatted JSON strings
Failure: | None.

Related

_WD_Cookies