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

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() } })()理解这段代码需要注意两个关键点build()返回的是 ThenableWebDriver。根据 index.js 的实现Builder.build()返回一个 thenable 包装对象其内部 promise 解析为具体的WebDriver实例如果远程端创建会话失败promise 会被拒绝所有后续命令都会失败。因此可以直接await或链式调用命令。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-managerWindows 下为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级别日志映射为 warningDEBUG / 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()源码可以还原其完整决策流程复制一份 Capabilities若未调用disableEnvironmentOverrides()且设置了SELENIUM_BROWSER则按browser[:version[:platform]]格式解析并覆盖浏览器名、版本、平台若仍未解析出浏览器名会尝试从已设置的浏览器 Optionschrome / firefox / ie / safari / edge中读取其browserNameindex.js根据最终浏览器名仅将对应浏览器的 Options 合并进 Capabilitiesindex.js——这就是“未选中浏览器选项被丢弃”的实现依据判断是走远程分支设置了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 能力举例ChromesetChromeBinaryPath(path)指定 Chrome 可执行文件路径chrome.jsandroidChrome()通过 adb 在 Android 上启动 ChromesetChromeLogFile()设置日志文件setMobileEmulation()进行移动设备模拟。Firefoxfirefox.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支持三组环境变量允许不改代码即可切换运行目标环境变量格式 / 值作用SELENIUM_BROWSERbrowser[:version[:platform]]指定目标浏览器可选版本与平台例如firefox、chrome:36:LINUXSELENIUM_REMOTE_URL完整的 WebDriver 服务器 URL所有 Builder 实例改为连接该远程端点优先级高于SELENIUM_SERVER_JARSELENIUM_SERVER_JAR本地 standalone server jar 路径首次创建 WebDriver 实例时启动该服务器进程退出时关闭例如一个写死forBrowser(chrome)的脚本可以不改代码就改为在远程机器上运行SELENIUM_BROWSERchrome:36:LINUX \ SELENIUM_REMOTE_URLhttp://www.example.com:4444/wd/hub \ node mytest.js也可以使用本地 standalone 服务器SELENIUM_BROWSERchrome:36:LINUX \ SELENIUM_SERVER_JAR/path/to/selenium-server-standalone.jar \ node mytest.jsbuild()中对应逻辑见 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_URLSELENIUM_REMOTE_URLhttp://localhost:4444 node script.jsusingServer(url)在 index.js 中实现将url_记录为远程端点build()的远程分支index.js会创建HttpClient与Executor将协议命令发送到远程服务器。README 中也提到可将脚本指向 Selenium Grid 或 standalone serverGrid 的分布式能力由仓库整体生态提供包括 java/src 下的 Grid 实现。仓库 example/google_search.js 的头部注释还给出了一组可直接套用的运行示例# 默认行为本地 Firefox node selenium-webdriver/example/google_search.js # 本地 Chrome需 chromedriver 在 PATH或由 Selenium Manager 自动处理 SELENIUM_BROWSERchrome 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_URLhttp://www.example.com:4444/wd/hub \ node selenium-webdriver/example/google_search.js八、Node.js 支持策略selenium-webdriver只支持处于上游活跃维护期内的 Node.js 版本某个版本到达其 end-of-life 日期后即不再支持。README 给出的支持时间表如下Node.js支持截止222027-04-30242028-04-30262029-04-30CI 会测试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.jsnpm 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、Androidchrome_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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考