DesiredCapabilities

Luke Inman-Semerau edited this page Apr 16, 2015 · 5 revisions

Introduction

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.

Used by the selenium server for browser selection

Key Type Description
browserName string The name of the browser being used; should be one of {android|chrome|firefox|htmlunit|internet explorer|iPhone|iPad|opera|safari}.
version string The browser version, or the empty string if unknown.
platform string A key specifying which platform the browser should be running on. This value should be one of {WINDOWS|XP|VISTA|MAC|LINUX|UNIX|ANDROID}. When requesting a new session, the client may specify ANY to indicate any available platform may be used. For more information see [GridPlatforms]

Read-only capabilities

Key Type Description
handlesAlerts boolean Whether the session can interact with modal popups, such as window.alert and window.confirm.
cssSelectorsEnabled boolean Whether the session supports CSS selectors when searching for elements.

Read-write capabilities

Key Type Description
javascriptEnabled boolean Whether the session supports executing user supplied JavaScript in the context of the current page (only on HTMLUnitDriver).
databaseEnabled boolean Whether the session can interact with database storage.
locationContextEnabled boolean Whether the session can set and query the browser's location context.
applicationCacheEnabled boolean Whether the session can interact with the application cache.
browserConnectionEnabled boolean Whether the session can query for the browser's connectivity and disable it if desired.
webStorageEnabled boolean Whether the session supports interactions with storage objects.
acceptSslCerts boolean Whether the session should accept all SSL certs by default.
rotatable boolean Whether the session can rotate the current page's current layout between portrait and landscape orientations (only applies to mobile platforms).
nativeEvents boolean Whether the session is capable of generating native events when simulating user input.
proxy proxy object Details of any proxy to use. If no proxy is specified, whatever the system's current or default state is used. The format is specified under Proxy JSON Object.
unexpectedAlertBehaviour string What the browser should do with an unhandled alert before throwing out the UnhandledAlertException. Possible values are "accept", "dismiss" and "ignore"
elementScrollBehavior integer Allows the user to specify whether elements are scrolled into the viewport for interaction to align with the top (0) or bottom (1) of the viewport. The default value is to align with the top of the viewport. Supported in IE and Firefox (since 2.36)

RemoteWebDriver specific

webdriver.remote.sessionid string WebDriver session ID for the session. Readonly and only returned if the server implements a server-side webdriver-backed selenium.
webdriver.remote.quietExceptions boolean Disable automatic screnshot capture on exceptions. This is False by default.

Grid-specific

path string ??? Path to route request to, or maybe listen on.
seleniumProtocol string Which protocol to use. Accepted values: WebDriver, Selenium.
maxInstances integer Maximum number of instances to allow to connect to grid,
environment string ??? Possible duplicate of browserName? See RegistrationRequest.

Selenium RC (1.0) only

proxy_pac DoNotUseProxyPac Legacy proxy mechanism. Do not use.
commandLineFlags string Flags to pass to browser command line.
executablePath string Path to browser executable.
timeoutInSeconds long integer Timeout to wait for the browser to launch, in seconds.
onlyProxySeleniumTraffic boolean Whether to only proxy selenium traffic. See browserlaunchers.Proxies
avoidProxy boolean ??? See browserlaunchers.Proxies
proxyEverything boolean ??? See browserlaunchers.Proxies
proxyRequired boolean ??? See browserlaunchers.Proxies
browserSideLog boolean ??? See AbstractBrowserLauncher.
optionsSet boolean ??? See BrowserOptions.
singleWindow boolean Whether to enable single window mode.
dontInjectRegex javascript RegExp Regular expression that proxy injection mode can use to know when to bypss injection. Ignored if not in proxy injection mode.
userJSInjection boolean ??? Whether to inject user JS. Ignored if not in proxy injection mode.
userExtensions string Path to a JavaScript file that will be loaded into selenium.

Selenese-Backed-WebDriver specific

selenium.server.url string URL of Selenium server to use, to back this WebDriver

Browser Specific Capabilities

Chrome specific

See Chrome capabilities

Firefox specific

WebDriver

firefox_profile string Base64-encoded profile. TODO: Document format
loggingPrefs LoggingPreferences object Preferences for logging
firefox_binary string Path to firefox binary file to use.
pageLoadingStrategy string See https://w3c.github.io/webdriver/webdriver-spec.html#the-page-load-strategy

RC

mode string Mode for browser. Possible values: chrome, proxyInjection, proxy. Defaults to chrome, if not set. proxyInjection requires -proxyInjection to be passed to server command line.
captureNetworkTraffic boolean Whether to capture network traffic.
addCustomRequestHeaders boolean Whether to add custom request headers.
trustAllSSLCertificates boolean Whether to trust all SSL certificates.
changeMaxConnections boolean ??? See FirefoxChromeLauncher.
firefoxProfileTemplate string ??? See FirefoxChromeLauncher.
profile string ??? See FirefoxChromeLauncher

IE specific

WebDriver

ignoreProtectedModeSettings boolean Whether to skip the protected mode check. If set, tests may become flaky, unresponsive, or browsers may hang. If not set, and protected mode settings are not the same for all zones, an exception will be thrown on driver construction. Only "best effort" support is provided when using this capability.
ignoreZoomSetting boolean Indicates whether to skip the check that the browser's zoom level is set to 100%. Value is set to false by default.
initialBrowserUrl string Allows the user to specify the initial URL loaded when IE starts. Intended to be used with ignoreProtectedModeSettings to allow the user to initialize IE in the proper Protected Mode zone. Using this capability may cause browser instability or flaky and unresponsive code. Only "best effort" support is provided when using this capability.
enablePersistentHover boolean Determines whether persistent hovering is enabled (true by default). Persistent hovering is achieved by continuously firing mouse over events at the last location the mouse cursor has been moved to.
enableElementCacheCleanup boolean Determines whether the driver should attempt to remove obsolete elements from the element cache on page navigation (true by default). This is to help manage the IE driver's memory footprint, removing references to invalid elements.
requireWindowFocus boolean Determines whether to require that the IE window have focus before performing any user interaction operations (mouse or keyboard events). This capability is false by default, but delivers much more accurate native events interactions.
browserAttachTimeout integer The timeout, in milliseconds, that the driver will attempt to locate and attach to a newly opened instance of Internet Explorer. The default is zero, which indicates waiting indefinitely.
ie.forceCreateProcessApi boolean Forces launching Internet Explorer using the CreateProcess API. If this option is not specified, IE is launched using the IELaunchURL, if it is available. For IE 8 and above, this option requires the TabProcGrowth registry value to be set to 0.
ie.browserCommandLineSwitches string Specifies command-line switches with which to launch Internet Explorer. This is only valid when used with the forceCreateProcess.
ie.usePerProcessProxy boolean When a proxy is specified using the proxy capability, this capability sets the proxy settings on a per-process basis when set to true. The default is false, which means the proxy capability will set the system proxy, which IE will use.
ie.ensureCleanSession boolean When set to true, this capability clears the cache, cookies, history, and saved form data. When using this capability, be aware that this clears the cache for all running instances of Internet Explorer, including those started manually.
logFile string The path to file where server should write log messages to. By default it writes to stdout.
logLevel string The log level used by the server. Valid values are TRACE, DEBUG, INFO, WARN, ERROR, and FATAL. Defaults to FATAL if not specified.
host string The address of the host adapter on which the server will listen for commands.
extractPath string The path to the directory used to extract supporting files used by the server. Defaults to the TEMP directory if not specified.
silent boolean Suppresses diagnostic output when the server is started.
ie.setProxyByServer boolean Defines used proxy setter. False means WindowsProxyManager will be used for setting proxy settings. True means IEDriverServer will be used for setting proxy settings. Currently it's False by default. In next releases it will be set to True by default and removed.

RC

mode string Mode for browser. Possible values: iehta, proxyInjectionMode, proxy. Defaults to iehta if not set. proxyInjection requires -proxyInjection to be passed to server command line.
killProcessesByName boolean Whether to try to kill processes by name, instead (or addition) to killing processes we happen to have handles to.
honorSystemProxy boolean Whether to honor the system proxy.
ensureCleanSession boolean Whether to make sure the session has no cookies or temporary internet files on Windows. I believe this is passed to the IEDriver as well, but ignored by it.

Safari specific

WebDriver

Key Type Description
safari.options object A map of configuration options, as enumerated below.

Available options:

Key Type Description
cleanSession boolean Whether to make sure the session has no cookies, cache entries, local storage, or databases.

RC

mode string Mode for browser. Possible values: filebased, proxyInjectionMode, proxy. Defaults to filebased. Note: filebased does not work on newer Safaris. proxyInjection requires -proxyInjection to be passed to server command line.
honorSystemProxy boolean Whether to honour the sysem proxy.
ensureCleanSession boolean Whether to make sure the session has no cookies, cache entries. And that any registry and proxy settings are restored after the session.

Object structures

Proxy JSON Object

A JSON object describing a Proxy configuration.

Key Type Description
proxyType string (Required) The type of proxy being used. Possible values are: direct - A direct connection - no proxy in use, manual - Manual proxy settings configured, e.g. setting a proxy for HTTP, a proxy for FTP, etc, pac - Proxy autoconfiguration from a URL, autodetect - Proxy autodetection, probably with WPAD, system - Use system settings
proxyAutoconfigUrl string (Required if proxyType == pac, Ignored otherwise) Specifies the URL to be used for proxy autoconfiguration. Expected format example: http://hostname.com:1234/pacfile
ftpProxy, httpProxy, sslProxy, socksProxy string (Optional, Ignored if proxyType != manual) Specifies the proxies to be used for FTP, HTTP, HTTPS and SOCKS requests respectively. Behaviour is undefined if a request is made, where the proxy for the particular protocol is undefined, if proxyType is manual. Expected format example: hostname.com:1234
socksUsername string (Optional, Ignored if proxyType != manual and socksProxy is not set) Specifies SOCKS proxy username.
socksPassword string (Optional, Ignored if proxyType != manual and socksProxy is not set) Specifies SOCKS proxy password.
noProxy string (Optional, Ignored if proxyType != manual) Specifies proxy bypass addresses. Format is driver specific.

LoggingPreferences JSON object

A JSON object describing the logging level of different components in the browser, the driver, or any intermediary WebDriver servers.

Available values for most loggers are "OFF", "SEVERE", "WARNING", "INFO", "CONFIG", "FINE", "FINER", "FINEST", "ALL".

This produces a JSON object looking something like: {"loggingPrefs": {"driver": "INFO", "server": "OFF", "browser": "FINE"}}.

See the documentation of each driver for what browser specific logging components are available.

Key Type Description
component string How verbose the logging should be.

FirefoxProfile settings

Preferences accepted by the FirefoxProfile with special meaning, in the WebDriver API:

Key Type Description
webdriver_accept_untrusted_certs boolean Whether to trust all SSL certificates. TODO: Maybe in some way different to the acceptSslCerts or trustAllSSLCertificates capabilities.
webdriver_assume_untrusted_issuer boolean Whether to trust all SSL certificate issuers. TODO: Maybe in some way different to the acceptSslCerts or trustAllSSLCertificates capabilities.
webdriver.log.driver string Level at which to log FirefoxDriver logging statements to a temporary file, so that they can be retrieved by a getLogs command. Available options; DEBUG, INFO, WARNING, ERROR, OFF. Defaults to OFF.
webdriver.log.file string Path to file to which to copy firefoxdriver logging output. Defaults to no file (like /dev/null).
webdriver.load.strategy string Experimental API. Defines different strategies for how long to wait until a page is loaded. Values: unstable, conservative. Defaults to conservative.
webdriver_firefox_port integer Port to listen on for WebDriver commands. Defaults to 7055.