Skip to content

Latest commit

 

History

History
657 lines (578 loc) · 18.4 KB

options.en.md

File metadata and controls

657 lines (578 loc) · 18.4 KB
title linkTitle weight description aliases
Browser Options
Options
2
These capabilities are shared by all browsers.
/documentation/en/driver_idiosyncrasies/shared_capabilities/
/documentation/webdriver/capabilities/shared_capabilities/
/documentation/en/webdriver/http_proxies/
/documentation/webdriver/http_proxies/
/documentation/webdriver/capabilities/http_proxies/
/documentation/en/webdriver/page_loading_strategy/
/documentation/webdriver/page_loading_strategy/
/documentation/webdriver/capabilities/page_loading_strategy/
/documentation/capabilitis/shared/

In Selenium 3, capabilities were defined in a session by using Desired Capabilities classes. As of Selenium 4, you must use the browser options classes. For remote driver sessions, a browser options instance is required as it determines which browser will be used.

These options are described in the w3c specification for Capabilities.

Each browser has [custom options]({{< ref "../browsers/" >}}) that may be defined in addition to the ones defined in the specification.

browserName

Browser name is set by default when using an Options class instance.

{{< tabpane text=true >}} {{< tab header="Java" >}} {{< badge-code >}} {{< /tab >}} {{% tab header="Python" %}} {{< badge-code >}} {{% /tab %}} {{< tab header="CSharp" >}} {{< badge-code >}} {{< /tab >}} {{< tab header="Ruby" >}} {{< gh-codeblock path="examples/ruby/spec/drivers/options_spec.rb#L11" >}} {{< /tab >}} {{< tab header="JavaScript" >}} {{< badge-code >}} {{< /tab >}} {{< tab header="Kotlin" >}} {{< badge-code >}} {{< /tab >}} {{< /tabpane >}}

browserVersion

This capability is optional, this is used to set the available browser version at remote end. In recent versions of Selenium, if the version is not found on the system, it will be automatically downloaded by [Selenium Manager]({{< ref "../../selenium_manager" >}})

{{< tabpane text=true >}} {{< tab header="Java" >}} {{< badge-code >}} {{< /tab >}} {{% tab header="Python" %}} {{< badge-code >}} {{% /tab %}} {{< tab header="CSharp" >}} {{< badge-code >}} {{< /tab >}} {{< tab header="Ruby" >}} {{< gh-codeblock path="examples/ruby/spec/drivers/service_spec.rb#L40" >}} {{< /tab >}} {{< tab header="JavaScript" >}} {{< badge-code >}} {{< /tab >}} {{< tab header="Kotlin" >}} {{< badge-code >}} {{< /tab >}} {{< /tabpane >}}

pageLoadStrategy

Three types of page load strategies are available.

The page load strategy queries the document.readyState as described in the table below:

Strategy Ready State Notes
normal complete Used by default, waits for all resources to download
eager interactive DOM access is ready, but other resources like images may still be loading
none Any Does not block WebDriver at all

The document.readyState property of a document describes the loading state of the current document.

When navigating to a new page via URL, by default, WebDriver will hold off on completing a navigation method (e.g., driver.navigate().get()) until the document ready state is complete. This does not necessarily mean that the page has finished loading, especially for sites like Single Page Applications that use JavaScript to dynamically load content after the Ready State returns complete. Note also that this behavior does not apply to navigation that is a result of clicking an element or submitting a form.

If a page takes a long time to load as a result of downloading assets (e.g., images, css, js) that aren't important to the automation, you can change from the default parameter of normal to eager or none to speed up the session. This value applies to the entire session, so make sure that your [waiting strategy]({{< ref "/documentation/webdriver/waits.md" >}}) is sufficient to minimize flakiness.

normal (default)

WebDriver waits until the load event fire is returned.

{{< tabpane langEqualsHeader=true >}} {{< badge-examples >}} {{< tab header="Java" text=true >}} {{< gh-codeblock path="/examples/java/src/test/java/dev/selenium/drivers/OptionsTest.java#L14-L16">}} {{< /tab >}} {{< tab header="Python" text=true >}} {{< gh-codeblock path="/examples/python/tests/drivers/test_options.py#L7-L9">}} {{< /tab >}} {{< tab header="CSharp" >}} using OpenQA.Selenium; using OpenQA.Selenium.Chrome;

namespace pageLoadStrategy { class pageLoadStrategy { public static void Main(string[] args) { var chromeOptions = new ChromeOptions(); chromeOptions.PageLoadStrategy = PageLoadStrategy.Normal; IWebDriver driver = new ChromeDriver(chromeOptions); try { driver.Navigate().GoToUrl("https://example.com"); } finally { driver.Quit(); } } } } {{< /tab >}} {{< tab header="Ruby" text=true >}} {{< gh-codeblock path="/examples/ruby/spec/drivers/options_spec.rb#L11-L12">}} {{< /tab >}} {{< tab header="JavaScript" text=true >}} {{< gh-codeblock path="/examples/javascript/test/capabilities/pageLoading.spec.js#L28-L34">}} {{< /tab >}} {{< tab header="Kotlin" >}} import org.openqa.selenium.PageLoadStrategy import org.openqa.selenium.chrome.ChromeDriver import org.openqa.selenium.chrome.ChromeOptions

fun main() { val chromeOptions = ChromeOptions() chromeOptions.setPageLoadStrategy(PageLoadStrategy.NORMAL) val driver = ChromeDriver(chromeOptions) try { driver.get("https://www.google.com") } finally { driver.quit() } } {{< /tab >}} {{< /tabpane >}}

eager

WebDriver waits until DOMContentLoaded event fire is returned.

{{< tabpane langEqualsHeader=true >}} {{< badge-examples >}} {{< tab header="Java" text=true >}} {{< gh-codeblock path="/examples/java/src/test/java/dev/selenium/drivers/OptionsTest.java#L27-L29">}} {{< /tab >}} {{< tab header="Python" text=true >}} {{< gh-codeblock path="/examples/python/tests/drivers/test_options.py#L17-L18">}} {{< /tab >}} {{< tab header="CSharp" >}} using OpenQA.Selenium; using OpenQA.Selenium.Chrome;

namespace pageLoadStrategy { class pageLoadStrategy { public static void Main(string[] args) { var chromeOptions = new ChromeOptions(); chromeOptions.PageLoadStrategy = PageLoadStrategy.Eager; IWebDriver driver = new ChromeDriver(chromeOptions); try { driver.Navigate().GoToUrl("https://example.com"); } finally { driver.Quit(); } } } } {{< /tab >}} {{< tab header="Ruby" text=true >}} {{< gh-codeblock path="/examples/ruby/spec/drivers/options_spec.rb#L20-L21">}} {{< /tab >}} {{< tab header="JavaScript" text=true >}} {{< gh-codeblock path="/examples/javascript/test/capabilities/pageLoading.spec.js#L8-L14">}} {{< /tab >}} {{< tab header="Kotlin" >}} import org.openqa.selenium.PageLoadStrategy import org.openqa.selenium.chrome.ChromeDriver import org.openqa.selenium.chrome.ChromeOptions

fun main() { val chromeOptions = ChromeOptions() chromeOptions.setPageLoadStrategy(PageLoadStrategy.EAGER) val driver = ChromeDriver(chromeOptions) try { driver.get("https://www.google.com") } finally { driver.quit() } } {{< /tab >}} {{< /tabpane >}}

none

WebDriver only waits until the initial page is downloaded.

{{< tabpane langEqualsHeader=true >}} {{< badge-examples >}} {{< tab header="Java" text=true >}} {{< gh-codeblock path="/examples/java/src/test/java/dev/selenium/drivers/OptionsTest.java#L40-L42">}} {{< /tab >}} {{< tab header="Python" text=true >}} {{< gh-codeblock path="/examples/python/tests/drivers/test_options.py#L27-L28">}} {{< /tab >}} {{< tab header="CSharp" >}} using OpenQA.Selenium; using OpenQA.Selenium.Chrome;

namespace pageLoadStrategy { class pageLoadStrategy { public static void Main(string[] args) { var chromeOptions = new ChromeOptions(); chromeOptions.PageLoadStrategy = PageLoadStrategy.None; IWebDriver driver = new ChromeDriver(chromeOptions); try { driver.Navigate().GoToUrl("https://example.com"); } finally { driver.Quit(); } } } } {{< /tab >}} {{< tab header="Ruby" text=true >}} {{< gh-codeblock path="/examples/ruby/spec/drivers/options_spec.rb#L29-L30">}} {{< /tab >}} {{< tab header="JavaScript" text=true >}} {{< gh-codeblock path="/examples/javascript/test/capabilities/pageLoading.spec.js#L18-L24">}} {{< /tab >}} {{< tab header="Kotlin" >}} import org.openqa.selenium.PageLoadStrategy import org.openqa.selenium.chrome.ChromeDriver import org.openqa.selenium.chrome.ChromeOptions

fun main() { val chromeOptions = ChromeOptions() chromeOptions.setPageLoadStrategy(PageLoadStrategy.NONE) val driver = ChromeDriver(chromeOptions) try { driver.get("https://www.google.com") } finally { driver.quit() } } {{< /tab >}} {{< /tabpane >}}

platformName

This identifies the operating system at the remote-end, fetching the platformName returns the OS name.

In cloud-based providers, setting platformName sets the OS at the remote-end.

{{< tabpane text=true >}} {{< tab header="Java" >}} {{< badge-code >}} {{< /tab >}} {{% tab header="Python" %}} {{< badge-code >}} {{% /tab %}} {{< tab header="CSharp" >}} {{< badge-code >}} {{< /tab >}} {{< tab header="Ruby" >}} {{< gh-codeblock path="examples/ruby/spec/drivers/options_spec.rb#L38-L39" >}} {{< /tab >}} {{< tab header="JavaScript" >}} {{< badge-code >}} {{< /tab >}} {{< tab header="Kotlin" >}} {{< badge-code >}} {{< /tab >}} {{< /tabpane >}}

acceptInsecureCerts

This capability checks whether an expired (or) invalid TLS Certificate is used while navigating during a session.

If the capability is set to false, an insecure certificate error will be returned as navigation encounters any domain certificate problems. If set to true, invalid certificate will be trusted by the browser.

All self-signed certificates will be trusted by this capability by default. Once set, acceptInsecureCerts capability will have an effect for the entire session.

{{< tabpane text=true >}} {{< tab header="Java" >}} {{< badge-code >}} {{< /tab >}} {{% tab header="Python" %}} {{< badge-code >}} {{% /tab %}} {{< tab header="CSharp" >}} {{< badge-code >}} {{< /tab >}} {{< tab header="Ruby" >}} {{< gh-codeblock path="examples/ruby/spec/drivers/options_spec.rb#L51-L52" >}} {{< /tab >}} {{< tab header="JavaScript" >}} {{< badge-code >}} {{< /tab >}} {{< tab header="Kotlin" >}} {{< badge-code >}} {{< /tab >}} {{< /tabpane >}}

timeouts

A WebDriver session is imposed with a certain session timeout interval, during which the user can control the behaviour of executing scripts or retrieving information from the browser.

Each session timeout is configured with combination of different timeouts as described below:

Script Timeout

Specifies when to interrupt an executing script in a current browsing context. The default timeout 30,000 is imposed when a new session is created by WebDriver.

{{< tabpane text=true >}} {{< tab header="Java" >}} {{< badge-code >}} {{< /tab >}} {{% tab header="Python" %}} {{< badge-code >}} {{% /tab %}} {{< tab header="CSharp" >}} {{< badge-code >}} {{< /tab >}} {{< tab header="Ruby" >}} {{< gh-codeblock path="examples/ruby/spec/drivers/options_spec.rb#L114-L115" >}} {{< /tab >}} {{< tab header="JavaScript" >}} {{< badge-code >}} {{< /tab >}} {{< tab header="Kotlin" >}} {{< badge-code >}} {{< /tab >}} {{< /tabpane >}}

Page Load Timeout

Specifies the time interval in which web page needs to be loaded in a current browsing context. The default timeout 300,000 is imposed when a new session is created by WebDriver. If page load limits a given/default time frame, the script will be stopped by TimeoutException.

{{< tabpane text=true >}} {{< tab header="Java" >}} {{< badge-code >}} {{< /tab >}} {{% tab header="Python" %}} {{< badge-code >}} {{% /tab %}} {{< tab header="CSharp" >}} {{< badge-code >}} {{< /tab >}} {{< tab header="Ruby" >}} {{< gh-codeblock path="examples/ruby/spec/drivers/options_spec.rb#L105-L106" >}} {{< /tab >}} {{< tab header="JavaScript" >}} {{< badge-code >}} {{< /tab >}} {{< tab header="Kotlin" >}} {{< badge-code >}} {{< /tab >}} {{< /tabpane >}}

Implicit Wait Timeout

This specifies the time to wait for the implicit element location strategy when locating elements. The default timeout 0 is imposed when a new session is created by WebDriver.

{{< tabpane text=true >}} {{< tab header="Java" >}} {{< badge-code >}} {{< /tab >}} {{% tab header="Python" %}} {{< badge-code >}} {{% /tab %}} {{< tab header="CSharp" >}} {{< badge-code >}} {{< /tab >}} {{< tab header="Ruby" >}} {{< gh-codeblock path="examples/ruby/spec/drivers/options_spec.rb#L96-L97" >}} {{< /tab >}} {{< tab header="JavaScript" >}} {{< badge-code >}} {{< /tab >}} {{< tab header="Kotlin" >}} {{< badge-code >}} {{< /tab >}} {{< /tabpane >}}

unhandledPromptBehavior

Specifies the state of current session's user prompt handler. Defaults to dismiss and notify state

User Prompt Handler

This defines what action must take when a user prompt encounters at the remote-end. This is defined by unhandledPromptBehavior capability and has the following states:

  • dismiss
  • accept
  • dismiss and notify
  • accept and notify
  • ignore

{{< tabpane text=true >}} {{< tab header="Java" >}} {{< badge-code >}} {{< /tab >}} {{% tab header="Python" %}} {{< badge-code >}} {{% /tab %}} {{< tab header="CSharp" >}} {{< badge-code >}} {{< /tab >}} {{< tab header="Ruby" >}} {{< gh-codeblock path="examples/ruby/spec/drivers/options_spec.rb#L60-L61" >}} {{< /tab >}} {{< tab header="JavaScript" >}} {{< badge-code >}} {{< /tab >}} {{< tab header="Kotlin" >}} {{< badge-code >}} {{< /tab >}} {{< /tabpane >}}

setWindowRect

Indicates whether the remote end supports all of the resizing and repositioning commands.

{{< tabpane text=true >}} {{< tab header="Java" >}} {{< badge-code >}} {{< /tab >}} {{% tab header="Python" %}} {{< badge-code >}} {{% /tab %}} {{< tab header="CSharp" >}} {{< badge-code >}} {{< /tab >}} {{< tab header="Ruby" >}} {{< gh-codeblock path="examples/ruby/spec/drivers/options_spec.rb#L69-L70" >}} {{< /tab >}} {{< tab header="JavaScript" >}} {{< badge-code >}} {{< /tab >}} {{< tab header="Kotlin" >}} {{< badge-code >}} {{< /tab >}} {{< /tabpane >}}

strictFileInteractability

This new capability indicates if strict interactability checks should be applied to input type=file elements. As strict interactability checks are off by default, there is a change in behaviour when using Element Send Keys with hidden file upload controls.

{{< tabpane text=true >}} {{< tab header="Java" >}} {{< badge-code >}} {{< /tab >}} {{% tab header="Python" %}} {{< badge-code >}} {{% /tab %}} {{< tab header="CSharp" >}} {{< badge-code >}} {{< /tab >}} {{< tab header="Ruby" >}} {{< gh-codeblock path="examples/ruby/spec/drivers/options_spec.rb#L78-L79" >}} {{< /tab >}} {{< tab header="JavaScript" >}} {{< badge-code >}} {{< /tab >}} {{< tab header="Kotlin" >}} {{< badge-code >}} {{< /tab >}} {{< /tabpane >}}

proxy

A proxy server acts as an intermediary for requests between a client and a server. In simple terms, the traffic flows through the proxy server on its way to the address you requested and back.

A proxy server for automation scripts with Selenium could be helpful for:

  • Capture network traffic
  • Mock backend calls made by the website
  • Access the required website under complex network topologies or strict corporate restrictions/policies.

If you are in a corporate environment, and a browser fails to connect to a URL, this is most likely because the environment needs a proxy to be accessed.

Selenium WebDriver provides a way to proxy settings:

{{< tabpane text=true >}} {{< badge-examples >}} {{% tab header="Java" %}}

import org.openqa.selenium.Proxy;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.chrome.ChromeDriver;
import org.openqa.selenium.chrome.ChromeOptions;

public class ProxyTest {
  public static void main(String[] args) {
    Proxy proxy = new Proxy();
    proxy.setHttpProxy("<HOST:PORT>");
    ChromeOptions options = new ChromeOptions();
    options.setCapability("proxy", proxy);
    WebDriver driver = new ChromeDriver(options);
    driver.get("https://www.google.com/");
    driver.manage().window().maximize();
    driver.quit();
  }
}

{{% /tab %}} {{% tab header="Python" %}}

from selenium import webdriver

PROXY = "<HOST:PORT>"
webdriver.DesiredCapabilities.FIREFOX['proxy'] = {
"httpProxy": PROXY,
"ftpProxy": PROXY,
"sslProxy": PROXY,
"proxyType": "MANUAL",

}

with webdriver.Firefox() as driver:
    driver.get("https://selenium.dev")

{{% /tab %}} {{% tab header="CSharp" %}}

using OpenQA.Selenium;
using OpenQA.Selenium.Chrome;

public class ProxyTest{
public static void Main() {
ChromeOptions options = new ChromeOptions();
Proxy proxy = new Proxy();
proxy.Kind = ProxyKind.Manual;
proxy.IsAutoDetect = false;
proxy.SslProxy = "<HOST:PORT>";
options.Proxy = proxy;
options.AddArgument("ignore-certificate-errors");
IWebDriver driver = new ChromeDriver(options);
driver.Navigate().GoToUrl("https://www.selenium.dev/");
}
}

{{% /tab %}} {{< tab header="Ruby" >}} {{< gh-codeblock path="examples/ruby/spec/drivers/options_spec.rb#L87-L88" >}} {{< /tab >}} {{% tab header="JavaScript" %}}

let webdriver = require('selenium-webdriver');
let chrome = require('selenium-webdriver/chrome');
let proxy = require('selenium-webdriver/proxy');
let opts = new chrome.Options();

(async function example() {
opts.setProxy(proxy.manual({http: '<HOST:PORT>'}));
let driver = new webdriver.Builder()
.forBrowser('chrome')
.setChromeOptions(opts)
.build();
try {
await driver.get("https://selenium.dev");
}
finally {
await driver.quit();
}
}());

{{% /tab %}} {{% tab header="Kotlin" %}}

import org.openqa.selenium.Proxy
import org.openqa.selenium.WebDriver
import org.openqa.selenium.chrome.ChromeDriver
import org.openqa.selenium.chrome.ChromeOptions

class proxyTest {
fun main() {

        val proxy = Proxy()
        proxy.setHttpProxy("<HOST:PORT>")
        val options = ChromeOptions()
        options.setCapability("proxy", proxy)
        val driver: WebDriver = ChromeDriver(options)
        driver["https://www.google.com/"]
        driver.manage().window().maximize()
        driver.quit()
    }
}

{{% /tab %}} {{< /tabpane >}}