Vitest 浏览器模式 provider 配置全解析:从内置 Playwright/WebdriverIO/Preview 到自定义浏览器驱动 Vitest 浏览器模式 provider 配置全解析从内置 Playwright/WebdriverIO/Preview 到自定义浏览器驱动【免费下载链接】vitestNext generation testing framework powered by Vite.项目地址: https://gitcode.com/GitHub_Trending/vi/vitestbrowser.provider是 Vitest 浏览器模式Browser Mode的核心配置项它决定了测试用例究竟由哪一套浏览器自动化驱动来执行——是 Playwright、WebdriverIO还是直接打开一个预览浏览器窗口。本文基于官方配置文档结合仓库内packages/browser-playwright、packages/browser-preview、packages/vitest/src/node/types/browser.ts等源码实现系统讲解 provider 的类型与取值、如何向 provider 工厂函数传递初始化参数、多浏览器实例下如何覆盖 provider 配置以及如何编写自定义 provider。读完本文你将能根据项目环境CI 无头模式、本地有头调试、多浏览器矩阵正确选型并精确配置 Vitest 的浏览器驱动。browser.provider是什么在 Vitest 配置中browser.provider的类型为BrowserProviderOption它是 provider 工厂函数的返回值。你既可以从vitest/browser-provider-name中导入现成的工厂函数也可以自行实现一个 providerimport { playwright } from vitest/browser-playwright import { webdriverio } from vitest/browser-webdriverio import { preview } from vitest/browser-preview export default defineConfig({ test: { browser: { provider: playwright(), // provider: webdriverio(), // provider: preview(), }, }, })注意以上三种写法在同一个配置中只能取其一此处并列仅为展示三种内置 provider 的导入与调用方式。从源码结构看BrowserProviderOption与BrowserProvider接口定义在 packages/vitest/src/node/types/browser.tsBrowserProviderOptionprovider 的静态描述包含name如playwright、supportedBrowser支持的浏览器列表、options用户传入的配置对象、providerFactory根据 TestProject 创建真实 provider 实例的工厂、serverFactory创建浏览器服务端的工厂内置 provider 统一由createBrowserServer提供以及可选的prewarm在 Vite 服务创建前并发预热浏览器。BrowserProviderprovider 的运行时接口即真正负责打开页面、注入脚本、提供命令上下文、管理生命周期的对象。这种选项对象 工厂函数的分层设计使得同一个 provider 可以针对不同浏览器实例instances产出不同的运行时实例而公共配置仍可共享。三种内置 provider 的选型Vitest 官方文档明确了三条导入路径对应的三个内置 providerProvider导入来源适用场景playwright()vitest/browser-playwright功能最完整支持 Chromium / Firefox / Webkit支持无头模式与并行文件webdriverio()vitest/browser-webdriverio社区维护见 docs/config/browser/webdriverio.md兼容 Selenium 生态适合已使用 WebdriverIO 的团队preview()vitest/browser-preview仅用于本地有头预览直接在系统浏览器中打开测试页面不支持无头模式其中previewprovider 的实现非常有辨识度在 packages/browser-preview/src/preview.ts 中PreviewBrowserProvider声明supportsParallelism false并且构造函数会直接检查headless配置——一旦启用无头模式就抛出错误提示改用playwright或webdriverio。它的openPage只是调用 Vite 的openBrowser()把 URL 交给系统默认浏览器打开close()是空实现因此它本质上是一个把浏览器当作观察窗口的轻量驱动而非自动化测试驱动。向 provider 工厂函数传递初始化参数browser.provider的值是工厂函数的返回值因此你可以把初始化参数直接传给工厂函数用于配置 provider 如何启动浏览器import { playwright } from vitest/browser-playwright export default defineConfig({ test: { browser: { // 所有浏览器实例共享的 provider 选项 provider: playwright({ launchOptions: { slowMo: 50, // 每个操作之间插入 50ms 延迟便于观察 channel: chrome-beta, // 使用 Chrome Beta 渠道 }, actionTimeout: 5_000, // userEvent 动作超时 5 秒 }), instances: [ { browser: chromium }, { browser: firefox, // 仅对单个实例覆盖 provider 选项 // 注意此处不会与父级选项合并 provider: playwright({ launchOptions: { firefoxUserPrefs: { browser.startup.homepage: https://example.com, }, }, }) } ], }, }, })各参数详解以 Playwright provider 为例playwright()工厂函数接收的PlaywrightProviderOptions在 packages/browser-playwright/src/playwright.ts 中有完整定义launchOptions透传给 PlaywrightbrowserType.launch()的启动参数但不允许传tracesDir它由 Vitest 的 trace 配置管理。常见的如headless、slowMo、channel、args、executablePath等。源码中resolveLaunchOptions会把配置解析为最终的LaunchOptions默认强制使用browser.headless作为headless值若启用了inspector调试会自动追加--remote-debugging-port启动参数当browser.ui开启且浏览器为 chromium 时会自动追加--start-maximized让 Vitest UI 最大化。connectOptions仅在你通过 WebSocket 远程连接 Playwright 实例时使用需包含wsEndpoint。源码实现中Vitest 会把解析好的launchOptions序列化到x-playwright-launch-options请求头一并发送以便远端按相同配置启动浏览器若检测到用户自定义了该请求头则会告警并忽略 provider 层的launchOptions。contextOptions透传给browser.newContext()的上下文参数但不允许覆盖ignoreHTTPSErrors与serviceWorkers因为 Vitest 强制ignoreHTTPSErrors: true以便测试 HTTPS 页面。另外当处于有头 UI 模式时源码会把viewport设为null让页面采用真实窗口尺寸。actionTimeoutuserEvent动作的默认超时时间单位毫秒默认0即不超时。在createContext中通过context.setDefaultTimeout(actionTimeout)生效。persistentContext布尔值或字符串。设为true时使用持久化上下文浏览器状态Cookie、localStorage 等会保存在./node_modules/.cache/vitest-playwright-user-data设为字符串则作为用户数据目录路径。注意并行运行时该选项会被忽略见下文supportsParallelism说明源码会打印黄色警告并回退到普通上下文。实例级覆盖不会与父级合并上例中 firefox 实例自带一份provider配置这是browser.instances的实例级覆盖能力。关键语义是实例级 provider 选项不会与父级根配置的 provider 选项做浅合并——firefox 实例只会收到自己那份launchOptionsslowMo、actionTimeout等父级参数在该实例上不生效。如果你需要两者兼顾必须在实例级配置中显式补齐。这一点与instances的整体继承规则形成对比browser.instances的每个实例会继承根配置的setupFile、testerHtmlPath等公共选项参见 docs/config/browser/instances.md但 provider 是一个整体覆盖的对象而非可合并的散列项。使用 WebdriverIO provider 时的注意事项WebdriverIO provider 由 Vitest 社区在vitest-community组织下独立维护详见 docs/config/browser/webdriverio.md需要安装vitest/browser-webdriverio并导入其webdriverio导出import { webdriverio } from vitest/browser-webdriverio import { defineConfig } from vitest/config export default defineConfig({ test: { browser: { provider: webdriverio({ capabilities: { browserVersion: 82, }, }), instances: [{ browser: chrome }], }, }, })webdriverio()工厂接收 WebdriverIOremote()函数支持的所有参数。与 Playwright 类似它同样支持在instances中按实例覆盖provider: webdriverio({ capabilities: { moz:firefoxOptions: { args: [--disable-gpu], }, }, })几点关键限制官方文档明确说明Vitest 会忽略所有 WebdriverIO 的测试运行器选项只使用其浏览器 capabilities最常用的选项都位于capabilities对象上但 Vitest 会忽略嵌套 capabilities它依赖自身机制来启动多个浏览器Vitest 会忽略capabilities.browserName浏览器名称一律通过test.browser.instances.browser指定。另外如果要在 Linux CI如 GitHub Actions上跑有头 Chrome由于没有显示服务器WebDriverIO 或 ChromeDriver 可能报出令人困惑的错误例如session not created: probably user data directory is already in use此时需要通过虚拟显示服务器运行测试xvfb-run npm test更稳妥的做法是保持 CI 中的browser.headless为默认开启CI 环境下 Vitest 会自动启用无头仅在本地调试时使用有头模式。自定义 ProviderBrowserProvider 接口深入如果内置 provider 无法满足需求你可以实现自己的 provider。官方文档特别强调这是ADVANCED / 实验性 API接口可能在补丁版本之间发生变化若只是想在浏览器中跑测试应优先使用browser.instances选项。BrowserProvider接口的完整定义与文档一致见 packages/vitest/src/node/types/browser.tsexport interface BrowserProvider { name: string mocker?: BrowserModuleMocker readonly initScripts?: string[] /** * experimental opt-in into file parallelisation */ supportsParallelism: boolean getCommandsContext: (sessionId: string) Recordstring, unknown openPage: (sessionId: string, url: string) Promisevoid getCDPSession?: (sessionId: string) PromiseCDPSession close: () Awaitablevoid }各成员的职责nameprovider 的唯一标识如playwright、preview用于日志与错误报告。mocker可选浏览器端模块 Mock 器实现register/delete/clear三个方法分别用于在指定会话中注册、移除、清空被 Mock 的模块。以 Playwright 为例其 mocker 通过page.context().route()拦截模块请求依据模块类型manual/redirect/automock/autospy决定是用route.fulfill()返回手工模块源码、302 重定向还是标记为自动 mock针对 WebKit 不支持重定向响应的问题见 playwright#18318 关联实现还做了特判处理。initScripts需要在主页面中注入的初始化脚本路径数组。内置 provider 都会注入dist/locators.js定位器实现。supportsParallelism是否支持测试文件并行。Playwright 声明为truePreview 声明为false。它是实验性开关并行场景下persistentContext等有状态能力会被自动禁用。getCommandsContext(sessionId)返回该会话内浏览器命令vitest/browser的commandsAPI可访问的上下文对象。Playwright 的实现返回page、context、frame()与iframeFrameLocatorPreview 则返回空对象。openPage(sessionId, url)在指定会话中打开测试页面。Playwright 会创建或复用BrowserContext 与 Page然后page.goto(url)Preview 则调用 Vite 的openBrowser()。getCDPSession?可选获取 Chrome DevTools Protocol 会话用于性能分析、覆盖率等底层操作。Playwright 通过page.context().newCDPSession(page)实现。close()关闭浏览器、清理会话。Playwright 的close()会依次关闭页面、上下文与浏览器实例并处理尚未被认领的预热浏览器。用defineBrowserProvider组装选项官方文档只展示了BrowserProvider接口本身而在实际开发中推荐通过vitest/browser导出的defineBrowserProvider来构造BrowserProviderOption。其实现位于 packages/browser/src/node/index.tsexport function defineBrowserProviderT extends object object(options: Omit BrowserProviderOptionT, serverFactory | options { options?: T }): BrowserProviderOption { return { ...options, options: options.options || {}, serverFactory: createBrowserServer, } }它会补齐options默认值并统一挂上createBrowserServer作为serverFactory。内置三个 provider 正是这样实现的例如playwright()packages/browser-playwright/src/playwright.tsexport function playwright(options: PlaywrightProviderOptions {}): BrowserProviderOptionPlaywrightProviderOptions { return defineBrowserProvider({ name: playwright, supportedBrowser: playwrightBrowsers, // [firefox, webkit, chromium] options, prewarm(ctx) { prewarmBrowser(ctx, options) }, providerFactory(project) { return new PlaywrightBrowserProvider(project, options) }, }) }值得注意的是prewarm钩子Playwright 会在 Node 端创建 Vite 服务的同时异步导入playwright并启动浏览器让启动延迟与 Vite 服务初始化重叠若最终解析出的 launch 选项与预热时不符预热实例会被安全丢弃并重新启动相关逻辑见 packages/browser-playwright/src/playwright.ts。这是从源码中可以确认的启动优化机制。小结browser.provider是 Vitest 浏览器模式与底层浏览器驱动之间的唯一接口选型自动化测试首选playwright()支持无头、并行、多浏览器已有 WebdriverIO/Selenium 生态选webdriverio()本地有头观察用preview()不支持无头与并行。传参把初始化参数直接传给工厂函数如launchOptions、actionTimeout、capabilities注意实例级provider覆盖不会与父级合并。扩展通过实现BrowserProvider接口并配合defineBrowserProvider组装即可接入任意浏览器驱动该 API 高度实验性升级时需关注变更。配置好 provider 之后可以继续通过browser.instances编排多浏览器矩阵并参考 Multiple Setups 指南 了解实例级继承与覆盖的完整语义。【免费下载链接】vitestNext generation testing framework powered by Vite.项目地址: https://gitcode.com/GitHub_Trending/vi/vitest创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考