企业官网建设流程全解析

Selenium WebDriver JavaScript 绑定（selenium-webdriver）使用指南：从 Builder 配置到远程执行

【免费下载链接】seleniumA browser automation framework and ecosystem.项目地址: https://gitcode.com/GitHub_Trending/se/selenium

本指南以 Selenium 项目官方 JavaScript 语言绑定selenium-webdriver（位于仓库 javascript/selenium-webdriver/README.md）为核心，系统讲解其安装、快速上手、Builder 配置、Selenium Manager 自动驱动管理、远程服务器连接以及 Node.js 版本支持策略。读完本文，你将能够用一套连贯的链式 API 在本地或 Selenium Grid / 独立服务器上驱动 Chrome、Firefox、Edge、Safari 等浏览器完成自动化测试与 Web 任务自动化，并掌握通过环境变量在运行时切换目标浏览器与远程端点的实战技巧。

一、模块定位：JavaScript 世界的 WebDriver 官方客户端

selenium-webdriver是 Selenium 项目（A browser automation framework and ecosystem）为 JavaScript / Node.js 环境提供的官方语言绑定，用于通过 W3C WebDriver 协议自动化真实浏览器，服务于测试与基于 Web 的任务自动化。从仓库 package.json 可以看到其定位与形态：

• 包名selenium-webdriver，版本为4.49.0-nightly…，协议 Apache-2.0，关键词包含automation / testing / webdriver / webdriverjs；
• 运行时要求"node": ">= 22.0.0"（与 README 中 "Requires Node.js >= 22" 一致）；
• 运行时依赖仅有四个：@bazel/runfiles、jszip、tmp、ws，其中ws用于 WebSocket 通道，是 BiDi（双向协议）等现代特性的基础设施。

模块的公开 API 集中在 index.js：入口模块导出了Builder、Browser、By、until、WebDriver、WebElement、Capabilities、Key、Select、Color等核心对象，以及LogInspector、BrowsingContext、BrowsingContextInspector、ScriptManager、NetworkInspector等 BiDi 相关类。浏览器专属子模块（chrome.js、firefox.js、edge.js、ie.js、safari.js、chromium.js）则负责各浏览器的 Options 与 Driver 实现。

二、环境要求与安装

使用前需要准备：

• Node.js >= 22（含 24、26，详见下文“Node 支持策略”），npm 随 Node.js 一同安装；
• 目标浏览器本体（Chrome、Firefox、Edge 等）已安装；
• 浏览器驱动（如 chromedriver、geckodriver）——无需手动下载，Selenium Manager 会自动处理（见第四节）。

安装命令（项目根目录或任意 Node 项目中均可执行）：

npm install selenium-webdriver

安装完成后，模块的main指向./index（见 package.json），即require('selenium-webdriver')直接返回入口模块的导出对象。

三、快速开始：第一个自动化脚本

README 的 Quick Start 给出了最小可运行示例，它演示了“创建会话 → 打开页面 → 读取标题 → 关闭会话”的完整生命周期：

const { Builder, Browser } = require('selenium-webdriver') ;(async function example() { let driver = await new Builder().forBrowser(Browser.CHROME).build() try { await driver.get('https://www.selenium.dev') console.log(await driver.getTitle()) } finally { await driver.quit() } })()

理解这段代码需要注意两个关键点：

1. build()返回的是 ThenableWebDriver。根据 index.js 的实现，Builder.build()返回一个 thenable 包装对象，其内部 promise 解析为具体的WebDriver实例；如果远程端创建会话失败，promise 会被拒绝，所有后续命令都会失败。因此可以直接await或链式调用命令。
2. forBrowser(Browser.CHROME)是必选的。build()中若无法从配置或环境变量解析出浏览器名，会抛出TypeError: Target browser must be a string...; did you forget to call forBrowser()?（见 index.js）。

仓库 example/google_search.js 提供了一个更完整的 Promise 链式版本，展示了定位元素、输入关键词、按回车、等待标题变化的典型流程：

const { Builder, By, Key, until } = require('..') const driver = new Builder().forBrowser('firefox').build() driver .get('http://www.google.com/ncr') .then((_) => driver.findElement(By.name('q')).sendKeys('webdriver', Key.RETURN)) .then((_) => driver.wait(until.titleIs('webdriver - Google Search'), 1000)) .then((_) => driver.quit())

四、Selenium Manager：免手动配置驱动的自动机制

README 强调：“Selenium Manager automatically handles browser driver installation — no manual driver setup required.” 即从 4.x 起，客户端会自动下载并管理浏览器驱动，无需再手工放置 chromedriver / geckodriver 到 PATH。

其底层实现位于 common/seleniumManager.js（该文件注释明确标注 “This implementation is still in beta, and may change”，属于 Selenium Manager 的 Beta 封装）：

• 二进制定位（getBinary()）：按运行平台从bin/目录下选取macos / windows / linux对应子目录中的selenium-manager（Windows 下为selenium-manager.exe）。可以通过SE_MANAGER_PATH环境变量覆盖二进制路径；若找不到二进制文件，会抛出Unable to obtain Selenium Manager at <path>错误。
• 驱动解析（binaryPaths(args)）：以spawnSync同步调用 Selenium Manager 并解析其 JSON 输出，返回{ driverPath, browserPath }，其中driverPath是浏览器驱动路径、browserPath是浏览器可执行文件路径。
• 日志转发（logOutput()）：把 Selenium Manager 输出的WARN级别日志映射为 warning，DEBUG / INFO映射为 debug 日志。

也就是说，当你调用new Builder().forBrowser(Browser.CHROME).build()时，本地构建分支会通过该机制自动获取匹配版本的 chromedriver 并启动浏览器会话，这正是“零手工配置”的来源。

五、配置 Builder：一套配置，多浏览器就绪

README 指出Builder支持在同一条链上为所有浏览器预设默认选项，build()时仅合并“被选中的浏览器”的选项，未选中的会被丢弃。典型写法：

const { Builder, Browser } = require('selenium-webdriver') const chrome = require('selenium-webdriver/chrome') const firefox = require('selenium-webdriver/firefox') let driver = new Builder() .forBrowser(Browser.FIREFOX) .setChromeOptions(new chrome.Options()) .setFirefoxOptions(new firefox.Options()) .build()

从 index.js 的build()源码可以还原其完整决策流程：

1. 复制一份 Capabilities，若未调用disableEnvironmentOverrides()且设置了SELENIUM_BROWSER，则按browser[:version[:platform]]格式解析并覆盖浏览器名、版本、平台；
2. 若仍未解析出浏览器名，会尝试从已设置的浏览器 Options（chrome / firefox / ie / safari / edge）中读取其browserName（index.js）；
3. 根据最终浏览器名，仅将对应浏览器的 Options 合并进 Capabilities（index.js）——这就是“未选中浏览器选项被丢弃”的实现依据；
4. 判断是走远程分支（设置了usingServer或环境变量）还是本地原生驱动分支（chrome.Driver、firefox.Driver、ie.Driver、edge.Driver、safari.Driver等）。

此外Builder还提供withCapabilities()、setCapability()、setProxy()、setLoggingPrefs()、setAlertBehavior()、usingWebDriverProxy()、usingHttpAgent()等方法，以及setChromeService()/setFirefoxService()等驱动服务定制入口。需要特别注意的是 checkOptions 的约束：现代chrome.Options、firefox.Options等类本身已继承自Capabilities，不应再以withCapabilities({ 'moz:firefoxOptions': ffo })的形式手动塞入，而应使用setFirefoxOptions()等专用方法，否则会抛出InvalidArgumentError。

5.1 常用 Options 能力举例

• Chrome：setChromeBinaryPath(path)指定 Chrome 可执行文件路径（chrome.js）；androidChrome()通过 adb 在 Android 上启动 Chrome；setChromeLogFile()设置日志文件；setMobileEmulation()进行移动设备模拟。
• Firefox：firefox.Options().addArguments('-headless')以无头模式启动。
• 跨浏览器通用：windowSize({ width, height })设置窗口尺寸。

仓库 example/headless.js 展示了“一套 Builder 同时配置 Chrome 与 Firefox 的无头选项”的典型用法：

const chrome = require('../chrome') const firefox = require('../firefox') const { Builder, By, Key, until } = require('..') const width = 640 const height = 480 let driver = new Builder() .forBrowser('chrome') .setChromeOptions(new chrome.Options().addArguments('-headless').windowSize({ width, height })) .setFirefoxOptions(new firefox.Options().addArguments('-headless').windowSize({ width, height })) .build()

example/chrome_mobile_emulation.js 则示范了移动端模拟：new Options().setMobileEmulation({ deviceName: 'Pixel 10' })配合forBrowser('chrome')，用于验证移动端页面表现。

六、运行目标切换：环境变量的运行时覆盖

README 强调“The target browser can be swapped at runtime via theSELENIUM_BROWSERenvironment variable”。结合 index.js 的文档注释，Builder支持三组环境变量，允许不改代码即可切换运行目标：

例如，一个写死forBrowser('chrome')的脚本，可以不改代码就改为在远程机器上运行：

SELENIUM_BROWSER=chrome:36:LINUX \ SELENIUM_REMOTE_URL=http://www.example.com:4444/wd/hub \ node mytest.js

也可以使用本地 standalone 服务器：

SELENIUM_BROWSER=chrome:36:LINUX \ SELENIUM_SERVER_JAR=/path/to/selenium-server-standalone.jar \ node mytest.js

build()中对应逻辑见 index.js（浏览器解析）与 index.js（远程 URL 与 server jar 解析）。若想彻底忽略环境变量、仅使用代码内配置，可调用builder.disableEnvironmentOverrides()（index.js）。

七、连接远程服务器：Selenium Grid 与独立服务器

README 提供了两种指向远程端点的方式。

方式一：代码内usingServer()

let driver = new Builder().forBrowser(Browser.CHROME).usingServer('http://localhost:4444').build()

方式二：环境变量SELENIUM_REMOTE_URL

SELENIUM_REMOTE_URL="http://localhost:4444" node script.js

usingServer(url)在 index.js 中实现，将url_记录为远程端点；build()的远程分支（index.js）会创建HttpClient与Executor，将协议命令发送到远程服务器。README 中也提到可将脚本指向 Selenium Grid 或 standalone server（Grid 的分布式能力由仓库整体生态提供，包括 java/src 下的 Grid 实现）。

仓库 example/google_search.js 的头部注释还给出了一组可直接套用的运行示例：

# 默认行为（本地 Firefox） node selenium-webdriver/example/google_search.js # 本地 Chrome（需 chromedriver 在 PATH，或由 Selenium Manager 自动处理） SELENIUM_BROWSER=chrome node selenium-webdriver/example/google_search.js # 使用本地 standalone Selenium server SELENIUM_SERVER_JAR=/path/to/selenium-server-standalone.jar \ node selenium-webdriver/example/google_search.js # 连接远程 Selenium server SELENIUM_REMOTE_URL=http://www.example.com:4444/wd/hub \ node selenium-webdriver/example/google_search.js

八、Node.js 支持策略

selenium-webdriver只支持处于上游活跃维护期内的 Node.js 版本；某个版本到达其 end-of-life 日期后即不再支持。README 给出的支持时间表如下：

CI 会测试rules_nodejs中可用的最早与最晚支持版本；对任一受支持版本提交 issue 或 pull request 都是欢迎的。从 package.json 的engines字段（"node": ">= 22.0.0"）可以印证当前仓库对最低版本的硬性约束。

九、本地开发与测试

若希望在本仓库内对selenium-webdriver进行开发与验证，仓库提供了 Bazel 化的测试入口。根据 package.json 的 scripts 配置：

• npm test等价于bazel test //javascript/selenium-webdriver/...，即对javascript/selenium-webdriver下所有 Bazel 目标执行测试；
• npm run lint/npm run lint:fix执行 ESLint 检查与自动修复（配置见 eslint.config.js）；
• npm run generate-docs基于 jsdoc_conf.json 生成 JSDoc API 文档。

测试的更多约定可参考 TESTING.md；测试用例目录为 test/，其中既包含针对 Promise、网络等底层能力的单元测试（如 test/lib/promise_test.js），也包含面向真实浏览器的集成测试。

十、进一步学习路径

• API 参考：入口导出与Builder全部方法定义见 index.js；浏览器 Options 类见 chrome.js 等各浏览器子模块。
• 示例代码：example/ 目录提供了搜索、无头模式（headless）、Chrome 移动模拟（chrome_mobile_emulation）、Android（chrome_android）、日志（logging）等可直接运行的脚本。
• Selenium Manager 底层机制：common/seleniumManager.js 是客户端调用 Selenium Manager 的封装，配合SE_MANAGER_PATH环境变量可覆盖二进制位置。
• BiDi 能力：bidi/ 目录包含LogInspector、BrowsingContext、ScriptManager、NetworkInspector等现代双向协议能力的实现，对应入口导出的同名类。

十一、许可证

selenium-webdriver以 Apache License 2.0 许可发布（见 package.json 与仓库根目录 LICENSE），可以自由用于商业与非商业自动化项目。

【免费下载链接】seleniumA browser automation framework and ecosystem.项目地址: https://gitcode.com/GitHub_Trending/se/selenium