WebDriver Capabilities

This page is still a work in progress.

WebDriver Capabilities

What are Capabilities?

A good description can be found here:
Not all server implementations will support every WebDriver feature. Therefore, the client and server should use JSON objects with the properties listed below when describing which features a user requests that a session support. If a session cannot support a capability that is requested in the desired capabilities, no error is thrown; a read-only capabilities object is returned that indicates the capabilities the session actually supports.

• Capabilities are options that you can use to customize and configure a Browser session
• The capabilities you want to set are passed as a formatted string to function _WD_CreateSession
• The WebDriver UDF uses the Capabilities class to pass the capabilities string to the WebDriver Exe
• Format and content of the capabilities string differ from Browser to Browser
• Some capabilities are read-only, some are read-write

Take a look at remark about Legacy capabilities.

Chrome

Link to the documentation of Capabilities for Chrome.

Link to List of Chromium Command Line Switches.

Examples

Local $sCapabilities = '{"capabilities": {"alwaysMatch": {"goog:chromeOptions": {"w3c": true, "excludeSwitches": [ "enable-automation"]}}}}'

Firefox

Link to the documentation of Capabilities for Firefox.

Examples

Local $sCapabilities = '{"capabilities": {"alwaysMatch": {"browserName": "firefox", "acceptInsecureCerts":true}}}'

Edge

Link to the documentation of Capabilities for Edge.

Examples

Local $sCapabilities = '{"capabilities": {"alwaysMatch": {"ms:edgeOptions": {"excludeSwitches": [ "enable-automation"]}}}}'

WD_Capabilities UDF

Creating a correct Capabilities string can become quite complex. Debugging problems as well.
That's why the WD_Capabilities.au3 UDF has been created. It makes sure the created Capabilities string is perfectly formatted all the time. The WD_Capabilities.au3 UDF is part of AutoIt WebDriver sets of UDF.

Chrome Examples

To get the following Capabilities string

"{"capabilities": {"alwaysMatch": {"goog:chromeOptions": {"w3c": true, "excludeSwitches": [ "enable-automation"]}}}}"

you have to call this sequence of functions:

_WD_CapabilitiesStartup()
_WD_CapabilitiesAdd("alwaysMatch", "chrome")
_WD_CapabilitiesAdd("w3c", True)
_WD_CapabilitiesAdd("excludeSwitches", "enable-automation")
Local $sCapabilities = _WD_CapabilitiesGet()

Firefox Examples

To get the following Capabilities string

"{"capabilities": {"alwaysMatch": {"browserName": "firefox", "acceptInsecureCerts":true}}}"

you have to call this sequence of functions:

_WD_CapabilitiesStartup()
_WD_CapabilitiesAdd("alwaysMatch", "firefox")
_WD_CapabilitiesAdd("browserName", "firefox")
_WD_CapabilitiesAdd("acceptInsecureCerts", True)
Local $sCapabilities = _WD_CapabilitiesGet()

Edge Examples

To get the following Capabilities string

"{"capabilities": {"alwaysMatch": {"ms:edgeOptions": {"excludeSwitches": [ "enable-automation"]}}}}"

you have to call this sequence of functions:

_WD_CapabilitiesStartup()
_WD_CapabilitiesAdd("alwaysMatch", "edge")
_WD_CapabilitiesAdd("excludeSwitches", "enable-automation")
Local $sCapabilities = _WD_CapabilitiesGet()

A complete working example

#include <MsgBoxConstants.au3>

#include "wd_capabilities.au3"
#include "wd_helper.au3"

_Example()
If @error Then ConsoleWrite("! ---> @error=" & @error & "  @extended=" & @extended & _
		" : Error launching browser" & @CRLF)


Func _Example()
	Local $WD_SESSION = _WD_SetupChrome()
	If @error Then Return SetError(@error, @extended, $WD_SESSION)

	MsgBox($MB_OK + $MB_TOPMOST + $MB_ICONINFORMATION, "Information #" & @ScriptLineNumber, "Waiting before _WD_Shutdown()")
	_WD_DeleteSession($WD_SESSION)
	_WD_Shutdown()
EndFunc   ;==>_Example

Func _WD_SetupChrome($s_DriverLocation = @ScriptDir & "\chromedriver.exe", $b_Headless = False, $s_Download_dir = Default, $_WD_DEBUG_LEVEL = Default, $s_Log_FileFullPath = Default)
	If $_WD_DEBUG_LEVEL = Default Then
		$_WD_DEBUG = $_WD_DEBUG_Error
		If Not @Compiled Then $_WD_DEBUG = $_WD_DEBUG_Info
	EndIf

	_WD_Option("Driver", $s_DriverLocation)
	_WD_Option("Port", 9515)
	_WD_Option("DefaultTimeout", 1000)
	_WD_Option("Sleep", _My_Check_State)

	If $s_Download_dir = Default Then $s_Download_dir = @ScriptDir & "\WD_Download"

	Local $bTest = _WD_Validate_Browser_Driver("chrome", "chromedriver.exe")
	If Not $bTest Then Return SetError(@error, @extended, $bTest)

	If $s_Log_FileFullPath = Default Then $s_Log_FileFullPath = @ScriptDir & "\Chrome-Testing.log"
	If IsString($s_Log_FileFullPath) And StringLen(($s_Log_FileFullPath)) Then
		If Not @Compiled Then ConsoleWrite(@ScriptLineNumber & " WebDriver: Log Path = " & $s_Log_FileFullPath & @CRLF)
		_WD_Option("DriverParams", "--log-path=" & """ & $s_Log_FileFullPath & """)
	EndIf

	_WD_CapabilitiesStartup()
	_WD_CapabilitiesAdd("alwaysMatch")
	_WD_CapabilitiesAdd("acceptInsecureCerts", True)
	_WD_CapabilitiesAdd("platformName", "windows")
	_WD_CapabilitiesAdd("firstMatch", "chrome")
	_WD_CapabilitiesAdd("browserName", "chrome")
	_WD_CapabilitiesAdd("w3c", True)
	_WD_CapabilitiesAdd("args", "user-data-dir", "C:\Users\" & @UserName & "\AppData\Local\Google\Chrome\User Data\WD_Testing")
	_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")
	_WD_CapabilitiesAdd("args", "--profile-directory", Default)
	_WD_CapabilitiesAdd("args", "start-maximized")
	_WD_CapabilitiesAdd("args", "disable-infobars")
	_WD_CapabilitiesAdd("args", "--no-sandbox")
	_WD_CapabilitiesAdd("args", "--disable-blink-features=AutomationControlled")
	_WD_CapabilitiesAdd("args", "--disable-web-security")
	_WD_CapabilitiesAdd("args", "--allow-running-insecure-content")
	_WD_CapabilitiesAdd("args", "--ignore-certificate-errors")
	If $b_Headless Then _
			_WD_CapabilitiesAdd("args", "--headless")
	If $s_Download_dir Then _
			_WD_CapabilitiesAdd("prefs", "download.default_directory", $s_Download_dir)
	_WD_CapabilitiesAdd("excludeSwitches", "disable-popup-blocking")
	_WD_CapabilitiesAdd("excludeSwitches", "enable-automation")
	_WD_CapabilitiesAdd("excludeSwitches", "load-extension")

	_WD_CapabilitiesDump(@ScriptLineNumber & " test 1")
	Local $s_Capabilities = _WD_CapabilitiesGet()

	_WD_Startup()
	If @error Then Return SetError(@error, @extended, "")
	If Not @Compiled Then ConsoleWrite(@ScriptLineNumber & " WebDriver: StartUp via chrome" & @CRLF)

	Local $WD_SESSION = _WD_CreateSession($s_Capabilities)
	Return SetError(@error, @extended, $WD_SESSION)
EndFunc   ;==>_WD_SetupChrome

Func _WD_Validate_Browser_Driver($s_Browser_name, $s_Driver_name)

	Local $s_GetBrowserVersion = _WD_GetBrowserVersion($s_Browser_name)
	If @error Then Return SetError(@error, @extended, $s_GetBrowserVersion)
	If Not @Compiled Then ConsoleWrite("Browser version = " & $s_GetBrowserVersion & @CRLF)
	Local $s_GetBrowserVersion_main_number = Number(StringLeft($s_GetBrowserVersion, 2))

	Local $s_GetWebDriverVersion = _WD_GetWebDriverVersion(@ScriptDir, $s_Driver_name)
	If @error Then Return SetError(@error, @extended, $s_GetWebDriverVersion)
	If Not @Compiled Then ConsoleWrite("WEBDRIVER version = " & $s_GetWebDriverVersion & @CRLF)
	Local $s_GetWebDriverVersion_main_number = Number(StringLeft($s_GetWebDriverVersion, 2))

	Local $bTest = ($s_GetBrowserVersion_main_number = $s_GetWebDriverVersion_main_number)
	Return SetError($s_GetBrowserVersion_main_number, $s_GetWebDriverVersion_main_number, $bTest)
EndFunc   ;==>_WD_Validate_Browser_Driver

Func _My_Check_State($iSleep)
	If Not @Compiled Then ConsoleWrite("Sleeping " & $iSleep & " ms" & @CRLF)
	Sleep($iSleep)
EndFunc   ;==>_My_Check_State

This example generates and uses Capabilities string as follows:

{
    "capabilities":{
        "alwaysMatch":{
            "acceptInsecureCerts":true,
            "platformName":"windows"
        },
        "firstMatch":[
            {
                "browserName":"chrome",
                "goog:chromeOptions":{
                    "w3c":true,
                    "args":[
                        "user-data-dir=C:\\Users\\LoginName\\AppData\\Local\\Google\\Chrome\\User Data\\WD_Testing",
                        "user-agent=Mozilla\/5.0 (Windows NT 10.0; Win64; X64) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/96.0.4664.93 Safari\/537.36",
                        "--profile-directory=default",
                        "start-maximized",
                        "disable-infobars",
                        "--no-sandbox",
                        "--disable-blink-features=AutomationControlled",
                        "--disable-web-security",
                        "--allow-running-insecure-content",
                        "--ignore-certificate-errors"
                    ],
                    "prefs":{
                        "download.default_directory":"C:\\Testing\\WD_Download"
                    },
                    "excludeSwitches":[
                        "disable-popup-blocking",
                        "enable-automation",
                        "load-extension"
                    ]
                }
            }
        ]
    }
}

Presented Capabilities string may differ as is automatically generated according to the Windows environment.