Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/atata-framework/atata-webdriversetup

Sets up browser drivers for Selenium WebDriver
https://github.com/atata-framework/atata-webdriversetup

atata browser-drivers chromedriver edgedriver geckodriver internetexplorerdriver operadriver selenium webdriver

Last synced: 3 months ago
JSON representation

Sets up browser drivers for Selenium WebDriver

Awesome Lists containing this project

README

        

# Atata.WebDriverSetup

[![NuGet](http://img.shields.io/nuget/v/Atata.WebDriverSetup.svg?style=flat)](https://www.nuget.org/packages/Atata.WebDriverSetup/)
[![GitHub release](https://img.shields.io/github/release/atata-framework/atata-webdriversetup.svg)](https://github.com/atata-framework/atata-webdriversetup/releases)
[![Build status](https://dev.azure.com/atata-framework/atata-webdriversetup/_apis/build/status/atata-webdriversetup-ci?branchName=main)](https://dev.azure.com/atata-framework/atata-webdriversetup/_build/latest?definitionId=39&branchName=main)
[![Atata Templates](https://img.shields.io/badge/get-Atata_Templates-green.svg?color=4BC21F)](https://marketplace.visualstudio.com/items?itemName=YevgeniyShunevych.AtataTemplates)\
[![Slack](https://img.shields.io/badge/join-Slack-green.svg?colorB=4EB898)](https://join.slack.com/t/atata-framework/shared_invite/zt-5j3lyln7-WD1ZtMDzXBhPm0yXLDBzbA)
[![Atata docs](https://img.shields.io/badge/docs-Atata_Framework-orange.svg)](https://atata.io)
[![Twitter](https://img.shields.io/badge/[email protected])](https://twitter.com/AtataFramework)

**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](#features)
- [Installation](#installation)
- [Usage](#usage)
- [Set Up Version Corresponding to Locally Installed Browser Version](#set-up-version-corresponding-to-locally-installed-browser-version)
- [Set Up Latest Version](#set-up-latest-version)
- [Set Up Specific Version](#set-up-specific-version)
- [Set Up Version Corresponding to Specific Browser Version](#set-up-version-corresponding-to-specific-browser-version)
- [DriverSetup Members](#driversetup-members)
- [DriverSetup Properties](#driversetup-properties)
- [DriverSetup Methods](#driversetup-methods)
- [Configuration](#configuration)
- [Global Configuration](#global-configuration)
- [Driver-Specific Configuration](#driver-specific-configuration)
- [Configuration Methods](#configuration-methods)
- [Handle HTTPS Certificate Errors](#handle-https-certificate-errors)
- [BrowserDetector](#browserdetector)
- [BrowserDetector Methods](#browserdetector-methods)
- [BrowserDetector Usage](#browserdetector-usage)
- [Feedback](#feedback)
- [SemVer](#semver)
- [License](#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`](https://www.nuget.org/packages/Atata.WebDriverSetup/) NuGet package.

- Package Manager:
```
Install-Package Atata.WebDriverSetup
```

- .NET CLI:
```
dotnet add package Atata.WebDriverSetup
```

The package depends on:

- [`Microsoft.Win32.Registry`](https://www.nuget.org/packages/Microsoft.Win32.Registry/) - is used to detect locally installed browser version through Windows Registry.
- [`Atata.Cli`](https://www.nuget.org/packages/Atata.Cli/) - is used to detect locally installed browser version through CLI on Linux and macOS.
- [`System.Text.Json`](https://www.nuget.org/packages/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:

```cs
[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.

```cs
ChromeDriver chromeDriver = new ChromeDriver();
```

### Set Up Version Corresponding to Locally Installed Browser Version

1. Configure with default configuration options:
```cs
DriverSetup.AutoSetUp(BrowserNames.Chrome);
```
1. Configure with custom configuration options:
```cs
DriverSetup.ConfigureChrome()
.WithAutoVersion()
// Additional options can be set here.
.SetUp();
```

`DriverSetup.AutoSetUp` method also supports multiple drivers setup:

```cs
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

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

### Set Up Specific Version

```cs
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

```cs
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 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 driverSetupStrategyFactory)`**\
Creates the driver setup configuration builder using `driverSetupStrategyFactory`
that instantiates specific `IDriverSetupStrategy`.
- **`DriverSetupResult AutoSetUp(string browserName)`** &\
**`Task 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 browserNames)`** &\
**`Task AutoSetUpAsync(params string[] browserNames)`** &\
**`Task AutoSetUpAsync(IEnumerable 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 browserNames)`** &\
**`Task AutoSetUpSafelyAsync(IEnumerable 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 SetUpPendingConfigurationsAsync()`**\
Sets up pending configurations that are stored in `PendingConfigurations` property.
- **`void RegisterStrategyFactory(string browserName, Func 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

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

#### Using Options Properties

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

### Default Driver Configuration

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

### Driver-Specific Configuration

```cs
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 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.

```cs
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 browserNames)`**\
Gets the name of the first installed browser among the `browserNames`.

### BrowserDetector Usage

#### Get First Installed Browser Name

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

#### Is Browser Installed

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

#### Get Installed Browser Version

```cs
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](https://github.com/atata-framework/atata-webdriversetup/issues),
[ask a question on Stack Overflow](https://stackoverflow.com/questions/ask?tags=atata+csharp) using [atata](https://stackoverflow.com/questions/tagged/atata) tag
or use another [Atata Contact](https://atata.io/contact/) way.

## SemVer

Atata Framework follows [Semantic Versioning 2.0](https://semver.org/).
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](LICENSE) for details.