Difference between revisions of "WebDriver Capabilities"

From AutoIt Wiki
Jump to navigation Jump to search
(WD_Capabilities UDF: link to WD_Capabilities.au3 on github)
m (Additional sources of information: URL added)
 
(34 intermediate revisions by 2 users not shown)
Line 3: Line 3:
 
= WebDriver Capabilities =
 
= WebDriver Capabilities =
 
What are Capabilities?<p>
 
What are Capabilities?<p>
A good description can be found [https://github.com/SeleniumHQ/selenium/wiki/DesiredCapabilities here]:<br>
+
A good description can be found [https://www.selenium.dev/documentation/legacy/desired_capabilities/ ]:<br>
 
''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.''
 
''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
 
* 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 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
+
* The WebDriver UDF uses the Capabilities class to pass the capabilities string to the WebDriver exe file
 
* Format and content of the capabilities string differ from Browser to Browser
 
* Format and content of the capabilities string differ from Browser to Browser
 
* Some capabilities are read-only, some are read-write
 
* Some capabilities are read-only, some are read-write
 +
* There are [https://www.w3.org/TR/webdriver/#capabilities standard capabilities] each implementation must support. An implementation may define additional extension capabilities
 +
* Some capabilities are [https://developer.mozilla.org/en-US/docs/Web/WebDriver/Capabilities#legacy_capabilities deprecated] and should be avoided.
  
Take a look at remark about [https://developer.mozilla.org/en-US/docs/Web/WebDriver/Capabilities#legacy_capabilities Legacy capabilities].
+
== Chrome related documentations ==
 +
Link to the [https://chromedriver.chromium.org/capabilities Documentation of Capabilities for Chrome].
  
== Chrome ==
+
Link to the [https://peter.sh/experiments/chromium-command-line-switches/ List of Chromium Command Line Switches].
Link to the documentation of Capabilities for [https://chromedriver.chromium.org/capabilities Chrome].
 
  
Link to [https://chromedriver.chromium.org/capabilities List of Chromium Command Line Switches].
+
== Firefox related documentations ==
 +
Link to the [https://developer.mozilla.org/en-US/docs/Web/WebDriver/Capabilities/firefoxOptions Documentation of Capabilities for Firefox].
  
=== Examples ===
+
== Edge related documentations ==
<syntaxhighlight lang="autoit">
+
Link to the [https://docs.microsoft.com/en-us/microsoft-edge/webdriver-chromium/capabilities-edge-options Documentation of Capabilities for Edge].
$sCapabilities = '{"capabilities": {"alwaysMatch": {"goog:chromeOptions": {"w3c": true, "excludeSwitches": [ "enable-automation"]}}}}'
+
 
</syntaxhighlight>
+
== Desired/Required capabilities ==
 +
In many sources there are names such as: '''desiredCapabilities''' and '''requiredCapabilities'''.
  
== Firefox ==
+
These are old nomenclatures for old solutions.
Link to the documentation of Capabilities for [https://developer.mozilla.org/en-US/docs/Web/WebDriver/Capabilities/firefoxOptions Firefox].
 
  
=== Examples ===
+
`[https://developer.mozilla.org/en-US/docs/Web/WebDriver/Capabilities#legacy_capabilities Some drivers support these legacy capabilities, but they are deprecated and should be avoided.]`
<syntaxhighlight lang="autoit">
 
$sCapabilities = '{"capabilities": {"alwaysMatch": {"browserName": "firefox", "acceptInsecureCerts":true}}}'
 
</syntaxhighlight>
 
  
== Edge ==
+
Currently '''Capabilities''' should be used.
Link to the documentation of Capabilities for [https://docs.microsoft.com/en-us/microsoft-edge/webdriver-chromium/capabilities-edge-options Edge].
 
  
=== Examples ===
+
For more details take a look on:
<syntaxhighlight lang="autoit">
+
* [https://www.selenium.dev/documentation/legacy/desired_capabilities/ Legacy Selenium Desired Capabilities].
$sCapabilities = '{"capabilities": {"alwaysMatch": {"ms:edgeOptions": {"excludeSwitches": [ "enable-automation"]}}}}'
+
* [https://developer.mozilla.org/en-US/docs/Web/WebDriver/Capabilities#legacy_capabilities Legacy capabilities]
</syntaxhighlight>
 
  
 
= WD_Capabilities UDF =
 
= WD_Capabilities UDF =
 
Creating a correct Capabilities string can become quite complex. Debugging problems as well.<br>
 
Creating a correct Capabilities string can become quite complex. Debugging problems as well.<br>
 
That's why the WD_Capabilities.au3 UDF has been created. It makes sure the created Capabilities string is perfectly formatted all the time.
 
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 [https://github.com/Danp2/WebDriver AutoIt WebDriver sets of UDF].
 
The WD_Capabilities.au3 UDF is part of [https://github.com/Danp2/WebDriver AutoIt WebDriver sets of UDF].
  
Line 49: Line 46:
 
To get the following Capabilities string
 
To get the following Capabilities string
 
<syntaxhighlight lang="autoit">
 
<syntaxhighlight lang="autoit">
'{"capabilities": {"alwaysMatch": {"goog:chromeOptions": {"w3c": true, "excludeSwitches": [ "enable-automation"]}}}}'
+
Local $sCapabilities = '{"capabilities": {"alwaysMatch": {"goog:chromeOptions": {"w3c": true, "excludeSwitches": [ "enable-automation"]}}}}'
 
</syntaxhighlight>
 
</syntaxhighlight>
 
you have to call this sequence of functions:
 
you have to call this sequence of functions:
 
<syntaxhighlight lang="autoit">
 
<syntaxhighlight lang="autoit">
 
_WD_CapabilitiesStartup()
 
_WD_CapabilitiesStartup()
_WD_CapabilitiesAdd('alwaysMatch', 'chrome')
+
_WD_CapabilitiesAdd("alwaysMatch", "chrome")
_WD_CapabilitiesAdd('w3c', True)
+
_WD_CapabilitiesAdd("w3c", True)
_WD_CapabilitiesAdd('excludeSwitches', 'enable-automation')
+
_WD_CapabilitiesAdd("excludeSwitches", "enable-automation")
 
Local $sCapabilities = _WD_CapabilitiesGet()
 
Local $sCapabilities = _WD_CapabilitiesGet()
 
</syntaxhighlight>
 
</syntaxhighlight>
Line 63: Line 60:
 
To get the following Capabilities string
 
To get the following Capabilities string
 
<syntaxhighlight lang="autoit">
 
<syntaxhighlight lang="autoit">
'{"capabilities": {"alwaysMatch": {"browserName": "firefox", "acceptInsecureCerts":true}}}'
+
Local $sCapabilities = '{"capabilities": {"alwaysMatch": {"browserName": "firefox", "acceptInsecureCerts":true}}}'
 
</syntaxhighlight>
 
</syntaxhighlight>
 
you have to call this sequence of functions:
 
you have to call this sequence of functions:
 
<syntaxhighlight lang="autoit">
 
<syntaxhighlight lang="autoit">
 
_WD_CapabilitiesStartup()
 
_WD_CapabilitiesStartup()
_WD_CapabilitiesAdd('alwaysMatch', 'firefox')
+
_WD_CapabilitiesAdd("alwaysMatch", "firefox")
_WD_CapabilitiesAdd('browserName', 'firefox')
+
_WD_CapabilitiesAdd("browserName", "firefox")
_WD_CapabilitiesAdd('acceptInsecureCerts', True)
+
_WD_CapabilitiesAdd("acceptInsecureCerts", True)
 
Local $sCapabilities = _WD_CapabilitiesGet()
 
Local $sCapabilities = _WD_CapabilitiesGet()
 
</syntaxhighlight>
 
</syntaxhighlight>
Line 77: Line 74:
 
To get the following Capabilities string
 
To get the following Capabilities string
 
<syntaxhighlight lang="autoit">
 
<syntaxhighlight lang="autoit">
'{"capabilities": {"alwaysMatch": {"ms:edgeOptions": {"excludeSwitches": [ "enable-automation"]}}}}'
+
Local $sCapabilities = '{"capabilities": {"alwaysMatch": {"ms:edgeOptions": {"excludeSwitches": [ "enable-automation"]}}}}'
 
</syntaxhighlight>
 
</syntaxhighlight>
 
you have to call this sequence of functions:
 
you have to call this sequence of functions:
 
<syntaxhighlight lang="autoit">
 
<syntaxhighlight lang="autoit">
 
_WD_CapabilitiesStartup()
 
_WD_CapabilitiesStartup()
_WD_CapabilitiesAdd('alwaysMatch', 'edge')
+
_WD_CapabilitiesAdd("alwaysMatch", "edge")
_WD_CapabilitiesAdd('excludeSwitches', 'enable-automation')
+
_WD_CapabilitiesAdd("excludeSwitches", "enable-automation")
 
Local $sCapabilities = _WD_CapabilitiesGet()
 
Local $sCapabilities = _WD_CapabilitiesGet()
 
</syntaxhighlight>
 
</syntaxhighlight>
  
== Advanced Capabilities example ==
+
== A complete working example ==
...WorkInProgress...
 
 
 
 
<syntaxhighlight lang="autoit">
 
<syntaxhighlight lang="autoit">
 
#include <MsgBoxConstants.au3>
 
#include <MsgBoxConstants.au3>
 +
 +
#include "wd_capabilities.au3"
 
#include "wd_helper.au3"
 
#include "wd_helper.au3"
#include "wd_capabilities.au3"
 
 
Global Const $_EXAMPLE_DRIVER_FIREFOX = @ScriptDir & '\geckodriver.exe' ; CHANGE TO PROPER FILE FULL PATH
 
Global Const $_EXAMPLE_DRIVER_CHROME = @ScriptDir & '\chromedriver.exe' ; CHANGE TO PROPER FILE FULL PATH
 
Global Const $_EXAMPLE_DRIVER_EDGE = @ScriptDir & '\msedgedriver.exe' ; CHANGE TO PROPER FILE FULL PATH
 
 
Global Const $_EXAMPLE_PROFILE_FIREFOX = @LocalAppDataDir & '\Mozilla\Firefox\Profiles\WD_Testing_Profile' ; CHANGE TO PROPER DIRECTORY PATH
 
Global Const $_EXAMPLE_PROFILE_CHROME = @LocalAppDataDir & '\Google\Chrome\User Data\WD_Testing_Profile' ; CHANGE TO PROPER DIRECTORY PATH
 
Global Const $_EXAMPLE_PROFILE_EDGE = @LocalAppDataDir & '\MicrosoftEdge\User\\WD_Testing_Profile' ; CHANGE TO PROPER DIRECTORY PATH
 
 
Global Const $_EXAMPLE_DOWNLOAD_DIR = @UserProfileDir & '\Downloads\WD_Testing_download' ; CHANGE TO PROPER DIRECTORY PATH
 
 
Global Const $_EXAMPLE_OPTION_RUN_BROWSER = ( _
 
$IDYES = MsgBox($MB_YESNO + $MB_TOPMOST + $MB_ICONQUESTION + $MB_DEFBUTTON1, 'Question', _
 
'Do you want to test with running browsers ?' & @CRLF & _
 
'' & @CRLF & _
 
' [YES] = Run browser' & @CRLF & _
 
' [NO] = only put $s_Capabilities_JSON to console') _
 
)
 
 
Global Const $_EXAMPLE_OPTION_CHOOSEN_DRIVER = (($_EXAMPLE_OPTION_RUN_BROWSER) ? (_WD_Capabilities_Example_ChooseDriver()) : (''))
 
  
Global Const $_EXAMPLE_OPTION_HEADLESS = ($_EXAMPLE_OPTION_RUN_BROWSER And _
+
_Example_UsingCapabilitesWithChrome()
($IDYES = MsgBox($MB_YESNO + $MB_TOPMOST + $MB_ICONQUESTION + $MB_DEFBUTTON1, 'Question', _
+
If @error Then ConsoleWrite("! ---> @error=" & @error & "  @extended=" & @extended & _
'Do you want to test with headless mode ?' & @CRLF & _
+
" : Error launching browser" & @CRLF)
'' & @CRLF & _
 
' [YES] = Run browser in headless mode' & @CRLF & _
 
' [NO] = Run browser in "visible" mode') _
 
) _
 
)
 
  
Global Const $_EXAMPLE_OPTION_PROXY = _
+
Func _Example_UsingCapabilitesWithChrome()
($IDYES = MsgBox($MB_YESNO + $MB_TOPMOST + $MB_ICONQUESTION + $MB_DEFBUTTON1, 'Question', _
+
#Region - creating capabilities string
'Do you want to test with connection buffered via Proxy server ?' & @CRLF & _
+
; startup - cleaning internal capabilities JSON object
'' & @CRLF & _
 
' [YES] = use Proxy' & @CRLF & _
 
' [NO] = direct coonection') _
 
)
 
 
 
Global Const $_EXAMPLE_OPTION_ALLCAPS = _
 
($IDYES = MsgBox($MB_YESNO + $MB_TOPMOST + $MB_ICONQUESTION + $MB_DEFBUTTON1, 'Question', _
 
'Do you want to test with Capabilities for all "firstMatch" ?' & @CRLF & _
 
'' & @CRLF & _
 
' [YES] = test "firstMatch" Capabilites for all browser toogether' & @CRLF & _
 
' [NO] = test only "firstMatch" desired for specified browser') _
 
)
 
 
 
_WD_Capabilities_Example()
 
Exit
 
 
 
Func _WD_Capabilities_Example()
 
 
_WD_CapabilitiesStartup()
 
_WD_CapabilitiesStartup()
ConsoleWrite("! @ScriptLineNumber = " & @ScriptLineNumber & @CRLF)
+
; starting with "alwaysMatch" settings
#Region - _WD_Capabilities_Example() ... "alwaysMatch" section
+
_WD_CapabilitiesAdd("alwaysMatch")
_WD_CapabilitiesAdd('alwaysMatch')
+
_WD_CapabilitiesAdd("acceptInsecureCerts", True)
_WD_CapabilitiesAdd('acceptInsecureCerts', True)
 
_WD_CapabilitiesAdd('timeouts', 'script', 300) ; https://www.w3.org/TR/webdriver/#timeouts
 
_WD_CapabilitiesAdd('timeouts', 'pageLoad', 30000) ; https://www.w3.org/TR/webdriver/#timeouts
 
_WD_CapabilitiesAdd('timeouts', 'implicit', 4) ; https://www.w3.org/TR/webdriver/#timeouts
 
If $_EXAMPLE_OPTION_PROXY Then
 
_WD_CapabilitiesAdd('proxy', 'proxyType', 'manual')
 
_WD_CapabilitiesAdd('proxy', 'proxyAutoconfigUrl', '127.0.0.1') ; change '127.0.0.1' to your own 'proxyAutoconfigUrl' host
 
_WD_CapabilitiesAdd('proxy', 'ftpProxy', '127.0.0.1') ; change '127.0.0.1' to your own 'ftpProxy' host
 
_WD_CapabilitiesAdd('proxy', 'httpProxy', '127.0.0.1') ; change '127.0.0.1' to your own 'httpProxy' host
 
_WD_CapabilitiesAdd('proxy', 'noProxy', 'www.w3.org') ; an example url which should not to bo opened via proxy server
 
_WD_CapabilitiesAdd('proxy', 'noProxy', 'www.autoitscript.com') ; an example url which should not to bo opened via proxy server
 
_WD_CapabilitiesAdd('proxy', 'noProxy', 'www.google.com') ; an example url which should not to bo opened via proxy server
 
_WD_CapabilitiesAdd('proxy', 'noProxy', 'www.google.pl') ; an example url which should not to bo opened via proxy server
 
_WD_CapabilitiesAdd('proxy', 'sslProxy', '127.0.0.1') ; change '127.0.0.1' to your own 'sslProxy' host
 
_WD_CapabilitiesAdd('proxy', 'socksProxy', '127.0.0.1') ; change '127.0.0.1' to your own 'socksProxy' host
 
_WD_CapabilitiesAdd('proxy', 'socksVersion', 1)
 
EndIf
 
#TODO check why 'WIN10' have issue when using FireFox - with the commented following line
 
;~ _WD_CapabilitiesAdd('platformName', 'WIN10') ; https://stackoverflow.com/a/45621125/5314940
 
_WD_CapabilitiesDump(@ScriptLineNumber)
 
#EndRegion - _WD_Capabilities_Example() ... "alwaysMatch" section
 
 
 
#Region - _WD_Capabilities_Example() ... "firstMatch" section for Microsoft Edge
 
If $_EXAMPLE_OPTION_ALLCAPS Or $_EXAMPLE_OPTION_CHOOSEN_DRIVER = $_EXAMPLE_DRIVER_EDGE Then
 
; https://docs.microsoft.com/en-us/microsoft-edge/webdriver-chromium/capabilities-edge-options
 
ConsoleWrite("! @ScriptLineNumber = " & @ScriptLineNumber & @CRLF)
 
_WD_CapabilitiesAdd('firstMatch', 'edge')
 
_WD_CapabilitiesDump(@ScriptLineNumber)
 
#TODO CHECK .... "invalid argument: entry 0 of 'firstMatch' is invalid\nfrom invalid argument: unrecognized capability: browsername"
 
;~ _WD_CapabilitiesAdd('browsername', 'edge')
 
#TODO CHECK .... How to use 'WIN10'
 
;~ _WD_CapabilitiesAdd('platformName', 'WIN10')
 
_WD_CapabilitiesAdd('w3c', True)
 
#TODO CHECK .... How to use 'maxInstances'
 
;~ _WD_CapabilitiesAdd('maxInstances', 1) ; https://stackoverflow.com/a/45621125/5314940
 
If $_EXAMPLE_OPTION_HEADLESS Then _
 
_WD_CapabilitiesAdd('args', '--headless')
 
_WD_CapabilitiesAdd('prefs', 'plugins.always_open_pdf_externally', True) ; https://www.autoitscript.com/forum/topic/205553-webdriver-udf-help-support-iii/?do=findComment&comment=1482786
 
_WD_CapabilitiesAdd('prefs', 'edge.sleeping_tabs.enabled', False) ; https://www.autoitscript.com/forum/topic/205553-webdriver-udf-help-support-iii/?do=findComment&comment=1482798
 
_WD_CapabilitiesDump(@ScriptLineNumber)
 
EndIf
 
#EndRegion - _WD_Capabilities_Example() ... "firstMatch" section for Microsoft Edge
 
 
 
#Region - _WD_Capabilities_Example() ... "firstMatch" section for Microsoft Google Chrome
 
If $_EXAMPLE_OPTION_ALLCAPS Or $_EXAMPLE_OPTION_CHOOSEN_DRIVER = $_EXAMPLE_DRIVER_CHROME Then
 
ConsoleWrite("! @ScriptLineNumber = " & @ScriptLineNumber & @CRLF)
 
_WD_CapabilitiesAdd('firstMatch', 'chrome')
 
#TODO ADD REMARK about:  "firstMatch key shadowed a value in alwaysMatch"
 
_WD_CapabilitiesAdd('browserName', 'chrome')
 
_WD_CapabilitiesAdd('w3c', True)
 
_WD_CapabilitiesAdd('binary', 'C:\Program Files (x86)\Google\Chrome\Application\chrome.exe')
 
_WD_CapabilitiesAdd('args', 'user-data-dir', $_EXAMPLE_PROFILE_CHROME)
 
_WD_CapabilitiesAdd('args', '--profile-directory', Default)
 
_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', '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') ; https://stackoverflow.com/a/60409220
 
_WD_CapabilitiesAdd('args', '--ignore-certificate-errors') ; https://stackoverflow.com/a/60409220
 
If $_EXAMPLE_OPTION_HEADLESS Then _
 
_WD_CapabilitiesAdd('args', '--headless')
 
_WD_CapabilitiesAdd('excludeSwitches', 'disable-popup-blocking') ; https://help.applitools.com/hc/en-us/articles/360007189411--Chrome-is-being-controlled-by-automated-test-software-notification
 
_WD_CapabilitiesAdd('excludeSwitches', 'enable-automation')
 
_WD_CapabilitiesAdd('excludeSwitches', 'load-extension')
 
_WD_CapabilitiesDump(@ScriptLineNumber)
 
EndIf
 
#EndRegion - _WD_Capabilities_Example() ... "firstMatch" section for Microsoft Google Chrome
 
  
#Region - _WD_Capabilities_Example() ... "firstMatch" section for FireFox
+
; switching to "firstMatch" with "chrome" which will specify to use "goog:chromeOptions"
If $_EXAMPLE_OPTION_ALLCAPS Or $_EXAMPLE_OPTION_CHOOSEN_DRIVER = $_EXAMPLE_DRIVER_FIREFOX Then
+
_WD_CapabilitiesAdd("firstMatch", "chrome")
ConsoleWrite("! @ScriptLineNumber = " & @ScriptLineNumber & @CRLF)
 
_WD_CapabilitiesAdd('firstMatch', 'firefox')
 
_WD_CapabilitiesAdd('browserName', 'firefox')
 
_WD_CapabilitiesAdd('binary', 'c:\Program Files (x86)\Mozilla Firefox\firefox.exe')
 
If $_EXAMPLE_OPTION_HEADLESS Then _
 
_WD_CapabilitiesAdd('args', '--headless')
 
_WD_CapabilitiesAdd('args', '-profile')
 
_WD_CapabilitiesAdd('args', $_EXAMPLE_PROFILE_FIREFOX)
 
_WD_CapabilitiesAdd('prefs', 'download.default_directory', @ScriptDir)
 
_WD_CapabilitiesAdd('prefs', 'dom.ipc.processCount', 8)
 
_WD_CapabilitiesAdd('prefs', 'javascript.options.showInConsole', False)
 
_WD_CapabilitiesAdd('prefs', 'browser.toolbars.bookmarks.visibility', 'always') ; check    about:config
 
_WD_CapabilitiesAdd('prefs', 'app.update.download.attempts', 0) ; check    about:config
 
_WD_CapabilitiesAdd('prefs', 'browser.safebrowsing.downloads.enabled', False) ; check    about:config
 
_WD_CapabilitiesAdd('prefs', 'browser.safebrowsing.downloads.enabled', False) ; check    about:config
 
; https://tarunlalwani.com/post/change-profile-settings-at-runtime-firefox-selenium/
 
# 0 means to download to the desktop, 1 means to download to the default "Downloads" directory, 2 means to use the directory
 
_WD_CapabilitiesAdd('prefs', 'browser.download.folderList', 2)
 
_WD_CapabilitiesAdd('prefs', 'browser.download.manager.showWhenStarting', False)
 
_WD_CapabilitiesAdd('prefs', 'browser.download.dir', $_EXAMPLE_DOWNLOAD_DIR)
 
_WD_CapabilitiesAdd('prefs', 'browser.helperApps.neverAsk.saveToDisk', 'application/x-gzip')
 
_WD_CapabilitiesAdd('prefs', 'browser.helperApps.neverAsk.saveToDisk', 'application/zip')
 
  
_WD_CapabilitiesAdd('log', 'level', 'trace')
+
; setting vendor specific "goog:chromeOptions" settings
 +
_WD_CapabilitiesAdd("w3c", True)
 +
_WD_CapabilitiesAdd("prefs", "download.default_directory", @ScriptDir & "\Downloads")
 +
_WD_CapabilitiesAdd("excludeSwitches", "enable-automation")
  
_WD_CapabilitiesAdd('env', 'MOZ_LOG', 'nsHttp:5')
+
; dump Capabilities string to Console - reason: only to check how it looks
_WD_CapabilitiesAdd('env', 'MOZ_LOG_FILE', $_EXAMPLE_PROFILE_FIREFOX & '\log')
+
_WD_CapabilitiesDump(@ScriptLineNumber & " Testing")
_WD_CapabilitiesDump(@ScriptLineNumber)
 
EndIf
 
#EndRegion - _WD_Capabilities_Example() ... "firstMatch" section for FireFox
 
  
_WD_CapabilitiesDisplay(@ScriptLineNumber)
+
; get/assign Capabilities JSON Object content to string
 +
Local $sCapabilities = _WD_CapabilitiesGet()
 +
#EndRegion - creating capabilities string
  
If Not $_EXAMPLE_OPTION_RUN_BROWSER Then Return
+
; 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))
  
_WD_Option('Driver', $_EXAMPLE_OPTION_CHOOSEN_DRIVER)
+
; starting WebDriver with specified options
If $_EXAMPLE_OPTION_CHOOSEN_DRIVER = $_EXAMPLE_DRIVER_FIREFOX Then _WD_Option('Port', 4444)
 
If $_EXAMPLE_OPTION_CHOOSEN_DRIVER = $_EXAMPLE_DRIVER_CHROME Then _WD_Option('Port', 9515)
 
If $_EXAMPLE_OPTION_CHOOSEN_DRIVER = $_EXAMPLE_DRIVER_EDGE Then _WD_Option('Port', 9515)
 
 
_WD_Startup()
 
_WD_Startup()
 +
If @error Then Return SetError(@error, @extended, "")
  
Local $s_Capabilities_JSON = _WD_CapabilitiesGet()
+
; trying to create Session - connecting to WebDriver with specified capabilities
;~ Local $s_Capabilities_JSON = _WD_CapabilitiesGet()
+
Local $WD_SESSION = _WD_CreateSession($sCapabilities)
ConsoleWrite("! $s_Capabilities_JSON = " & $s_Capabilities_JSON & @CRLF)
+
If @error Then Return SetError(@error, @extended, $WD_SESSION)
  
Local $WD_SESSION = _WD_CreateSession($s_Capabilities_JSON)
+
; 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()")
 
If Not @Compiled Then MsgBox($MB_OK + $MB_TOPMOST + $MB_ICONINFORMATION, "Information #" & @ScriptLineNumber, "Waiting before _WD_Shutdown()")
 +
 +
; delete/close session - disconnecting AutoIt script from running WebDriver process
 
_WD_DeleteSession($WD_SESSION)
 
_WD_DeleteSession($WD_SESSION)
 +
 +
; close WebDriver process
 
_WD_Shutdown()
 
_WD_Shutdown()
 +
EndFunc  ;==>_Example_UsingCapabilitesWithChrome
 +
</syntaxhighlight>
  
EndFunc  ;==>_WD_Capabilities_Example
+
This example generates and uses Capabilities string as follows:
 +
<syntaxhighlight lang="json">
 +
{
 +
    "capabilities":{
 +
        "alwaysMatch":{
 +
            "acceptInsecureCerts":true
 +
        },
 +
        "firstMatch":[
 +
            {
 +
                "goog:chromeOptions":{
 +
                    "w3c":true,
 +
                    "prefs":{
 +
                        "download.default_directory":"C:\\Testing\\WD_Download"
 +
                    },
 +
                    "excludeSwitches":[
 +
                        "enable-automation"
 +
                    ]
 +
                }
 +
            }
 +
        ]
 +
    }
 +
}
 +
</syntaxhighlight>
  
Func _WD_Capabilities_Example_ChooseDriver()
+
= Additional sources of information =
Local $_CHOOSEN_DRIVER = ''
+
For Additional sources of information take a look on this following links:
If $IDYES = MsgBox($MB_YESNO + $MB_TOPMOST + $MB_ICONQUESTION + $MB_DEFBUTTON1, "Question", _
+
 
"Do you want to use FireFox browser") Then
+
* https://w3c.github.io/webdriver/#capabilities
$_CHOOSEN_DRIVER = $_EXAMPLE_DRIVER_FIREFOX
+
* https://github.com/Danp2/au3WebDriver/blob/master/wd_capabilities.au3
ElseIf $IDYES = MsgBox($MB_YESNO + $MB_TOPMOST + $MB_ICONQUESTION + $MB_DEFBUTTON1, "Question", _
+
* https://docs.yugabyte.com/preview/api/ysql/datatypes/type_json/primitive-and-compound-data-types
"Do you want to use Google Chrome browser") Then
+
* https://developer.mozilla.org/en-US/docs/Web/WebDriver/Capabilities
$_CHOOSEN_DRIVER = $_EXAMPLE_DRIVER_CHROME
+
* https://chromedriver.chromium.org/capabilities
ElseIf $IDYES = MsgBox($MB_YESNO + $MB_TOPMOST + $MB_ICONQUESTION + $MB_DEFBUTTON1, "Question", _
+
* https://www.selenium.dev/documentation/webdriver/capabilities/shared/
"Do you want to use Miscrosoft Edge browser") Then
+
* https://www.selenium.dev/documentation/webdriver/capabilities/internet_explorer/
$_CHOOSEN_DRIVER = $_EXAMPLE_DRIVER_EDGE
+
* https://github.com/SeleniumHQ/seleniumhq.github.io/tree/dev/website_and_docs/content/documentation/webdriver/capabilities
EndIf
+
*
If Not FileExists($_CHOOSEN_DRIVER) Then
 
MsgBox($MB_OK + $MB_TOPMOST + $MB_ICONERROR, "! Error occurred", _
 
"WebDriver file:" & @CRLF & _
 
$_CHOOSEN_DRIVER & @CRLF & _
 
"Not exist !" & @CRLF & _
 
"")
 
Exit
 
EndIf
 
ConsoleWrite("> USING: " & $_CHOOSEN_DRIVER & @CRLF)
 
Return $_CHOOSEN_DRIVER
 
EndFunc  ;==>_WD_Capabilities_Example_ChooseDriver
 
</syntaxhighlight>
 

Latest revision as of 23:17, 9 April 2022

This page is still a work in progress.

WebDriver Capabilities

What are Capabilities?

A good description can be found [1]:
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 file
  • Format and content of the capabilities string differ from Browser to Browser
  • Some capabilities are read-only, some are read-write
  • There are standard capabilities each implementation must support. An implementation may define additional extension capabilities
  • Some capabilities are deprecated and should be avoided.

Chrome related documentations

Link to the Documentation of Capabilities for Chrome.

Link to the 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.

Desired/Required capabilities

In many sources there are names such as: desiredCapabilities and requiredCapabilities.

These are old nomenclatures for old solutions.

`Some drivers support these legacy capabilities, but they are deprecated and should be avoided.`

Currently Capabilities should be used.

For more details take a look on:

* Legacy Selenium Desired Capabilities.
* Legacy capabilities

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 with "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/assign Capabilities JSON Object content to string
	Local $sCapabilities = _WD_CapabilitiesGet()
	#EndRegion - creating capabilities string

	; 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 capabilities
	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 running 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"
                    ]
                }
            }
        ]
    }
}

Additional sources of information

For Additional sources of information take a look on this following links: