AutoIt Wiki - User contributions [en]

WebDriver

2022-10-10T11:38:14Z

Danp2: /* Translate IE UDF to WebDriver */

The W3C WebDriver API is a platform and language-neutral interface and wire protocol allowing programs or scripts to control the behavior of a web browser.

== Introduction ==

=== WebDriver API ===
WebDriver enables developers to create automated tests that simulate user interaction. This is different from JavaScript unit tests because WebDriver has access to functionality and information that JavaScript running in the browser doesn't, and it can more accurately simulate user events or OS-level events. WebDriver can also manage testing across multiple windows, tabs and webpages in a single test session.

=== WebDriver UDF ===
The WebDriver UDF allows 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 ===
<small>(Last modified: 2022/01/25)<br></small>

The following UDFs need to be installed - '''independent''' of the Browser you try to automate:
* [https://www.autoitscript.com/forum/topic/148114-a-non-strict-json-udf-jsmn JSON UDF (AutoIt)] by Ward and Jos
* [https://www.autoitscript.com/forum/topic/84133-winhttp-functions/ WinHTTP UDF (AutoIt)] by trancexx or [https://github.com/dragana-r/autoit-winhttp autoit-winhttp (GitHub)]
* [https://github.com/Danp2/au3WebDriver/releases/latest WebDriver UDF (GitHub)] by Danp2
One of the following Drivers needs to be installed - '''depending''' on the Browser type and version you try to automate:
{| class="wikitable"
|-
! Browser !! Download Link !! Comments
|-
| Chrome || [https://sites.google.com/chromium.org/driver/downloads Google] || Follow this [https://sites.google.com/a/chromium.org/chromedriver/downloads/version-selection link] to select the correct version depending on the Chrome version you run!
|-
| Edge || [https://developer.microsoft.com/en-us/microsoft-edge/tools/webdriver/ Microsoft] ||
|-
| Firefox || [https://github.com/mozilla/geckodriver/releases/latest GitHub] || Firefox version ≥ 60 is recommended<br>
'''Note:''' You must still have the Microsoft Visual Studio redistributable runtime installed on your system for the binary to run. This is a known bug in version 0.26 which the authors weren't able fix for this release.
|-
| Opera || [https://github.com/operasoftware/operachromiumdriver/releases/latest GitHub] || The versioning of OperaDriver matches the Chromium version on which Opera browser is based on.
|}

=== Limitations ===
<small>(Last modified: 2020/01/28)<br></small>
Not all WebDriver functions have been implemented by each browser. To check the status goto the corresponding website below:

* [https://chromium.googlesource.com/chromium/src/+/master/docs/chromedriver_status.md Chrome]
* [https://docs.microsoft.com/en-us/microsoft-edge/webdriver#w3c-webdriver-specification-supporthttpsw3cgithubiowebdriverwebdriver-spechtml Edge]
* [https://developer.mozilla.org/en-US/docs/Mozilla/QA/Marionette/WebDriver/status Firefox]
* [https://github.com/operasoftware/operachromiumdriver Opera]: "''OperaChromiumDriver is a WebDriver implementation derived from ChromeDriver and adapted by Opera''". That's why I think it has at least the same limitations as ChromeDriver.

=== Big Picture ===
How the browser independent and browser dependent parts fit together:<br>

[[File:WebDriver.png|800px|||Big Picture - How everything fits together]]

=== Technical terms ===
<small>(Last modified: 2022/02/12)<br></small>

You will encounter the following technical terms when working with the WebDriver UDF.<br>
These terms are not unique to the UDF, so you will find just the general description in this section.
How to use these terms with the WebDriver UDF can be found in the FAQ.<br><br>

; CDP (Chrome DevTools Protocol) : Is a [https://chromedevtools.github.io/devtools-protocol/ protocol] that allows for tools to instrument, inspect, debug and profile Chromium, Chrome and other [https://en.wikipedia.org/wiki/Blink_(browser_engine) Blink]-based browsers.

; CSS Selector : Please see '''Selector'''.

; Locator Strategy : A Locator strategy describes the method to use to search elements. This includes Linktext, Partial Linktext, Tag Name, CSS selector, XPath selector.

; Marionette : Marionette is an automation driver for Mozilla’s Gecko engine. It can remotely control either the UI or the internal JavaScript of a Gecko platform, such as Firefox. It can control both the chrome (i.e. menus and functions) or the content (the webpage loaded inside the browsing context), giving a high level of control and ability to replicate user actions. In addition to performing actions on the browser, Marionette can also read the properties and attributes of the DOM.<br>Marionette consists of two parts: a server which takes requests and executes them in Gecko (the Marionette server ships with Firefox), and a client (the Marionette client ships with the GeckoDriver exe). The client sends commands to the server and the server executes the command inside the browser.<br>For details please [https://firefox-source-docs.mozilla.org/testing/marionette/Intro.html visit this site].

; Selector : Selectors are patterns used to select the element(s) you want to process. They are used by <br>CSS (see [https://www.w3schools.com/css/css_selectors.asp this link for Beginners] or [https://www.w3.org/TR/CSS21/selector.html this link for Advanced)] and<br>[https://www.w3schools.com/xml/xpath_syntax.asp XPath] (see [https://www.w3schools.com/xml/xml_xpath.asp this link for Beginners] and [https://www.w3.org/TR/1999/REC-xpath-19991116/ this link for Advanced]).

; ShadowRoot : The ShadowRoot interface of the Shadow DOM API is the root node of a DOM sub tree that is rendered separately from a document's main DOM tree.<br>For details please [https://dom.spec.whatwg.org/#interface-shadowroot visit this site].

; XPath : XPath is a language for navigating in XML documents. XPath is a major element in the XSLT standard and includes over 200 built-in functions.

; XQuery : XQuery is a language for querying XML documents.<br>For details please [https://www.w3schools.com/xml/xml_xquery.asp visit this site].

; XSLT : XSLT is a language for transforming XML documents.<br>For details please [https://www.w3schools.com/xml/xml_xslt.asp visit this site].

== Installation ==
<small>(Last modified: 2022/02/02)<br></small>

To automate your browser the following installation steps are needed:
* Download the files listed in section "[[WebDriver#Requirements|Requirements]]"
* Move the UDFs to a directory where SciTE and Autoit can find them:
** wd_Core.au3, wd_helper.au3 , wd_cdp.au3 , wd_capabilities.au3 from the WebDriver UDF
** Json.au3 and BinaryCall.au3 from the JSON UDF
** WinHttp.au3 and WinHttpConstants.au3 from the WinHttp UDF
* Move the browser dependent WebDriver to the same directory (with WD_Demo.au3):
** chromedriver.exe (Chrome)
** geckodriver.exe (Firefox)
** msedgedriver.exe (Edge - Chromium) or MicrosoftWebDriver.exe (Edge - EdgeHTML)
** or use "Update" option by choosing one of ComboBox option in WD_Demo.au3
* Run WD_Demo.au3 and select "DemoNavigation" to validate the installation.<br>The result (for Firefox) displayed in the DOS window should be similar to the following:
<syntaxhighlight lang="text">
1577745813519 geckodriver DEBUG Listening on 127.0.0.1:4444
1577745813744 webdriver::server DEBUG -> POST /session {"capabilities": {"alwaysMatch": {"browserName": "firefox", "acceptInsecureCerts":true}}}
1577745813746 geckodriver::capabilities DEBUG Trying to read firefox version from ini files
1577745813747 geckodriver::capabilities DEBUG Found version 71.0
1577745813757 mozrunner::runner INFO Running command: "C:\\Program Files\\Mozilla Firefox\\firefox.exe" "-marionette" "-foreground" "-no-remote" "-profile" "C:\\ ...
1577745813783 geckodriver::marionette DEBUG Waiting 60s to connect to browser on 127.0.0.1:55184
1577745817392 geckodriver::marionette DEBUG Connection to Marionette established on 127.0.0.1:55184.
1577745817464 webdriver::server DEBUG <- 200 OK {"value":{"sessionId":"925641bf-6c5d-4fe2-a985-02de9b1c7c74","capabilities":"acceptInsecureCerts":true,"browserName":"firefox", ...
</syntaxhighlight>

== Function reference ==
<small>(Last modified: 2021/12/09)<br></small>

The functions are now documented in the CHM help file that comes with the UDF.

== Capabilities ==
WebDriver capabilities are used to communicate the features supported by a given implementation. The local end may use capabilities to define which features it requires the remote end to satisfy when creating a new session. Likewise, the remote end uses capabilities to describe the full feature set for a session. <br>
Details can be found at [[WebDriver_Capabilities|WebDriver Capabilities (sub page)]].

== Browser related functionality ==
=== Google Chrome ===
ChromeDriver supports "Chrome DevTools Protocol" (CDP) commands (for an explanation of the term and related links please see the [[WebDriver#Used_Terms|Used Terms]] section).<br>
Details can be found in the CHM Help file that comes with the UDF.

=== Translate IE UDF to WebDriver ===
{{WIP}}
Internet Explorer is no longer supported by Microsoft. Therefore, it may be necessary to rewrite existing scripts for other browsers using the WebDriver UDF.
Below you will find a mapping of the functions of the IE UDF to the functions of the WebDriver UDF.
{| class="wikitable"
|-
! IE function !! WebDriver function !! Comments
|-
| _IEAction || _WD_ElementAction + _WD_ElementActionEx ||
|-
| _IEAttach || _WD_Attach ||
_WD_Attach: '''Attach to''' existing browser '''tab'''.

Attaching to running browser instance/session is much more difficult. [https://www.autoitscript.com/forum/topic/201537-webdriver-example-scripts-collection/?tab=comments#comment-1498168 Examples can be found here].
|-
| _IEBodyReadHTML || _WD_GetSource ||
|-
| _IEBodyReadText || _WD_ExecuteScript($sSession, 'return document.body.innerText',Default,Default, $_WD_JSON_Value) ||
|-
| _IEBodyWriteHTML || _WD_ExecuteScript($s_Session, "document.body.outerHTML='" & $sHTML & "'") ||
|-
| _IECreate || _WD_CreateSession ||
|-
| _IECreateEmbedded || N/A ||
|-
| _IEDocGetObj || ||
|-
| _IEDocInsertHTML || ||
|-
| _IEDocInsertText || ||
|- || ||
|-
| _IEDocReadHTML || _WD_GetSource ||
|-
| _IEDocWriteHTML || _WD_ExecuteScript($s_Session, "document.open();document.write(" & $sHTML & ");document.close();") || https://stackoverflow.com/a/11984907/5314940
|-
| _IEErrorNotify || N/A || you can set debug level for example: $_WD_DEBUG = $_WD_DEBUG_Full
|-
| _IEFormElementCheckBoxSelect || _WD_ElementActionEx || _WD_FindElement + _WD_ElementActionEx($sSession, $sElement, "check")
|-
| _IEFormElementGetCollection || _WD_FindElement ||
|-
| _IEFormElementGetObjByName || _WD_GetElementByName ||
|-
| _IEFormElementGetValue || _WD_ElementAction || _WD_FindElement + _WD_ElementAction($sSession, $sSelectElement, "value")
|-
| _IEFormElementOptionSelect || _WD_ElementSelectAction + _WD_ElementOptionSelect ||
|-
| _IEFormElementRadioSelect || _WD_ElementSelectAction ||
|-
| _IEFormElementSetValue || _WD_SetElementValue ||
|-
| _IEFormGetCollection || _WD_FindElement ||
|-
| _IEFormGetObjByName || _WD_GetElementByName ||
|-
| _IEFormImageClick || _WD_ElementAction || _WD_FindElement + _WD_ElementAction($sSession, $sElement, "click")
|-
| _IEFormReset || ||
|-
| _IEFormSubmit || ||
|-
| _IEFrameGetCollection || _WD_FrameList || _WD_FrameList($sSession, True)
|-
| _IEFrameGetObjByName || _WD_GetElementByName + _WD_FrameEnter ||
|-
| _IEGetObjById || _WD_GetElementById ||
|-
| _IEGetObjByName || _WD_GetElementByName ||
|-
| _IEHeadInsertEventScript || ||
|-
| _IEImgClick || _WD_ElementAction || _WD_FindElement + _WD_ElementAction($sSession, $sElement, "click")
|-
| _IEImgGetCollection || _WD_FindElement ||
|-
| _IEIsFrameSet || ||
|-
| _IELinkClickByIndex || _WD_ElementAction || _WD_FindElement + _WD_ElementAction($sSession, $sElement, "click")
|-
| _IELinkClickByText || _WD_LinkClickByText ||
|-
| _IELinkGetCollection || _WD_FindElement ||
|-
| _IELoadWait || _WD_LoadWait ||
|-
| _IELoadWaitTimeout || _WD_SetTimeouts ||
|-
| _IENavigate || _WD_Navigate ||
|-
| _IEPropertyGet || _WD_ElementAction || _WD_FindElement + _WD_ElementAction($sSession, $sElement, 'property', 'nodeName')
|-
| _IEPropertySet || _WD_ExecuteScript || _WD_FindElement + ......
|-
| _IEQuit || _WD_DeleteSession ||
|-
| _IETableGetCollection || _WD_FindElement ||
|-
| _IETableWriteToArray || _WD_GetTable || _WD_FindElement + _WD_GetTable( ......
|-
| _IETagNameAllGetCollection || _WD_FindElement ||
|-
| _IETagNameGetCollection || _WD_FindElement ||
|-
| _IE_Example || N/A || Take a look at wd_demo.au3 script
|-
| _IE_Introduction || N/A || Take a look at wd_demo.au3 script
|-
| _IE_VersionInfo || _WD_Option('version') ||
|}

== Troubleshooting ==
=== Debug the WebDriver setup ===
<small>(Last modified: 2020/07/06)<br></small>
==== WinHTTP UDF ====
Make sure that you are running at least version 1.6.4.2 (currently unreleased, but can be obtained [https://raw.githubusercontent.com/dragana-r/autoit-winhttp/master/WinHttp.au3 here]).
==== Chrome ====
<div class="usermessage mw-customtoggle-DebugChrome1">Chrome does not start and the DOS window for chromedriver does not get displayed</div>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-DebugChrome1">
{| class="wikitable"
|-
! Problem !! Solution !! Reference
|-
| When running WD_Demo.au3 it does not start up Chrome and does not display the DOS window for chromedriver.<br>When you manually run the chromedriver in a DOS window you get message "[0.023][SEVERE]: CreatePlatformSocket() returned an error: An invalid argument was supplied."|| This could be caused by missing execution permission for the network drive. Please ask your IT admin for "Applocker" or "application directory whitelisting". <br>Or run the chrome driver from a local HDD and call _WD_Option to set the location of the webdriver executable. Example: _WD_Option("Driver", "C:\Local\WebDriver\chromedriver.exe") || [https://stackoverflow.com/questions/51056121/createplatformsocket-returned-an-error-an-invalid-argument-was-supplied-0x2 Stackoverflow]
|}
</div>

==== Firefox ====
<div class="usermessage mw-customtoggle-DebugFirefox1">Firefox does not start and the DOS window for geckodriver does not get displayed</div>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-DebugFirefox1">
{| class="wikitable"
|-
! Problem !! Solution !! Reference
|-
| When running WD_Demo.au3 it does not start up Firefox and does not display the DOS window for geckodriver.<br>When you manually run the geckodriver in a DOS window you get message "geckodriver: error: An invalid argument was supplied. (os error 10022)"|| This could be caused by missing execution permission for the network drive. Please ask your IT admin for "Applocker" or "application directory whitelisting". <br>Or run the gecko driver from a local HDD and call _WD_Option to set the location of the webdriver executable. Example: _WD_Option("Driver", "C:\Local\WebDriver\geckodriver.exe") || [https://stackoverflow.com/questions/51056121/createplatformsocket-returned-an-error-an-invalid-argument-was-supplied-0x2 Stackoverflow]
|}
</div>

=== Debug your Script ===

== FAQ ==
<small>(Last modified: 2022/03/24)<br></small>

<div class="usermessage mw-customtoggle-FAQ1">1. How to connect to a running browser instance</div>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-FAQ1">
<div class="toccolours mw-collapsible-content">Q: How can I connect to a running browser instance?<br>A: That's described (for Firefox, but should work similar for other browsers) in [https://www.autoitscript.com/forum/topic/201537-webdriver-example-scripts-collection/?do=findComment&comment=1498168 this post].</div>
</div>

<div class="usermessage mw-customtoggle-FAQ2">2. How to hide the webdriver console</div>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-FAQ2">
<div class="toccolours mw-collapsible-content">Q: How can I hide the webdriver console?<br>A: The console can be completely hidden from the start by adding the following line near the beginning of your script:<br><syntaxhighlight lang="autoit">$_WD_DEBUG = $_WD_DEBUG_None ; You could also use $_WD_DEBUG_Error</syntaxhighlight>You can also control the visibility of the console with the function _WD_ConsoleVisible.</div>
</div>

<div class="usermessage mw-customtoggle-FAQ3">3. How to utilize an existing user profile</div>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-FAQ3">
<div class="toccolours mw-collapsible-content">Q: Can I use an existing user profile instead of the default behavior of using a new one?<br>A: This is controlled by your "capabilities" declaration, with each browser using a different method to implement. Here are some examples:<br>
<br>'''Chrome'''<syntaxhighlight lang="autoit">$sDesiredCapabilities = '{"capabilities": {"alwaysMatch": {"goog:chromeOptions": {"w3c": true, "args":["--user-data-dir=C:\\Users\\' & @UserName & '\\AppData\\Local\\Google\\Chrome\\User Data\\", "--profile-directory=Default"]}}}}'</syntaxhighlight>'''MS Edge'''<syntaxhighlight lang="autoit">$sDesiredCapabilities = '{"capabilities": {"alwaysMatch": {"ms:edgeOptions": {"args": ["user-data-dir=C:\\Users\\' & @UserName & '\\AppData\\Local\\Microsoft\\Edge\\User Data\\", "profile-directory=Default"]}}}}'</syntaxhighlight>'''Firefox'''<syntaxhighlight lang="autoit">
$sDesiredCapabilities = '{"capabilities":{"alwaysMatch": {"moz:firefoxOptions": {"args": ["-profile", "' & GetDefaultFFProfile() & '"],"log": {"level": "trace"}}}}}'

Func GetDefaultFFProfile()
Local $sDefault, $sProfilePath = ''

Local $sProfilesPath = StringReplace(@AppDataDir, '\', '/') & "/Mozilla/Firefox/"
Local $sFilename = $sProfilesPath & "profiles.ini"
Local $aSections = IniReadSectionNames ($sFilename)

If Not @error Then
For $i = 1 To $aSections[0]
$sDefault = IniRead($sFilename, $aSections[$i], 'Default', '0')

If $sDefault = '1' Then
$sProfilePath = $sProfilesPath & IniRead($sFilename, $aSections[$i], "Path", "")
ExitLoop
EndIf
Next
EndIf

Return $sProfilePath
EndFunc
</syntaxhighlight>You will also likely need to specify the marionette port:
<syntaxhighlight lang="autoit">_WD_Option('DriverParams', '--marionette-port 2828')</syntaxhighlight></div>
</div>

<div class="usermessage mw-customtoggle-FAQ4">4. How to specify location of browser executable</div>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-FAQ4">
<div class="toccolours mw-collapsible-content">Q: Is it possible to launch a browser installed in a non-standard location?<br>A: This is controlled by your "capabilities" declaration. Here are some examples:<br>
<br>'''Chrome'''<syntaxhighlight lang="autoit">$sDesiredCapabilities = '{"capabilities": {"alwaysMatch": {"goog:chromeOptions": {"w3c": true, "binary":"C:\\Path\\To\\Alternate\\Browser\\chrome.exe" }}}}'
</syntaxhighlight>'''Firefox'''<syntaxhighlight lang="autoit">$sDesiredCapabilities = '{"desiredCapabilities":{"javascriptEnabled":true,"nativeEvents":true,"acceptInsecureCerts":true,"moz:firefoxOptions":{"binary":"C:\\Path\\To\\Alternate\\Browser\\firefox.exe"}}}'</syntaxhighlight>Alternate Firefox method:<br><syntaxhighlight lang="autoit">
_WD_Option('DriverParams', '--binary "C:\Program Files\Mozilla Firefox\firefox.exe" --log trace ')</syntaxhighlight>
</div>
</div>

<div class="usermessage mw-customtoggle-FAQ5">5. How to maximize the browser window</div>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-FAQ5">
<div class="toccolours mw-collapsible-content">Q: Is it possible to maximize the browser window?<br>A: Simply call the following function:<syntaxhighlight lang="autoit">_WD_Window($sSession, "Maximize")
</syntaxhighlight>Make sure to call _WD_Window after the session has been created with _WD_CreateSession.</div></div>

<div class="usermessage mw-customtoggle-FAQ6">6. How to specify location of WebDriver executable</div>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-FAQ6">
<div class="toccolours mw-collapsible-content">Q: Is it possible to launch the WebDriver executable from a specific location?<br>A: This is controlled by function "_WD_Option". Example:
<br><syntaxhighlight lang="autoit">_WD_Option("Driver", "C:\local\WebDriver\WebDriver.exe")</syntaxhighlight>
</div>
</div>

<div class="usermessage mw-customtoggle-FAQ7">7. How to retrieve the values of a drop-down list</div>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-FAQ7">
<div class="toccolours mw-collapsible-content">Q: How to retrieve the values of a drop-down list (<Select> tag)?<br>A1: Here's a simple way to do it:
<br><syntaxhighlight lang="autoit">$sElement = _WD_FindElement($sSession, $_WD_LOCATOR_ByXPath, "//select[@name='xxx']")
$sText = _WD_ElementAction($sSession, $sElement, 'property', 'innerText')
$aOptions = StringSplit ( $sText, @LF, $STR_NOCOUNT)
_ArrayDisplay($aOptions)</syntaxhighlight>
'xxx' is the name of the drop-down list.
<br>A2: This can now be accomplished using the function _WD_ElementSelectAction:<br><syntaxhighlight lang="autoit">$sElement = _WD_FindElement($sSession, $_WD_LOCATOR_ByXPath, "//select[@name='xxx']")
$aOptions = _WD_ElementSelectAction ($sSession, $sElement, 'options')
_ArrayDisplay($aOptions)</syntaxhighlight>
</div>
</div>

<div class="usermessage mw-customtoggle-FAQ8">8. How to run the browser in headless mode (hidden mode)</div>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-FAQ8">
<div class="toccolours mw-collapsible-content">Q: How do I run the browser in "headless" mode?<br>A: This is controlled by the Capabilities string that is passed to _WD_CreateSession. Example:
<br><syntaxhighlight lang="autoit">$sDesiredCapabilities = '{"capabilities": {"alwaysMatch": {"goog:chromeOptions": {"w3c": true, "args": ["--headless", "--allow-running-insecure-content"] }}}}' </syntaxhighlight>
</div>
</div>

<div class="usermessage mw-customtoggle-FAQ9">9. How to configure the UDF to call a user-defined Sleep function</div>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-FAQ9">
<div class="toccolours mw-collapsible-content">
Q: How to configure the UDF to call a user-defined Sleep function, and interact with _WD_WaitElement() and _WD_LoadWait() to make the script more responsive?
<br>
A: Try to use: _WD_Option("Sleep") . Example:
<br>
<syntaxhighlight lang="autoit">
#include <ButtonConstants.au3>
#include <GuiComboBoxEx.au3>
#include <GUIConstantsEx.au3>
#include <MsgBoxConstants.au3>
#include <WindowsConstants.au3>
#include "wd_helper.au3"

Global $idAbortTest
Global $WD_SESSION
_Example()

Func _Example()
SetupChrome()

; Create a GUI with various controls.
Local $hGUI = GUICreate("Example")
Local $idTest = GUICtrlCreateButton("Test", 10, 370, 85, 25)
$idAbortTest = GUICtrlCreateButton("Abort", 150, 370, 85, 25)

; Display the GUI.
GUISetState(@SW_SHOW, $hGUI)

ConsoleWrite("- TESTING" & @CRLF)

Local $sFilePath = _WriteTestHtml()

; Loop until the user exits.
While 1
Switch GUIGetMsg()
Case $idTest
_WD_Navigate($WD_SESSION, $sFilePath)
_WD_WaitElement($WD_SESSION, $_WD_LOCATOR_ByXPath, '//a[contains(text(),"TEST")]', 100, 30 * 1000) ; timeout = 50 seconds
ConsoleWrite("---> @error=" & @error & " @extended=" & @extended & _
" : after _WD_WaitElement()" & @CRLF)

Case $GUI_EVENT_CLOSE
ExitLoop

EndSwitch
WEnd

; Delete the previous GUI and all controls.
GUIDelete($hGUI)

EndFunc ;==>_Example

Func _My_Sleep($iDelay)
Local $hTimer = TimerInit() ; Begin the timer and store the handle in a variable.
Do
Switch GUIGetMsg()
Case $GUI_EVENT_CLOSE
ConsoleWrite("! USER EXIT" & @CRLF)
Exit
Case $idAbortTest
Return SetError($_WD_ERROR_UserAbort)
EndSwitch
Until TimerDiff($hTimer) > $iDelay
EndFunc ;==>_My_Sleep

Func _WriteTestHtml($sFilePath = @ScriptDir & "\TestFile.html")
FileDelete($sFilePath)
Local Const $sHtml = _
"<html lang='en'>" & @CRLF & _
" <head>" & @CRLF & _
" <meta charset='utf-8'>" & @CRLF & _
" <title>TESTING</title>" & @CRLF & _
" </head>" & @CRLF & _
" <body>" & @CRLF & _
" <div id='MyLink'>Waiting</div>" & @CRLF & _
" </body>" & @CRLF & _
" <script type='text/javascript'>" & @CRLF & _
" setTimeout(function()" & @CRLF & _
" {" & @CRLF & _
" // Delayed code in here" & @CRLF & _
" document.getElementById('MyLink').innerHTML='<a>TESTING</a>';" & @CRLF & _
" }, 20000); // 20000 = 20 seconds" & @CRLF & _
" </script>" & @CRLF & _
"</html>"
FileWrite($sFilePath, $sHtml)
Return "file:///" & StringReplace($sFilePath, "\", "/")
EndFunc ;==>_WriteTestHtml

Func SetupChrome()
_WD_Startup()
_WD_Option('Driver', 'chromedriver.exe')
_WD_Option('Port', 9515)
_WD_Option('HTTPTimeouts', True)
_WD_Option('DefaultTimeout', 40001)
_WD_Option('DriverParams', '--verbose --log-path="' & @ScriptDir & '\chrome.log"')
_WD_Option("Sleep", _My_Sleep)

Local $sCapabilities = '{"capabilities": {"alwaysMatch": {"goog:chromeOptions": {"w3c": true, "excludeSwitches": [ "enable-automation"]}}}}'
$WD_SESSION = _WD_CreateSession($sCapabilities)
_WD_Timeouts($WD_SESSION, 40002)
EndFunc ;==>SetupChrome
</syntaxhighlight>
</div>
</div>

<div class="usermessage mw-customtoggle-FAQ10">10. How to keep my WebDriver environment up-to-date</div>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-FAQ10">
<div class="toccolours mw-collapsible-content">
Q: How can I keep my WebDriver environment up-to-date?<br>
A: You have to check the following components:<p>
<b>WebDriver UDF:</b> Function _WD_IsLatestRelease compares local UDF version to latest release on Github. Returns True if the local UDF version is the latest, otherwise False. If you need to update the UDF you have to download it manually.<br>
<b>WebDriver Exe:</b> Function _WD_UpdateDriver checks or updates the Web Driver with newer version, if available.<br>
<b>Browser:</b> Function _WD_GetBrowserVersion returns the version number of the specified browser. If you need to update the Browser you have to download and install it by hand.<br>
</div>
</div>

<div class="usermessage mw-customtoggle-FAQ11">11. How to use "Locator strategy" and "Selectors"?</div>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-FAQ11">
<div class="toccolours mw-collapsible-content">
Q: How to use "Locator strategies" and how to find "Selectors"?<br>
A: This UDF supports all locators defined in the Webdriver specifications. Below is a listing of predefined constants:<br>
{| class="wikitable"
|-
! Locator strategy !! Description how to use "Selector"
|-
| $_WD_LOCATOR_ByCSSSelector || CSS Selector string (see this [https://www.w3schools.com/css/css_selectors.asp site]). In CSS, pattern matching rules determine which style rules apply to elements in the HTML DOM document tree.
|-
| $_WD_LOCATOR_ByXPath || XPath string (see this [https://www.w3schools.com/xml/xml_xpath.asp site]). XPath is a language for addressing parts of an XML document.
|-
| $_WD_LOCATOR_ByLinkText || String with exact text of <a> element, which should be used to locate the proper <a> element.
|-
| $_WD_LOCATOR_ByPartialLinkText || String with partial text of <a> element, which should be used to locate the proper <a> element.
|-
| $_WD_LOCATOR_ByTagName || String that matches the desired element tag name, for example "button" is tag name of this element: <button name="ClickMe">
|}
<br>
Q: How can I check XPath and CSSSelector in the Browser?<br>
A: '''Work in progress....'''<br>
A: Take a look on this link: [https://developer.chrome.com/docs/devtools/dom/ Get Started With Viewing And Changing The DOM]<br>
A: Take a look on this link: [https://www.selenium.dev/documentation/webdriver/elements/locators/ Locator strategies]<br>
A: Take a look on this link: [https://testerlive.wordpress.com/2016/07/02/how-to-search-by-xpathcss-in-chrome-developer-tools/ How to search by Xpath/Css in Chrome Developer Tools?]<br>

</div>
</div>

<div class="usermessage mw-customtoggle-FAQ12">12. How to download PDF file automatically?</div>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-FAQ12">
<div class="toccolours mw-collapsible-content">
Q: How to avoid browsers asking what to do with a file after clicking the "Download" button on a website?<br>
A: In FireFox you should add additional capabilites settings:
<syntaxhighlight lang="autoit">
_WD_CapabilitiesAdd("prefs", "pdfjs.disabled", True)
_WD_CapabilitiesAdd("prefs", "browser.download.folderList", 2)
_WD_CapabilitiesAdd("prefs", "browser.download.dir", $s_Download_dir)
_WD_CapabilitiesAdd("prefs", "browser.helperApps.neverAsk.saveToDisk", "application/pdf,application/octet-stream")
_WD_CapabilitiesAdd("prefs", "browser.helperApps.neverAsk.openFile", "application/pdf,application/octet-stream")
_WD_CapabilitiesAdd("prefs", "browser.download.useDownloadDir", True)
_WD_CapabilitiesAdd("prefs", "browser.download.alwaysOpenPanel", False)
</syntaxhighlight>
</div>
</div>

<div class="usermessage mw-customtoggle-FAQ13">13. How to setup session with proxy?</div>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-FAQ13">
<div class="toccolours mw-collapsible-content">
Q: How to automate websites behind proxy?<br>
A: Take a look on:

https://www.autoitscript.com/forum/topic/205553-webdriver-udf-help-support-iii/?do=findComment&comment=1498049

and

https://www.autoitscript.com/forum/topic/205553-webdriver-udf-help-support-iii/?do=findComment&comment=1498085
</div>
</div>

<div class="usermessage mw-customtoggle-FAQ14">14. How to add capabilities options for '''"goog:chromeOptions"''' or '''"ms:edgeOptions"''' or '''"moz:firefoxOptions"'''?</div>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-FAQ14">
<div class="toccolours mw-collapsible-content">
Q: How to add options for '''"goog:chromeOptions"''' or '''"ms:edgeOptions"''' or '''"moz:firefoxOptions"''' ?<br>
A: WORK IN PROGRESS: https://github.com/Danp2/au3WebDriver/pull/263

</div>
</div>

<div class="usermessage mw-customtoggle-FAQ15">15. How to change user-agent?</div>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-FAQ15">
<div class="toccolours mw-collapsible-content">
Q: How to change user-agent?<br>
A: Example for chrome:
<syntaxhighlight lang="autoit">
_WD_CapabilitiesAdd("args", "user-agent", "Mozilla/5.0 (Windows NT 10.0; Win" & StringReplace(@OSArch, "X", "") & "; " & @CPUArch & ") AppleWebKit/537.36 (KHTML, like Gecko) Chrome/" & _WD_GetBrowserVersion("chrome") & " Safari/537.36")
</syntaxhighlight>

A: Example for firefox:
<syntaxhighlight lang="autoit">
_WD_CapabilitiesAdd("args", "user-agent", "Mozilla/5.0 (Windows NT 10.0; Win" & StringReplace(@OSArch, "X", "") & "; " & @CPUArch & ") AppleWebKit/537.36 (KHTML, like Gecko) Chrome/" & _WD_GetBrowserVersion("firefox") & " Safari/537.36")
</syntaxhighlight>

</div>
</div>

<div class="usermessage mw-customtoggle-FAQ16">16. How to enable/disable logging into webdriver console?</div>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-FAQ16">
<div class="toccolours mw-collapsible-content">
Q: How to enable/disable logging into webdriver console?<br>
A: Example for chrome:
<syntaxhighlight lang="autoit">
_WD_CapabilitiesAdd("excludeSwitches", "enable-logging")
_WD_CapabilitiesAdd("excludeSwitches", "disable-logging")
</syntaxhighlight>

</div>
</div>

<div class="usermessage mw-customtoggle-FAQ17">17. How to work with frames in Firefox?</div>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-FAQ17">
<div class="toccolours mw-collapsible-content">
Q: How to work with frames in Firefox?<br>
A: https://www.youtube.com/watch?v=Me9hjqd74m8&t=58s

</div>
</div>

== Tools ==
The following tools will help you to automate your browser:
* [https://autonomiq.io/deviq-chropath.html ChroPath] plugin: Makes finding an element by XPath, ID or CSS incredibly easy (Chrome, Firefox, Opera)
* [https://selectorshub.com/ SelectorsHub] plugin: Next Gen XPath tool to generate, write and verify the XPath and cssSelectors (All browsers)
* [https://addons.mozilla.org/pl/firefox/addon/save-page-we Save Page WE] plugin: helps to save web page content as single MHTML file (Firefox, [https://chrome.google.com/webstore/detail/save-page-we/dhhpefjklgkmgeafimnjhojgjamoafof Save Page WE for Chrome])

== References ==
<small>(Last modified: 2022/02/12)<br></small>

Further information sources:
* W3C: https://www.w3.org/TR/webdriver/
* AutoIt WebDriver discussion threads:
** '''[https://www.autoitscript.com/forum/topic/191990-webdriver-udf-w3c-compliant-version-01312022/ WebDriver UDF (W3C compliant version)]''' by @Danp2
** '''[https://www.autoitscript.com/forum/topic/192730-webdriver-udf-help-support/ WebDriver UDF - Help & Support]''' by @Danp2
** '''[https://www.autoitscript.com/forum/topic/201106-webdriver-udf-help-support-ii/ WebDriver UDF - Help & Support (II)]''' by @Danp2
** '''[https://www.autoitscript.com/forum/topic/205553-webdriver-udf-help-support-iii/ WebDriver UDF - Help & Support (III)]''' by @Danp2
** '''[https://www.autoitscript.com/forum/topic/208640-webdriver-udf-help-support-iv/ WebDriver UDF - Help & Support (IV)]''' by @Danp2
** '''[https://www.autoitscript.com/forum/topic/201283-im-creating-a-webdriver-tutorial I'm creating a WebDriver tutorial]''' by @Water
** '''[https://www.autoitscript.com/forum/topic/201537-webdriver-example-scripts-collection/ WebDriver example scripts collection]''' by @Water
** '''[https://www.autoitscript.com/forum/topic/201537-webdriver-example-scripts-collection/ Webdriver, Websockets, and Chrome DevTools Protocol]''' by @Danp2

* WebDriver Exe documentation:
** [https://sites.google.com/chromium.org/driver/ Chrome]
** [https://docs.microsoft.com/en-us/microsoft-edge/webdriver Edge]
** [https://docs.microsoft.com/en-us/microsoft-edge/webdriver-chromium Edge Chromium]
** [https://firefox-source-docs.mozilla.org/testing/geckodriver/ Firefox]
** [https://selenium.dev/documentation/en/webdriver/ Opera (Selenium)]

* Other useful links:
** [https://github.com/jlipps/simple-wd-spec/ The W3C WebDriver Spec: A Simplified Guide]

[[Category:Tutorials]]

WebDriver

2021-12-26T14:53:08Z

Danp2: /* FAQ */ Add MS Edge profile example

WebDriver

2021-06-04T14:09:13Z

Danp2: /* Tools */

The W3C WebDriver API is a platform and language-neutral interface and wire protocol allowing programs or scripts to control the behavior of a web browser.

== Introduction ==

=== WebDriver API ===
WebDriver enables developers to create automated tests that simulate user interaction. This is different from JavaScript unit tests because WebDriver has access to functionality and information that JavaScript running in the browser doesn't, and it can more accurately simulate user events or OS-level events. WebDriver can also manage testing across multiple windows, tabs and webpages in a single test session.

=== WebDriver UDF ===
The WebDriver UDF allows 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 ===
<small>(Last modified: 2021/02/07)<br></small>

The following UDFs need to be installed - '''independent''' of the Browser you try to automate:
* [https://www.autoitscript.com/forum/topic/148114-a-non-strict-json-udf-jsmn JSON UDF (AutoIt)] by Ward and Jos
* [https://www.autoitscript.com/forum/topic/84133-winhttp-functions/ WinHTTP UDF (AutoIt)] by trancexx or [https://github.com/dragana-r/autoit-winhttp autoit-winhttp (GitHub)]
* [https://github.com/Danp2/WebDriver/releases/latest WebDriver UDF (GitHub)] by Danp2
One of the following Drivers needs to be installed - '''depending''' on the Browser type and version you try to automate:
{| class="wikitable"
|-
! Browser !! Download Link !! Latest Version / Date !! Comments
|-
| Chrome || [https://sites.google.com/a/chromium.org/chromedriver/downloads Google] || 89.0.4389.23 / <br> 2021.01.28 || Follow this [https://sites.google.com/a/chromium.org/chromedriver/downloads/version-selection link] to select the correct version depending on the Chrome version you run!
|-
| Edge || [https://developer.microsoft.com/en-us/microsoft-edge/tools/webdriver/ Microsoft] || 90.0.789.0 / <br> 2021.02.05 ||
|-
| Firefox || [https://github.com/mozilla/geckodriver/releases GitHub] || 0.29 / <br> 2021.01.14 || Firefox version ≥ 60 is recommended<br>
'''Note:''' You must still have the Microsoft Visual Studio redistributable runtime installed on your system for the binary to run. This is a known bug in version 0.26 which the authors weren't able fix for this release.
|-
| Opera || [https://github.com/operasoftware/operachromiumdriver/releases/latest GitHub] || 88.0.4324.104 / <br> 2021.02.03 || The versioning of OperaDriver matches the Chromium version on which Opera browser is based on.
|}

=== Limitations ===
<small>(Last modified: 2020/01/28)<br></small>
Not all WebDriver functions have been implemented by each browser. To check the status goto the corresponding website below:

* [https://chromium.googlesource.com/chromium/src/+/master/docs/chromedriver_status.md Chrome]
* [https://docs.microsoft.com/en-us/microsoft-edge/webdriver#w3c-webdriver-specification-supporthttpsw3cgithubiowebdriverwebdriver-spechtml Edge]
* [https://developer.mozilla.org/en-US/docs/Mozilla/QA/Marionette/WebDriver/status Firefox]
* [https://github.com/operasoftware/operachromiumdriver Opera]: "''OperaChromiumDriver is a WebDriver implementation derived from ChromeDriver and adapted by Opera''". That's why I think it has at least the same limitations as ChromeDriver.

=== Big Picture ===
How the browser independent and browser dependent parts fit together:<br>

[[File:WebDriver.png|800px|||Big Picture - How everything fits together]]

=== Used Terms ===
<small>(Last modified: 2020/03/08)<br></small>

You will find the following terms when using WebDriver. We try to shed some light onto this subject here:

'''Marionette'''<br>
Marionette is an automation driver for Mozilla’s Gecko engine. It can remotely control either the UI or the internal JavaScript of a Gecko platform, such as Firefox. It can control both the chrome (i.e. menus and functions) or the content (the webpage loaded inside the browsing context), giving a high level of control and ability to replicate user actions. In addition to performing actions on the browser, Marionette can also read the properties and attributes of the DOM.<br>
Marionette consists of two parts: a server which takes requests and executes them in Gecko (the Marionette server ships with Firefox), and a client (the Marionette client ships with the GeckoDriver exe). The client sends commands to the server and the server executes the command inside the browser.<br>
For details please [https://firefox-source-docs.mozilla.org/testing/marionette/Intro.html visit this site].

'''ShadowRoot'''<br>
The ShadowRoot interface of the Shadow DOM API is the root node of a DOM subtree that is rendered separately from a document's main DOM tree.<br>
For details please [https://dom.spec.whatwg.org/#interface-shadowroot visit this site].

== Installation ==
<small>(Last modified: 2020/09/27)<br></small>

To automate your browser the following installation steps are needed:
* Download the files listed in section "[[WebDriver#Requirements|Requirements]]"
* Move the UDFs to a directory where SciTE and Autoit can find them:
** Json.au3 and BinaryCall.au3 from the JSON UDF
** wd_Core.au3 and wd_helper.au3 from the WebDriver UDF
** WinHttp.au3 and WinHttpConstants.au3 from the WinHttp UDF
* Move the browser dependent WebDriver to the same directory (with WD_Demo.au3):
** chromedriver.exe (Chrome)
** geckodriver.exe (Firefox)
** msedgedriver.exe (Edge - Chromium) or MicrosoftWebDriver.exe (Edge - EdgeHTML)
* Run WD_Demo.au3 and select "DemoNavigation" to validate the installation.<br>The result (for Firefox) displayed in the DOS window should be similar to the following:
<syntaxhighlight lang="text">
1577745813519 geckodriver DEBUG Listening on 127.0.0.1:4444
1577745813744 webdriver::server DEBUG -> POST /session {"capabilities": {"alwaysMatch": {"browserName": "firefox", "acceptInsecureCerts":true}}}
1577745813746 geckodriver::capabilities DEBUG Trying to read firefox version from ini files
1577745813747 geckodriver::capabilities DEBUG Found version 71.0
1577745813757 mozrunner::runner INFO Running command: "C:\\Program Files\\Mozilla Firefox\\firefox.exe" "-marionette" "-foreground" "-no-remote" "-profile" "C:\\ ...
1577745813783 geckodriver::marionette DEBUG Waiting 60s to connect to browser on 127.0.0.1:55184
1577745817392 geckodriver::marionette DEBUG Connection to Marionette established on 127.0.0.1:55184.
1577745817464 webdriver::server DEBUG <- 200 OK {"value":{"sessionId":"925641bf-6c5d-4fe2-a985-02de9b1c7c74","capabilities":"acceptInsecureCerts":true,"browserName":"firefox", ...
</syntaxhighlight>

== Function reference ==
<small>(Last modified: 2021/02/07 - based on version 0.4.0.1)<br></small>

=== WD_CORE ===
The WD_Core.au3 file holds functions to implement the Webdriver W3C document.
{| class="wikitable"
|-
! scope="col" style="width: 200px;" | Function !! scope="col" style="width: 450px;" | Description !! Comment
|-
| _WD_Action || Perform various interactions with the web driver session || Use one of the following values for parameter $sCommand:
''actions'',
''back'',
''forward'',
''refresh'',
''title'',
''url''.
For command ''actions'': Pass the actions to be set using parameter $sOption. If $sOption is empty then the set actions will be removed.
|-
| _WD_Alert || Respond to user prompt || Use one of the following actions to respond to the user prompt:
''accept'',
''dismiss'',
''gettext'',
''sendtext'',
''status''.
|-
| _WD_Cookies || Gets, sets, or deletes the session's cookies || Use one of the following commands:
''get'' (Gets a single cookie),
''getall'' (Gets all cookies),
''add'' (Sets a single cookie),
''delete'' (Deletes a single cookie).
|-
| _WD_CreateSession|| Request new session from web driver || Define the capabilities of the browser with this function
|-
| _WD_DeleteSession || Delete existing session || Closes the session created by _WD_CreateSession
|-
| _WD_ElementAction || Perform action on designated element || Use one of the following actions:
''Active'',
''Attribute'',
''Clear'',
''Click'',
''CompLabel''(Get element's computed label),
''CompRole'' (Get element's computed role),
''CSS'',
''Displayed'',
''Enabled'',
''Name'',
''Property'',
''Rect'',
''Screenshot'',
''Selected'',
''Shadow'' (Get element's shadow root),
''Text'',
''Value''.

''Clear'', ''Click'' and ''Value'' use POST to modify or process the element. All other actions use GET to retrieve data from the element
|-
| _WD_ExecuteScript || Execute Javascipt commands ||
|-
| _WD_FindElement|| Find element(s) by designated strategy || You can specify whether the function should only return the first find or all of them
|-
| _WD_GetSource || Get page source ||
|-
| _WD_Navigate || Navigate to the designated URL ||
|-
| _WD_Option || Sets and get options for the web driver UDF || The following options can be used:
''BaseURL'' (IP address used for web driver communication),
''BinaryFormat'' (format used to store binary data),
''Console'' (define destination for console output),
''Driver'' (set the full path name to web driver executable),
''DriverParams'' (parameters to pass to web driver executable),
''Port'' (port used for web driver communication).
If no value is passed to be set the current value is returned
|-
| _WD_Shutdown || Kill the web driver console app ||
|-
| _WD_Startup || Launch the designated web driver console app || The PID for the WebDriver console is returned
|-
| _WD_Status || Get current web driver state || Returns a raw JSON response from the web driver
|-
| _WD_Timeouts || Set or retrieve the session timeout parameters || Specify the type and value of the timeout like this: '{"type":value}'. Example: '{"pageLoad":2000}'
|-
| _WD_Window || Perform interactions related to the current window || 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),
''parent'' (switch to parent frame),
''rect'' (get or set the window's size & position),
''screenshot'' (take screenshot of window),
''switch'' (switch to designated tab),
''window'' (get current tab's window handle).
|-
|}

=== WD_HELPER ===
The WD_Helper.au3 file holds functions to help you automate a web site.
{| class="wikitable"
|-
! scope="col" style="width: 200px;" | Function !! scope="col" style="width: 450px;" | Description !! Comment
|-
| _WD_Attach || Attach to existing browser tab || Use one of the following search modes:
''HTML'',
''Title'',
''URL''.
|-
| _WD_ConsoleVisible || Control visibility of the webdriver console app ||
|-
| _WD_DownloadFile || Download file and save to disk ||
|-
| _WD_ElementActionEx || Perform advanced action on desginated element || Use one of the following commands:
''hover'',
''doubleclick'',
''rightclick'',
''clickandhold'',
''hide'',
''show''.
''childcount''.
''modifierclick''.
|-
| _WD_ElementOptionSelect || Find and click on an option from a Select element ||
|-
| _WD_ElementSelectAction || Perform action on designated Select element || Use one of the following commands:
''options'',
''value''.
|-
| _WD_ExecuteCdpCommand || ChromeDriver specific function to execute "Chrome DevTools Protocol" (CDP) commands ||
|-
| _WD_FrameEnter || Will enter the specified frame for subsequent WebDriver operations ||
|-
| _WD_FrameLeave || Will leave the current frame, to its parent, not necessarily the Top, for subsequent WebDriver operations ||
|-
| _WD_GetElementById || Locate element by id ||
|-
| _WD_GetElementByName || Locate element by name ||
|-
| _WD_GetElementFromPoint || Retrieves reference to element descriped by x/y coordinate ||
|-
| _WD_GetFrameCount || Returns how many frames/iframes are in your current window/frame || It will not traverse to nested frames
|-
| _WD_GetMouseElement || Retrieves reference to element below mouse pointer ||
|-
| _WD_GetShadowRoot || Retrieves the shadow root of an element ||
|-
| _WD_GetTable || Return all elements of a table ||
|-
| _WD_HighlightElement || Will highlight the specified element ||
|-
| _WD_HighlightElements || Will highlight multiple elements passed as an array ||
|-
| _WD_IsLatestRelease || Compares local UDF version to latest release on Github ||
|-
| _WD_IsWindowTop || Returns a boolean of the session being at the top level, or in a frame(s) ||
|-
| _WD_jQuerify || Inject jQuery library into current session ||
|-
| _WD_LastHTTPResult || Return the result of the last WinHTTP request ||
|-
| _WD_LinkClickByText || Simulate a mouse click on a link with text matching the provided string ||
|-
| _WD_LoadWait || Wait for a browser page load to complete before returning ||
|-
| _WD_NewTab || Create new tab using Javascript ||
|-
| _WD_PrintToPDF || Print the current tab in paginated PDF format ||
|-
| _WD_Screenshot || Will return a screenshot of the browser window or a specified element ||
|-
| _WD_SelectFiles || Select files for uploading to a website ||
|-
| _WD_SetElementValue || Set value of designated element ||
|-
| _WD_SetTimeouts || User friendly function to set webdriver session timeouts ||
|-
| _WD_UpdateDriver || Replace web driver with newer version, if available ||
|-
| _WD_WaitElement || Wait for a element to be found in the current tab before returning ||
|-
|}

== Troubleshooting ==
=== Debug the WebDriver setup ===
<small>(Last modified: 2020/07/06)<br></small>
==== WinHTTP UDF ====
Make sure that you are running at least version 1.6.4.2 (currently unreleased, but can be obtained [https://raw.githubusercontent.com/dragana-r/autoit-winhttp/master/WinHttp.au3 here]).
==== Chrome ====
<div class="usermessage mw-customtoggle-DebugChrome1">Chrome does not start and the DOS window for chromedriver does not get displayed</div>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-DebugChrome1">
{| class="wikitable"
|-
! Problem !! Solution !! Reference
|-
| When running WD_Demo.au3 it does not start up Chrome and does not display the DOS window for chromedriver.<br>When you manually run the chromedriver in a DOS window you get message "[0.023][SEVERE]: CreatePlatformSocket() returned an error: An invalid argument was supplied."|| This could be caused by missing execution permission for the network drive. Please ask your IT admin for "Applocker" or "application directory whitelisting". <br>Or run the chrome driver from a local HDD and call _WD_Option to set the location of the webdriver executable. Example: _WD_Option("Driver", "C:\Local\WebDriver\chromedriver.exe") || [https://stackoverflow.com/questions/51056121/createplatformsocket-returned-an-error-an-invalid-argument-was-supplied-0x2 Stackoverflow]
|}
</div>

==== Firefox ====
<div class="usermessage mw-customtoggle-DebugFirefox1">Firefox does not start and the DOS window for geckodriver does not get displayed</div>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-DebugFirefox1">
{| class="wikitable"
|-
! Problem !! Solution !! Reference
|-
| When running WD_Demo.au3 it does not start up Firefox and does not display the DOS window for geckodriver.<br>When you manually run the geckodriver in a DOS window you get message "geckodriver: error: An invalid argument was supplied. (os error 10022)"|| This could be caused by missing execution permission for the network drive. Please ask your IT admin for "Applocker" or "application directory whitelisting". <br>Or run the gecko driver from a local HDD and call _WD_Option to set the location of the webdriver executable. Example: _WD_Option("Driver", "C:\Local\WebDriver\geckodriver.exe") || [https://stackoverflow.com/questions/51056121/createplatformsocket-returned-an-error-an-invalid-argument-was-supplied-0x2 Stackoverflow]
|}
</div>

=== Debug your Script ===

== FAQ ==
<small>(Last modified: 2020/10/11)<br></small>

<div class="usermessage mw-customtoggle-FAQ1">1. How to connect to a running browser instance</div>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-FAQ1">
<div class="toccolours mw-collapsible-content">Q: How can I connect to a running browser instance?<br>A: That's described (for Firefox, but should work similar for other browsers) in this [https://www.autoitscript.com/forum/topic/201106-webdriver-udf-help-support-ii/?do=findComment&comment=1444173 post].</div>
</div>

<div class="usermessage mw-customtoggle-FAQ2">2. How to hide the webdriver console</div>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-FAQ2">
<div class="toccolours mw-collapsible-content">Q: How can I hide the webdriver console?<br>A: The console can be completely hidden from the start by adding the following line near the beginning of your script:<br><syntaxhighlight lang="autoit">$_WD_DEBUG = $_WD_DEBUG_None ; You could also use $_WD_DEBUG_Error</syntaxhighlight>You can also control the visibility of the console with the function _WD_ConsoleVisible.</div>
</div>

<div class="usermessage mw-customtoggle-FAQ3">3. How to utilize an existing user profile</div>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-FAQ3">
<div class="toccolours mw-collapsible-content">Q: Can I use an existing user profile instead of the default behavior of using a new one?<br>A: This is controlled by your "capabilities" declaration, with each browser using a different method to implement. Here are some examples:<br>
<br>'''Chrome'''<syntaxhighlight lang="autoit">$sDesiredCapabilities = '{"capabilities": {"alwaysMatch": {"goog:chromeOptions": {"w3c": true, "args":["--user-data-dir=C:\\Users\\' & @UserName & '\\AppData\\Local\\Google\\Chrome\\User Data\\", "--profile-directory=Default"]}}}}'</syntaxhighlight>'''Firefox'''<syntaxhighlight lang="autoit">
$sDesiredCapabilities = '{"capabilities":{"alwaysMatch": {"moz:firefoxOptions": {"args": ["-profile", "' & GetDefaultFFProfile() & '"],"log": {"level": "trace"}}}}}'

Func GetDefaultFFProfile()
Local $sDefault, $sProfilePath = ''

Local $sProfilesPath = StringReplace(@AppDataDir, '\', '/') & "/Mozilla/Firefox/"
Local $sFilename = $sProfilesPath & "profiles.ini"
Local $aSections = IniReadSectionNames ($sFilename)

If Not @error Then
For $i = 1 To $aSections[0]
$sDefault = IniRead($sFilename, $aSections[$i], 'Default', '0')

If $sDefault = '1' Then
$sProfilePath = $sProfilesPath & IniRead($sFilename, $aSections[$i], "Path", "")
ExitLoop
EndIf
Next
EndIf

Return $sProfilePath
EndFunc
</syntaxhighlight>You will also likely need to specify the marionette port:
<syntaxhighlight lang="autoit">_WD_Option('DriverParams', '--marionette-port 2828')</syntaxhighlight></div>
</div>

<div class="usermessage mw-customtoggle-FAQ4">4. How to specify location of browser executable</div>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-FAQ4">
<div class="toccolours mw-collapsible-content">Q: Is it possible to launch a browser installed in a non-standard location?<br>A: This is controlled by your "capabilities" declaration. Here are some examples:<br>
<br>'''Chrome'''<syntaxhighlight lang="autoit">$sDesiredCapabilities = '{"capabilities": {"alwaysMatch": {"goog:chromeOptions": {"w3c": true, "binary":"C:\\Path\\To\\Alternate\\Browser\\chrome.exe" }}}}'
</syntaxhighlight>'''Firefox'''<syntaxhighlight lang="autoit">$sDesiredCapabilities = '{"desiredCapabilities":{"javascriptEnabled":true,"nativeEvents":true,"acceptInsecureCerts":true,"moz:firefoxOptions":{"binary":"C:\\Path\\To\\Alternate\\Browser\\firefox.exe"}}}'</syntaxhighlight>Alternate Firefox method:<br><syntaxhighlight lang="autoit">
_WD_Option('DriverParams', '--binary "C:\Program Files\Mozilla Firefox\firefox.exe" --log trace ')</syntaxhighlight></div>
</div>

<div class="usermessage mw-customtoggle-FAQ5">5. How to maximize the browser window</div>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-FAQ5">
<div class="toccolours mw-collapsible-content">Q: Is it possible to maximize the browser window?<br>A: Simply call the following function:<syntaxhighlight lang="autoit">_WD_Window($sSession, "Maximize")
</syntaxhighlight>Make sure to call _WD_Window after the session has been created with _WD_CreateSession.</div></div>

<div class="usermessage mw-customtoggle-FAQ6">6. How to specify location of WebDriver executable</div>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-FAQ6">
<div class="toccolours mw-collapsible-content">Q: Is it possible to launch the WebDriver executable from a specific location?<br>A: This is controlled by function "_WD_Option". Example:
<br><syntaxhighlight lang="autoit">_WD_Option("Driver", "C:\local\WebDriver\WebDriver.exe")</syntaxhighlight></div>
</div>

<div class="usermessage mw-customtoggle-FAQ7">7. How to retrieve the values of a drop-down list</div>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-FAQ7">
<div class="toccolours mw-collapsible-content">Q: How to retrieve the values of a drop-down list (<Select> tag)?<br>A1: Here's a simple way to do it:
<br><syntaxhighlight lang="autoit">$sElement = _WD_FindElement($sSession, $_WD_LOCATOR_ByXPath, "//select[@name='xxx']")
$sText = _WD_ElementAction($sSession, $sElement, 'property', 'innerText')
$aOptions = StringSplit ( $sText, @LF, $STR_NOCOUNT)
_ArrayDisplay($aOptions)</syntaxhighlight>
'xxx' is the name of the drop-down list.
<br>A2: This can now be accomplished using the function _WD_ElementSelectAction:<br><syntaxhighlight lang="autoit">$sElement = _WD_FindElement($sSession, $_WD_LOCATOR_ByXPath, "//select[@name='xxx']")
$aOptions = _WD_ElementSelectAction ($sSession, $sElement, 'options')
_ArrayDisplay($aOptions)</syntaxhighlight>
</div>
</div>

<div class="usermessage mw-customtoggle-FAQ8">8. How to run the browser in headless mode</div>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-FAQ8">
<div class="toccolours mw-collapsible-content">Q: How do I run the browser in "headless" mode?<br>A: This is controlled by the Capabilities string that is passed to _WD_CreateSession. Example:
<br><syntaxhighlight lang="autoit">$sDesiredCapabilities = '{"capabilities": {"alwaysMatch": {"goog:chromeOptions": {"w3c": true, "args": ["--headless", "--allow-running-insecure-content"] }}}}' </syntaxhighlight></div>
</div>

== Tools ==
The following tools will help you to automate your browser:
* [https://autonomiq.io/deviq-chropath.html ChroPath] plugin: Makes finding an element by XPath, ID or CSS incredibly easy (Chrome, Firefox, Opera)
* [https://selectorshub.com/ SelectorsHub] plugin: Next Gen XPath tool to generate, write and verify the XPath and cssSelectors (All browsers)

== References ==
<small>(Last modified: 2020/03/01)<br></small>

Further information sources:
* W3C: https://www.w3.org/TR/webdriver/
* AutoIt WebDriver threads:
** Danp2's thread in the '''[https://www.autoitscript.com/forum/topic/191990-webdriver-udf-w3c-compliant-version-12242019 Example Scripts]''' forum - WebDriver UDF (W3C compliant version)
** Danp2's closed thread in the '''[https://www.autoitscript.com/forum/topic/192730-webdriver-udf-help-support/ General Help and Support]''' forum - WebDriver UDF - Help & Support (this is part I)
** Danp2's closed thread in the '''[https://www.autoitscript.com/forum/topic/201106-webdriver-udf-help-support-ii/ General Help and Support II]''' forum - WebDriver UDF - Help & Support (II)
** Danp2's active thread in the '''[https://www.autoitscript.com/forum/topic/205553-webdriver-udf-help-support-iii/ General Help and Support III]''' forum - WebDriver UDF - Help & Support (III)
** Water's thread in the '''[https://www.autoitscript.com/forum/topic/201283-im-creating-a-webdriver-tutorial General Help and Support]''' forum - Discussion about this Wiki Page
** Water's thread in the '''[https://www.autoitscript.com/forum/topic/201537-webdriver-example-scripts-collection/ Example Scripts]''' forum - WebDriver example scripts collection

* WebDriver Exe documentation:
** [https://sites.google.com/a/chromium.org/chromedriver/ Chrome]
** [https://docs.microsoft.com/en-us/microsoft-edge/webdriver Edge]
** [https://docs.microsoft.com/en-us/microsoft-edge/webdriver-chromium Edge Chromium]
** [https://firefox-source-docs.mozilla.org/testing/geckodriver/ Firefox]
** [https://selenium.dev/documentation/en/webdriver/ Opera]

WebDriver

2021-04-14T16:02:24Z

Danp2: /* FAQ */

The W3C WebDriver API is a platform and language-neutral interface and wire protocol allowing programs or scripts to control the behavior of a web browser.

== Introduction ==

=== WebDriver API ===
WebDriver enables developers to create automated tests that simulate user interaction. This is different from JavaScript unit tests because WebDriver has access to functionality and information that JavaScript running in the browser doesn't, and it can more accurately simulate user events or OS-level events. WebDriver can also manage testing across multiple windows, tabs and webpages in a single test session.

=== WebDriver UDF ===
The WebDriver UDF allows 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 ===
<small>(Last modified: 2021/02/07)<br></small>

The following UDFs need to be installed - '''independent''' of the Browser you try to automate:
* [https://www.autoitscript.com/forum/topic/148114-a-non-strict-json-udf-jsmn JSON UDF (AutoIt)] by Ward and Jos
* [https://www.autoitscript.com/forum/topic/84133-winhttp-functions/ WinHTTP UDF (AutoIt)] by trancexx or [https://github.com/dragana-r/autoit-winhttp autoit-winhttp (GitHub)]
* [https://github.com/Danp2/WebDriver/releases/latest WebDriver UDF (GitHub)] by Danp2
One of the following Drivers needs to be installed - '''depending''' on the Browser type and version you try to automate:
{| class="wikitable"
|-
! Browser !! Download Link !! Latest Version / Date !! Comments
|-
| Chrome || [https://sites.google.com/a/chromium.org/chromedriver/downloads Google] || 89.0.4389.23 / <br> 2021.01.28 || Follow this [https://sites.google.com/a/chromium.org/chromedriver/downloads/version-selection link] to select the correct version depending on the Chrome version you run!
|-
| Edge || [https://developer.microsoft.com/en-us/microsoft-edge/tools/webdriver/ Microsoft] || 90.0.789.0 / <br> 2021.02.05 ||
|-
| Firefox || [https://github.com/mozilla/geckodriver/releases GitHub] || 0.29 / <br> 2021.01.14 || Firefox version ≥ 60 is recommended<br>
'''Note:''' You must still have the Microsoft Visual Studio redistributable runtime installed on your system for the binary to run. This is a known bug in version 0.26 which the authors weren't able fix for this release.
|-
| Opera || [https://github.com/operasoftware/operachromiumdriver/releases/latest GitHub] || 88.0.4324.104 / <br> 2021.02.03 || The versioning of OperaDriver matches the Chromium version on which Opera browser is based on.
|}

=== Limitations ===
<small>(Last modified: 2020/01/28)<br></small>
Not all WebDriver functions have been implemented by each browser. To check the status goto the corresponding website below:

* [https://chromium.googlesource.com/chromium/src/+/master/docs/chromedriver_status.md Chrome]
* [https://docs.microsoft.com/en-us/microsoft-edge/webdriver#w3c-webdriver-specification-supporthttpsw3cgithubiowebdriverwebdriver-spechtml Edge]
* [https://developer.mozilla.org/en-US/docs/Mozilla/QA/Marionette/WebDriver/status Firefox]
* [https://github.com/operasoftware/operachromiumdriver Opera]: "''OperaChromiumDriver is a WebDriver implementation derived from ChromeDriver and adapted by Opera''". That's why I think it has at least the same limitations as ChromeDriver.

=== Big Picture ===
How the browser independent and browser dependent parts fit together:<br>

[[File:WebDriver.png|800px|||Big Picture - How everything fits together]]

=== Used Terms ===
<small>(Last modified: 2020/03/08)<br></small>

You will find the following terms when using WebDriver. We try to shed some light onto this subject here:

'''Marionette'''<br>
Marionette is an automation driver for Mozilla’s Gecko engine. It can remotely control either the UI or the internal JavaScript of a Gecko platform, such as Firefox. It can control both the chrome (i.e. menus and functions) or the content (the webpage loaded inside the browsing context), giving a high level of control and ability to replicate user actions. In addition to performing actions on the browser, Marionette can also read the properties and attributes of the DOM.<br>
Marionette consists of two parts: a server which takes requests and executes them in Gecko (the Marionette server ships with Firefox), and a client (the Marionette client ships with the GeckoDriver exe). The client sends commands to the server and the server executes the command inside the browser.<br>
For details please [https://firefox-source-docs.mozilla.org/testing/marionette/Intro.html visit this site].

'''ShadowRoot'''<br>
The ShadowRoot interface of the Shadow DOM API is the root node of a DOM subtree that is rendered separately from a document's main DOM tree.<br>
For details please [https://dom.spec.whatwg.org/#interface-shadowroot visit this site].

== Installation ==
<small>(Last modified: 2020/09/27)<br></small>

To automate your browser the following installation steps are needed:
* Download the files listed in section "[[WebDriver#Requirements|Requirements]]"
* Move the UDFs to a directory where SciTE and Autoit can find them:
** Json.au3 and BinaryCall.au3 from the JSON UDF
** wd_Core.au3 and wd_helper.au3 from the WebDriver UDF
** WinHttp.au3 and WinHttpConstants.au3 from the WinHttp UDF
* Move the browser dependent WebDriver to the same directory (with WD_Demo.au3):
** chromedriver.exe (Chrome)
** geckodriver.exe (Firefox)
** msedgedriver.exe (Edge - Chromium) or MicrosoftWebDriver.exe (Edge - EdgeHTML)
* Run WD_Demo.au3 and select "DemoNavigation" to validate the installation.<br>The result (for Firefox) displayed in the DOS window should be similar to the following:
<syntaxhighlight lang="text">
1577745813519 geckodriver DEBUG Listening on 127.0.0.1:4444
1577745813744 webdriver::server DEBUG -> POST /session {"capabilities": {"alwaysMatch": {"browserName": "firefox", "acceptInsecureCerts":true}}}
1577745813746 geckodriver::capabilities DEBUG Trying to read firefox version from ini files
1577745813747 geckodriver::capabilities DEBUG Found version 71.0
1577745813757 mozrunner::runner INFO Running command: "C:\\Program Files\\Mozilla Firefox\\firefox.exe" "-marionette" "-foreground" "-no-remote" "-profile" "C:\\ ...
1577745813783 geckodriver::marionette DEBUG Waiting 60s to connect to browser on 127.0.0.1:55184
1577745817392 geckodriver::marionette DEBUG Connection to Marionette established on 127.0.0.1:55184.
1577745817464 webdriver::server DEBUG <- 200 OK {"value":{"sessionId":"925641bf-6c5d-4fe2-a985-02de9b1c7c74","capabilities":"acceptInsecureCerts":true,"browserName":"firefox", ...
</syntaxhighlight>

== Function reference ==
<small>(Last modified: 2021/02/07 - based on version 0.4.0.1)<br></small>

=== WD_CORE ===
The WD_Core.au3 file holds functions to implement the Webdriver W3C document.
{| class="wikitable"
|-
! scope="col" style="width: 200px;" | Function !! scope="col" style="width: 450px;" | Description !! Comment
|-
| _WD_Action || Perform various interactions with the web driver session || Use one of the following values for parameter $sCommand:
''actions'',
''back'',
''forward'',
''refresh'',
''title'',
''url''.
For command ''actions'': Pass the actions to be set using parameter $sOption. If $sOption is empty then the set actions will be removed.
|-
| _WD_Alert || Respond to user prompt || Use one of the following actions to respond to the user prompt:
''accept'',
''dismiss'',
''gettext'',
''sendtext'',
''status''.
|-
| _WD_Cookies || Gets, sets, or deletes the session's cookies || Use one of the following commands:
''get'' (Gets a single cookie),
''getall'' (Gets all cookies),
''add'' (Sets a single cookie),
''delete'' (Deletes a single cookie).
|-
| _WD_CreateSession|| Request new session from web driver || Define the capabilities of the browser with this function
|-
| _WD_DeleteSession || Delete existing session || Closes the session created by _WD_CreateSession
|-
| _WD_ElementAction || Perform action on designated element || Use one of the following actions:
''Active'',
''Attribute'',
''Clear'',
''Click'',
''CompLabel''(Get element's computed label),
''CompRole'' (Get element's computed role),
''CSS'',
''Displayed'',
''Enabled'',
''Name'',
''Property'',
''Rect'',
''Screenshot'',
''Selected'',
''Shadow'' (Get element's shadow root),
''Text'',
''Value''.

''Clear'', ''Click'' and ''Value'' use POST to modify or process the element. All other actions use GET to retrieve data from the element
|-
| _WD_ExecuteScript || Execute Javascipt commands ||
|-
| _WD_FindElement|| Find element(s) by designated strategy || You can specify whether the function should only return the first find or all of them
|-
| _WD_GetSource || Get page source ||
|-
| _WD_Navigate || Navigate to the designated URL ||
|-
| _WD_Option || Sets and get options for the web driver UDF || The following options can be used:
''BaseURL'' (IP address used for web driver communication),
''BinaryFormat'' (format used to store binary data),
''Console'' (define destination for console output),
''Driver'' (set the full path name to web driver executable),
''DriverParams'' (parameters to pass to web driver executable),
''Port'' (port used for web driver communication).
If no value is passed to be set the current value is returned
|-
| _WD_Shutdown || Kill the web driver console app ||
|-
| _WD_Startup || Launch the designated web driver console app || The PID for the WebDriver console is returned
|-
| _WD_Status || Get current web driver state || Returns a raw JSON response from the web driver
|-
| _WD_Timeouts || Set or retrieve the session timeout parameters || Specify the type and value of the timeout like this: '{"type":value}'. Example: '{"pageLoad":2000}'
|-
| _WD_Window || Perform interactions related to the current window || 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),
''parent'' (switch to parent frame),
''rect'' (get or set the window's size & position),
''screenshot'' (take screenshot of window),
''switch'' (switch to designated tab),
''window'' (get current tab's window handle).
|-
|}

=== WD_HELPER ===
The WD_Helper.au3 file holds functions to help you automate a web site.
{| class="wikitable"
|-
! scope="col" style="width: 200px;" | Function !! scope="col" style="width: 450px;" | Description !! Comment
|-
| _WD_Attach || Attach to existing browser tab || Use one of the following search modes:
''HTML'',
''Title'',
''URL''.
|-
| _WD_ConsoleVisible || Control visibility of the webdriver console app ||
|-
| _WD_DownloadFile || Download file and save to disk ||
|-
| _WD_ElementActionEx || Perform advanced action on desginated element || Use one of the following commands:
''doubleclick'',
''hide'',
''hover'',
''rightclick'',
''show''.
|-
| _WD_ElementOptionSelect || Find and click on an option from a Select element ||
|-
| _WD_ElementSelectAction || Perform action on designated Select element || Use one of the following commands:
''options'',
''value''.
|-
| _WD_ExecuteCdpCommand || ChromeDriver specific function to execute "Chrome DevTools Protocol" (CDP) commands ||
|-
| _WD_FrameEnter || Will enter the specified frame for subsequent WebDriver operations ||
|-
| _WD_FrameLeave || Will leave the current frame, to its parent, not necessarily the Top, for subsequent WebDriver operations ||
|-
| _WD_GetElementById || Locate element by id ||
|-
| _WD_GetElementByName || Locate element by name ||
|-
| _WD_GetElementFromPoint || Retrieves reference to element descriped by x/y coordinate ||
|-
| _WD_GetFrameCount || Returns how many frames/iframes are in your current window/frame || It will not traverse to nested frames
|-
| _WD_GetMouseElement || Retrieves reference to element below mouse pointer ||
|-
| _WD_GetShadowRoot || Retrieves the shadow root of an element ||
|-
| _WD_GetTable || Return all elements of a table ||
|-
| _WD_HighlightElement || Will highlight the specified element ||
|-
| _WD_HighlightElements || Will highlight multiple elements passed as an array ||
|-
| _WD_IsLatestRelease || Compares local UDF version to latest release on Github ||
|-
| _WD_IsWindowTop || Returns a boolean of the session being at the top level, or in a frame(s) ||
|-
| _WD_jQuerify || Inject jQuery library into current session ||
|-
| _WD_LastHTTPResult || Return the result of the last WinHTTP request ||
|-
| _WD_LinkClickByText || Simulate a mouse click on a link with text matching the provided string ||
|-
| _WD_LoadWait || Wait for a browser page load to complete before returning ||
|-
| _WD_NewTab || Create new tab using Javascript ||
|-
| _WD_PrintToPDF || Print the current tab in paginated PDF format ||
|-
| _WD_Screenshot || Will return a screenshot of the browser window or a specified element ||
|-
| _WD_SelectFiles || Select files for uploading to a website ||
|-
| _WD_SetElementValue || Set value of designated element ||
|-
| _WD_SetTimeouts || User friendly function to set webdriver session timeouts ||
|-
| _WD_UpdateDriver || Replace web driver with newer version, if available ||
|-
| _WD_WaitElement || Wait for a element to be found in the current tab before returning ||
|-
|}

== Troubleshooting ==
=== Debug the WebDriver setup ===
<small>(Last modified: 2020/07/06)<br></small>
==== WinHTTP UDF ====
Make sure that you are running at least version 1.6.4.2 (currently unreleased, but can be obtained [https://raw.githubusercontent.com/dragana-r/autoit-winhttp/master/WinHttp.au3 here]).
==== Chrome ====
<div class="usermessage mw-customtoggle-DebugChrome1">Chrome does not start and the DOS window for chromedriver does not get displayed</div>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-DebugChrome1">
{| class="wikitable"
|-
! Problem !! Solution !! Reference
|-
| When running WD_Demo.au3 it does not start up Chrome and does not display the DOS window for chromedriver.<br>When you manually run the chromedriver in a DOS window you get message "[0.023][SEVERE]: CreatePlatformSocket() returned an error: An invalid argument was supplied."|| This could be caused by missing execution permission for the network drive. Please ask your IT admin for "Applocker" or "application directory whitelisting". <br>Or run the chrome driver from a local HDD and call _WD_Option to set the location of the webdriver executable. Example: _WD_Option("Driver", "C:\Local\WebDriver\chromedriver.exe") || [https://stackoverflow.com/questions/51056121/createplatformsocket-returned-an-error-an-invalid-argument-was-supplied-0x2 Stackoverflow]
|}
</div>

==== Firefox ====
<div class="usermessage mw-customtoggle-DebugFirefox1">Firefox does not start and the DOS window for geckodriver does not get displayed</div>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-DebugFirefox1">
{| class="wikitable"
|-
! Problem !! Solution !! Reference
|-
| When running WD_Demo.au3 it does not start up Firefox and does not display the DOS window for geckodriver.<br>When you manually run the geckodriver in a DOS window you get message "geckodriver: error: An invalid argument was supplied. (os error 10022)"|| This could be caused by missing execution permission for the network drive. Please ask your IT admin for "Applocker" or "application directory whitelisting". <br>Or run the gecko driver from a local HDD and call _WD_Option to set the location of the webdriver executable. Example: _WD_Option("Driver", "C:\Local\WebDriver\geckodriver.exe") || [https://stackoverflow.com/questions/51056121/createplatformsocket-returned-an-error-an-invalid-argument-was-supplied-0x2 Stackoverflow]
|}
</div>

=== Debug your Script ===

== FAQ ==
<small>(Last modified: 2020/10/11)<br></small>

<div class="usermessage mw-customtoggle-FAQ1">1. How to connect to a running browser instance</div>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-FAQ1">
<div class="toccolours mw-collapsible-content">Q: How can I connect to a running browser instance?<br>A: That's described (for Firefox, but should work similar for other browsers) in this [https://www.autoitscript.com/forum/topic/201106-webdriver-udf-help-support-ii/?do=findComment&comment=1444173 post].</div>
</div>

<div class="usermessage mw-customtoggle-FAQ2">2. How to hide the webdriver console</div>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-FAQ2">
<div class="toccolours mw-collapsible-content">Q: How can I hide the webdriver console?<br>A: The console can be completely hidden from the start by adding the following line near the beginning of your script:<br><syntaxhighlight lang="autoit">$_WD_DEBUG = $_WD_DEBUG_None ; You could also use $_WD_DEBUG_Error</syntaxhighlight>You can also control the visibility of the console with the function _WD_ConsoleVisible.</div>
</div>

<div class="usermessage mw-customtoggle-FAQ3">3. How to utilize an existing user profile</div>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-FAQ3">
<div class="toccolours mw-collapsible-content">Q: Can I use an existing user profile instead of the default behavior of using a new one?<br>A: This is controlled by your "capabilities" declaration, with each browser using a different method to implement. Here are some examples:<br>
<br>'''Chrome'''<syntaxhighlight lang="autoit">$sDesiredCapabilities = '{"capabilities": {"alwaysMatch": {"goog:chromeOptions": {"w3c": true, "args":["--user-data-dir=C:\\Users\\' & @UserName & '\\AppData\\Local\\Google\\Chrome\\User Data\\", "--profile-directory=Default"]}}}}'</syntaxhighlight>'''Firefox'''<syntaxhighlight lang="autoit">
$sDesiredCapabilities = '{"capabilities":{"alwaysMatch": {"moz:firefoxOptions": {"args": ["-profile", "' & GetDefaultFFProfile() & '"],"log": {"level": "trace"}}}}}'

Func GetDefaultFFProfile()
Local $sDefault, $sProfilePath = ''

Local $sProfilesPath = StringReplace(@AppDataDir, '\', '/') & "/Mozilla/Firefox/"
Local $sFilename = $sProfilesPath & "profiles.ini"
Local $aSections = IniReadSectionNames ($sFilename)

If Not @error Then
For $i = 1 To $aSections[0]
$sDefault = IniRead($sFilename, $aSections[$i], 'Default', '0')

If $sDefault = '1' Then
$sProfilePath = $sProfilesPath & IniRead($sFilename, $aSections[$i], "Path", "")
ExitLoop
EndIf
Next
EndIf

Return $sProfilePath
EndFunc
</syntaxhighlight>You will also likely need to specify the marionette port:
<syntaxhighlight lang="autoit">_WD_Option('DriverParams', '--marionette-port 2828')</syntaxhighlight></div>
</div>

<div class="usermessage mw-customtoggle-FAQ4">4. How to specify location of browser executable</div>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-FAQ4">
<div class="toccolours mw-collapsible-content">Q: Is it possible to launch a browser installed in a non-standard location?<br>A: This is controlled by your "capabilities" declaration. Here are some examples:<br>
<br>'''Chrome'''<syntaxhighlight lang="autoit">$sDesiredCapabilities = '{"capabilities": {"alwaysMatch": {"goog:chromeOptions": {"w3c": true, "binary":"C:\\Path\\To\\Alternate\\Browser\\chrome.exe" }}}}'
</syntaxhighlight>'''Firefox'''<syntaxhighlight lang="autoit">$sDesiredCapabilities = '{"desiredCapabilities":{"javascriptEnabled":true,"nativeEvents":true,"acceptInsecureCerts":true,"moz:firefoxOptions":{"binary":"C:\\Path\\To\\Alternate\\Browser\\firefox.exe"}}}'</syntaxhighlight>Alternate Firefox method:<br><syntaxhighlight lang="autoit">
_WD_Option('DriverParams', '--binary "C:\Program Files\Mozilla Firefox\firefox.exe" --log trace ')</syntaxhighlight></div>
</div>

<div class="usermessage mw-customtoggle-FAQ5">5. How to maximize the browser window</div>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-FAQ5">
<div class="toccolours mw-collapsible-content">Q: Is it possible to maximize the browser window?<br>A: Simply call the following function:<syntaxhighlight lang="autoit">_WD_Window($sSession, "Maximize")
</syntaxhighlight>Make sure to call _WD_Window after the session has been created with _WD_CreateSession.</div></div>

<div class="usermessage mw-customtoggle-FAQ6">6. How to specify location of WebDriver executable</div>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-FAQ6">
<div class="toccolours mw-collapsible-content">Q: Is it possible to launch the WebDriver executable from a specific location?<br>A: This is controlled by function "_WD_Option". Example:
<br><syntaxhighlight lang="autoit">_WD_Option("Driver", "C:\local\WebDriver\WebDriver.exe")</syntaxhighlight></div>
</div>

<div class="usermessage mw-customtoggle-FAQ7">7. How to retrieve the values of a drop-down list</div>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-FAQ7">
<div class="toccolours mw-collapsible-content">Q: How to retrieve the values of a drop-down list (<Select> tag)?<br>A1: Here's a simple way to do it:
<br><syntaxhighlight lang="autoit">$sElement = _WD_FindElement($sSession, $_WD_LOCATOR_ByXPath, "//select[@name='xxx']")
$sText = _WD_ElementAction($sSession, $sElement, 'property', 'innerText')
$aOptions = StringSplit ( $sText, @LF, $STR_NOCOUNT)
_ArrayDisplay($aOptions)</syntaxhighlight>
'xxx' is the name of the drop-down list.
<br>A2: This can now be accomplished using the function _WD_ElementSelectAction:<br><syntaxhighlight lang="autoit">$sElement = _WD_FindElement($sSession, $_WD_LOCATOR_ByXPath, "//select[@name='xxx']")
$aOptions = _WD_ElementSelectAction ($sSession, $sElement, 'options')
_ArrayDisplay($aOptions)</syntaxhighlight>
</div>
</div>

<div class="usermessage mw-customtoggle-FAQ8">8. How to run the browser in headless mode</div>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-FAQ8">
<div class="toccolours mw-collapsible-content">Q: How do I run the browser in "headless" mode?<br>A: This is controlled by the Capabilities string that is passed to _WD_CreateSession. Example:
<br><syntaxhighlight lang="autoit">$sDesiredCapabilities = '{"capabilities": {"alwaysMatch": {"chromeOptions": {"w3c": true, "args": ["--headless", "--allow-running-insecure-content"] }}}}' </syntaxhighlight></div>
</div>

== Tools ==
The following tools will help you to automate your browser:
* [https://autonomiq.io/deviq-chropath.html ChroPath] plugin: Makes finding an element by XPath, ID or CSS incredibly easy (Chrome, Firefox, Opera)

== References ==
<small>(Last modified: 2020/03/01)<br></small>

Further information sources:
* W3C: https://www.w3.org/TR/webdriver/
* AutoIt WebDriver threads:
** Danp2's thread in the '''[https://www.autoitscript.com/forum/topic/191990-webdriver-udf-w3c-compliant-version-12242019 Example Scripts]''' forum - WebDriver UDF (W3C compliant version)
** Danp2's closed thread in the '''[https://www.autoitscript.com/forum/topic/192730-webdriver-udf-help-support/ General Help and Support]''' forum - WebDriver UDF - Help & Support (this is part I)
** Danp2's active thread in the '''[https://www.autoitscript.com/forum/topic/201106-webdriver-udf-help-support-ii/ General Help and Support II]''' forum - WebDriver UDF - Help & Support (II)
** Water's thread in the '''[https://www.autoitscript.com/forum/topic/201283-im-creating-a-webdriver-tutorial General Help and Support]''' forum - Discussion about this Wiki Page
** Water's thread in the '''[https://www.autoitscript.com/forum/topic/201537-webdriver-example-scripts-collection/ Example Scripts]''' forum - WebDriver example scripts collection

* WebDriver Exe documentation:
** [https://sites.google.com/a/chromium.org/chromedriver/ Chrome]
** [https://docs.microsoft.com/en-us/microsoft-edge/webdriver Edge]
** [https://docs.microsoft.com/en-us/microsoft-edge/webdriver-chromium Edge Chromium]
** [https://firefox-source-docs.mozilla.org/testing/geckodriver/ Firefox]
** [https://selenium.dev/documentation/en/webdriver/ Opera]

WebDriver

2021-01-27T21:03:24Z

Danp2: /* Tools */

WebDriver

2021-01-27T21:02:39Z

Danp2: Fix link

WebDriver

2021-01-27T21:01:27Z

Danp2: /* Tools */

WebDriver

2021-01-10T15:57:02Z

Danp2: Update FAQ #3, Firefox example code

WebDriver

2020-11-12T18:00:05Z

Danp2: /* FAQ */

AdlibEnable

2020-08-09T14:04:29Z

Danp2:

NOTE: As of 3.3.4.0 AdlibEnable/AdlibDisable were replaced with AdlibRegister/[[AdlibUnRegister]].
[http://www.autoitscript.com/forum/topic/115139-adlibenable-func-dont-work/ See reference forum topic]

Adlib's functionality is like that of combining {{Help File|Sleep}} with {{Help File|Call}} in that a function will be called after so many milliseconds.

=Syntax=
AdlibEnable("''func''"[, ''time''])

=Parameters=
<table border="1">
<tr><td>func</td><td>Name of function to be called.</td></tr>
<tr><td>time</td><td>Time in milliseconds till next ''func'' call. Default 250ms. (Optional)</td></tr>
</table>

=Return Value=
None.

=Example=
<pre>
Local $x = 0, $y

Func myFunction()
$y = MsgBox(1,"Count the boxes",$x,1) ; timeout in 1 second
if $y = 2 then Exit ; exit on cancel
$x += 1
AdlibEnable(myFunction(),1000) ; call this function again in 1 second
EndFunc

myFunction()
</pre>

=Related Functions=
<nowiki>[[AdlibDisable]] [[Call]] [[Sleep]]</nowiki>

WebDriver

2020-07-17T13:18:49Z

Danp2: /* FAQ */

WebDriver

2020-07-11T21:27:48Z

Danp2: /* FAQ */

WebDriver

2020-07-06T15:51:42Z

Danp2: Troubleshooting / WinHTTP

WebDriver

2020-04-19T17:46:00Z

Danp2: /* FAQ */

{{WIP}}
The W3C WebDriver API is a platform and language-neutral interface and wire protocol allowing programs or scripts to control the behavior of a web browser.

== Introduction ==

=== WebDriver API ===
WebDriver enables developers to create automated tests that simulate user interaction. This is different from JavaScript unit tests because WebDriver has access to functionality and information that JavaScript running in the browser doesn't, and it can more accurately simulate user events or OS-level events. WebDriver can also manage testing across multiple windows, tabs and webpages in a single test session.

=== WebDriver UDF ===
The WebDriver UDF allows 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 ===
<small>(Last modified: 2020/04/16)<br></small>

The following UDFs need to be installed - '''independent''' of the Browser you try to automate:
* [https://www.autoitscript.com/forum/topic/148114-a-non-strict-json-udf-jsmn JSON UDF]
* [https://www.autoitscript.com/forum/topic/84133-winhttp-functions/ WinHTTP UDF]
* [https://github.com/Danp2/WebDriver/releases/latest WebDriver UDF]
One of the following Drivers needs to be installed - '''depending''' on the Browser type and version you try to automate:
{| class="wikitable"
|-
! Browser !! Download Link !! Latest Version / Date !! Comments
|-
| Chrome || [https://sites.google.com/a/chromium.org/chromedriver/downloads Google] || 81.0.4044.69 / 2020.03.17 || Follow this [https://sites.google.com/a/chromium.org/chromedriver/downloads/version-selection link] to select the correct version depending on the Chrome version you run!
|-
| Edge || [https://developer.microsoft.com/en-us/microsoft-edge/tools/webdriver/ Microsoft] || 81.0.410.0 ||
|-
| Firefox || [https://github.com/mozilla/geckodriver/releases github] || 0.26 / 2019.10.12 || Firefox version ≥ 60 is recommended<br>
'''Note:''' You must still have the Microsoft Visual Studio redistributable runtime installed on your system for the binary to run. This is a known bug in version 0.26 which the authors weren't able fix for this release.
|-
| Opera || [https://github.com/operasoftware/operachromiumdriver/releases github] || 80.0.3987.100 / 2020.02.25 || The versioning of OperaDriver matches the Chromium version on which Opera browser is based on.
|}

=== Limitations ===
<small>(Last modified: 2020/01/28)<br></small>
Not all WebDriver functions have been implemented by each browser. To check the status goto the corresponding website below:

* [https://chromium.googlesource.com/chromium/src/+/master/docs/chromedriver_status.md Chrome]
* [https://docs.microsoft.com/en-us/microsoft-edge/webdriver#w3c-webdriver-specification-supporthttpsw3cgithubiowebdriverwebdriver-spechtml Edge]
* [https://developer.mozilla.org/en-US/docs/Mozilla/QA/Marionette/WebDriver/status Firefox]
* [https://github.com/operasoftware/operachromiumdriver Opera]: "''OperaChromiumDriver is a WebDriver implementation derived from ChromeDriver and adapted by Opera''". That's why I think it has at least the same limitations as ChromeDriver.

=== Big Picture ===
How the browser independent and browser dependent parts fit together:<br>

[[File:WebDriver.png|800px|||Big Picture - How everything fits together]]

=== Used Terms ===
<small>(Last modified: 2020/03/08)<br></small>

You will find the following terms when using WebDriver. We try to shed some light onto this subject here:

'''Marionette'''<br>
Marionette is an automation driver for Mozilla’s Gecko engine. It can remotely control either the UI or the internal JavaScript of a Gecko platform, such as Firefox. It can control both the chrome (i.e. menus and functions) or the content (the webpage loaded inside the browsing context), giving a high level of control and ability to replicate user actions. In addition to performing actions on the browser, Marionette can also read the properties and attributes of the DOM.<br>
Marionette consists of two parts: a server which takes requests and executes them in Gecko (the Marionette server ships with Firefox), and a client (the Marionette client ships with the GeckoDriver exe). The client sends commands to the server and the server executes the command inside the browser.<br>
For details please [https://firefox-source-docs.mozilla.org/testing/marionette/Intro.html visit this site].

'''ShadowRoot'''<br>
The ShadowRoot interface of the Shadow DOM API is the root node of a DOM subtree that is rendered separately from a document's main DOM tree.<br>
For details please [https://dom.spec.whatwg.org/#interface-shadowroot visit this site].

== Installation ==
<small>(Last modified: 2020/01/23)<br></small>

To automate your browser the following installation steps are needed:
* Download the files listed in section "[[WebDriver#Requirements|Requirements]]"
* Move the UDFs to a directory where SciTE and Autoit can find them:
** Json.au3 and BinaryCall.au3 from the JSON UDF
** wd_Core.au3 and wd_helper.au3 from the WebDriver UDF
** WinHttp.au3 and WinHttpConstants.au3 from the WinHttp UDF
* Move the browser dependent WebDriver to the same directory:
** chromedriver.exe (Chrome)
** geckodriver.exe (Firefox)
** msedgedriver.exe (Edge - Chromium) or MicrosoftWebDriver.exe (Edge - EdgeHTML)
* Run WD_Demo.au3 and select "DemoNavigation" to validate the installation.<br>The result (for Firefox) displayed in the DOS window should be similar to the following:
<syntaxhighlight lang="text">
1577745813519 geckodriver DEBUG Listening on 127.0.0.1:4444
1577745813744 webdriver::server DEBUG -> POST /session {"capabilities": {"alwaysMatch": {"browserName": "firefox", "acceptInsecureCerts":true}}}
1577745813746 geckodriver::capabilities DEBUG Trying to read firefox version from ini files
1577745813747 geckodriver::capabilities DEBUG Found version 71.0
1577745813757 mozrunner::runner INFO Running command: "C:\\Program Files\\Mozilla Firefox\\firefox.exe" "-marionette" "-foreground" "-no-remote" "-profile" "C:\\ ...
1577745813783 geckodriver::marionette DEBUG Waiting 60s to connect to browser on 127.0.0.1:55184
1577745817392 geckodriver::marionette DEBUG Connection to Marionette established on 127.0.0.1:55184.
1577745817464 webdriver::server DEBUG <- 200 OK {"value":{"sessionId":"925641bf-6c5d-4fe2-a985-02de9b1c7c74","capabilities":"acceptInsecureCerts":true,"browserName":"firefox", ...
</syntaxhighlight>

== Function reference ==
<small>(Last modified: 2020/03/07 - based on version 0.2.0.6)<br></small>

=== WD_CORE ===
The WD_Core.au3 file holds functions to implement the Webdriver W3C document.
{| class="wikitable"
|-
! Function !! Description !! Comment
|-
| _WD_Action || Perform various interactions with the web driver session || Use one of the following values for parameter $sCommand: ''refresh'', ''back'', ''forward'', ''url'', ''title'', ''actions''.<br>For command ''actions'': Pass the actions to be set using parameter $sOption. If $sOption is empty then the set actions will be removed.
|-
| _WD_Alert || Respond to user prompt || Use one of the following actions to respond to the user prompt: ''dismiss'', ''accept'', ''gettext'', ''sendtext'', ''status''
|-
| _WD_Cookies || Gets, sets, or deletes the session's cookies || Gets a single (command ''get'') or all (command ''getall'') cookies, ''adds'' or ''delete''s a single cookie
|-
| _WD_CreateSession|| Request new session from web driver || Define the capabilities of the browser with this function
|-
| _WD_DeleteSession || Delete existing session || Closes the session created by _WD_CreateSession
|-
| _WD_ElementAction || Perform action on designated element || Use one of the following actions: ''Name'', ''Rect'', ''Text'', ''Selected'', ''Enabled'', ''Displayed'', ''Active'', ''Attribute'', ''Property'', ''CSS'', ''Clear'', ''Click'', ''Value'', ''Screenshot''.<br>''Clear'', ''Click'' and ''Value'' use POST to modify or process the element. All other actions use GET to retrieve data from the element
|-
| _WD_ExecuteScript || Execute Javascipt commands ||
|-
| _WD_FindElement|| Find element(s) by designated strategy || You can specify whether the function should only return the first find or all of them
|-
| _WD_GetSource || Get page source ||
|-
| _WD_Navigate || Navigate to the designated URL ||
|-
| _WD_Option || Sets and get options for the web driver UDF || The following options can be used: ''Driver'' (set the full path name to web driver executable), ''DriverParams'' (parameters to pass to web driver executable), ''BaseURL'' (IP address used for web driver communication), ''Port'' (port used for web driver communication), ''BinaryFormat'' (format used to store binary data). If no value is passed to be set the current value is returned
|-
| _WD_Shutdown || Kill the web driver console app ||
|-
| _WD_Startup || Launch the designated web driver console app || The PID for the WD console is returned
|-
| _WD_Status || Get current web driver state || Returns a raw JSON response from the web driver
|-
| _WD_Timeouts || Set or retrieve the session timeout parameters || Specify the type and value of the timeout like this: '{"type":value}'. Example: '{"pageLoad":2000}'
|-
| _WD_Window || Perform interactions related to the current window || One of the following actions: ''window'' (get current tab's window handle), ''handles'' (get all window handles), ''maximize'' (maximize window), ''minimize'' (minimize window), ''fullscreen'' (set window to fullscreen), ''rect'' (get or set the window's size & position), ''screenshot'' (take screenshot of window), ''close'' (close current tab), ''switch'' (switch to designated tab), ''frame'' (switch to frame), ''parent'' (switch to parent frame)
|-
|}

=== WD_HELPER ===
The WD_Helper.au3 file holds functions to help you automate a web site.
{| class="wikitable"
|-
! Function !! Description !! Comment
|-
| _WD_Attach || Attach to existing browser tab ||
|-
| _WD_ConsoleVisible || Control visibility of the webdriver console app ||
|-
| _WD_DownloadFile || Download file and save to disk ||
|-
| _WD_ElementOptionSelect || Find and click on an option from a Select element ||
|-
| _WD_FrameEnter || Will enter the specified frame for subsequent WebDriver operations ||
|-
| _WD_FrameLeave || Will leave the current frame, to its parent, not necessarily the Top, for subsequent WebDriver operations ||
|-
| _WD_GetElementFromPoint || Retrieves reference to element descriped by x/y coordinate ||
|-
| _WD_GetFrameCount || Returns how many frames/iframes are in your current window/frame || It will not traverse to nested frames
|-
| _WD_GetMouseElement || Retrieves reference to element below mouse pointer ||
|-
| _WD_GetShadowRoot || ||
|-
| _WD_HighlightElement || Will highlight the specified element ||
|-
| _WD_HighlightElements || Will highlight multiple elements passed as an array ||
|-
| _WD_IsLatestRelease || Compares local UDF version to latest release on Github ||
|-
| _WD_IsWindowTop || Returns a boolean of the session being at the top level, or in a frame(s) ||
|-
| _WD_LastHTTPResult || Return the result of the last WinHTTP request ||
|-
| _WD_LinkClickByText || Simulate a mouse click on a link with text matching the provided string ||
|-
| _WD_LoadWait || Wait for a browser page load to complete before returning ||
|-
| _WD_NewTab || Create new tab using Javascript ||
|-
| _WD_Screenshot || Will return a screenshot of the browser window or a specified element ||
|-
| _WD_SelectFiles || Select files for uploading to a website ||
|-
| _WD_UpdateDriver || Replace web driver with newer version, if available ||
|-
| _WD_WaitElement || Wait for a element to be found in the current tab before returning ||
|-
| _WD_jQuerify || Inject jQuery library into current session ||
|-
|}

== Debugging ==
=== Debug the WebDriver setup ===
<small>(Last modified: 2020/01/27)<br></small>

==== Chrome ====
<div class="usermessage mw-customtoggle-DebugChrome1">Chrome does not start and the DOS window for chromedriver does not get displayed</div>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-DebugChrome1">
{| class="wikitable"
|-
! Problem !! Solution !! Reference
|-
| When running WD_Demo.au3 it does not start up Chrome and does not display the DOS window for chromedriver.<br>When you manually run the chromedriver in a DOS window you get message "[0.023][SEVERE]: CreatePlatformSocket() returned an error: An invalid argument was supplied."|| This could be caused by missing execution permission for the network drive. Please ask your IT admin for "Applocker" or "application directory whitelisting". <br>Or run the chrome driver from a local HDD and call _WD_Option to set the location of the webdriver executable. Example: _WD_Option("Driver", "C:\Local\WebDriver\chromedriver.exe") || [https://stackoverflow.com/questions/51056121/createplatformsocket-returned-an-error-an-invalid-argument-was-supplied-0x2 Stackoverflow]
|}
</div>

==== Firefox ====
<div class="usermessage mw-customtoggle-DebugFirefox1">Firefox does not start and the DOS window for geckodriver does not get displayed</div>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-DebugFirefox1">
{| class="wikitable"
|-
! Problem !! Solution !! Reference
|-
| When running WD_Demo.au3 it does not start up Firefox and does not display the DOS window for geckodriver.<br>When you manually run the geckodriver in a DOS window you get message "geckodriver: error: An invalid argument was supplied. (os error 10022)"|| This could be caused by missing execution permission for the network drive. Please ask your IT admin for "Applocker" or "application directory whitelisting". <br>Or run the gecko driver from a local HDD and call _WD_Option to set the location of the webdriver executable. Example: _WD_Option("Driver", "C:\Local\WebDriver\geckodriver.exe") || [https://stackoverflow.com/questions/51056121/createplatformsocket-returned-an-error-an-invalid-argument-was-supplied-0x2 Stackoverflow]
|}
</div>

=== Debug your Script ===

== FAQ ==
<small>(Last modified: 2020/03/01)<br></small>

<div class="usermessage mw-customtoggle-FAQ1">1. How to connect to a running browser instance</div>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-FAQ1">
<div class="toccolours mw-collapsible-content">Q: How can I connect to a running browser instance?<br>A: That's described (for Firefox, but should work similar for other browsers) in this [https://www.autoitscript.com/forum/topic/201106-webdriver-udf-help-support-ii/?do=findComment&comment=1444173 post] or in the [https://github.com/Danp2/WebDriver/wiki/Connecting-to-existing-browser-instance Github wiki].</div>
</div>

<div class="usermessage mw-customtoggle-FAQ2">2. How to hide the webdriver console</div>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-FAQ2">
<div class="toccolours mw-collapsible-content">Q: How can I hide the webdriver console?<br>A: The console can be completely hidden from the start by adding the following line near the beginning of your script:<br><syntaxhighlight lang="autoit">$_WD_DEBUG = $_WD_DEBUG_None ; You could also use $_WD_DEBUG_Error</syntaxhighlight>You can also control the visibility of the console with the function _WD_ConsoleVisible.</div>
</div>

<div class="usermessage mw-customtoggle-FAQ3">3. How to utilize an existing user profile</div>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-FAQ3">
<div class="toccolours mw-collapsible-content">Q: Can I use an existing user profile instead of the default behavior of using a new one?<br>A: This is controlled by your "capabilities" declaration, with each browser using a different method to implement. Here are some examples:<br>
<br>'''Chrome'''<syntaxhighlight lang="autoit">$sDesiredCapabilities = '{"capabilities": {"alwaysMatch": {"goog:chromeOptions": {"w3c": true, "args":["--user-data-dir=C:\\Users\\' & @UserName & '\\AppData\\Local\\Google\\Chrome\\User Data\\", "--profile-directory=Default"]}}}}'</syntaxhighlight>'''Firefox'''<syntaxhighlight lang="autoit">$sDesiredCapabilities = '{"capabilities":{"alwaysMatch": {"moz:firefoxOptions": {"args": ["-profile", "C:/Users/AppData/Roaming/Mozilla/Firefox/Profiles/gbjaumrnd.default"],"log": {"level": "trace"}}}}}'</syntaxhighlight></div>
</div>

<div class="usermessage mw-customtoggle-FAQ4">4. How to specify location of browser executable</div>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-FAQ4">
<div class="toccolours mw-collapsible-content">Q: Is it possible to launch a browser installed in a non-standard location?<br>A: This is controlled by your "capabilities" declaration. Here are some examples:<br>
<br>'''Chrome'''<syntaxhighlight lang="autoit">$sDesiredCapabilities = '{"capabilities": {"alwaysMatch": {"goog:chromeOptions": {"w3c": true, "binary":"C:\\Path\\To\\Alternate\\Browser\\chrome.exe" }}}}'
</syntaxhighlight>'''Firefox'''<syntaxhighlight lang="autoit">$sDesiredCapabilities = '{"desiredCapabilities":{"javascriptEnabled":true,"nativeEvents":true,"acceptInsecureCerts":true,"moz:firefoxOptions":{"binary":"C:\\Path\\To\\Alternate\\Browser\\firefox.exe"}}}'</syntaxhighlight>Alternate Firefox method:<br><syntaxhighlight lang="autoit">
_WD_Option('DriverParams', '--binary "C:\Program Files\Mozilla Firefox\firefox.exe" --log trace ')</syntaxhighlight></div>
</div>

<div class="usermessage mw-customtoggle-FAQ5">5. How to maximize the browser window</div>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-FAQ5">
<div class="toccolours mw-collapsible-content">Q: Is it possible to maximize the browser window?<br>A: Simply call the following function:<syntaxhighlight lang="autoit">_WD_Window($sSession, "Maximize")
</syntaxhighlight></div>
</div>

<div class="usermessage mw-customtoggle-FAQ6">6. How to specify location of WebDriver executable</div>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-FAQ6">
<div class="toccolours mw-collapsible-content">Q: Is it possible to launch the WebDriver executable from a specific location?<br>A: This is controlled by function "_WD_Option". Example:
<br><syntaxhighlight lang="autoit">_WD_Option("Driver", "C:\local\WebDriver\WebDriver.exe")</syntaxhighlight></div>
</div>

<div class="usermessage mw-customtoggle-FAQ7">7. How to retrieve the values of a drop-down list</div>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-FAQ7">
<div class="toccolours mw-collapsible-content">Q: How to retrieve the values of a drop-down list (<Select> tag)?<br>A1: Here's a simple way to do it:
<br><syntaxhighlight lang="autoit">$sElement = _WD_FindElement($sSession, $_WD_LOCATOR_ByXPath, "//select[@name='xxx']")
$sText = _WD_ElementAction($sSession, $sElement, 'property', 'innerText')
$aOptions = StringSplit ( $sText, @LF, $STR_NOCOUNT)
_ArrayDisplay($aOptions)</syntaxhighlight>
'xxx' is the name of the drop-down list.
<br>A2: This can now be accomplished using the function _WD_ElementSelectAction --<br><syntaxhighlight lang="autoit">$sElement = _WD_FindElement($sSession, $_WD_LOCATOR_ByXPath, "//select[@name='xxx']")
$aOptions = _WD_ElementSelectAction ($sSession, $sElement, 'options')
_ArrayDisplay($aOptions)</syntaxhighlight>
</div>
</div>

== Tools ==
The following tools will help you to automate your browser:
* [https://autonomiq.io/chropath/ ChroPath] plugin: Makes finding an element by XPath, ID or CSS incredibly easy (Chrome, Firefox, Opera)

== References ==
<small>(Last modified: 2020/01/28)<br></small>

Further information sources:
* W3C: https://www.w3.org/TR/webdriver/
* AutoIt WebDriver threads:
** Danp2's thread in the '''[https://www.autoitscript.com/forum/topic/191990-webdriver-udf-w3c-compliant-version-12242019 Example Scripts]''' forum - WebDriver UDF (W3C compliant version)
** Danp2's closed thread in the '''[https://www.autoitscript.com/forum/topic/192730-webdriver-udf-help-support/ General Help and Support]''' forum - WebDriver UDF - Help & Support (this is part I)
** Danp2's active thread in the '''[https://www.autoitscript.com/forum/topic/201106-webdriver-udf-help-support-ii/ General Help and Support II]''' forum - WebDriver UDF - Help & Support (II)
** Water's thread in the '''[https://www.autoitscript.com/forum/topic/201283-im-creating-a-webdriver-tutorial General Help and Support]''' forum - Discussion about this Wiki Page
** Water's thread in the '''[https://www.autoitscript.com/forum/topic/201537-webdriver-example-scripts-collection/ Example Scripts]''' forum - WebDriver example scripts collection

* WebDriver Exe documentation:
** [https://sites.google.com/a/chromium.org/chromedriver/ Chrome]
** [https://docs.microsoft.com/en-us/microsoft-edge/webdriver Edge]
** [https://docs.microsoft.com/en-us/microsoft-edge/webdriver-chromium Edge Chromium]
** [https://firefox-source-docs.mozilla.org/testing/geckodriver/ Firefox]
** [https://selenium.dev/documentation/en/webdriver/ Opera]

WebDriver

2020-02-22T01:56:45Z

Danp2: /* FAQ */

{{WIP}}
The W3C WebDriver API is a platform and language-neutral interface and wire protocol allowing programs or scripts to control the behavior of a web browser.

== Introduction ==

=== WebDriver API ===
WebDriver enables developers to create automated tests that simulate user interaction. This is different from JavaScript unit tests because WebDriver has access to functionality and information that JavaScript running in the browser doesn't, and it can more accurately simulate user events or OS-level events. WebDriver can also manage testing across multiple windows, tabs and webpages in a single test session.

=== WebDriver UDF ===
The WebDriver UDF allows 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 ===
<small>(Last modified: 2020/01/25)<br></small>

The following UDFs need to be installed - '''independent''' of the Browser you try to automate:
* [https://www.autoitscript.com/forum/topic/148114-a-non-strict-json-udf-jsmn JSON UDF]
* [https://www.autoitscript.com/forum/topic/84133-winhttp-functions/ WinHTTP UDF]
* [https://github.com/Danp2/WebDriver/releases/latest WebDriver UDF]
One of the following Drivers needs to be installed - '''depending''' on the Browser type and version you try to automate:
{| class="wikitable"
|-
! Browser !! Download Link !! Latest Version / Date !! Comments
|-
| Chrome || [https://sites.google.com/a/chromium.org/chromedriver/downloads Google] || 80.0.3987.16 / 2019.12.19 || Follow this [https://sites.google.com/a/chromium.org/chromedriver/downloads/version-selection link] to select the correct version depending on the Chrome version you run!
|-
| Edge || [https://developer.microsoft.com/en-us/microsoft-edge/tools/webdriver/ Microsoft] || 81.0.403.0 ||
|-
| Firefox || [https://github.com/mozilla/geckodriver/releases github] || 0.26 / 2019.10.12 || Firefox version ≥ 60 is recommended<br>
'''Note:''' You must still have the Microsoft Visual Studio redistributable runtime installed on your system for the binary to run. This is a known bug in version 0.26 which the authors weren't able fix for this release.
|-
| Opera || [https://github.com/operasoftware/operachromiumdriver/releases github] || 79.0.3945.79 - 2020.01.08 || The versioning of OperaDriver matches the Chromium version on which Opera browser is based on.
|}

=== Limitations ===
<small>(Last modified: 2020/01/28)<br></small>
Not all WebDriver functions have been implemented by each browser. To check the status goto the corresponding website below:

* [https://chromium.googlesource.com/chromium/src/+/master/docs/chromedriver_status.md Chrome]
* [https://docs.microsoft.com/en-us/microsoft-edge/webdriver#w3c-webdriver-specification-supporthttpsw3cgithubiowebdriverwebdriver-spechtml Edge]
* [https://developer.mozilla.org/en-US/docs/Mozilla/QA/Marionette/WebDriver/status Firefox]
* [https://github.com/operasoftware/operachromiumdriver Opera]: "''OperaChromiumDriver is a WebDriver implementation derived from ChromeDriver and adapted by Opera''". That's why I think it has at least the same limitations as the chromedriver.

=== Big Picture ===
How the browser independent and browser dependent parts fit together:<br>

[[File:WebDriver.png|800px|||Big Picture - How everything fits together]]

=== Used Terms ===
<small>(Last modified: 2020/01/03)<br></small>

You will find the following terms when using WebDriver. We try to shed some light onto this subject here:

==== Firefox ====
'''Marionette'''<br>
Marionette is an automation driver for Mozilla’s Gecko engine. It can remotely control either the UI or the internal JavaScript of a Gecko platform, such as Firefox. It can control both the chrome (i.e. menus and functions) or the content (the webpage loaded inside the browsing context), giving a high level of control and ability to replicate user actions. In addition to performing actions on the browser, Marionette can also read the properties and attributes of the DOM.<br>
Marionette consists of two parts: a server which takes requests and executes them in Gecko (the Marionette server ships with Firefox), and a client (the Marionette client ships with the GeckoDriver exe). The client sends commands to the server and the server executes the command inside the browser.<br>
For details please [https://firefox-source-docs.mozilla.org/testing/marionette/Intro.html visit this site].

== Installation ==
<small>(Last modified: 2020/01/23)<br></small>

To automate your browser the following installation steps are needed:
* Download the files listed in section "[[WebDriver#Requirements|Requirements]]"
* Move the UDFs to a directory where SciTE and Autoit can find them:
** Json.au3 and BinaryCall.au3 from the JSON UDF
** wd_Core.au3 and wd_helper.au3 from the WebDriver UDF
** WinHttp.au3 and WinHttpConstants.au3 from the WinHttp UDF
* Move the browser dependent WebDriver to the same directory:
** chromedriver.exe (Chrome)
** geckodriver.exe (Firefox)
** msedgedriver.exe (Edge - Chromium) or MicrosoftWebDriver.exe (Edge - EdgeHTML)
* Run WD_Demo.au3 and select "DemoNavigation" to validate the installation.<br>The result (for Firefox) displayed in the DOS window should be similar to the following:
<syntaxhighlight lang="text">
1577745813519 geckodriver DEBUG Listening on 127.0.0.1:4444
1577745813744 webdriver::server DEBUG -> POST /session {"capabilities": {"alwaysMatch": {"browserName": "firefox", "acceptInsecureCerts":true}}}
1577745813746 geckodriver::capabilities DEBUG Trying to read firefox version from ini files
1577745813747 geckodriver::capabilities DEBUG Found version 71.0
1577745813757 mozrunner::runner INFO Running command: "C:\\Program Files\\Mozilla Firefox\\firefox.exe" "-marionette" "-foreground" "-no-remote" "-profile" "C:\\ ...
1577745813783 geckodriver::marionette DEBUG Waiting 60s to connect to browser on 127.0.0.1:55184
1577745817392 geckodriver::marionette DEBUG Connection to Marionette established on 127.0.0.1:55184.
1577745817464 webdriver::server DEBUG <- 200 OK {"value":{"sessionId":"925641bf-6c5d-4fe2-a985-02de9b1c7c74","capabilities":"acceptInsecureCerts":true,"browserName":"firefox", ...
</syntaxhighlight>

== Function reference ==
<small>(Last modified: 2020/01/27 - based on version 0.2.0.5)<br></small>

=== WD_CORE ===
The WD_Core.au3 file holds functions to implement the Webdriver W3C document.
{| class="wikitable"
|-
! Function !! Description !! Comment
|-
| _WD_Action || Perform various interactions with the web driver session || Use one of the following values for parameter $sCommand: ''refresh'', ''back'', ''forward'', ''url'', ''title'', ''actions''.<br>For command ''actions'': Pass the actions to be set using parameter $sOption. If $sOption is empty then the set actions will be removed.
|-
| _WD_Alert || Respond to user prompt || Use one of the following actions to respond to the user prompt: ''dismiss'', ''accept'', ''gettext'', ''sendtext'', ''status''
|-
| _WD_Cookies || Gets, sets, or deletes the session's cookies || Gets a single (command ''get'') or all (command ''getall'') cookies, ''adds'' or ''delete''s a single cookie
|-
| _WD_CreateSession|| Request new session from web driver || Define the capabilities of the browser with this function
|-
| _WD_DeleteSession || Delete existing session || Closes the session created by _WD_CreateSession
|-
| _WD_ElementAction || Perform action on designated element || Use one of the following actions: ''Name'', ''Rect'', ''Text'', ''Selected'', ''Enabled'', ''Displayed'', ''Active'', ''Attribute'', ''Property'', ''CSS'', ''Clear'', ''Click'', ''Value'', ''Screenshot''.<br>''Clear'', ''Click'' and ''Value'' use POST to modify or process the element. All other actions use GET to retrieve data from the element
|-
| _WD_ExecuteScript || Execute Javascipt commands ||
|-
| _WD_FindElement|| Find element(s) by designated strategy || You can specify whether the function should only return the first find or all of them
|-
| _WD_GetSource || Get page source ||
|-
| _WD_Navigate || Navigate to the designated URL ||
|-
| _WD_Option || Sets and get options for the web driver UDF || The following options can be used: ''Driver'' (set the full path name to web driver executable), ''DriverParams'' (parameters to pass to web driver executable), ''BaseURL'' (IP address used for web driver communication), ''Port'' (port used for web driver communication), ''BinaryFormat'' (format used to store binary data). If no value is passed to be set the current value is returned
|-
| _WD_Shutdown || Kill the web driver console app ||
|-
| _WD_Startup || Launch the designated web driver console app || The PID for the WD console is returned
|-
| _WD_Status || Get current web driver state || Returns a raw JSON response from the web driver
|-
| _WD_Timeouts || Set or retrieve the session timeout parameters || Specify the type and value of the timeout like this: '{"type":value}'. Example: '{"pageLoad":2000}'
|-
| _WD_Window || Perform interactions related to the current window || One of the following actions: ''window'' (get current tab's window handle), ''handles'' (get all window handles), ''maximize'' (maximize window), ''minimize'' (minimize window), ''fullscreen'' (set window to fullscreen), ''rect'' (get or set the window's size & position), ''screenshot'' (take screenshot of window), ''close'' (close current tab), ''switch'' (switch to designated tab), ''frame'' (switch to frame), ''parent'' (switch to parent frame)
|-
|}

=== WD_HELPER ===
The WD_Helper.au3 file holds functions to help you automate a web site.
{| class="wikitable"
|-
! Function !! Description !! Comment
|-
| _WD_Attach || Attach to existing browser tab ||
|-
| _WD_ConsoleVisible || Control visibility of the webdriver console app ||
|-
| _WD_DownloadFile || Download file and save to disk ||
|-
| _WD_ElementOptionSelect || Find and click on an option from a Select element ||
|-
| _WD_FrameEnter || Will enter the specified frame for subsequent WebDriver operations ||
|-
| _WD_FrameLeave || Will leave the current frame, to its parent, not necessarily the Top, for subsequent WebDriver operations ||
|-
| _WD_GetElementFromPoint || Retrieves reference to element descriped by x/y coordinate ||
|-
| _WD_GetFrameCount || Returns how many frames/iframes are in your current window/frame || It will not traverse to nested frames
|-
| _WD_GetMouseElement || Retrieves reference to element below mouse pointer ||
|-
| _WD_GetShadowRoot || ||
|-
| _WD_HighlightElement || Will highlight the specified element ||
|-
| _WD_HighlightElements || Will highlight multiple elements passed as an array ||
|-
| _WD_IsLatestRelease || Compares local UDF version to latest release on Github ||
|-
| _WD_IsWindowTop || Returns a boolean of the session being at the top level, or in a frame(s) ||
|-
| _WD_LastHTTPResult || Return the result of the last WinHTTP request ||
|-
| _WD_LinkClickByText || Simulate a mouse click on a link with text matching the provided string ||
|-
| _WD_LoadWait || Wait for a browser page load to complete before returning ||
|-
| _WD_NewTab || Create new tab using Javascript ||
|-
| _WD_Screenshot || Will return a screenshot of the browser window or a specified element ||
|-
| _WD_SelectFiles || ||
|-
| _WD_UpdateDriver || Replace web driver with newer version, if available ||
|-
| _WD_WaitElement || Wait for a element to be found in the current tab before returning ||
|-
| _WD_jQuerify || Inject jQuery library into current session ||
|-
|}

== Debugging ==
=== Debug the WebDriver setup ===
<small>(Last modified: 2020/01/27)<br></small>

==== Chrome ====
<div class="usermessage mw-customtoggle-DebugChrome1">Chrome does not start and the DOS window for chromedriver does not get displayed</div>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-DebugChrome1">
{| class="wikitable"
|-
! Problem !! Solution !! Reference
|-
| When running WD_Demo.au3 it does not start up Chrome and does not display the DOS window for chromedriver.<br>When you manually run the chromedriver in a DOS window you get message "[0.023][SEVERE]: CreatePlatformSocket() returned an error: An invalid argument was supplied."|| This could be caused by missing execution permission for the network drive. Please ask your IT admin for "Applocker" or "application directory whitelisting". <br>Or run the chrome driver from a local HDD and call _WD_Option to set the location of the webdriver executable. Example: _WD_Option("Driver", "C:\Local\WebDriver\chromedriver.exe") || [https://stackoverflow.com/questions/51056121/createplatformsocket-returned-an-error-an-invalid-argument-was-supplied-0x2 Stackoverflow]
|}
</div>

==== Firefox ====
<div class="usermessage mw-customtoggle-DebugFirefox1">Firefox does not start and the DOS window for geckodriver does not get displayed</div>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-DebugFirefox1">
{| class="wikitable"
|-
! Problem !! Solution !! Reference
|-
| When running WD_Demo.au3 it does not start up Firefox and does not display the DOS window for geckodriver.<br>When you manually run the geckodriver in a DOS window you get message "geckodriver: error: An invalid argument was supplied. (os error 10022)"|| This could be caused by missing execution permission for the network drive. Please ask your IT admin for "Applocker" or "application directory whitelisting". <br>Or run the gecko driver from a local HDD and call _WD_Option to set the location of the webdriver executable. Example: _WD_Option("Driver", "C:\Local\WebDriver\geckodriver.exe") || [https://stackoverflow.com/questions/51056121/createplatformsocket-returned-an-error-an-invalid-argument-was-supplied-0x2 Stackoverflow]
|}
</div>

=== Debug your Script ===

== FAQ ==
<small>(Last modified: 2020/02/17)<br></small>

<div class="usermessage mw-customtoggle-FAQ1">How to connect to a running browser instance</div>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-FAQ1">
<div class="toccolours mw-collapsible-content">Q: How can I connect to a running browser instance?<br>A: That's described (for Firefox, but should work similar for other browsers) in this [https://www.autoitscript.com/forum/topic/201106-webdriver-udf-help-support-ii/?do=findComment&comment=1444173 post] or in the [https://github.com/Danp2/WebDriver/wiki/Connecting-to-existing-browser-instance Github wiki].</div>
</div>

<div class="usermessage mw-customtoggle-FAQ2">How to hide the webdriver console</div>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-FAQ2">
<div class="toccolours mw-collapsible-content">Q: How can I hide the webdriver console?<br>A: The console can be completely hidden from the start by adding the following line near the beginning of your script:<br><syntaxhighlight lang="autoit">$_WD_DEBUG = $_WD_DEBUG_None ; You could also use $_WD_DEBUG_Error</syntaxhighlight>You can also control the visibility of the console with the function _WD_ConsoleVisible.</div>
</div>

<div class="usermessage mw-customtoggle-FAQ3">How to utilize an existing user profile</div>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-FAQ3">
<div class="toccolours mw-collapsible-content">Q: Can I use an existing user profile instead of the default behavior of using a new one?<br>A: This is controlled by your "capabilities" declaration, with each browser using a different method to implement. Here are some examples --<br>
<br>'''Chrome'''<syntaxhighlight lang="autoit">$sDesiredCapabilities = '{"capabilities": {"alwaysMatch": {"goog:chromeOptions": {"w3c": true, "args":["--user-data-dir=C:\\Users\\' & @UserName & '\\AppData\\Local\\Google\\Chrome\\User Data\\", "--profile-directory=Default"]}}}}'</syntaxhighlight>'''Firefox'''<syntaxhighlight lang="autoit">$sDesiredCapabilities = '{"capabilities":{"alwaysMatch": {"moz:firefoxOptions": {"args": ["-profile", "C:/Users/AppData/Roaming/Mozilla/Firefox/Profiles/gbjaumrnd.default"],"log": {"level": "trace"}}}}}'</syntaxhighlight></div>
</div>

<div class="usermessage mw-customtoggle-FAQ4">How to specify location of browser executable</div>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-FAQ4">
<div class="toccolours mw-collapsible-content">Q: Is it possible to launch a browser installed in a non-standard location?<br>A: This is controlled by your "capabilities" declaration. Here are some examples --<br>
<br>'''Chrome'''<syntaxhighlight lang="autoit">$sDesiredCapabilities = '{"capabilities": {"alwaysMatch": {"goog:chromeOptions": {"w3c": true, "binary":"C:\\Path\\To\\Alternate\\Browser\\chrome.exe" }}}}'
</syntaxhighlight>'''Firefox'''<syntaxhighlight lang="autoit">$sDesiredCapabilities = '{"desiredCapabilities":{"javascriptEnabled":true,"nativeEvents":true,"acceptInsecureCerts":true,"moz:firefoxOptions":{"binary":"C:\\Path\\To\\Alternate\\Browser\\firefox.exe"}}}'</syntaxhighlight>Alternate Firefox method --<br><syntaxhighlight lang="autoit">
_WD_Option('DriverParams', '--binary "C:\Program Files\Mozilla Firefox\firefox.exe" --log trace ')</syntaxhighlight></div>
</div>

<div class="usermessage mw-customtoggle-FAQ5">How to maximize the browser window</div>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-FAQ5">
<div class="toccolours mw-collapsible-content">Q: Is it possible to maximize the browser window?<br>A: Simply call the following function:<syntaxhighlight lang="autoit">_WD_Window($sSession, "Maximize")
</syntaxhighlight></div>
</div>

<div class="usermessage mw-customtoggle-FAQ6">How to specify location of WebDriver executable</div>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-FAQ6">
<div class="toccolours mw-collapsible-content">Q: Is it possible to launch the WebDriver executable from a specific location?<br>A: This is controlled by function "_WD_Option". Example:
<br><syntaxhighlight lang="autoit">_WD_Option("Driver", "C:\local\WebDriver\WebDriver.exe")</syntaxhighlight></div>
</div>

== Tools ==
The following tools will help you to automate your browser:
* [https://autonomiq.io/chropath/ ChroPath] plugin: Makes finding an element by XPath, ID or CSS incredibly easy (Chrome, Firefox, Opera)

== References ==
<small>(Last modified: 2020/01/28)<br></small>

Further information sources:
* W3C: https://www.w3.org/TR/webdriver/
* AutoIt WebDriver threads:
** Danp2's thread in the '''[https://www.autoitscript.com/forum/topic/191990-webdriver-udf-w3c-compliant-version-12242019 Example Scripts]''' forum
** Danp2's thread in the '''[https://www.autoitscript.com/forum/topic/192730-webdriver-udf-help-support/ General Help and Support]''' forum
** WebDriver '''[https://www.autoitscript.com/forum/topic/201537-webdriver-example-scripts-collection/ Example Scripts Collection]'''
* WebDriver Exe documentation
** [https://sites.google.com/a/chromium.org/chromedriver/ Chrome]
** [https://docs.microsoft.com/en-us/microsoft-edge/webdriver Edge]
** [https://firefox-source-docs.mozilla.org/testing/geckodriver/ Firefox]
** [https://selenium.dev/documentation/en/webdriver/ Opera]

WebDriver

2020-01-28T16:23:18Z

Danp2: /* FAQ */

{{WIP}}
The W3C WebDriver API is a platform and language-neutral interface and wire protocol allowing programs or scripts to control the behavior of a web browser.

== Introduction ==

=== WebDriver API ===
WebDriver enables developers to create automated tests that simulate user interaction. This is different from JavaScript unit tests because WebDriver has access to functionality and information that JavaScript running in the browser doesn't, and it can more accurately simulate user events or OS-level events. WebDriver can also manage testing across multiple windows, tabs and webpages in a single test session.

=== WebDriver UDF ===
The WebDriver UDF allows 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 ===
<small>(Last modified: 2020/01/25)<br></small>

The following UDFs need to be installed - '''independent''' of the Browser you try to automate:
* [https://www.autoitscript.com/forum/topic/148114-a-non-strict-json-udf-jsmn JSON UDF]
* [https://www.autoitscript.com/forum/topic/84133-winhttp-functions/ WinHTTP UDF]
* [https://github.com/Danp2/WebDriver/releases/latest WebDriver UDF]
One of the following Drivers needs to be installed - '''depending''' on the Browser type and version you try to automate:
{| class="wikitable"
|-
! Browser !! Download Link !! Latest Version / Date !! Comments
|-
| Chrome || [https://sites.google.com/a/chromium.org/chromedriver/downloads Google] || 80.0.3987.16 / 2019.12.19 || Follow this [https://sites.google.com/a/chromium.org/chromedriver/downloads/version-selection link] to select the correct version depending on the Chrome version you run!
|-
| Edge || [https://developer.microsoft.com/en-us/microsoft-edge/tools/webdriver/ Microsoft] || 81.0.403.0 ||
|-
| Firefox || [https://github.com/mozilla/geckodriver/releases github] || 0.26 / 2019.10.12 || Firefox version ≥ 60 is recommended<br>
'''Note:''' You must still have the Microsoft Visual Studio redistributable runtime installed on your system for the binary to run. This is a known bug in version 0.26 which the authors weren't able fix for this release.
|-
| Opera || [https://github.com/operasoftware/operachromiumdriver/releases github] || 79.0.3945.79 - 2020.01.08 || The versioning of OperaDriver matches the Chromium version on which Opera browser is based on.
|}

=== Limitations ===
<small>(Last modified: 2020/01/28)<br></small>
Not all WebDriver functions have been implemented by each browser. To check the status goto the corresponding website below:

* [https://chromium.googlesource.com/chromium/src/+/master/docs/chromedriver_status.md Chrome]
* [https://docs.microsoft.com/en-us/microsoft-edge/webdriver#w3c-webdriver-specification-supporthttpsw3cgithubiowebdriverwebdriver-spechtml Edge]
* [https://developer.mozilla.org/en-US/docs/Mozilla/QA/Marionette/WebDriver/status Firefox]
* [https://github.com/operasoftware/operachromiumdriver Opera]: "''OperaChromiumDriver is a WebDriver implementation derived from ChromeDriver and adapted by Opera''". That's why I think it has at least the same limitations as the chromedriver.

=== Big Picture ===
How the browser independent and browser dependent parts fit together:<br>

[[File:WebDriver.png|800px|||Big Picture - How everything fits together]]

=== Used Terms ===
<small>(Last modified: 2020/01/03)<br></small>

You will find the following terms when using WebDriver. We try to shed some light onto this subject here:

==== Firefox ====
'''Marionette'''<br>
Marionette is an automation driver for Mozilla’s Gecko engine. It can remotely control either the UI or the internal JavaScript of a Gecko platform, such as Firefox. It can control both the chrome (i.e. menus and functions) or the content (the webpage loaded inside the browsing context), giving a high level of control and ability to replicate user actions. In addition to performing actions on the browser, Marionette can also read the properties and attributes of the DOM.<br>
Marionette consists of two parts: a server which takes requests and executes them in Gecko (the Marionette server ships with Firefox), and a client (the Marionette client ships with the GeckoDriver exe). The client sends commands to the server and the server executes the command inside the browser.<br>
For details please [https://firefox-source-docs.mozilla.org/testing/marionette/Intro.html visit this site].

== Installation ==
<small>(Last modified: 2020/01/23)<br></small>

To automate your browser the following installation steps are needed:
* Download the files listed in section "[[WebDriver#Requirements|Requirements]]"
* Move the UDFs to a directory where SciTE and Autoit can find them:
** Json.au3 and BinaryCall.au3 from the JSON UDF
** wd_Core.au3 and wd_helper.au3 from the WebDriver UDF
** WinHttp.au3 and WinHttpConstants.au3 from the WinHttp UDF
* Move the browser dependent WebDriver to the same directory:
** chromedriver.exe (Chrome)
** geckodriver.exe (Firefox)
** msedgedriver.exe (Edge - Chromium) or MicrosoftWebDriver.exe (Edge - EdgeHTML)
* Run WD_Demo.au3 and select "DemoNavigation" to validate the installation.<br>The result (for Firefox) displayed in the DOS window should be similar to the following:
<syntaxhighlight lang="text">
1577745813519 geckodriver DEBUG Listening on 127.0.0.1:4444
1577745813744 webdriver::server DEBUG -> POST /session {"capabilities": {"alwaysMatch": {"browserName": "firefox", "acceptInsecureCerts":true}}}
1577745813746 geckodriver::capabilities DEBUG Trying to read firefox version from ini files
1577745813747 geckodriver::capabilities DEBUG Found version 71.0
1577745813757 mozrunner::runner INFO Running command: "C:\\Program Files\\Mozilla Firefox\\firefox.exe" "-marionette" "-foreground" "-no-remote" "-profile" "C:\\ ...
1577745813783 geckodriver::marionette DEBUG Waiting 60s to connect to browser on 127.0.0.1:55184
1577745817392 geckodriver::marionette DEBUG Connection to Marionette established on 127.0.0.1:55184.
1577745817464 webdriver::server DEBUG <- 200 OK {"value":{"sessionId":"925641bf-6c5d-4fe2-a985-02de9b1c7c74","capabilities":"acceptInsecureCerts":true,"browserName":"firefox", ...
</syntaxhighlight>

== Function reference ==
<small>(Last modified: 2020/01/27 - based on version 0.2.0.5)<br></small>

=== WD_CORE ===
The WD_Core.au3 file holds functions to implement the Webdriver W3C document.
{| class="wikitable"
|-
! Function !! Description !! Comment
|-
| _WD_Action || Perform various interactions with the web driver session || Use one of the following values for parameter $sCommand: ''refresh'', ''back'', ''forward'', ''url'', ''title'', ''actions''.<br>For command ''actions'': Pass the actions to be set using parameter $sOption. If $sOption is empty then the set actions will be removed.
|-
| _WD_Alert || Respond to user prompt || Use one of the following actions to respond to the user prompt: ''dismiss'', ''accept'', ''gettext'', ''sendtext'', ''status''
|-
| _WD_Cookies || Gets, sets, or deletes the session's cookies || Gets a single (command ''get'') or all (command ''getall'') cookies, ''adds'' or ''delete''s a single cookie
|-
| _WD_CreateSession|| Request new session from web driver || Define the capabilities of the browser with this function
|-
| _WD_DeleteSession || Delete existing session || Closes the session created by _WD_CreateSession
|-
| _WD_ElementAction || Perform action on designated element || Use one of the following actions: ''Name'', ''Rect'', ''Text'', ''Selected'', ''Enabled'', ''Displayed'', ''Active'', ''Attribute'', ''Property'', ''CSS'', ''Clear'', ''Click'', ''Value'', ''Screenshot''.<br>''Clear'', ''Click'' and ''Value'' use POST to modify or process the element. All other actions use GET to retrieve data from the element
|-
| _WD_ExecuteScript || Execute Javascipt commands ||
|-
| _WD_FindElement|| Find element(s) by designated strategy || You can specify whether the function should only return the first find or all of them
|-
| _WD_GetSource || Get page source ||
|-
| _WD_Navigate || Navigate to the designated URL ||
|-
| _WD_Option || Sets and get options for the web driver UDF || The following options can be used: ''Driver'' (set the full path name to web driver executable), ''DriverParams'' (parameters to pass to web driver executable), ''BaseURL'' (IP address used for web driver communication), ''Port'' (port used for web driver communication), ''BinaryFormat'' (format used to store binary data). If no value is passed to be set the current value is returned
|-
| _WD_Shutdown || Kill the web driver console app ||
|-
| _WD_Startup || Launch the designated web driver console app || The PID for the WD console is returned
|-
| _WD_Status || Get current web driver state || Returns a raw JSON response from the web driver
|-
| _WD_Timeouts || Set or retrieve the session timeout parameters || Specify the type and value of the timeout like this: '{"type":value}'. Example: '{"pageLoad":2000}'
|-
| _WD_Window || Perform interactions related to the current window || One of the following actions: ''window'' (get current tab's window handle), ''handles'' (get all window handles), ''maximize'' (maximize window), ''minimize'' (minimize window), ''fullscreen'' (set window to fullscreen), ''rect'' (get or set the window's size & position), ''screenshot'' (take screenshot of window), ''close'' (close current tab), ''switch'' (switch to designated tab), ''frame'' (switch to frame), ''parent'' (switch to parent frame)
|-
|}

=== WD_HELPER ===
The WD_Helper.au3 file holds functions to help you automate a web site.
{| class="wikitable"
|-
! Function !! Description !! Comment
|-
| _WD_Attach || Attach to existing browser tab ||
|-
| _WD_ConsoleVisible || Control visibility of the webdriver console app ||
|-
| _WD_DownloadFile || Download file and save to disk ||
|-
| _WD_ElementOptionSelect || Find and click on an option from a Select element ||
|-
| _WD_FrameEnter || Will enter the specified frame for subsequent WebDriver operations ||
|-
| _WD_FrameLeave || Will leave the current frame, to its parent, not necessarily the Top, for subsequent WebDriver operations ||
|-
| _WD_GetElementFromPoint || Retrieves reference to element descriped by x/y coordinate ||
|-
| _WD_GetFrameCount || Returns how many frames/iframes are in your current window/frame || It will not traverse to nested frames
|-
| _WD_GetMouseElement || Retrieves reference to element below mouse pointer ||
|-
| _WD_GetShadowRoot || ||
|-
| _WD_HighlightElement || Will highlight the specified element ||
|-
| _WD_HighlightElements || Will highlight multiple elements passed as an array ||
|-
| _WD_IsLatestRelease || Compares local UDF version to latest release on Github ||
|-
| _WD_IsWindowTop || Returns a boolean of the session being at the top level, or in a frame(s) ||
|-
| _WD_LastHTTPResult || Return the result of the last WinHTTP request ||
|-
| _WD_LinkClickByText || Simulate a mouse click on a link with text matching the provided string ||
|-
| _WD_LoadWait || Wait for a browser page load to complete before returning ||
|-
| _WD_NewTab || Create new tab using Javascript ||
|-
| _WD_Screenshot || Will return a screenshot of the browser window or a specified element ||
|-
| _WD_SelectFiles || ||
|-
| _WD_UpdateDriver || Replace web driver with newer version, if available ||
|-
| _WD_WaitElement || Wait for a element to be found in the current tab before returning ||
|-
| _WD_jQuerify || Inject jQuery library into current session ||
|-
|}

== Debugging ==
=== Debug the WebDriver setup ===
<small>(Last modified: 2020/01/27)<br></small>

==== Chrome ====
<div class="usermessage mw-customtoggle-DebugChrome1">Chrome does not start and the DOS window for chromedriver does not get displayed</div>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-DebugChrome1">
{| class="wikitable"
|-
! Problem !! Solution !! Reference
|-
| When running WD_Demo.au3 it does not start up Chrome and does not display the DOS window for chromedriver.<br>When you manually run the chromedriver in a DOS window you get message "[0.023][SEVERE]: CreatePlatformSocket() returned an error: An invalid argument was supplied."|| This could be caused by missing execution permission for the network drive. Please ask your IT admin for "Applocker" or "application directory whitelisting". <br>Or run the chrome driver from a local HDD and call _WD_Option to set the location of the webdriver executable. Example: _WD_Option("Driver", "C:\Local\WebDriver\chromedriver.exe") || [https://stackoverflow.com/questions/51056121/createplatformsocket-returned-an-error-an-invalid-argument-was-supplied-0x2 Stackoverflow]
|}
</div>

==== Firefox ====
<div class="usermessage mw-customtoggle-DebugFirefox1">Firefox does not start and the DOS window for geckodriver does not get displayed</div>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-DebugFirefox1">
{| class="wikitable"
|-
! Problem !! Solution !! Reference
|-
| When running WD_Demo.au3 it does not start up Firefox and does not display the DOS window for geckodriver.<br>When you manually run the geckodriver in a DOS window you get message "geckodriver: error: An invalid argument was supplied. (os error 10022)"|| This could be caused by missing execution permission for the network drive. Please ask your IT admin for "Applocker" or "application directory whitelisting". <br>Or run the gecko driver from a local HDD and call _WD_Option to set the location of the webdriver executable. Example: _WD_Option("Driver", "C:\Local\WebDriver\geckodriver.exe") || [https://stackoverflow.com/questions/51056121/createplatformsocket-returned-an-error-an-invalid-argument-was-supplied-0x2 Stackoverflow]
|}
</div>

=== Debug your Script ===

== FAQ ==
<small>(Last modified: 2020/01/16)<br></small>

<div class="usermessage mw-customtoggle-FAQ1">How to connect to a running browser instance</div>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-FAQ1">
<div class="toccolours mw-collapsible-content">Q: How can I connect to a running browser instance?<br>A: That's described (for Firefox, but should work similar for other browsers) in this [https://www.autoitscript.com/forum/topic/201106-webdriver-udf-help-support-ii/?do=findComment&comment=1444173 post] or in the [https://github.com/Danp2/WebDriver/wiki/Connecting-to-existing-browser-instance Github wiki].</div>
</div>

<div class="usermessage mw-customtoggle-FAQ2">How to hide the webdriver console</div>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-FAQ2">
<div class="toccolours mw-collapsible-content">Q: How can I hide the webdriver console?<br>A: The console can be completely hidden from the start by adding the following line near the beginning of your script:<br><syntaxhighlight lang="autoit">$_WD_DEBUG = $_WD_DEBUG_None ; You could also use $_WD_DEBUG_Error</syntaxhighlight>You can also control the visibility of the console with the function _WD_ConsoleVisible.</div>
</div>

<div class="usermessage mw-customtoggle-FAQ3">How to utilize an existing user profile</div>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-FAQ3">
<div class="toccolours mw-collapsible-content">Q: Can I use an existing user profile instead of the default behavior of using a new one?<br>A: This is controlled by your "capabilities" declaration, with each browser using a different method to implement. Here are some examples --<br>
<br>'''Chrome'''<syntaxhighlight lang="autoit">$sDesiredCapabilities = '{"capabilities": {"alwaysMatch": {"goog:chromeOptions": {"w3c": true, "args":["--user-data-dir=C:\\Users\\' & @UserName & '\\AppData\\Local\\Google\\Chrome\\User Data\\", "--profile-directory=Default"]}}}}'</syntaxhighlight>'''Firefox'''<syntaxhighlight lang="autoit">$sDesiredCapabilities = '{"capabilities":{"alwaysMatch": {"moz:firefoxOptions": {"args": ["-profile", "C:/Users/AppData/Roaming/Mozilla/Firefox/Profiles/gbjaumrnd.default"],"log": {"level": "trace"}}}}}'</syntaxhighlight></div>
</div>

<div class="usermessage mw-customtoggle-FAQ4">How to specify location of browser executable</div>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-FAQ4">
<div class="toccolours mw-collapsible-content">Q: Is it possible to launch a browser installed in a non-standard location?<br>A: This is controlled by your "capabilities" declaration. Here are some examples --<br>
<br>'''Chrome'''<syntaxhighlight lang="autoit">$sDesiredCapabilities = '{"capabilities": {"alwaysMatch": {"goog:chromeOptions": {"w3c": true, "binary":"C:\\Path\\To\\Alternate\\Browser\\chrome.exe" }}}}'
</syntaxhighlight>'''Firefox'''<syntaxhighlight lang="autoit">$sDesiredCapabilities = '{"desiredCapabilities":{"javascriptEnabled":true,"nativeEvents":true,"acceptInsecureCerts":true,"moz:firefoxOptions":{"binary":"C:\\Path\\To\\Alternate\\Browser\\firefox.exe"}}}'</syntaxhighlight>Alternate Firefox method --<br><syntaxhighlight lang="autoit">
_WD_Option('DriverParams', '--binary "C:\Program Files\Mozilla Firefox\firefox.exe" --log trace ')</syntaxhighlight></div>
</div>

== Tools ==
The following tools will help you to automate your browser:
* [https://autonomiq.io/chropath/ ChroPath] plugin: Makes finding an element by XPath, ID or CSS incredibly easy (Chrome, Firefox, Opera)

== References ==
<small>(Last modified: 2020/01/28)<br></small>

Further information sources:
* W3C: https://www.w3.org/TR/webdriver/
* AutoIt WebDriver threads:
** Danp2's thread in the '''[https://www.autoitscript.com/forum/topic/191990-webdriver-udf-w3c-compliant-version-12242019 Example Scripts]''' forum
** Danp2's thread in the '''[https://www.autoitscript.com/forum/topic/192730-webdriver-udf-help-support/ General Help and Support]''' forum
** WebDriver '''[https://www.autoitscript.com/forum/topic/201537-webdriver-example-scripts-collection/ Example Scripts Collection]'''
* WebDriver Exe documentation
** [https://sites.google.com/a/chromium.org/chromedriver/ Chrome]
** [https://docs.microsoft.com/en-us/microsoft-edge/webdriver Edge]
** [https://firefox-source-docs.mozilla.org/testing/geckodriver/ Firefox]
** [https://selenium.dev/documentation/en/webdriver/ Opera]

WebDriver

2020-01-09T23:56:06Z

Danp2: /* FAQ */

WebDriver

2020-01-08T13:52:28Z

Danp2: /* FAQ */

WebDriver

2020-01-08T13:50:10Z

Danp2: /* FAQ */

WebDriver

2019-12-31T16:50:08Z

Danp2:

WebDriver

2019-12-30T23:42:37Z

Danp2: /* Connect to a running browser instance */

WebDriver

2019-12-30T22:46:33Z

Danp2: /* Installation */ Update console contents

FAQ

2018-03-02T12:52:46Z

Danp2: /* How can I control (click, edit etc) an external (html) application? */

This is a list of frequently asked questions asked on the forums.

Other FAQs include:
* The one found in the [http://www.autoitscript.com/autoit3/docs/faq.htm AutoIt HelpFile]. Much of it is about the transition from V2 to V3, but most is still relevant and should be a port of call, as well as this one.

==How can I debug my script?==

=== In SciTE ===
This one has a myriad of answers, but the most effective is to begin by using the [http://www.autoitscript.com/autoit3/scite/ SciTE4AutoIt3 Editor] to create or edit scripts. This program is useful in debugging for the following reasons:

* Syntax highlighting allows for immediate viewing of any mistakes from unended script tags or quotes. This allows the scripter to visibly see the difference between the following portions of code.
[[File:FAQ_Q1_2.jpg|center|Incorrect code]]
And the correct version:
[[File:FAQ_Q1_3.jpg|center||Correct Code]]
* Global syntax check built directly into the tools menu allows you to check an entire script for problems all at once.
* Built-in code tidying program that correctly indents untidy code and repairs messy scripts to allow them to be more readable. It also corrects problems with incorrectly capitalised function names and variables.
* Per-line trace insertion allows you to log every line of code executed to debug errors.
* Debug MsgBoxes or ConsoleWrites are able to be added anywhere in the script directly from SciTE. ConsoleWrite lines are less intrusive and prevent the added annoyance to the user of MsgBoxes.

You can also use AutoIt3Wrapper directive:
<syntaxhighlight lang="autoit">#AutoIt3Wrapper_Run_Debug_Mode=Y</syntaxhighlight>
[[File:FAQ_Q1_4.jpg|center|Picture of SciTE4AutoIt3]]

=== Using more code to check @error value ===
Nearly all functions will return something. Most of the time when a function fails, it returns 0 and sets @error. You can use this information not only to create scripts that handle for different errors but to debug and find out exactly why you are having problems. Check the help file for specific functions and their return values.

=== Via the Tray icon===
You can add this line at the top of your script (1 is on, 0 is off) to enable debugging from the tray icon.

<syntaxhighlight lang="autoit">AutoItSetOption ("TrayIconDebug", 1);0-off</syntaxhighlight>
Then if you run the script (uncompiled as an AU3 file), you can mouse over the AutoIt icon in the system tray (down by the clock) to display debugging information.

[[File:FAQ_Q1_1.jpg|center|Example output for TrayIconDebug]]

=== OutputDebugString native call ===
You can also debug a script on any computer by adding the following code to your script:

<syntaxhighlight lang="autoit">
Func _MyDebug($sMessage, $iError = @error, $iExtended = @extended)
If $iError Or $iExtended Then
$sMessage &= '[ @error = ' & $iError & ' @extended = ' & $iExtended & ' ]'
EndIf
DllCall("kernel32.dll", "none", "OutputDebugString", "str", $sMessage)
Return SetError($iError, $iExtended, '')
EndFunc ;==>_MyDebug
</syntaxhighlight>
Then, when you need to add a debug line, call it as necessary. Example:

<syntaxhighlight lang="autoit">_MyDebug("The value of Variable 1 at this time is " & $var1)</syntaxhighlight>
This debugging is completely transparent to the user, and is only viewable with a program such as DebugView from SysInternals. This method of debugging has the added advantage of being available to the developer in situations where is not acceptable or feasable to install SciTE on a client's unit.

=== Graphical debugger ===
Stumpii created a [http://www.autoitscript.com/forum/index.php?showtopic=21834 Graphical AutoIt Debugger], similar to Dev-C++'s debugging style.

[[File:FAQ_Q1_5.jpg|center|Stumpii's Graphical AutoIt Debugger]]

=== Another debugger for AutoIt ===
Heron created a [http://www.autoitscript.com/forum/index.php?showtopic=103142 Another debugger for AutoIt].

The latest version by asdf8 is here:
https://www.autoitscript.com/forum/topic/103142-another-debugger-for-autoit/?do=findComment&comment=1303208

==How can I run something that is not an exe file [.txt, .msi, .pdf,.jpg etc.] [or] How can I open a webpage in the default browser?==
It was for this reason that the ShellExecute function was created. Here is one example:

<syntaxhighlight lang="autoit">ShellExecute("C:\autoitscripts\test.au3", "", "", "edit", @SW_MAXIMIZE)</syntaxhighlight>

You can also specify a web address this way:

<syntaxhighlight lang="autoit">ShellExecute("http://www.autoitscript.com/forum", "", "", "open")</syntaxhighlight>

If you normally are able to right-click the file and select print, then you can also print the file from AutoIt using this function:

<syntaxhighlight lang="autoit">ShellExecute("C:\boot.ini", "", "", "print")</syntaxhighlight>

If you wish to open the file with the default program, you can do as follows:
<syntaxhighlight lang="autoit">ShellExecute("C:\autoitscripts\test.au3")</syntaxhighlight>

If you wish your script to wait until the process is finished, you can use the ShellExecuteWait function with the same parameters.

Note:
The default verb is the verb configured in the registry. If no verb is set as default in the registry then the "open" verb is used. If the "open" verb is not present then the first verb listed in the registry is used.

==How can I prevent more than one copy of my script from running at once, or detect another copy of my script running?==

=== _Singleton function ===
There are a few different ways to go about this. You can use a function called _Singleton to detect multiple instances of your script. An example of how to use this code:

<syntaxhighlight lang="autoit">#include <Misc.au3>
_Singleton("TheNameOfMyScript")</syntaxhighlight>

In this instance, the script will bring up some messages explaining to the user of the occurring events.
This example will show you how the above function can be used in a real world application.
<syntaxhighlight lang="autoit">#include <Misc.au3>
#include <MsgBoxConstants.au3>

If _Singleton("MyScriptName", 1) = 0 Then
; If successful, running our script a second time should cause us to fall through here
MsgBox($MB_ICONERROR, "User Generated Error Message", "Error: This script is already running!")
Else
; We have detected that we are the only instance running, now we will run a second instance to display _Singleton's function!
MsgBox($MB_ICONINFORMATION, "Information!", "We are the first instance of this script, press OK to run another instance and trigger the error message!")
Switch @Compiled
Case 1
Run(FileGetShortName(@ScriptFullPath));when running an app, it's usually better to use its short name
Case 0
Run(FileGetShortName(@AutoItExe) & ' /AutoIt3ExecuteScript ' & FileGetShortName(@ScriptFullPath))
EndSwitch
Sleep(1000)
MsgBox($MB_ICONINFORMATION, "Information!", "We ran a second instance, you should have recieved an error message!", 5)
EndIf
Exit</syntaxhighlight>

===_MutexExists function ===
Another method is to use _MutexExists.

<syntaxhighlight lang="autoit">#include <MsgBoxConstants.au3>

If _MutexExists("MydeswswScriptName") Then
; We know the script is already running. Let the user know.
MsgBox($MB_OK, "Script Name", "This script is already running. Using multiple copies of this script at the same time is unsupported!")
Exit
EndIf

;Function Author- Martin
Func _MutexExists($sOccurenceName)
Local $ERROR_ALREADY_EXISTS = 183, $handle, $lastError
$sOccurenceName = StringReplace($sOccurenceName, "", ""); to avoid error
$handle = DllCall("kernel32.dll", "int", "CreateMutex", "int", 0, "long", 1, "str", $sOccurenceName)
$lastError = DllCall("kernel32.dll", "int", "GetLastError")
Return $lastError[0] = $ERROR_ALREADY_EXISTS
EndFunc;==>_MutexExists</syntaxhighlight>

==How can I run my script as a service?==
This is also a question with multiple answers, and none of them are the only way to do it. The first question to ask yourself is whether or not you wish to install the service on other computers besides your own.

=== On your own computer - One time only ===
The easiest way to do this is to use Pirmasoft RunAsSvc. This program makes services easy to install and easy to remove when necessary.

=== On all computers that run your script===
To do this you can use SRVANY.EXE and [http://www.autoitscript.com/forum/index.php?showtopic=6487 ServiceControl.au3]. You can then use this code to install your script as a service:

<syntaxhighlight lang="autoit">
#include "ServiceControl.au3"
$servicename = "MyServiceName"
_CreateService("", $servicename, "My AutoIt Script", "C:\Path_to_\srvany.exe", "LocalSystem", "", 0x110)
RegWrite("HKLM\SYSTEM\CurrentControlSet\Services\" & $servicename & "\Parameters", "Application", "REG_SZ", @ScriptFullPath)
</syntaxhighlight>

Or use the following code to delete this service:

<syntaxhighlight lang="autoit">
#include "ServiceControl.au3"
$servicename = "MyServiceName"
_DeleteService("", $servicename)
</syntaxhighlight>

There is one caveat to setting up AutoIt as a service. If the service is not installed using the above code, it must have the "allow service to interact with the desktop" setting or else automation functions such as Control* or Win* functions will not function. To assure the service does indeed have this setting, use the following code:

<syntaxhighlight lang="autoit">RegWrite("HKLM\SYSTEM\CurrentControlSet\Services\[ServiceName]", "Type", "REG_DWORD", 0x110)</syntaxhighlight>

==How can I create/start/stop or otherwise control a service?==
There are two include libraries that are designed specifically to interact with services. These are the following:

* [http://www.autoitscript.com/forum/index.php?showtopic=6487 ServiceControl.au3] made by SumTingWong. Functionality:
** _StartService()
** _StopService()
** _ServiceExists()
** _ServiceRunning()
** _CreateService()
** _DeleteService()
* [http://www.autoitscript.com/forum/index.php?showtopic=22165 _NTServices.au3] made by CatchFish. Functionality:
** _ServiceStart()
** _ServiceStop()
** _ServiceStatus()
** _ServicePause()

==How can I display a progress bar while copying files or directories?==
There are a many different topics on how to do this. For more, just search the forums for [http://www.autoitscript.com/forum/index.php?act=Search&CODE=show&searchid=22030d4d4effe5e32da23fdb69ed772f&search_in=posts&result_type=topics&highlite=%2BCopy%2B Progress Copy + Progress].
* [http://www.autoitscript.com/forum/index.php?showtopic=11313 Copy with progress dialog]... By ezztabi
* [http://www.autoitscript.com/forum/index.php?showtopic=11888 Yet another copy with progress]... By SumTingWong
* [http://www.autoit.de/index.php?page=Thread&postID=58875 _MultiFileCopy]... By Oscar (German Forums)
* [http://www.autoitscript.com/forum/index.php?showtopic=19370&st=45&p=186198&#entry186198 _FileCopy]... By Jos

[[File:FAQ_Q6_1.jpg|center|Copy progress dialog by ezztabi]]

==How can I make a hotkey that only works in my GUI?==
It used to be quite tedious setting hotkeys to only work in your GUI. Now there is an easier way with the function GUISetAccelerators.

(From Helpfile example)
<syntaxhighlight lang="autoit">
; A simple custom messagebox that uses the MessageLoop mode
#include <GUIConstantsEx.au3>
#include <MsgBoxConstants.au3>

GUICreate("Custom Msgbox", 210, 80)

GUICtrlCreateLabel("Please click a button!", 10, 10)
$YesID = GUICtrlCreateButton("Yes", 10, 50, 50, 20)
$NoID = GUICtrlCreateButton("No", 80, 50, 50, 20)
$ExitID = GUICtrlCreateButton("Exit", 150, 50, 50, 20)

; Set accelerators for Ctrl+y and Ctrl+n
Dim $AccelKeys[2][2]=[["^y", $YesID], ["^n", $NoID]]
GUISetAccelerators($AccelKeys)

GUISetState(); display the GUI

Do
$msg = GUIGetMsg()

Select
Case $msg = $YesID
MsgBox($MB_OK, "You clicked on", "Yes")
Case $msg = $NoID
MsgBox($MB_OK, "You clicked on", "No")
Case $msg = $ExitID
MsgBox($MB_OK, "You clicked on", "Exit")
Case $msg = $GUI_EVENT_CLOSE
MsgBox($MB_OK, "You clicked on", "Close")
EndSelect
Until $msg = $GUI_EVENT_CLOSE Or $msg = $ExitID
</syntaxhighlight>

==How can I perform an action while a key is held down?==
You can use the _IsPressed() function to determine when a key is held down. The values that can be specified in this function are listed in the AutoIt Help File under User Defined Functions -> Misc Management -> _IsPressed. The following example will press the left mouse button while the k key is held down.

<syntaxhighlight lang="autoit">#include <Misc.au3>
$pressed = 0
While 1
If _IsPressed("4B") Then
If Not $pressed Then
ToolTip("K Key being held down")
MouseDown("left")
$pressed = 1
EndIf
Else
If $pressed Then
ToolTip("")
MouseUp("left")
$pressed = 0
EndIf
EndIf
Sleep(250)
WEnd</syntaxhighlight>

==How can I run my script on a remote computer over the network?==
The answer to this question depends on how much experience you have in networking. If the target system is a Windows system to which you have administrator access then you may use one of the following programs:

* PsExec from SysInternals
* BeyondExec from BeyondLogic

With either of these programs it is possible to launch any process on a remote system and even copy your script to the target computer before starting it. Neither these programs nor any others will work with Windows XP Home Edition unless you create a custom "command listener" that you manually install on the target system.

NOTE: Those of you with more advanced programming skills and a little imagination can figure out how to use the service control libraries and srvany.exe to do this same thing without either of the above mentioned programs.

==How can I make a User Defined Function with optional parameters like the ones I see in the Help File?==
You can specify optional parameters by giving them a default value in the Func declaration. An example of how this is done:
<syntaxhighlight lang="autoit">#include <MsgBoxConstants.au3>

Func testme($param1, $param2 = "nothing", $param3 = 5)
MsgBox($MB_OK, "", "Parameter one is required. The value of Parameter 1 is " & $param1 & @CRLF & _
"Parameter 2 is optional. The value of Parameter 2 is " & $param2 & @CRLF & _
"Parameter 3 is optional. The value of Parameter 3 is " & $param3)
EndFunc</syntaxhighlight>

If testme() is called with only one parameter [I.E. testme("test")] then the output is:
<blockquote>
Parameter one is required. The value of Parameter 1 is test<br />
Parameter 2 is optional. The value of Parameter 2 is nothing<br />
Parameter 3 is optional. The value of Parameter 3 is 5<br />
</blockquote>
However, if the function is called with more than one parameter like this testme("test", "something"), then the output is
<blockquote>
Parameter one is required. The value of Parameter 1 is test<br />
Parameter 2 is optional. The value of Parameter 2 is something<br />
Parameter 3 is optional. The value of Parameter 3 is 5<br />
</blockquote>

==How can I make my script start every time windows starts?==
You can use one of the following codes to allow your script to start with Windows:
<syntaxhighlight lang="autoit">RegWrite("HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\Run", "MyProgramName", "REG_SZ", @ScriptFullPath)</syntaxhighlight>
or
<syntaxhighlight lang="autoit">FileCreateShortcut(@ScriptFullPath, @StartupCommonDir & "\MyProgramName.lnk")</syntaxhighlight>
or place a Shortcut in the Startup folder, or the entire Executable. For Win8+ systems, use the Win+R keys to open a Run box, then "Shell:Startup" to access the Startup folder. Due to Windows User Account Control (UAC) restrictions, your script may require [https://www.autoitscript.com/autoit3/docs/keywords/RequireAdmin.htm #RequireAdmin].

==How can I have the script delete itself?==
The following function will delete the running script or .exe once it has finished execution.

'''WARNING: Make a copy of your script before calling this function!!!'''

<syntaxhighlight lang="autoit">
Func _SelfDelete($iDelay = 0)
Local $sCmdFile
FileDelete(@TempDir & "\scratch.bat")
$sCmdFile = 'ping -n ' & $iDelay & ' 127.0.0.1 > nul' & @CRLF _
& ':loop' & @CRLF _
& 'del "' & @ScriptFullPath & '"' & @CRLF _
& 'if exist "' & @ScriptFullPath & '" goto loop' & @CRLF _
& 'del %0'
FileWrite(@TempDir & "\scratch.bat", $sCmdFile)
Run(@TempDir & "\scratch.bat", @TempDir, @SW_HIDE)
EndFunc;==>_SelfDelete
</syntaxhighlight>

==How can I create a clickable website hyperlink in my gui?==
[[File:FAQ_Q13_1.jpg|center|Example GUI using Gary's UDF.]]

Gary Frost has made great advances in this area and has provided a [http://www.autoitscript.com/forum/index.php?showtopic=23111&st=0 UDF here] to help with doing this.

==How can I change the screen resolution / refresh rate / color depth?==
[http://www.autoitscript.com/forum/index.php?showtopic=20121 ChangeResolution.au3] is a library function created to make changes to these settings.

== How can I get the screen resolution in multiple monitor setups?==
The following code was worked out by Larry to determine the total screen resolution of multiple monitors:

<syntaxhighlight lang="autoit">#include <MsgBoxConstants.au3>

$aTSR = _GetTotalScreenResolution()
MsgBox($MB_OK, "Total Screen Resolution", "Width = " & $aTSR[0] & @CRLF & _
"Height = " & $aTSR[1])

;Original code by Larry.
;Edited by BrettF
Func _GetTotalScreenResolution()
Local $aRet[2]
Global Const $SM_VIRTUALWIDTH = 78
Global Const $SM_VIRTUALHEIGHT = 79
$VirtualDesktopWidth = DllCall("user32.dll", "int", "GetSystemMetrics", "int", $SM_VIRTUALWIDTH)
$aRet[0] = $VirtualDesktopWidth[0]
$VirtualDesktopHeight = DllCall("user32.dll", "int", "GetSystemMetrics", "int", $SM_VIRTUALHEIGHT)
$aRet[1] = $VirtualDesktopHeight[0]
Return $aRet
EndFunc
</syntaxhighlight>

== How can I register a file type with my program [or] How can I make files with a certain extension open in my program?==
[[File:FAQ_Q16_1.jpg|center|Example of how a file type can be registered.]]
File registration can be a tricky business for those who have not done it before. The first thing to be done is to modify your script to allow it to accept files from the command line. Here is one example of how to do this:

<syntaxhighlight lang="autoit">#include <MsgBoxConstants.au3>

;$cmdline[0] is the number of parameters passed
If $cmdline[0] <> 0 Then
$filename = $cmdline[1]
;Do something with the file here
MsgBox($MB_OK, "UXYFixer", 'The file name passed to the command line is "' & $filename & '"')
Else
; We did not get any command line parameters.
; If this is a command line only program, you would want to
; alert the user that the command line parameters were incorrect.
; If this is a GUI program (like a notepad program), you would
; want to simply continue from here without opening a file.
MsgBox($MB_OK, "UXYFixer", 'Command line parameters incorrect.' & @CRLF & 'Command line usage: "' & @ScriptName & '" "file to process"')
EndIf</syntaxhighlight>
After your script is ready to accept files, you can begin to register the file type you need with your program. To prevent errors, this-is-me has created a UDF that will allow you to do this easily:

Here is an example of how to register and unregister a file extension using this UDF:
<syntaxhighlight lang="autoit">#include "FileRegister.au3"
;================================================
;
; Description: FileRegister($ext, $cmd, $verb [, $def [, $icon = "" [, $desc = "" ]]])
; Registers a file type in Explorer
;
; Parameter(s): $ext - File Extension without period eg. "zip"
; $cmd - Program path with arguments eg. '"C:\test\testprog.exe" "%1"'
; (%1 is 1st argument, %2 is 2nd, etc.)
; $verb - Name of action to perform on file
; eg. "Open with ProgramName" or "Extract Files"
; $def - Action is the default action for this filetype
; (1 for true 0 for false)
; If the file is not already associated, this will be the default.
; $icon - Default icon for filetype including resource # if needed
; eg. "C:\test\testprog.exe,0" or "C:\test\filetype.ico"
; $desc - File Description eg. "Zip File" or "ProgramName Document"
;
;================================================

FileRegister("uxy", '"' & @ScriptFullPath & '" "%1"', "Open in UXYFixer", 1, @ScriptFullPath & ',0', "UXYFixer Document")

;========================================
;
; Description: FileUnRegister($ext, $verb)
; UnRegisters a verb for a file type in Explorer
; Parameter(s): $ext - File Extension without period eg. "zip"
; $verb - Name of file action to remove
; eg. "Open with ProgramName" or "Extract Files"
;
;========================================

FileUnRegister("uxy", "Open in UXYFixer")</syntaxhighlight>

'''Download here:'''
[http://www.autoitscript.com/forum/index.php?app=core&module=attach&section=attach&attach_id=26378 FileRegister.au3]

==Why doesn't my combobox (GUICtrlCreateCombo) show a dropdown list when clicked?==
When using GUICtrlCreateCombo be sure to enter the desired height for your combobox list in the "height" parameter. Windows XP automatically selects an appropriate height for combo boxes, but other versions of Windows usually do not.
<syntaxhighlight lang="autoit">$combo = GUICtrlCreateCombo("",10,10,200,20)</syntaxhighlight>
Would correctly be changed to:
<syntaxhighlight lang="autoit">$combo = GUICtrlCreateCombo("",10,10,200,200)</syntaxhighlight>

==Why isn't my thread getting any replies?==

=== Asking the right question right ===
Did you give a good description of the problem? If your title or explanation of the issue is not descriptive, users are likely to bypass your issue instead of helping. Post titles such as "Help Me", "I Have A Problem", "Question", "Help me fix my code", "This code doesn't work" or similarly worded titles will not readily draw forum users to your post. Experienced users (which are your best hope of resolving the issue) will often skip your post altogether in cases like this. An example of a post title descriptive enough to attract users to assist you is "Problem with WinWaitClose" or "Loop never ends".

=== Example for reproduction ===
Did you post example code? If you have not posted an example of the code you are having an issue with, then you will not recieve support. When posting a non-working script, please do so in the smallest amount of stand-alone code possible. If the code you post cannot run by itself on another person's computer, they will not be able to recreate the issue.

=== Speak English and speak it right ===
Did you use proper English? Here are guidelines for posting properly in the English language:
* Use proper case. THIS IS CONSIDERED YELLING. If you post in ALL UPPERCASE or all lowercase then you will not be taken seriously.
* Use proper punctuation. Complete sentences need only one trailing punctuation mark. Twelve exclamation points after every sentence <b>will not</b> get you an answer more quickly (just the opposite) Writing a sentence without simple punctuation such as commas reflects badly on your attention to detail, and is considered a good judge of the poster's coding style. If you cannot summon the intellect to write a sentence with correct punctuation, you will most likely miss simple coding mistakes such as unterminated quotes.

=== Breaking forum rules, law, modesty, or common sense ===
Show common sense by following the forum rules, http://www.autoitscript.com/forum/topic/169097-forum-rules/, as well as generally accepted forum etiquette. Repeated failure to do so will result in sanctions by the Moderation team as it ruins the experience for everyone.

==Why does the Ctrl key get stuck down after I run my script?==

=== Keys virtually stuck ===
It could equally be the Shift or the Alt key.

If you use Send in a script and you have a problem with keys being stuck down then Send is the most likely culprit. A similar problem can occur with BlockInput. The solution is generally quite simple. If there is a key like Shift or Alt held down at the start of the Send sequence, but that key is released by the time the Send sequence finishes then the key will get 'stuck' down. As an example of a solution, you could replace the Send function in your script with the _SendEx function below.

The _SendEx function waits for the Shift, Alt and Ctrl keys to be released or pops up a warning if the $warn parameter is not an empty string. Therefore it is not intended to be used when one of these modifier keys has been set to be down using any combination of {ALTDOWN}, {SHIFTDOWN} and {ALTDOWN}.
<syntaxhighlight lang="autoit">
#include < Misc.au3 >
#include <MsgBoxConstants.au3>
;Send the string $ss after the Shift Alt and Ctrl keys are released. Optionally give a warning after 1 sec if any of those keys are still down.
;Requires misc.au3 to be included in the script for the _IsPressed function.

Func _SendEx($ss, $warn = "")
Local $iT = TimerInit()

While _IsPressed("10") Or _IsPressed("11") Or _IsPressed("12")
If $warn <> "" And TimerDiff($iT) > 1000 Then
MsgBox($MB_TOPMOST, "Warning", $warn)
EndIf
Sleep(50)
WEnd
Send($ss)
EndFunc;==>_SendEx</syntaxhighlight>

=== General unstuck method ===
Shilbiz also discovered that the following can 'clear' locked down keys.
<syntaxhighlight lang="autoit"> ControlSend("", "", "", "text", 0)</syntaxhighlight>

==How can I use Pixel functions?==

=== Using a color change as an event ===
The following is an example of using the pixel to check if the colour has changed in a specific region.
<syntaxhighlight lang="autoit">#include <MsgBoxConstants.au3>

Local $PixelCheck = 0, $NewCheck
$PixelCheck = PixelCheckSum(40, 50, 60, 70); Get the checksum for this area.
While 1; Keep going
$NewCheck = PixelCheckSum(40, 50, 60, 70)
If $PixelCheck <> $NewCheck Then
; The old pixel checksum and the new one are different.
$PixelCheck = $NewCheck; Update the $PixelCheck to the new value
; Let us know it has changed. Change this to what you want to happen when the colour in the region changes.
Msgbox($MB_ICONWARNING,"PixelChecksum","Pixel region has changed !")
EndIf
Sleep(50); Just to give the CPU a bit of a break.
Wend</syntaxhighlight>

=== Searching for a specific pixel color ===
This is an example of searching for a specific pixel (red), both pure red (0xFF0000) and red in a few different shades.
<syntaxhighlight lang="autoit">#include <MsgBoxConstants.au3>
; Find a pure red pixel in the range 0,0-20,300

$coord = PixelSearch( 0, 0, 20, 300, 0xFF0000 )
If Not @error Then
MsgBox($MB_OK, "X and Y are:", $coord[0] & "," & $coord[1])
EndIf

; Find a pure red pixel or a red pixel within 10 shades variations of pure red
$coord = PixelSearch( 0, 0, 20, 300, 0xFF0000, 10 )
If Not @error Then
MsgBox($MB_OK, "X and Y are:", $coord[0] & "," & $coord[1])
EndIf</syntaxhighlight>

==Why doesn't my script work on a locked workstation?==
On a locked station any window will never be active (active is only dialog with text "Press Ctrl+Alt+Del"). In Windows locked state applications run hidden (behind that visible dialog) and do not have focus and active status. So generally don't use Send() MouseClick() WinActivate() WinWaitActive() WinActive() etc. Instead use ControlSend() ControlSetText() ControlClick() WinWait() WinExists() WinMenuSelectItem() etc. Doing so allows you to interact with an application regardless of whether it is active or not. It's possible to run such a script from scheduler on locked Windows stations.

==Where can I learn AutoIt? Are there any tutorials?==
AutoIt is a constantly growing and evolving language with a diverse and engaged community of volunteers. This wiki, along with the official forum, will always be your best place for answers to questions as well as examples and tutorials. With this in mind, below are a few resources that can also help you as you become familiar with the language:

AutoIt 1-2-3, an interactive classroom by Valuater:
[http://www.autoitscript.com/forum/index.php?showtopic=21048 http://www.autoitscript.com/forum/index.php?showtopic=21048]

BrettF's updated AutoIt tutorial:
[http://www.autoitscript.com/forum/index.php?showtopic=84960 http://www.autoitscript.com/forum/index.php?showtopic=84960]

"Learn To Program Using FREE Tools with AutoIt" PDF Book by Jfish
[https://www.autoitscript.com/forum/files/file/351-learn-to-program-using-free-tools-with-autoit/ Learn To Program Using FREE Tools with AutoIt]

YouTube has a number of videos available:
[http://www.youtube.com/results?search_query=autoit+tutorial&search_type=&aq=0&oq=AutoIt YouTube AutoIt tutorials list]

As always, when asking questions about a video or script you saw on an external source, please ensure you are adhering to the [[FAQ#Breaking_forum_rules.2C_law.2C_modesty.2C_or_common_Sense|forum rules]].

==Why does my script no longer decompile?==
Decompilation is no longer supported, and is only available for the older versions of AutoIt (Version 3.2.5.1 and earlier compiled scripts).

Please '''do not''' post on this topic; see the [[Decompiling FAQ]] for more information. Topics discussing decompilation of scripts will be locked immediately. Posting the source of a decompiled script with lead to immediate sanctions from the Moderation team, as it directly violates AutoIt EULA (End-User-License-Agreement).

<blockquote><i>You may not reverse engineer or disassemble the SOFTWARE PRODUCT or compiled scripts that were created with the SOFTWARE PRODUCT.</i></blockquote>

==How can I get a window handle when all I have is a PID?==
Refer to the following example showing converting and use when manipulating the window. The function is based on work by Smoke_N/Hubertus and Helge.
<syntaxhighlight lang="autoit">;Run process
$iPID = Run("Notepad.exe")

;Allow window to initialize...
Sleep (500)

;Get HWND.
$hWnd = _GetHwndFromPID($iPID)

;Maximize
WinSetState($hWnd, "", @SW_MAXIMIZE)

;Wait 2 seconds
Sleep(2000)

;Minimize
WinSetState($hWnd, "", @SW_MINIMIZE)

;Wait 2 seconds
Sleep(2000)

;Restore window
WinSetState($hWnd, "", @SW_RESTORE)

;Wait 2 seconds
Sleep(2000)

;Move top left corner of screen, and resize to 800x600
WinMove($hWnd, "", 0, 0, 800, 600)

;Wait 2 seconds
Sleep(2000)

;Calculate Center of screen.
$x = (@DesktopWidth / 2) - 400; Desktop width divided by 2, then minus half the width of the window
$y = (@DesktopHeight / 2) - 300; Desktop height divided by 2, then minus half the height of the window

;Move to center of screen
WinMove($hWnd, "", $x, $y)

;Wait 2 seconds
Sleep(2000)

;Close notepad
WinClose($hWnd)

;Function for getting HWND from PID
Func _GetHwndFromPID($PID)
$hWnd = 0
$winlist = WinList()
Do
For $i = 1 To $winlist[0][0]
If $winlist[$i][0] <> "" Then
$iPID2 = WinGetProcess($winlist[$i][1])
If $iPID2 = $PID Then
$hWnd = $winlist[$i][1]
ExitLoop
EndIf
EndIf
Next
Until $hWnd <> 0
Return $hWnd
EndFunc;==>_GetHwndFromPID</syntaxhighlight>

==How can I use single or double quotes in strings?==
It is a fairly simple concept once you get the basics down. Basically there are a few different ways to go about mixing quotes in strings.

A string in AutoIt can be encased in either single(') or double (") quotes. So if you want to add only one type of quote into your string, your first port of call is to use the other type of quote to encase the string. Like so:

<syntaxhighlight lang="autoit">#include <MsgBoxConstants.au3>

$var = "I am a 'quote' inside the string"
MsgBox ($MB_OK, "Test 1", $var)
$var = 'I wish I could be a "quote" inside the string!'
MsgBox ($MB_OK, "Test 1", $var)</syntaxhighlight>

If you have to have both types of quotes in the string, the easiest way is to escape the quote ending the string as so to speak. To do this, use two quotes instead of one. Like so:

<syntaxhighlight lang="autoit">#include <MsgBoxConstants.au3>

$var = 'I am a single ''quote'' inside the string made using "single quote!"'
MsgBox ($MB_OK, "Test 1", $var)</syntaxhighlight>

==When should I bump my threads?==
As a courtesy to other users you should only bump your post once in a 24 hour period. Doing this allows all users the chance to get helped equally. Also refer to [http://www.autoitscript.com/forum/index.php?showtopic=95704&view=findpost&p=688050 Why isn't my thread getting any replies?], as this will help you get replies.

==How can I protect my code from decompilation?==
The fact of the matter is '''you can't fully protect your code'''. AutoIt is an interpreted language, so all scripts are interpreted, and that script has to get stored somewhere. There is still hope though. You can take certain measures to make the decompiled code less usable to the person that decompiled it. The first step is to obfuscate your code. This causes the code to become less readable. Basically variables and functions are renamed, making it very hard to make head or tail of what is what.

Please see the [[Decompiling FAQ]] for more information.

==How can I decompile my AutoIt EXEs?==
You cannot decompile your AutoIt compiled scripts unless it was compiled with AutoIt 3.2.5.1 or earlier.

In order to be able to recover your script from the compiled executable, you can use the following:

<syntaxhighlight lang="autoit">;Original Author SmokeN
If $CMDLINE[0] Then
If $CMDLINE[1] == "/SOURCE" AND $CMDLINE[2] == "MYPASSWORD" Then
FileInstall("ThisSCript.au3", @ScriptDir & "\DecompiledScript.au3")
EndIf
EndIf</syntaxhighlight>

Then if you run the compiled script with the following command line parameters your source will be extracted.

<blockquote>myscript.exe /SOURCE MYPASSWORD</blockquote>

== What is proper forum etiquette? What rules are there for the forum?==
Proper forum etiquette will ensure you will stay a member of these forums. So try to follow these rules. Also see this [http://www.autoitscript.com/forum/index.php?showtopic=95704&st=15&p=688050&#entry688050 FAQ post], as you should follow what is outlined there as well.

* Use proper English. MSN speak and the like makes it very hard to understand what you want. Keep posts in proper case because UPPERCASE is considered yelling and lowercase makes you look stupid. Don't use more punctuation marks than necessary. For example ?!!!? and ????? is completely unnecessary.
* Before posting help with a script, make sure you follow these steps:
*# Search for your issue.
*#* There are many thousands of posts on this forum, and chances are your question has been asked before. Make sure to use a variety of terms to maximize your results.
*# Read the helpfile
*#* Most if not all things in the help file will have an example (native functions) or two. Give them a go to try see how the functions work. Most of the time it helps!
*# Give it a go
*#* Seriously, if you can't be bothered to give it a go, then why should we be bothered to help you? If you feel you can't do it and you don't try then how will you ever know? We always prefer that you give it a go because you can learn from your mistakes and hopefully understand it better.
*# Post your problem
*#* Make sure you post in the correct forum.
*#** <b>AutoIt Specific</b>
*#*** [https://www.autoitscript.com/forum/forum/2-autoit-general-help-and-support/ General Help and Support] (Most support questions)
*#*** [https://www.autoitscript.com/forum/forum/10-autoit-gui-help-and-support/ GUI Support] (Support for the Graphical User Interface)
*#*** [https://www.autoitscript.com/forum/forum/14-autoitx-help-and-support/ AutoItX Support] (Support for the COM, DLL, PowerShell and .NET add-ons for AutoIt)
*#** <b>Non-AutoIt</b>
*#*** Chat
*#*** Developer Chat
*#* Include a detailed description in the content of the post, and a detailed title
*#** Titles such as 'Help' and 'What's wrong?' are not acceptable. To get the most help with your problem, be as descriptive as you can in the title, but keep in mind your title cannot be too long.
*#** Make sure you also include a descriptive question. Just saying 'what is wrong with the following' is also not acceptable, as we will have no idea what the problem is. Describe what you think is wrong and what is not working. It makes our job easier.
*#* Always include your code
*#** It shows us that you have tried and gives us a head start with something to play with.
* Usually asking for a script is not taken too well, within reason. Keep in mind that this is a support forum, so please acknowledge that. We are here to help you with your scripts, not to spoon-feed code to you. If you do need something written for you, maybe try [http://www.rentacoder.com/ RentACoder], as they are more suited to requests.
* Don't PM other members asking for them to look at threads of to help you unless they request it. It is actually quite rude and annoying to receive PMs of that nature.
* Lurk a little before you dive right in. Read a number of posts, or check out the group's archives. Get a feel for the tone of the forum so you can participate accordingly.
* Say online exactly what you would say in person. In other words, if you wouldn't say it to the person's face in front of your Grandmother, you shouldn't type it here.
* Remember your face doesn't show. Words alone can convey sentiment, but without benefit of inflection or facial expression, they can be misconstrued. Use descriptive wording, emoticons or .gifs to ensure your meaning is clear. By the same token, don't jump to conclusions about another person's intent in posting an unclear comment. When in doubt, ask for clarification.
* Be respectful. Internet etiquette is similar to standard etiquette in this area. Appreciate that your opinion is one of many. You can disagree with another person without being disrespectful or rude to other people.
* Ignore Trolls. If you engage in conversation with one, you'll raise your blood pressure and empower the troll. You can't win a flame war, and you can't sway a troll's opinion. Often, they don't even care about the subject. They live for the conflict and nothing more. Trolls are common and not worthy of your time. Ignore their posts no matter how inflammatory and eventually they'll get bored and move on.
* When you have found an answer for your question:
*# Do not edit your post to be blank or to have worthless information. People may be searching for the same issue you have, so be courteous to them by leaving your question there.
*# It is also optional to add the word [SOLVED] into the title, as well as selecting the post that best answered your question. It can make the lives of people searching easier.
* Finally follow the rules:
** [http://www.autoitscript.com/forum/topic/169097-forum-rules/ Forum rules]
** [http://www.autoitscript.com/forum/index.php?showtopic=54168 Rules for the Chat forum]
** [http://www.autoitscript.com/forum/index.php?showtopic=65889 Rules for asking for source code]
** [http://www.autoitscript.com/forum/index.php?showtopic=37739 General policies and forum settings]

Some general points taken from [http://www.ehow.com/how_2106033_use-proper-forum-etiquette.html here].

==Are there forums available in my local language?==
Yes there are some available. Some forum members here participate in multiple forums.
* [http://www.autoit.de/ German Forums]
* [http://www.autoit.fr/ French Forums]
* [http://www.autoit.es/ Spanish Forums]
* [http://autoit-script.ru/ Russian Forums]
* [http://forum.autoitbrasil.com/ Portuguese Forums]

Please note that these are independent, community-run message boards and not just a translation of this board.

==How can I control (click, edit etc) an external (html) application?==
You can use the control* functions of autoit see helpfile
of use specific udf libraries
* [http://www.autoitscript.com/forum/topic/153520-iuiautomation-ms-framework-automate-chrome-ff-ie/ IUIAutomation for multiple applications]
* [http://www.autoitscript.com/forum/topic/154439-chrome-udf/ chrome chrome.au3]
* [http://www.autoitscript.com/forum/topic/149526-librariesieau3/ Internet explorer ie.au3]
* [http://www.autoitscript.com/forum/topic/95595-ffau3-v0601b-10/ firefox ff.au3] (End of life)
* [https://www.autoitscript.com/forum/topic/166830-java-object-automation-and-simple-spy/ java]
* [https://www.autoitscript.com/forum/search/?&q=Selenium Selenium]
* [https://www.autoitscript.com/forum/topic/191990-webdriver-udf-w3c-compliant-version/ WebDriver UDF (IE, Chrome, FireFox)]
<br />

You should use spy applications to identify objects like
* au3inf part of AutoIT
* [http://www.autoitscript.com/forum/topic/153520-iuiautomation-ms-framework-automate-chrome-ff-ie/ simplespy in the zip]
* jabsimplespy in examples section of the AutoIt forum
* [https://www.autoitscript.com/forum/topic/126716-control-viewer-autoit-window-info-tool/ control viewer]
* inspect as part of windows SDK
* VisualUIAVerifyNative.exe as part of windows SDK (8.1)
<br />

If above spy tools are not identifying your object you could try commercial tools (trials) like
* ranorex spy
* Testcomplete
* HP UFT
<br />

And your last recognition can be bitmaps
* search for GDI
* search for findBMP
* search for imagesearch

==Does AutoIt support database connections, such as SQL?==
Yes! UDFs exist for several popular SQL solutions, including SQLite, Firebird, MySQL, MSSQL and ODBC connections for PostGreSQL and others.

For an illustrative list, see this link:

* [https://www.autoitscript.com/wiki/User_Defined_Functions#Databases_and_web_connections Database and Web Connections]

A DBF UDF also exists

* [https://www.autoitscript.com/forum/topic/145142-dbf-udf-dbase-database-read-and-write-with-dll/ DBF UDF dBase with DLL]

==How can I include some files into my compiled Autoit's EXE?==
Use FileInstall() or ResourcesEx UDF from the forum Examples. Additional resources can also be included at compile time, click the "Res Add Files" tab.

==How can I test if checkbox / radiobutton is checked?==
Use this small function: If IsChecked($checkbox1) Then ...
<syntaxhighlight lang="autoit">
; by Zedna
Func IsChecked($control)
Return BitAND(GUICtrlRead($control), $GUI_CHECKED) = $GUI_CHECKED
EndFunc ;==>IsChecked
</syntaxhighlight>

==How to use the {enter} key as a Tab?==
Use
[https://www.autoitscript.com/autoit3/docs/functions/GUISetAccelerators.htm Accelerator keys]
<syntaxhighlight lang="autoit">

; by Melba23
#include <GUIConstantsEx.au3>
#include <MsgBoxConstants.au3>
#include <WinAPI.au3>

$hGUI = GUICreate("Test", 500, 500)

$cInput_1 = GUICtrlCreateInput("", 10, 10, 200, 20)
$cInput_2 = GUICtrlCreateInput("", 10, 50, 200, 20)
$cInput_3 = GUICtrlCreateInput("", 10, 90, 200, 20)

$cButton_1 = GUICtrlCreateButton("Button 1", 250, 10, 80, 30)
$cButton_2 = GUICtrlCreateButton("Button 2", 250, 50, 80, 30)
$cButton_3 = GUICtrlCreateButton("Button 3", 250, 90, 80, 30)

$cEnter = GUICtrlCreateDummy()

GUISetState()

Local $aAccelKeys[2][2] = [["{ENTER}", $cEnter], ["{TAB}", $cEnter]] ; Make {TAB} an accelerator
GUISetAccelerators($aAccelKeys)

While 1

Switch GUIGetMsg()
Case $GUI_EVENT_CLOSE
Exit
Case $cEnter
Switch _WinAPI_GetFocus()
Case GUICtrlGetHandle($cInput_1)
; Check the input content
If checkEntry() = True Then
; Correct so move to next input
GUICtrlSetState($cInput_2, $GUI_FOCUS)
EndIf
; Not correct so stay in current input
Case GUICtrlGetHandle($cInput_2)
If checkEntry() = True Then
GUICtrlSetState($cInput_3, $GUI_FOCUS)
EndIf
Case GUICtrlGetHandle($cInput_3)
If checkEntry() = True Then
ConsoleWrite("End" & @CRLF)
EndIf
Case Else
GUISetAccelerators(0) ; Remove accelerator link
ControlSend($hGUI, "", "", "{TAB}") ; Send {TAB} to the GUI
GUISetAccelerators($aAccelKeys) ; Reset the accelerator

EndSwitch
EndSwitch

WEnd

Func checkEntry()

; Random chance of correct answer or fail
If Mod(@SEC, 2) = 0 Then
MsgBox($MB_SYSTEMMODAL, "Test Fail", "Press Enter to close this message box")
Return False
EndIf
Return True

EndFunc ;==>checkEntry
</syntaxhighlight>

==Why are my number sort results wrong?==
AutoIt by default uses an alpha sort algorithm. This means that ABC is sorted correctly, but it sorts numbers as 1,10,2,22,3,31 where the user expects 1,2,3,10,22,31.
This can be remedied by using a custom sort function. An example of such a custom number sort by Valuater appears below. Search the Forum for [https://www.autoitscript.com/forum/topic/95383-sorting-numbers/ Number Sort] and [https://www.autoitscript.com/forum/topic/83626-natural-order-string-comparison/ Natural Order String Comparison]
<syntaxhighlight lang="autoit">
; by Valuater
#include <array.au3>

$Array = StringSplit("2,5,3,4,6,1,8,9,7", ",")

_ArraySortNum($Array)

_ArrayDisplay($Array, "Sorted Array")

Func _ArraySortNum(ByRef $n_array, $i_descending = 0, $i_start = 1)
Local $i_ub = UBound($n_array)
For $i_count = $i_start To $i_ub - 2
Local $i_se = $i_count
If $i_descending Then
For $x_count = $i_count To $i_ub - 1
If Number($n_array[$i_se]) < Number($n_array[$x_count]) Then $i_se = $x_count
Next
Else
For $x_count = $i_count To $i_ub - 1
If Number($n_array[$i_se]) > Number($n_array[$x_count]) Then $i_se = $x_count
Next
EndIf
Local $i_hld = $n_array[$i_count]
$n_array[$i_count] = $n_array[$i_se]
$n_array[$i_se] = $i_hld
Next
EndFunc ;==>_ArraySortNum
</syntaxhighlight>

==How do I include AutoIt functions in a C# / C++ / VB programme? AutoItX==
AutoIt is also supplied as a combined COM and DLL version of AutoIt called AutoItX that allows you to add the unique features of AutoIt to your own favourite scripting or programming languages!
[https://www.autoitscript.com/site/autoit/ Info on AutoItX]

From AutoItX.chm:
AutoItX is a DLL version of AutoIt v3 that provides a subset of the features of AutoIt via an ActiveX/COM and DLL interface. This means that you can add AutoIt-like features to your favourite scripting and programming languages, e.g. VB, VBScript, Delphi, C, C++, Kixtart, and most other languages that support the use of DLLs.

Here are some C++ source code samples from various projects by [https://www.autoitscript.com/forum/profile/1-jon/ Jon]. Most are free to use but check any license files that accompany the downloads for details. All code was created in Microsoft Visual C (6 and 7) but most would probably compile under mingw32 as well.
[https://www.autoitscript.com/site/code/ Download C++ examples for AutoItX]

You don't need to regsvr it if you are using the c# library. The c# library uses the non-COM part of the DLL so it just needs to be in the same folder as the exe and add the assembly.dll to your project. From the documenation:

Using the Assembly from VB/C# within in Visual Studio is very easy:
* Add a reference to AutoItX3.Assembly.dll to your project
* Add a using AutoIt; statement in the files you want to use AutoIt functions
* Distribute your final executable with the files AutoItX3.Assembly.dll, AutoItX3.dll, AutoItX3_x64.dll.
* Write code like this C# example:
using AutoIt;
...
<syntaxhighlight lang="autoit">
; by Jon
// Wow, this is C#!
AutoItX.Run("notepad.exe");
AutoItX.WinWaitActive("Untitled");
AutoItX.Send("I'm in notepad");
IntPtr winHandle = AutoItX.WinGetHandle("Untitled");
AutoItX.WinKill(winHandle);
</syntaxhighlight>

From the AutoItX Help File (included in the default AutoIt install):
AutoItX can be used as a standard DLL from any language capable of calling functions in external DLLs.

The following files are provided to allow you to use the DLL in C++:

* AutoItX3_DLL.h - C language header file showing the exported functions and parameters
* AutoItX3_DLL.lib - Microsoft format import library (x86)
* AutoItX3_x64_DLL.lib - Microsoft format import library (x64)
* AutoItX3.dll - The main AutoItX DLL (x86)
* AutoItX3_x64.dll - The main AutoItX DLL (x64)

==How can I search an image in another image? ==
You can use the Pixel* functions of AutoIt. See the help file for more information and examples.
You can also use one of the UDFs below; most of which use GDI:
* [https://www.autoitscript.com/forum/topic/158264-bmpsearch-search-for-bitmap-within-bitmap-assembly-version/ FASM example]
* [https://www.autoitscript.com/forum/topic/140478-bitmap-processing-using-raw-code/ asm bitmap processing]
* [https://www.autoitscript.com/forum/topic/66545-find-bmp-in-another-bmp-imagesearch/ find bitmap in bitmap]
* [https://www.autoitscript.com/forum/search/?type=all&q=_GDIPlus_BitmapLockBits/ GDI bitmaps]
Other libraries can be found that make use of a specific external dll but those above are considered "native" as no external dlls are required.

==Multithreading==
Multithreading basically is running multiple scripts/programs that have acces to the same variables, normally by sharing memory.

The AutoIt language is not threadsafe and multithreading is firmly on the <b>NOT TO DO</b> list

Multitasking and Multi<i>processing</i> are closely related, however, and multiple solutions have been explored:
* [https://www.autoitscript.com/forum/topic/25350-multithread/ Multithread technical discussion]
* [https://www.autoitscript.com/forum/topic/25494-threaded-dll-sample/ Multithread with external DLL]
* [https://www.autoitscript.com/forum/topic/146794-multi-thread-autoit/ Multithread with external DLL 2]
* [https://www.autoitscript.com/forum/topic/64390-how-to-multi-process-in-autoit/ Multi process]
* [https://www.autoitscript.com/forum/topic/187334-using-net-libary-with-autoit-possible/ Using C# - Host .NET]

==Test automation==
Many people are looking for freeware tools to do test automation and cannot afford the commercial tools like HP LeanFT, Ranorex, Squish etc.<br />
So how can AutoIt help you.<br />
Out of the box install the base full zip package and start Scite.Exe as a simple IDE.<br />
If you want to do more these links will help you.<br />
Read FAQ 31 for the basic stuff on which technologies are readable and which spying tools there are<br />
Read FAQ 38 for the bitmap stuff<br />
* [https://www.autoitscript.com/forum/topic/136766-isn-autoit-studio/ Alternative project IDE]
* [https://www.autoitscript.com/forum/topic/188158-net-common-language-runtime-clr-framework/ .NET stuff]
* [https://www.autoitscript.com/forum/topic/84133-winhttp-functions/ WinHTTP]
* [https://www.autoitscript.com/forum/topic/185401-restwhich-udf-to-use-webdriver-of-edge/ webdriver]
Android can be reached thru ADB and Webdriver<br />
iOS is limited to normal webdriver stuff thru WinHTTP library. So most likely you have to install additional iOS webdriver solutions<br />
And after reading FAQ just ask your questions in the support forum<br />