Atata.WebDriverSetup

Atata.WebDriverSetup is a .NET library that sets up browser drivers for Selenium WebDriver, e.g. chromedriver, geckodriver, etc. Basically, it provides functionality similar to Java WebDriverManager.

The package targets .NET Standard 2.0, which supports .NET 5+, .NET Framework 4.6.1+ and .NET Core/Standard 2.0+.

Table of Contents

• Features
• Installation
• Usage
  • Set Up Version Corresponding to Locally Installed Browser Version
  • Set Up Latest Version
  • Set Up Specific Version
  • Set Up Version Corresponding to Specific Browser Version
• DriverSetup Members
  • DriverSetup Properties
  • DriverSetup Methods
• Configuration
  • Global Configuration
  • Driver-Specific Configuration
  • Configuration Methods
  • Handle HTTPS Certificate Errors
• BrowserDetector
  • BrowserDetector Methods
  • BrowserDetector Usage
• Feedback
• SemVer
• License

Features

• Sets up drivers for browsers: Chrome, Firefox, Edge, Internet Explorer and Opera.
• Supports Windows, Linux and macOS platforms.
• Can download latest or specific driver versions.
• Can auto-detect locally installed browser version and download corresponding driver version.
• Caches the used driver versions.
• After a driver is set up, adds the driver path to environment "PATH" variable, which is consumed by WebDriver.

Installation

Install Atata.WebDriverSetup NuGet package.

• Package Manager:

  Install-Package Atata.WebDriverSetup
  

• .NET CLI:

  dotnet add package Atata.WebDriverSetup
  

The package depends on:

• Microsoft.Win32.Registry - is used to detect locally installed browser version through Windows Registry.
• Atata.Cli - is used to detect locally installed browser version through CLI on Linux and macOS.
• System.Text.Json - is used to read JSON HTTP responses.

Usage

The main class is DriverSetup. The recommended place to perform driver(s) setup is a global set up method.

NUnit example:

[SetUpFixture]
public class SetUpFixture
{
    [OneTimeSetUp]
    public void SetUp()
    {
        DriverSetup.AutoSetUp(BrowserNames.Chrome);
    }
}

After a driver is set up, the driver path is added to environment "PATH" variable, which is read by WebDriver's DriverService classes.

ChromeDriver chromeDriver = new ChromeDriver();

Set Up Version Corresponding to Locally Installed Browser Version

1. Configure with default configuration options:

   DriverSetup.AutoSetUp(BrowserNames.Chrome);

2. Configure with custom configuration options:

   DriverSetup.ConfigureChrome()
       .WithAutoVersion()
       // Additional options can be set here.
       .SetUp();

DriverSetup.AutoSetUp method also supports multiple drivers setup:

DriverSetup.AutoSetUp(BrowserNames.Chrome, BrowserNames.Edge);

Note: If the version of browser cannot be detected automatically, latest driver version is used. Version auto-detection is currently supported for Chrome, Firefox and Edge browsers.

Set Up Latest Version

DriverSetup.ConfigureChrome()
    .WithLatestVersion()
    .SetUp();

Set Up Specific Version

DriverSetup.ConfigureChrome()
    .WithVersion("87.0.4280.88")
    .SetUp();

Version format:

• Chrome: "87.0.4280.88"
• Firefox: "0.28.0"
• Edge: "89.0.774.4"
• Opera: "86.0.4240.80"
• InternetExplorer: "3.141.59"

Set Up Version Corresponding to Specific Browser Version

DriverSetup.ConfigureChrome()
    .ByBrowserVersion("87")
    .SetUp();

Note: This feature is currently supported for Chrome, Firefox and Edge browsers.

Version format:

• Chrome: "87" or "87.0.4280"
• Firefox: "104", "104.0" or "104.0.1"
• Edge: "89.0.774.4"

DriverSetup Members

DriverSetup is a static class, so all its members are static too.

DriverSetup Properties

• DriverSetupOptions GlobalOptions { get; }
  Gets the global setup options.
• DriverSetupOptionsBuilder GlobalConfiguration { get; }
  Gets the global setup configuration builder. Configures GlobalOptions.
• List<DriverSetupConfigurationBuilder> PendingConfigurations { get; }
  Gets the pending driver setup configurations, the configurations that were created but were not set up.

DriverSetup Methods

• DriverSetupConfigurationBuilder ConfigureChrome()
  Creates the Chrome driver setup configuration builder.
• DriverSetupConfigurationBuilder ConfigureFirefox()
  Creates the Firefox/Gecko driver setup configuration builder.
• DriverSetupConfigurationBuilder ConfigureEdge()
  Creates the Edge driver setup configuration builder.
• DriverSetupConfigurationBuilder ConfigureOpera()
  Creates the Opera driver setup configuration builder.
• DriverSetupConfigurationBuilder ConfigureInternetExplorer()
  Creates the Internet Explorer driver setup configuration builder.
• DriverSetupConfigurationBuilder Configure(string browserName)
  Creates the driver setup configuration builder for the specified browserName. Supported browser names are defined in BrowserNames static class.
• DriverSetupConfigurationBuilder Configure(string browserName, Func<IHttpRequestExecutor, IDriverSetupStrategy> driverSetupStrategyFactory)
  Creates the driver setup configuration builder using driverSetupStrategyFactory that instantiates specific IDriverSetupStrategy.
• DriverSetupResult AutoSetUp(string browserName) &
  Task<DriverSetupResult> AutoSetUpAsync(string browserName)
  Sets up driver with auto version detection for the browser with the specified name. Supported browser names are defined in BrowserNames static class.
• DriverSetupResult[] AutoSetUp(params string[] browserNames) &
  DriverSetupResult[] AutoSetUp(IEnumerable<string> browserNames) &
  Task<DriverSetupResult[]> AutoSetUpAsync(params string[] browserNames) &
  Task<DriverSetupResult[]> AutoSetUpAsync(IEnumerable<string> browserNames)
  Sets up drivers with auto version detection for the browsers with the specified names. Supported browser names are defined in BrowserNames static class.
• DriverSetupResult[] AutoSetUpSafely(IEnumerable<string> browserNames) &
  Task<DriverSetupResult[]> AutoSetUpSafelyAsync(IEnumerable<string> browserNames)
  Sets up drivers with auto version detection for the browsers with the specified names. Supported browser names are defined in BrowserNames static class. Skips invalid/unsupported browser names.
• DriverSetupOptionsBuilder GetDefaultConfiguration(string browserName)
  Gets the default driver setup configuration builder.
• DriverSetupResult[] SetUpPendingConfigurations() &
  Task<DriverSetupResult[]> SetUpPendingConfigurationsAsync()
  Sets up pending configurations that are stored in PendingConfigurations property.
• void RegisterStrategyFactory(string browserName, Func<IHttpRequestExecutor, IDriverSetupStrategy> driverSetupStrategyFactory)
  Registers the driver setup strategy factory.

Configuration

It's possible to set configuration options globally and separately for a specific driver.

Global Configuration

Using Fluent Builder

DriverSetup.GlobalConfiguration
    .WithStorageDirectoryPath("...")
    .WithVersionCache(false);

Using Options Properties

DriverSetup.GlobalOptions.StorageDirectoryPath = "...";
DriverSetup.GlobalOptions.UseVersionCache = false;

Default Driver Configuration

DriverSetup.GetDefaultConfiguration(BrowserNames.InternetExplorer)
    .WithX32Architecture();

Driver-Specific Configuration

DriverSetup.ConfigureChrome()
    .WithStorageDirectoryPath("...")
    .WithVersionCache(false)
    .SetUp();

Don't forget to call SetUp() or SetUpAsync() at the end.

Configuration Methods

Driver-Specific Configuration Methods

• WithAutoVersion()
  Sets the automatic driver version detection by installed browser version. If the version cannot be detected automatically, latest driver version should be used.
• WithLatestVersion()
  Sets the latest version of driver.
• ByBrowserVersion(string version)
  Sets the browser version. It will find driver version corresponding to the browser version.
• WithVersion(string version)
  Sets the version of driver to use.
• WithEnvironmentVariableName(string variableName)
  Sets the name of the environment variable that will be set with a value equal to the driver directory path. The default value is specific to the driver being configured. It has "{BrowserName}Driver" format. For example: "ChromeDriver" or "InternetExplorerDriver". The null value means that none variable should be set.

Common Configuration Methods

• WithStorageDirectoryPath(string path)
  Sets the storage directory path. The default value is "{basedir}/drivers").
• WithX32Architecture()
  Sets the x32 (x86) architecture.
• WithX64Architecture()
  Sets the x64 architecture.
• WithArm64Architecture()
  Sets the ARM64 architecture.
• WithArchitecture(Architecture architecture)
  Sets the architecture. The default value is Architecture.Auto.
• WithProxy(IWebProxy proxy)
  Sets the web proxy.
• WithCheckCertificateRevocationList(bool checkCertificateRevocationList)
  Sets a value indicating whether the certificate is automatically picked from the certificate store or if the caller is allowed to pass in a specific client certificate. The default value is true.
• WithHttpClientHandlerConfiguration(Action<HttpClientHandler> httpClientHandlerConfigurationAction)
  Sets the configuration action of HttpClientHandler. The HttpClientHandler instance is used to get a driver version information and to download a driver archive.
• WithMutex(bool isEnabled)
  Sets a value indicating whether to use mutex to sync driver setup across machine.. The default value is true.
• WithVersionCache(bool isEnabled)
  Sets a value indicating whether to use version cache. The default value is true.
• WithLatestVersionCheckInterval(TimeSpan interval)
  Sets the latest version check interval. The default values is 2 hours.
• WithSpecificVersionCheckInterval(TimeSpan interval)
  Sets the specific version check interval. The default values is 2 hours.
• WithHttpRequestTryCount(int count)
  Sets the HTTP request try count. The default values is 3.
• WithHttpRequestRetryInterval(TimeSpan interval)
  Sets the HTTP request retry interval. The default values is 3 seconds.
• WithEnabledState(bool isEnabled)
  Sets a value indicating whether the configuration is enabled. The default values is true.
• WithAddToEnvironmentPathVariable(bool isEnabled)
  Sets a value indicating whether to add the driver directory path to environment "Path" variable. The default value is true.

Handle HTTPS Certificate Errors

Rarely you can get HTTP certificate errors during driver setup. In order to handle such errors you can try one or both of the configuration settings below.

DriverSetup.GlobalConfiguration
    .WithCheckCertificateRevocationList(false)
    .WithHttpClientHandlerConfiguration(x => x.ServerCertificateCustomValidationCallback = HttpClientHandler.DangerousAcceptAnyServerCertificateValidator);

BrowserDetector

BrowserDetector - provides a set of static methods for a detection of browser installations. Browser detection is supported for Chrome, Firefox and Edge, so as a browser name the following constants can be used:

• BrowserNames.Chrome
• BrowserNames.Firefox
• BrowserNames.Edge

BrowserDetector Methods

• string GetInstalledBrowserVersion(string browserName)
  Gets the installed browser version by the browser name.
• bool IsBrowserInstalled(string browserName)
  Determines whether the browser with the specified name is installed.
• string GetFirstInstalledBrowserName(params string[] browserNames)
  Gets the name of the first installed browser among the browserNames.
• string GetFirstInstalledBrowserName(IEnumerable<string> browserNames)
  Gets the name of the first installed browser among the browserNames.

BrowserDetector Usage

Get First Installed Browser Name

string browserName = BrowserDetector.GetFirstInstalledBrowserName(
    BrowserNames.Chrome,
    BrowserNames.Firefox,
    BrowserNames.Edge);

Is Browser Installed

bool isChromeInstalled = BrowserDetector.IsBrowserInstalled(BrowserNames.Chrome);

Get Installed Browser Version

string chromeVersion = BrowserDetector.GetInstalledBrowserVersion(BrowserNames.Chrome);

Feedback

Any feedback, issues and feature requests are welcome.

If you faced an issue please report it to Atata.WebDriverSetup Issues, ask a question on Stack Overflow using atata tag or use another Atata Contact way.

SemVer

Atata Framework follows Semantic Versioning 2.0. Thus backward compatibility is followed and updates within the same major version (e.g. from 1.3 to 1.4) should not require code changes.

License

Atata is an open source software, licensed under the Apache License 2.0. See LICENSE for details.