Selenium Manager (测试版)

动机

简而言之: Selenium Manager 是 Selenium 项目的官方驱动程序管理器, 并且在每次 Selenium 发布时都会随附提供.

Selenium 利用每个浏览器实现的原生支持来执行自动化流程. 因此, Selenium 用户需要在使用 Selenium API 的脚本和浏览器之间放置一个名为 驱动程序(如 chromedriver、geckodriver、msedgedriver 等)的组件. 多年来, 管理这些驱动程序, 对Selenium 用户来说, 一直是个繁琐手动过程. 他们必须下载浏览器所需的驱动程序(如 Chrome 的 chromedriver、Firefox 的 geckodriver 等), 并将其放置在 PATH 中或以系统属性的形式导出驱动程序路径(如 Java、JavaScript 等). 但这种过程很麻烦, 导致了可维护性问题.

让我们来看一个例子. 假设您手动下载了用于通过 Selenium 驱动 Chrome 的所需 chromedriver. 在执行此操作时, Chrome 的稳定版本是 113, 所以您下载了 chromedriver 113 并将其放在您的 PATH 中. 此时, 您的 Selenium 脚本执行正确. 但 问题 在于 Chrome 是 保持更新 的. 这指的是 Chrome 能够在有新版本可用时自动且静默地升级到下一个稳定版本. 此功能对终端用户来说很棒, 但对浏览器自动化来说可能很危险. 让我们回到这个例子来明确这一点. 当您本地的 Chrome 最终更新到了 115 版本. 此时, 由于手动下载的驱动程序(113 版)与 Chrome 版本(115 版)不兼容, 您的 Selenium 脚本出错了. 因此, 您的 Selenium 脚本会因以下错误消息而失败: “会话无法创建: 此版本的 ChromeDriver 仅支持 Chrome 版本 113”.

这个问题是所谓的驱动管理器(例如 Java 的 WebDriverManager 、 Python 的 webdriver-manager 、 JavaScript 的 webdriver-manager 、 C# 的 WebDriverManager.Net 以及 Ruby 的 webdrivers 存在的主要原因. 所有这些项目都是一种启示, 也清楚地表明社区需要将此功能内置到 Selenium 中. 因此, Selenium 项目创建了 Selenium Manager, 这是 Selenium 的官方驱动管理器, 从 4.6 版本开始, 它随每个 Selenium 发行版一起提供.

用法

简而言之: 当驱动程序(如 ChromeDriver、GeckoDriver 等)不可用时, Selenium 绑定会使用 Selenium Manager.

通过 Selenium Manager 进行驱动程序管理是 Selenium 绑定的 可选功能 . 因此, 用户可以继续手动管理其驱动程序(将驱动程序放在 PATH 中或使用系统属性), 也可以依靠第三方 驱动程序管理器 自动完成. Selenium Manager 仅作为备用方案: 如果未提供驱动程序, Selenium Manager 将会介入.

Selenium Manager 是一个用 Rust 语言实现的命令行界面(CLI)工具, 可于 Windows、Linux 和 macOS 等多种操作系统上跨平台运行. Selenium Manager 的二进制文件随每个 Selenium 版本一起发布. 这样, 每个 Selenium 绑定语言都会调用 Selenium Manager 来执行以下各节中所述的自动化驱动程序和浏览器管理.

Automated driver management 自动驱动管理

简而言之: 当所需驱动程序不可用时, Selenium Manager 会自动寻找、下载并缓存 Selenium 所需的驱动程序.

Selenium Manager 的主要特性被称为 自动驱动管理 . 让我们通过一个例子来理解它. 假设我们想用 Selenium 驱动 Chrome(请参阅关于如何使用Selenium启动会话的文档). 在会话开始之前, 如果驱动程序不可用, Selenium Manager 会为我们管理 chromedriver. 我们用 管理 这个词来描述此功能(而不仅仅是 下载 ), 因为这个过程更广泛, 包含不同的步骤:

1. 探索浏览器版本. Selenium Manager 会发现执行 Selenium 的机器上安装的浏览器版本(例如, Chrome、Firefox、Edge). 此步骤使用 shell 命令(例如, google-chrome --version ).
2. 寻找驱动程序版本. 通过探索过的浏览器版本, 确定合适的驱动程序版本. 在此步骤中, 使用由浏览器供应商维护的在线元数据/端点(例如, chromedriver, geckodriver, 或 msedgedriver).
3. 驱动下载. 通过解析出的驱动程序版本获取驱动程序的 URL；利用该 URL 下载驱动程序文件, 解压后将其存储在本地.
4. 驱动程序缓存. 未压缩的驱动程序二进制文件存储在本地缓存文件夹( ~/.cache/selenium )中. 下次需要相同的驱动程序时, 如果该驱动程序已在缓存中, 则将从那里使用.

自动化浏览器管理

简而言之: 当本地系统未安装 Selenium 驱动的浏览器(Chrome、Firefox 和 Edge)时, Selenium Manager 会自动发现、下载并缓存这些浏览器.

从 Selenium 4.11.0 版本开始, Selenium Manager 还实现了 自动浏览器管理. 借助此功能, Selenium Manager 能够发现、下载并缓存不同浏览器的版本, 使其能够无缝地供 Selenium 使用. 在内部, Selenium Manager 使用了与前一节所述类似的管理流程, 但这次是针对浏览器版本的.

Selenium Manager 自动管理的浏览器有:

• Chrome浏览器, 基于 Chrome for Testing (CfT), 自 Selenium 4.11.0 版本起.
• 火狐浏览器. 基于public Firefox releases, 自 Selenium 4.12.0 版本.
• Edge浏览器, 基于 Edge downloads, 自 Selenium 4.14.0 版本.

让我们再次考虑用 Selenium 驱动 Chrome 的典型示例. 这一次, 假设在启动新会话时本地机器上未安装 Chrome. 在这种情况下, Selenium Manager会发现、下载并缓存当前的稳定版 Chrome 浏览器(在 ~/.cache/selenium/chrome 中).

但不仅如此. 除了稳定的浏览器版本, Selenium Manager 还允许下载旧版浏览器(对于 Chrome for Testing 而言, 从 113 版本开始, 这是作为 Chrome for Testing 发布的第一个版本). 要使用 Selenium 设置浏览器版本, 我们使用一个名为 browserVersion 的浏览器选项.

让我们考虑另一个简单的例子. 假设我们使用 Chrome options 将 browserVersion 设置为 114 . 在这种情况下, Selenium Manager会检查是否已安装 Chrome 114 版本. 如果已安装, 就会使用它. 如果没有安装, Selenium Manager会进行管理(即发现、下载并缓存)Chrome 114 版本. 无论哪种情况, chromedriver 也会被管理. 最后, Selenium 会像往常一样启动 Chrome 以实现程序化驱动.

但还有更多. 除了固定的浏览器版本(例如, 113, 114, 115 等), 我们还可以为 browserVersion 使用以下标签:

• stable: 当前 CfT 版本.
• beta: 下一个稳定版.
• dev: 当前正在开发的版本.
• canary: 面向开发者的夜间构建版本.
• esr: 扩展支持版本(仅适用于 Firefox 浏览器).

当指定了这些标签时, Selenium Manager首先会检查给定的浏览器是否已安装( beta, dev 等), 如果未检测到, 则会自动管理该浏览器.

Windows中的Edge

在 Windows 系统中, Selenium Manager 对 Edge 的自动化边缘管理与其他浏览器有所不同. 对于 Chrome 和 Firefox(以及 macOS 和 Linux 系统中的 Edge), Selenium Manager 会自动将其下载到本地缓存( ~/.cache/selenium ). 然而, 在 Windows 系统中, Edge 却无法实现同样的操作. 原因在于 Windows 版本的 Edge 安装程序是以微软安装程序(MSI)文件的形式分发的, 需要以管理员权限执行. 因此, 当在 Windows 系统中使用非管理员权限会话通过 Selenium Manager 安装 Edge 时, Selenium Manager 会显示如下警告信息:

edge can only be installed in Windows with administrator permissions

因此, 通过 Selenium Manager 在 Windows 系统中自动安装 Edge 浏览器需要管理员权限, 并且 Edge 最终会被安装在通常的程序文件夹中(例如 C:\Program Files (x86)\Microsoft\Edge ).

数据收集

Selenium Manager会向 Plausible 报送匿名使用statistics 数据. 这能让 Selenium 团队更深入地了解 Selenium 的使用情况, 从而更好地集中我们的开发精力. 所收集的数据包括:

Selenium Manager 每天会将这些数据发送给 Plausible 一次. 此周期基于 TTL 值(请参阅configuration).

选择退出数据收集

默认情况下会收集数据. 若要禁用数据收集, 请将 SE_AVOID_STATS 环境变量设置 true. 您也可以在配置文件中(见下文)通过设置 avoid-stats = true 来禁用数据收集.

配置

简而言之: 对于大多数用户而言, Selenium Manager 应该能静默且透明地运行. 不过, 在某些场景下(例如指定自定义缓存路径或全局设置代理), 可能需要自定义配置.

Selenium Manager 是一个命令行界面(CLI)工具. 因此, 在底层, Selenium 绑定通过调用 shell 命令来调用 Selenium Manager. 和任何其他 CLI 工具一样, 可以使用参数来指定 Selenium Manager 中的特定功能. 要查看 Selenium Manager 支持的不同参数, 可以运行以下命令:

$ ./selenium-manager --help

除了命令行参数之外, Selenium Manager 还支持两种额外的配置机制:

• 配置文件. Selenium Manager使用位于 Selenium 缓存中的一个名为 se-config.toml 的文件(默认情况下位于 ~/.cache/selenium )来存储自定义配置值. 此 TOML 文件包含用于自定义配置的键值集合.
• 环境变量. 每个配置键在环境变量中都有对应的等效项, 方法是将每个键名转换为大写, 将破折号(-)替换为下划线(_), 并在前面加上前缀SE_.

当存在配置文件且未指定相应的命令行参数时, Selenium Manager 会遵循该配置文件. 此外, 如果既未指定命令行参数也未提供配置文件, 则会使用环境变量. 换句话说, Selenium Manager 自定义配置的优先级顺序如下:

1. CLI参数.
2. 配置文件.
3. 环境变量.

请注意, Selenium 绑定使用命令行参数来指定配置值, 而这些配置值又在每个绑定中通过browser options来定义.

下表总结了 Selenium Manager 支持的所有参数及其在配置文件和环境变量中的对应键.

除了前面表格中指定的配置键之外, 还有一些特殊情况, 即:

• 浏览器版本. 除了 browser-version 之外, 我们还可以使用特定的配置键为每个受支持的浏览器指定自定义版本. 这样, 键 chrome-version, firefox-version, edge-version 等就得到了支持. 环境变量(即 SE_CHROME_VERSION, SE_FIREFOX_VERSION, SE_EDGE_VERSION 等)也是如此.
• 驱动程序版本. 遵循相同的模式, 我们可以在配置文件中使用 chromedriver-version, geckodriver-version, msedgedriver-version等, 在环境变量中使用 SE_CHROMEDRIVER_VERSION, SE_GECKODRIVER_VERSION, SE_MSEDGEDRIVER_VERSION 等.
• 浏览器路径. 遵循相同的模式, 我们可以在配置文件中使用 chrome-path, firefox-path, edge-path 等, 在环境变量中使用 SE_CHROME_PATH, SE_FIREFOX_PATH, SE_EDGE_PATH等. Selenium 绑定还允许使用选项指定浏览器路径的自定义位置, 例如: Chrome、Edge 或 Firefox.
• 驱动镜像. 遵循同样的模式, 我们可以在配置文件中使用 chromedriver-mirror-url, geckodriver-mirror-url, msedgedriver-mirror-url 等, 在环境变量中使用 SE_CHROMEDRIVER_MIRROR_URL, SE_GECKODRIVER_MIRROR_URL, SE_MSEDGEDRIVER_MIRROR_URL 等.
• 浏览器镜像. 遵循同样的模式, 我们可以在配置文件中使用 chrome-mirror-url, firefox-mirror-url, edge-mirror-url 等, 在环境变量中使用 SE_CHROME_MIRROR_URL, SE_FIREFOX_MIRROR_URL, SE_EDGE_MIRROR_URL 等.

se-config.toml 示例

• se-config.toml

0
22

browser = "chrome"                 # --browser BROWSER
driver = "chromedriver"             # --driver DRIVER
browser-version = "106"             # --browser-version BROWSER_VERSION
driver-version = "106.0.5249.61"    # --driver-version DRIVER_VERSION
browser-path = "/usr/bin/google-chrome"  # --browser-path BROWSER_PATH
driver-mirror-url = "https://custom-driver-mirror.com"  # --driver-mirror-url DRIVER_MIRROR_URL
browser-mirror-url = "https://custom-browser-mirror.com"  # --browser-mirror-url BROWSER_MIRROR_URL
output = "LOGGER"                   # --output OUTPUT
os = "linux"                        # --os OS
arch = "x64"                        # --arch ARCH
proxy = "myproxy:8080"              # --proxy PROXY
timeout = 300                       # --timeout TIMEOUT
offline = true                      # --offline
force-browser-download = true       # --force-browser-download
avoid-browser-download = false      # --avoid-browser-download
debug = true                        # --debug
trace = true                        # --trace
cache-path = "/custom/cache/path"    # --cache-path CACHE_PATH
ttl = 3600                          # --ttl TTL
language-binding = "Python"         # --language-binding LANGUAGE
avoid-stats = true                  # --avoid-stats

缓存

简而言之: 由 Selenium Manager 管理的驱动程序和浏览器会存储在本地文件夹(~/.cache/selenium )中.

Selenium Manager中的缓存是一个本地文件夹(默认为 ~/.cache/selenium ), 用于存储下载的资源(驱动程序和浏览器). 为了提高性能, 当驱动程序或浏览器已存在于缓存中(即存在 缓存 提示)时, Selenium Manager会从那里使用它们.

除了已下载的驱动程序和浏览器之外, 缓存根目录中还有两个额外的文件:

• 配置文件( se-config.toml ). 此文件是可选的, 正如前一节所述, 它允许为 Selenium Manager 存储自定义配置值. 此文件由最终用户维护, 并由 Selenium Manager 读取.
• 元数据文件( se-metadata.json ). 此文件包含由 Selenium Manager通过网络请求(例如, 使用 CfT JSON endpoints)发现的版本以及它们有效的生存时间(TTL). Selenium Manager会自动维护此文件.

Selenium Manager 中的生存时间(TTL)借鉴了 DNS 的 TTL 机制, 这是一种广为人知的机制, 指的是某些值在被自动刷新之前被缓存的时长. 对于 Selenium Manager 而言, 这些值是通过网络请求获取的驱动程序和浏览器版本发现的结果. 默认情况下, TTL 为 3600 秒(即 1 小时), 并且可以通过配置值进行调整, 或者将其设置为 0 来禁用此功能.

TTL 机制是一种提升 Selenium 总体性能的方法. 它基于这样一个事实: 在短期内, 发现的驱动程序和浏览器版本(例如, 适用于 Chrome 115 的正确 chromedriver 版本是 115.0.5790.170)很可能保持不变. 因此, 发现的版本会被写入元数据文件, 并从那里读取, 而不是连续进行相同的网络请求. 这样, 在驱动程序版本发现过程中(之前介绍的自动化驱动程序管理流程的第 2 步), Selenium Manager 首先读取元数据文件. 如果找到新的解决方案(即在 TTL 期间有效的驱动程序/浏览器版本), 则使用该版本(节省了进行新网络请求的时间). 如果未找到或 TTL 已过期, 则会进行网络请求, 并将结果存储在元数据文件中.

我们来看一个例子. 一个 Selenium 绑定请求 Selenium Manager解析 chromedriver. Selenium Manager检测到已安装 Chrome 115 版本, 于是向 CfT 端点发出网络请求以确定合适的 chromedriver 版本(当时为 115.0.5790.170). 此版本会被存储在元数据文件中, 并在接下来的一小时内(TTL)被视为有效. 如果在此期间(在执行测试套件时很可能发生)再次请求 Selenium Manager解析 chromedriver, 那么将通过读取元数据文件来获取 chromedriver 版本, 而无需向 CfT 端点发出新的请求. 一小时后, 缓存中存储的 chromedriver 版本将被视为过期, Selenium Manager会通过向相应端点发出新的网络请求来刷新它.

Selenium Manager includes two additional arguments two handle the cache, namely: Selenium Manager包含两个用于处理缓存的附加参数, 分别是:

• --clear-cache: 要删除缓存文件夹(相当于环境变量 SE_CLEAR_CACHE=true ).
• --clear-metadata : 删除元数据文件(相当于环境变量 SE_CLEAR_METADATA=true ).

版本控制

Selenium Manager 采用与 Selenium 相同的版本命名规则. 不过, 由于 Selenium Manager 仍处于测试阶段, 因此其主版本号为 0. 例如, 与 Selenium 4.12.0 一同发布的 Selenium Manager 二进制文件对应的是 0.4.12 版本.

获取 Selenium Manager

对于大多数用户而言, 由于 Selenium 绑定会在内部使用 Selenium Manager, 所以无需直接与之交互. 不过, 如果您想试用 Selenium Manager 或将其用于涉及驱动程序或浏览器管理的用例, 可以通过多种方式获取 Selenium Manager 的二进制文件

• Selenium Manager的源代码存储在 Selenium 主仓库的 rust 文件夹中. 此外, 您可以在 Selenium Manager Artifacts 仓库中找到适用于 Windows、Linux 和 macOS 的编译版本. 此文件中链接了稳定版的 Selenium Manager二进制file(即在最新稳定版 Selenium 中分发的那些).
• 在构建工作流中, Selenium Manager 是通过 GitHub Actions workflow进行编译的. 此工作流会为 Windows、Linux 和 macOS 创建二进制文件. 您可以从这些工作流执行中下载这些二进制文件.
• 在缓存中. 自 Selenium Java 绑定的 4.15.0 版本起, Selenium Manager 二进制文件会被提取并复制到缓存文件夹中. 例如, 与 Selenium 4.15.0 一同提供的 Selenium Manager 二进制文件会存储在文件夹 ~/.cache/selenium/manager/0.4.15 中.

例子

让我们来看一个典型的例子: 我们想要自动管理 chromedriver. 为此, 我们像下面这样调用 Selenium Manager (请注意, 标志 --debug 是可选的, 但它有助于我们理解 Selenium Manager 正在做什么):

$ ./selenium-manager --browser chrome --debug
DEBUG   chromedriver not found in PATH
DEBUG   chrome detected at C:\Program Files\Google\Chrome\Application\chrome.exe
DEBUG   Running command: wmic datafile where name='C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe' get Version /value
DEBUG   Output: "\r\r\n\r\r\nVersion=116.0.5845.111\r\r\n\r\r\n\r\r\n\r"
DEBUG   Detected browser: chrome 116.0.5845.111
DEBUG   Discovering versions from https://googlechromelabs.github.io/chrome-for-testing/known-good-versions-with-downloads.json
DEBUG   Required driver: chromedriver 116.0.5845.96
DEBUG   Downloading chromedriver 116.0.5845.96 from https://edgedl.me.gvt1.com/edgedl/chrome/chrome-for-testing/116.0.5845.96/win64/chromedriver-win64.zip
INFO    Driver path: C:\Users\boni\.cache\selenium\chromedriver\win64\116.0.5845.96\chromedriver.exe
INFO    Browser path: C:\Program Files\Google\Chrome\Application\chrome.exe

在这种情况下, Selenium Manager会检测到本地的 Chrome(在 Windows 系统中). 然后, 根据其版本和 CfT 端点, 会将合适的 chromedriver 版本(在此示例中为 115 版)下载到本地缓存. 最后, Selenium Manager提供两个结果: i)驱动程序路径(已下载)和 ii)浏览器路径(本地).

让我们再来看一个例子. 现在我们想要使用 Chrome 测试版. 因此, 我们调用 Selenium Manager并指定该版本标签, 如下所示(请注意, CfT 测试版会被发现、下载并存储在本地缓存中):

$ ./selenium-manager --browser chrome --browser-version beta --debug
DEBUG   chromedriver not found in PATH
DEBUG   chrome not found in PATH
DEBUG   chrome beta not found in the system
DEBUG   Discovering versions from https://googlechromelabs.github.io/chrome-for-testing/last-known-good-versions-with-downloads.json
DEBUG   Required browser: chrome 117.0.5938.22
DEBUG   Downloading chrome 117.0.5938.22 from https://edgedl.me.gvt1.com/edgedl/chrome/chrome-for-testing/117.0.5938.22/win64/chrome-win64.zip
DEBUG   chrome 117.0.5938.22 has been downloaded at C:\Users\boni\.cache\selenium\chrome\win64\117.0.5938.22\chrome.exe
DEBUG   Discovering versions from https://googlechromelabs.github.io/chrome-for-testing/known-good-versions-with-downloads.json
DEBUG   Required driver: chromedriver 117.0.5938.22
DEBUG   Downloading chromedriver 117.0.5938.22 from https://edgedl.me.gvt1.com/edgedl/chrome/chrome-for-testing/117.0.5938.22/win64/chromedriver-win64.zip
INFO    Driver path: C:\Users\boni\.cache\selenium\chromedriver\win64\117.0.5938.22\chromedriver.exe
INFO    Browser path: C:\Users\boni\.cache\selenium\chrome\win64\117.0.5938.22\chrome.exe

在您的脚本中实现 Selenium Manager

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

9
16

<details class="mt-3">
  <summary>Show full example</summary>
  <div class="pt-2">
    <div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-java" data-lang="java"><span style="display:flex;"><span><span style="color:#204a87;font-weight:bold">package</span><span style="color:#f8f8f8;text-decoration:underline"> </span><span style="color:#000">dev.selenium.selenium_manager</span><span style="color:#000;font-weight:bold">;</span><span style="color:#f8f8f8;text-decoration:underline">

<div class="text-end pb-2 mt-2">
  <a href="https://github.com/SeleniumHQ/seleniumhq.github.io/blob/display_full/examples/java/src/test/java/dev/selenium/selenium_manager/SeleniumManagerUsageDemo.java#L10-L15" target="_blank">
    <i class="fas fa-external-link-alt pl-2"></i>
    <strong>View full example on GitHub</strong>
  </a>
</div>

Selenium Manager

17
23

<details class="mt-3">
  <summary>Show full example</summary>
  <div class="pt-2">
    <div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-java" data-lang="java"><span style="display:flex;"><span><span style="color:#204a87;font-weight:bold">package</span><span style="color:#f8f8f8;text-decoration:underline"> </span><span style="color:#000">dev.selenium.selenium_manager</span><span style="color:#000;font-weight:bold">;</span><span style="color:#f8f8f8;text-decoration:underline">