Driver Sessions

• 1: Opções do navegador
• 2: HTTP Client Configuration
• 3: Driver Service Class
• 4: Remote WebDriver

      driver = Selenium::WebDriver.for :chrome, options: options

      driver.quit

1 - Opções do navegador

No Selenium 3, os recursos foram definidos em uma sessão usando classes de recursos desejados. A partir do Selenium 4, você deve usar as classes de opções do navegador. Para sessões remotas de driver, uma instância de opções do navegador é necessária, pois determina qual navegador será usado.

Essas opções são descritas na especificação w3c para Capabilities.

Cada navegador tem custom options que podem ser definidas além das definidas na especificação.

browserName

Esta capacidade é usada para definir o browserName para uma determinada sessão. Se o navegador especificado não estiver instalado no extremidade remota, a criação da sessão falhará.

• Java
• Python
• CSharp
• Ruby
• JavaScript
• Kotlin

      options = Selenium::WebDriver::Options.chrome

browserVersion

Esta capacidade é opcional, é usada para defina a versão do navegador disponível na extremidade remota. Por exemplo, se solicitar o Chrome versão 75 em um sistema que tiver apenas 80 instalados, a criação da sessão falhará.

• Java
• Python
• CSharp
• Ruby
• JavaScript
• Kotlin

    options = Selenium::WebDriver::Options.chrome(browser_version: 'stable')

pageLoadStrategy

Três tipos de estratégias de carregamento de página estão disponíveis.

A estratégia de carregamento da página consulta o document.readyState conforme descrito na tabela abaixo:

A propriedade document.readyState de um documento descreve o estado de carregamento do documento atual.

Ao navegar para uma nova página via URL, por padrão, o WebDriver irá adiar a conclusão de uma navegação (por exemplo, driver.navigate().get()) até que o estado pronto do documento seja concluído. isso não significa necessariamente que a página terminou de carregar, especialmente para sites como Single Page Applications que usam JavaScript para carregar conteúdo dinamicamente depois que o estado Pronto retorna completo. Observe também que esse comportamento não se aplica à navegação resultante de clicar em um elemento ou enviar um formulário.

Se uma página demorar muito para carregar como resultado do download de ativos (por exemplo, imagens, css, js) que não são importantes para a automação, você pode mudar do parâmetro padrão de normal para eager ou none para acelerar a sessão. Esse valor se aplica a toda a sessão, portanto, certifique-se que sua waiting strategy é suficiente para minimizar descamação.

normal (default)

WebDriver waits until the load event fire is returned.

• Java
• Python
• CSharp
• Ruby
• JavaScript
• Kotlin

    ChromeOptions chromeOptions = new ChromeOptions();
    chromeOptions.setPageLoadStrategy(PageLoadStrategy.NORMAL);
    WebDriver driver = new ChromeDriver(chromeOptions);

    options.page_load_strategy = 'normal'
    driver = webdriver.Chrome(options=options)

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();
      }
    }
  }
}

      options = Selenium::WebDriver::Options.chrome
      options.page_load_strategy = :normal

    it('Navigate using normal page loading strategy', async function () {
      let driver = await env
        .builder()
        .setChromeOptions(options.setPageLoadStrategy('normal'))
        .build();

      await driver.get('https://www.selenium.dev/selenium/web/blank.html');

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()
  }
}

eager

WebDriver waits until DOMContentLoaded event fire is returned.

• Java
• Python
• CSharp
• Ruby
• JavaScript
• Kotlin

    ChromeOptions chromeOptions = new ChromeOptions();
    chromeOptions.setPageLoadStrategy(PageLoadStrategy.EAGER);
    WebDriver driver = new ChromeDriver(chromeOptions);

    options.page_load_strategy = 'eager'
    driver = webdriver.Chrome(options=options)

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();
      }
    }
  }
}

      options = Selenium::WebDriver::Options.chrome
      options.page_load_strategy = :eager

    it('Navigate using eager page loading strategy', async function () {
      let driver = await env
        .builder()
        .setChromeOptions(options.setPageLoadStrategy('eager'))
        .build();

      await driver.get('https://www.selenium.dev/selenium/web/blank.html');

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()
  }
}

none

WebDriver only waits until the initial page is downloaded.

• Java
• Python
• CSharp
• Ruby
• JavaScript
• Kotlin

    ChromeOptions chromeOptions = new ChromeOptions();
    chromeOptions.setPageLoadStrategy(PageLoadStrategy.NONE);
    WebDriver driver = new ChromeDriver(chromeOptions);

    options.page_load_strategy = 'none'
    driver = webdriver.Chrome(options=options)

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();
      }
    }
  }
}

      options = Selenium::WebDriver::Options.chrome
      options.page_load_strategy = :none

    it('Navigate using none page loading strategy', async function () {
      let driver = await env
        .builder()
        .setChromeOptions(options.setPageLoadStrategy('none'))
        .build();

      await driver.get('https://www.selenium.dev/selenium/web/blank.html');

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()
  }
}

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.

• Java
• Python
• CSharp
• Ruby
• JavaScript
• Kotlin

      options = Selenium::WebDriver::Options.firefox
      options.platform_name = 'Windows 10'

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.

• Java
• Python
• CSharp
• Ruby
• JavaScript
• Kotlin

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.

• Java
• Python
• CSharp
• Ruby
• JavaScript
• Kotlin

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.

• Java
• Python
• CSharp
• Ruby
• JavaScript
• Kotlin

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.

• Java
• Python
• CSharp
• Ruby
• JavaScript
• Kotlin

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

• Java
• Python
• CSharp
• Ruby
• JavaScript
• Kotlin

setWindowRect

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

• Java
• Python
• CSharp
• Ruby
• JavaScript
• Kotlin

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.

• Java
• Python
• CSharp
• Ruby
• JavaScript
• Kotlin

proxy

A proxy server acts as an intermediary for requests between a client and a server. In simple, 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:

• Java
• Python
• CSharp
• Ruby
• JavaScript
• Kotlin

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();
  }
}

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")

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/");
}
}

proxy = Selenium::WebDriver::Proxy.new(http: '<HOST:PORT>')
cap   = Selenium::WebDriver::Remote::Capabilities.chrome(proxy: proxy)

driver = Selenium::WebDriver.for(:chrome, capabilities: cap)
driver.get('http://google.com')

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();
}
}());

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()
    }
}

2 - HTTP Client Configuration

These allow you to set various parameters for the HTTP library

• Java
• Python
• CSharp
• Ruby
• JavaScript
• Kotlin

3 - Driver Service Class

The Service classes are for managing the starting and stopping of drivers. They can not be used with a Remote WebDriver session.

Service classes allow you to specify information about the driver, like location and which port to use. They also let you specify what arguments get passed to the command line. Most of the useful arguments are related to logging.

Default Service instance

To start a driver with a default service instance:

• Java
• Python
• CSharp
• Ruby
• JavaScript
• Kotlin

    ChromeDriverService service = new ChromeDriverService.Builder().build();
    driver = new ChromeDriver(service);

    service = webdriver.ChromeService()
    driver = webdriver.Chrome(service=service)

            var service = ChromeDriverService.CreateDefaultService();
            driver = new ChromeDriver(service);

    service = Selenium::WebDriver::Service.chrome
    @driver = Selenium::WebDriver.for :chrome, service: service

Driver location

Note: If you are using Selenium 4.6 or greater, you shouldn’t need to set a driver location. If you can not update Selenium or have an advanced use case here is how to specify the driver location:

• Java
• Python
• CSharp
• Ruby
• JavaScript
• Kotlin

    ChromeDriverService service =
        new ChromeDriverService.Builder().usingDriverExecutable(driverPath).build();

    service = webdriver.ChromeService(executable_path=chromedriver_bin)

            var service = ChromeDriverService.CreateDefaultService(GetDriverLocation(options));

    service.executable_path = driver_path

Driver port

If you want the driver to run on a specific port, you may specify it as follows:

• Java
• Python
• CSharp
• Ruby
• JavaScript
• Kotlin

    ChromeDriverService service = new ChromeDriverService.Builder().usingPort(1234).build();

    service = webdriver.ChromeService(port=1234)

            service.Port = 1234;

    service.port = 1234

Logging

Logging functionality varies between browsers. Most browsers allow you to specify location and level of logs. Take a look at the respective browser page:

• Chrome
• Edge
• Firefox
• Internet Explorer
• Safari

4 - Remote WebDriver

Selenium lets you automate browsers on remote computers if there is a Selenium Grid running on them. The computer that executes the code is referred to as the client computer, and the computer with the browser and driver is referred to as the remote computer or sometimes as an end-node. To direct Selenium tests to the remote computer, you need to use a Remote WebDriver class and pass the URL including the port of the grid on that machine. Please see the grid documentation for all the various ways the grid can be configured.

Basic Example

The driver needs to know where to send commands to and which browser to start on the Remote computer. So an address and an options instance are both required.

• Java
• Python
• CSharp
• Ruby
• JavaScript
• Kotlin

    ChromeOptions options = new ChromeOptions();
    driver = new RemoteWebDriver(gridUrl, options);

    options = webdriver.ChromeOptions()
    driver = webdriver.Remote(command_executor=server, options=options)

            var options = new ChromeOptions();
            driver = new RemoteWebDriver(GridUrl, options);

    options = Selenium::WebDriver::Options.chrome
    driver = Selenium::WebDriver.for :remote, url: grid_url, options: options

Uploads

Uploading a file is more complicated for Remote WebDriver sessions because the file you want to upload is likely on the computer executing the code, but the driver on the remote computer is looking for the provided path on its local file system. The solution is to use a Local File Detector. When one is set, Selenium will bundle the file, and send it to the remote machine, so the driver can see the reference to it. Some bindings include a basic local file detector by default, and all of them allow for a custom file detector.

• Java
• Python
• CSharp
• Ruby
• JavaScript
• Kotlin

    ((RemoteWebDriver) driver).setFileDetector(new LocalFileDetector());
    WebElement fileInput = driver.findElement(By.cssSelector("input[type=file]"));
    fileInput.sendKeys(uploadFile.getAbsolutePath());
    driver.findElement(By.id("file-submit")).click();

    driver.file_detector = LocalFileDetector()
    file_input = driver.find_element(By.CSS_SELECTOR, "input[type='file']")
    file_input.send_keys(upload_file)
    driver.find_element(By.ID, "file-submit").click()

            ((RemoteWebDriver)driver).FileDetector = new LocalFileDetector();
            IWebElement fileInput = driver.FindElement(By.CssSelector("input[type=file]"));
            fileInput.SendKeys(uploadFile);
            driver.FindElement(By.Id("file-submit")).Click();

    driver.file_detector = ->((filename, *)) { filename.include?('selenium') && filename }
    file_input = driver.find_element(css: 'input[type=file]')
    file_input.send_keys(upload_file)
    driver.find_element(id: 'file-submit').click

Downloads

Chrome, Edge and Firefox each allow you to set the location of the download directory. When you do this on a remote computer, though, the location is on the remote computer’s local file system. Selenium allows you to enable downloads to get these files onto the client computer.

Enable Downloads in the Grid

Regardless of the client, when starting the grid in node or standalone mode, you must add the flag:

--enable-managed-downloads true

Enable Downloads in the Client

The grid uses the se:downloadsEnabled capability to toggle whether to be responsible for managing the browser location. Each of the bindings have a method in the options class to set this.

• Java
• Python
• CSharp
• Ruby
• JavaScript
• Kotlin

    ChromeOptions options = new ChromeOptions();
    options.setEnableDownloads(true);
    driver = new RemoteWebDriver(gridUrl, options);

    options = webdriver.ChromeOptions()
    options.enable_downloads = True
    driver = webdriver.Remote(command_executor=server, options=options)

            ChromeOptions options = new ChromeOptions
            {
                EnableDownloads = true
            };

            driver = new RemoteWebDriver(GridUrl, options);

    options = Selenium::WebDriver::Options.chrome(enable_downloads: true)
    driver = Selenium::WebDriver.for :remote, url: grid_url, options: options

List Downloadable Files

Be aware that Selenium is not waiting for files to finish downloading, so the list is an immediate snapshot of what file names are currently in the directory for the given session.

• Java
• Python
• CSharp
• Ruby
• JavaScript
• Kotlin

    List<String> files = ((HasDownloads) driver).getDownloadableFiles();

    files = driver.get_downloadable_files()

            IReadOnlyList<string> names = ((RemoteWebDriver)driver).GetDownloadableFiles();

    files = driver.downloadable_files

Download a File

Selenium looks for the name of the provided file in the list and downloads it to the provided target directory.

• Java
• Python
• CSharp
• Ruby
• JavaScript
• Kotlin

    ((HasDownloads) driver).downloadFile(downloadableFile, targetDirectory);

    driver.download_file(downloadable_file, target_directory)

            ((RemoteWebDriver)driver).DownloadFile(downloadableFile, targetDirectory);

    driver.download_file(downloadable_file, target_directory)

Delete Downloaded Files

By default, the download directory is deleted at the end of the applicable session, but you can also delete all files during the session.

• Java
• Python
• CSharp
• Ruby
• JavaScript
• Kotlin

    ((HasDownloads) driver).deleteDownloadableFiles();

    driver.delete_downloadable_files()

            ((RemoteWebDriver)driver).DeleteDownloadableFiles();

    driver.delete_downloadable_files

Browser specific functionalities

Each browser has implemented special functionality that is available only to that browser. Each of the Selenium bindings has implemented a different way to use those features in a Remote Session

• Java
• Python
• CSharp
• Ruby
• JavaScript
• Kotlin

    driver = new Augmenter().augment(driver);

        RemoteWebDriver.builder()
            .address(gridUrl)
            .oneOf(new ChromeOptions())
            .setCapability("ext:options", Map.of("key", "value"))
            .config(ClientConfig.defaultConfig())
            .build();

            var customCommandDriver = driver as ICustomDriverCommandExecutor;
            customCommandDriver.RegisterCustomDriverCommands(FirefoxDriver.CustomCommandDefinitions);

            var screenshotResponse = customCommandDriver
                .ExecuteCustomDriverCommand(FirefoxDriver.GetFullPageScreenshotCommand, null);

Tracing client requests

This feature is only available for Java client binding (Beta onwards). The Remote WebDriver client sends requests to the Selenium Grid server, which passes them to the WebDriver. Tracing should be enabled at the server and client-side to trace the HTTP requests end-to-end. Both ends should have a trace exporter setup pointing to the visualization framework. By default, tracing is enabled for both client and server. To set up the visualization framework Jaeger UI and Selenium Grid 4, please refer to Tracing Setup for the desired version.

For client-side setup, follow the steps below.

Add the required dependencies

Installation of external libraries for tracing exporter can be done using Maven. Add the opentelemetry-exporter-jaeger and grpc-netty dependency in your project pom.xml:

  <dependency>
      <groupId>io.opentelemetry</groupId>
      <artifactId>opentelemetry-exporter-jaeger</artifactId>
      <version>1.0.0</version>
    </dependency>
    <dependency>
      <groupId>io.grpc</groupId>
      <artifactId>grpc-netty</artifactId>
      <version>1.35.0</version>
    </dependency>

Add/pass the required system properties while running the client

• Java

System.setProperty("otel.traces.exporter", "jaeger");
System.setProperty("otel.exporter.jaeger.endpoint", "http://localhost:14250");
System.setProperty("otel.resource.attributes", "service.name=selenium-java-client");

ImmutableCapabilities capabilities = new ImmutableCapabilities("browserName", "chrome");

WebDriver driver = new RemoteWebDriver(new URL("http://www.example.com"), capabilities);

driver.get("http://www.google.com");

driver.quit();

Please refer to Tracing Setup for more information on external dependencies versions required for the desired Selenium version.

More information can be found at:

• OpenTelemetry: https://opentelemetry.io
• Configuring OpenTelemetry: https://github.com/open-telemetry/opentelemetry-java/tree/main/sdk-extensions/autoconfigure
• Jaeger: https://www.jaegertracing.io
• Selenium Grid Observability