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 related documentations

Link to the documentation of Capabilities for Chrome. Link to List of Chromium Command Line Switches.

Firefox related documentations

Link to the documentation of Capabilities for Firefox.

Edge related documentations

Link to the documentation of Capabilities for Edge.

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

Local $sCapabilities = '{"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

Local $sCapabilities = '{"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

Local $sCapabilities = '{"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_UsingCapabilitesWithChrome()
If @error Then ConsoleWrite("! ---> @error=" & @error & "  @extended=" & @extended & _
		" : Error launching browser" & @CRLF)

Func _Example_UsingCapabilitesWithChrome()
	#Region - creating capabilities string
	; startup - cleaning internal capabilities JSON object
	_WD_CapabilitiesStartup()
	; starting wiht "alwaysMatch" settings
	_WD_CapabilitiesAdd("alwaysMatch")
	_WD_CapabilitiesAdd("acceptInsecureCerts", True)

	; switching to "firstMatch" with "chrome" which will specify to use "goog:chromeOptions"
	_WD_CapabilitiesAdd("firstMatch", "chrome")

	; setting vendor specific "goog:chromeOptions" settings
	_WD_CapabilitiesAdd("w3c", True)
	_WD_CapabilitiesAdd("prefs", "download.default_directory", @ScriptDir & "\Downloads")
	_WD_CapabilitiesAdd("excludeSwitches", "enable-automation")

	; Dump Capabilities string to Console - reason: only to check how it looks"
	_WD_CapabilitiesDump(@ScriptLineNumber & " Testing")

	; get/assigne Capabilities JSON Object content to string
	Local $sCapabilities = _WD_CapabilitiesGet()
	#EndRegion - creating capabilities string

	; checking / downloading WebDriver version
	_WD_UpdateDriver("chrome")
	If @error Then Return SetError(@error, @extended, "")

	; setting WebDriver options
	_WD_Option("Driver", @ScriptDir & "\chromedriver.exe")
	_WD_Option("Port", 9515)
	_WD_Option("DefaultTimeout", 1000)
	_WD_Option("DriverParams", "--log-path=" & Chr(34) & @ScriptDir & "\WebDriver_Testing.log" & Chr(34))

	; starting WebDriver with specified options
	_WD_Startup()
	If @error Then Return SetError(@error, @extended, "")

	; trying to create Session - connecting to WebDriver with specified capabiliteies
	Local $WD_SESSION = _WD_CreateSession($sCapabilities)
	If @error Then Return SetError(@error, @extended, $WD_SESSION)

	; this MsgBox is placed here only to have possibility to manually check if all is fine with Chrome instance
	If Not @Compiled Then MsgBox($MB_OK + $MB_TOPMOST + $MB_ICONINFORMATION, "Information #" & @ScriptLineNumber, "Waiting before _WD_Shutdown()")

	; Delete/Close session - disconnecting AutoIt script from runing WebDriver process
	_WD_DeleteSession($WD_SESSION)

	; close WebDriver process
	_WD_Shutdown()
EndFunc   ;==>_Example_UsingCapabilitesWithChrome

This example generates and uses Capabilities string as follows:

{
    "capabilities":{
        "alwaysMatch":{
            "acceptInsecureCerts":true
        },
        "firstMatch":[
            {
                "goog:chromeOptions":{
                    "w3c":true,
                    "prefs":{
                        "download.default_directory":"C:\\Testing\\WD_Download"
                    },
                    "excludeSwitches":[
                        "enable-automation"
                    ]
                }
            }
        ]
    }
}