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_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=" & '"' & @ScriptDir & '\WebDriver_Testing.log' & '"')

	; 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 check if all is fine
	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"
                    ]
                }
            }
        ]
    }
}