Playwright 测试配置use完全指南Emulation、Network 与 Recording 选项的深度解析【免费下载链接】playwrightPlaywright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.项目地址: https://gitcode.com/GitHub_Trending/pl/playwright导读本文以 Playwright 测试运行器的核心配置块use为切入点系统梳理如何在playwright.config.ts中统一声明浏览器上下文BrowserContext的仿真、网络与录制行为并逐层讲解baseURL、设备仿真、代理、TLS、trace/video 录制模式、显式上下文创建以及全局/项目/测试三级作用域的继承与覆盖机制。阅读完成后你将掌握在单个文件中声明、按 project 细分、按test.use()精准覆盖的完整配置技巧并能理解这些选项在 Playwright 源码中是如何被解析为浏览器上下文参数的。use配置块的本质一组内建 fixture 选项在 playwright/test 的入口实现中use中的每一项配置都被实现为一个带option: true标记的 fixture。例如browserName在 packages/playwright/src/index.ts 中定义默认读取defaultBrowserType即chromiumviewport默认值为{ width: 1280, height: 720 }colorScheme默认light、locale默认en-USheadless默认取launchOptions.headless ?? true即默认无头运行。因此你写在use: {}里的每一项本质上都是为这些 fixture 赋初值再由运行器在你每个测试运行时装配到browser、context、page这些内建 fixture 之中。理解这一点就能理解为什么“有的选项作用于浏览器实例、有的作用于上下文”以及为什么它们可以按作用域层层覆盖。基础选项baseURL 与 storageState最常见的两个顶层选项是页面导航基准地址与登录态注入import { defineConfig } from playwright/test; export default defineConfig({ use: { // Base URL to use in actions like await page.goto(/). baseURL: http://localhost:3000, // Populates context with given storage state. storageState: state.json, }, });| Option | Description | | :- | :- | |baseURL| 配置上下文中所有页面使用的基准 URL允许仅凭路径完成导航例如page.goto(/settings)。 | |storageState| 用给定的存储状态填充上下文是快速实现登录态复用authentication的关键手段。 |补充细节baseURL也接受环境变量PLAYWRIGHT_TEST_BASE_URL的注入见 packages/playwright/src/index.ts这一特性对 CI 中切换不同测试环境非常实用。storageState参数既可以传相对配置文件所在目录的文件路径也可以直接传包含cookies、origins的对象字面量。关于基于 storageState 的完整登录态方案可阅读 认证指南。Emulation Options从设备到时区的全链路仿真Playwright 允许你仿真真实的移动端或平板设备也可以针对所有测试或单个测试仿真geolocation、locale、timezone并通过permissions授予通知等权限、通过colorScheme切换配色主题。项目级设备矩阵可参考 test projects 指南 与 Emulation 指南。import { defineConfig } from playwright/test; export default defineConfig({ use: { // Emulates prefers-colors-scheme media feature. colorScheme: dark, // Context geolocation. geolocation: { longitude: 12.492507, latitude: 41.889938 }, // Emulates the user locale. locale: en-GB, // Grants specified permissions to the browser context. permissions: [geolocation], // Emulates the user timezone. timezoneId: Europe/Paris, // Viewport used for all pages in the context. viewport: { width: 1280, height: 720 }, }, });| Option | Description | | :- | :- | |colorScheme| 仿真prefers-colors-scheme媒体特性支持light与dark默认light。 | |geolocation| 设置上下文的地理位置。 | |locale| 仿真的用户语言例如en-GB、de-DE等默认en-US。 | |permissions| 授予上下文所有页面的一组权限。 | |timezoneId| 改变上下文的时区。 | |viewport| 上下文所有页面使用的视口尺寸默认{ width: 1280, height: 720 }。 |从源码看这些配置最终会被逐一搬入BrowserContextOptions在 packages/playwright/src/index.ts 的_combinedContextOptionsfixture 中colorScheme、geolocation、locale、timezoneId、viewport等字段会被非空判断后写入上下文参数对象随后在 runBeforeCreateBrowserContext 钩子里只有在用户显式传入的参数不包含该 key 时测试选项才会被合并进去——这保证了运行时显式传入的上下文选项优先于use中的声明。值得注意的补充选项deviceScaleFactorDPR默认1、hasTouch、isMobile、userAgent、serviceWorkers、reducedMotion、contrast、forcedColors同样可以放进use这些上下文级选项在 packages/playwright/src/index.ts 中都有对应的默认值兜底。permissions常见取值包括geolocation、notifications、camera、microphone等浏览器权限名配置后上下文中所有页面默认已获得授权。Network Options下载、请求头、认证、TLS 与代理可用网络配置如下import { defineConfig } from playwright/test; export default defineConfig({ use: { // Whether to automatically download all the attachments. acceptDownloads: false, // An object containing additional HTTP headers to be sent with every request. extraHTTPHeaders: { X-My-Header: value, }, // Credentials for HTTP authentication. httpCredentials: { username: user, password: pass, }, // Whether to ignore HTTPS errors during navigation. ignoreHTTPSErrors: true, // Whether to emulate network being offline. offline: true, // Proxy settings used for all pages in the test. proxy: { server: http://myproxy.com:3128, bypass: localhost, }, }, });| Option | Description | | :- | :- | |acceptDownloads| 是否自动接受下载默认true。下载相关细节见 downloads 指南。 | |extraHTTPHeaders| 随每次请求发送的附加 HTTP 头对象所有头值必须是字符串。 | |httpCredentials| HTTP 认证凭据。 | |ignoreHTTPSErrors| 导航过程中是否忽略 HTTPS 错误默认false。 | |offline| 是否仿真网络离线默认false。 | |proxy| 测试中所有页面使用的代理设置。 |补充说明acceptDownloads、extraHTTPHeaders、httpCredentials、ignoreHTTPSErrors、offline、proxy等选项在 packages/playwright/src/index.ts 中同样声明了各自的默认值如acceptDownloads ?? true、offline ?? false说明它们是“面向测试运行器的封装”最终都会流入BrowserContextOptions。proxy中server为必填项bypass是可选的分号分隔的主机列表表示这些地址不走代理配置为*表示全部绕过。除代理、认证外Playwright 还支持clientCertificates为特定origin提供 TLS 客户端证书certPath/keyPath、或pfxPath可选passphrase见 packages/playwright/types/test.d.ts。证书相关路径会以配置文件所在目录为基准做解析。注模拟网络请求时你其实无需做任何配置。只要为浏览器上下文注册自定义Route即可完成对网络的 mock。完整的 mock 方案见 network mocking 指南。Recording Options截图、Trace 与视频Playwright 可以自动捕获截图、录制视频以及生成 trace。默认三者均关闭可通过在配置文件中设置screenshot、video、trace选项开启。trace、截图和视频文件都会输出到测试输出目录通常是test-results。import { defineConfig } from playwright/test; export default defineConfig({ use: { // Capture screenshot after each test failure. screenshot: only-on-failure, // Record trace only when retrying a test for the first time. trace: on-first-retry, // Record video only when retrying a test for the first time. video: on-first-retry }, });| Option | Description | | :- | :- | |screenshot| 捕获测试的截图可选off、on、only-on-failure。 | |trace| Playwright 在测试运行期间产生 trace之后可通过 Trace Viewer 回放详细的执行信息。可选off、on、retain-on-failure、on-first-retry等模式完整列表见下文。 | |video| 为测试录制视频模式集合与trace一致。 |Trace 模式速查trace选项支持多种模式其差异体现在哪些运行会被录制以及测试结束后哪些录制结果会被保留。一次测试的首次运行称为 “first run”由重试引起的后续运行称为 “retries”。| Mode | Records a trace on | Keeps the trace when | | :- | :- | :- | |off| never | — | |on| every run | always | |retain-on-failure| every run | that run failed | |retain-on-first-failure| first run only | the first run failed | |retain-on-failure-and-retries| every run | that run failed, or it is a retry | |on-first-retry| first retry only | always | |on-all-retries| every retry | always |下表展示了在配置retries: 2的前提下几个常见场景分别会保留哪些 trace| Mode | Passes on first run | Fails, then passes on retry | Fails on every run | | :- | :- | :- | :- | |off| — | — | — | |on| first run | first run retry | all three runs | |retain-on-failure| — | first run | all three runs | |retain-on-first-failure| — | first run | first run | |retain-on-failure-and-retries| — | first run retry | all three runs | |on-first-retry| — | first retry | first retry | |on-all-retries| — | first retry | both retries |模式名的完整集合可从类型定义 packages/playwright/types/test.d.ts 中确认off | on | retain-on-failure | on-first-retry | on-all-retries | retain-on-first-failure | retain-on-failure-and-retries。在 worker 端 trace 逻辑中可以看到这些模式的实际判定逻辑例如on-first-retry要求testInfo.retry 1即只在第一次重试时录制retain-on-failure在测试失败时保留录制。需要注意早期版本中的retry-with-trace已标记为废弃会被归一化为on-first-retry见 packages/playwright/src/worker/testTracing.ts。trace还支持对象形态{ mode: on, snapshots: true, screenshots: true, sources: true }用于精细化控制是否录制 DOM/ARIA 快照、页面截图与源码映射。视频模式速查video选项支持与trace完全相同的一组模式录制与保留遵循同样的规则。| Mode | Records a video on | Keeps the video when | | :- | :- | :- | |off| never | — | |on| every run | always | |retain-on-failure| every run | that run failed | |retain-on-first-failure| first run only | the first run failed | |retain-on-failure-and-retries| every run | that run failed, or it is a retry | |on-first-retry| first retry only | always | |on-all-retries| every retry | always |同样假设retries: 2各场景保留的视频如下| Mode | Passes on first run | Fails, then passes on retry | Fails on every run | | :- | :- | :- | :- | |off| — | — | — | |on| first run | first run retry | all three runs | |retain-on-failure| — | first run | all three runs | |retain-on-first-failure| — | first run | first run | |retain-on-failure-and-retries| — | first run retry | all three runs | |on-first-retry| — | first retry | first retry | |on-all-retries| — | first retry | both retries |从实现上看视频的“是否录制”与“是否保留”被拆成了两个独立函数shouldCaptureVideo与shouldPreserveVideo见 packages/playwright/src/index.ts录制决策发生在上下文创建之前例如on-first-retry需要testInfo.retry 1而保留决策则发生在测试结束、拿到testInfo.status之后。保留的视频会以test-{status}-{index}.webm命名并保存到测试输出目录。对象形态的video: { mode: retain-on-failure, size: { width, height } }允许你进一步指定录制分辨率retry-with-video同样已被废弃并归一化为on-first-retry。截图模式与失败时行为screenshot的类型在 packages/playwright/types/test.d.ts 中定义为off | on | only-on-failure | on-first-failure支持on-first-failure仅首次运行失败时截图。截图同样支持对象形态例如screenshot: { mode: on, fullPage: true, omitBackground: true }可透传fullPage与omitBackground给page.screenshot()。失败时测试错误上下文error-context也会被收集便于结合 trace 一起排障见 ArtifactsRecorder 的实现。其他选项超时、浏览器选择与选择器约定import { defineConfig } from playwright/test; export default defineConfig({ use: { // Maximum time each action such as click() can take. Defaults to 0 (no limit). actionTimeout: 0, // Name of the browser that runs tests. For example chromium, firefox, webkit. browserName: chromium, // Toggles bypassing Content-Security-Policy. bypassCSP: true, // Channel to use, for example chrome, chrome-beta, msedge, msedge-beta. channel: chrome, // Run browser in headless mode. headless: false, // Change the default>import { defineConfig } from playwright/test; export default defineConfig({ use: { launchOptions: { slowMo: 50, }, }, });这里slowMo: 50让每个操作之间人为停顿 50ms适合演示与调试。不过绝大多数常用项如headless、viewport已经直接暴露在use顶层正如上文的基础选项、仿真选项与网络选项所示只有在使用非内置的“长尾”参数时才需要借助这三个分组。相应地launchOptions默认{}worker 级真实启动参数会在 packages/playwright/src/index.ts 中合并headless、channel、tracesDir后传给浏览器进程connectOptions允许不本地启动浏览器而是连接一个已运行的远程端点若设置了PLAYWRIGHT_TEST_BASE_URL类似的环境变量或PW_TEST_CONNECT_WS_ENDPOINT连接信息会自动注入见 packages/playwright/src/index.tscontextOptions提供了把任意上下文参数“整体透传”的逃生通道其内容与_combinedContextOptions展开出的具名字段会做浅合并。显式创建上下文时的选项继承与优先级在一个测试或 hook 运行期间凡是经由测试运行器使用的 Playwright 实例创建的浏览器上下文都会自动继承use段中的上下文选项。这包括使用内建browserfixture 调用browser.newContext()创建的上下文通过另行 launch 的浏览器创建的上下文使用BrowserType.launchPersistentContext创建的持久化上下文直接 importplaywright-core且解析到同一实例时创建的上下文。并且显式传入的上下文选项始终优先于use声明。背后的机制是 packages/playwright/src/index.ts 中runBeforeCreateBrowserContext的合并逻辑——它只为参数对象里“还没有的 key”补充默认值。import { defineConfig } from playwright/test; export default defineConfig({ use: { userAgent: some custom ua, viewport: { width: 100, height: 100 }, }, });下面这个测试可以验证use选项确实被应用到了新创建的上下文上test(should inherit use options on context when using built-in browser fixture, async ({ browser, }) { const context await browser.newContext(); const page await context.newPage(); expect(await page.evaluate(() navigator.userAgent)).toBe(some custom ua); expect(await page.evaluate(() window.innerWidth)).toBe(100); await context.close(); });Configuration Scopes全局、项目、文件与单测的覆盖链Playwright 允许你按全局、按项目、按测试文件、按 describe 块甚至按单个测试来逐级配置。以locale为例可以先在全局use中设置默认值import { defineConfig } from playwright/test; export default defineConfig({ use: { locale: en-GB }, });然后在某个项目内覆盖为德语此处还借助了devices[Desktop Chrome]预置的设备描述符import { defineConfig, devices } from playwright/test; export default defineConfig({ projects: [ { name: chromium, use: { ...devices[Desktop Chrome], locale: de-DE, }, }, ], });devices描述符本质上就是一个展开的选项对象可对照 deviceDescriptors.ts 查看因此“合并项目专属仿真”与“展开某个设备定义”可以自然组合。也可以对整个测试文件覆盖——用test.use()传入选项即可。例如让特定文件里的测试以法语运行import { test, expect } from playwright/test; test.use({ locale: fr-FR }); test(example, async ({ page }) { // ... });同样的写法也适用于 describe 块内让块内测试使用法语import { test, expect } from playwright/test; test.describe(french language block, () { test.use({ locale: fr-FR }); test(example, async ({ page }) { // ... }); });优先级关系总结为单个测试的test.use() 文件/describe 内的test.use() project 的use config 顶层use。因为use选项本质是带作用域的 fixture option该机制与 fixtures.ts 中实现的 fixture 覆盖链完全一致——内层声明会覆盖外层同名选项。重置某个选项回到 config 或彻底置空如果文件级/describe 级test.use()已经把某个选项改掉你仍可以在更内层把它“重置”回配置文件定义的值。考虑如下 config它设置了baseURLimport { defineConfig } from playwright/test; export default defineConfig({ use: { baseURL: https://playwright.dev, }, });随后在测试文件中先为整个文件配置新的baseURL再在某个 describe 块里退回到 config 定义的值import { test } from playwright/test; // Configure baseURL for this file. test.use({ baseURL: https://playwright.dev/docs/intro }); test(check intro contents, async ({ page }) { // This test will use https://playwright.dev/docs/intro base url as defined above. }); test.describe(() { // Reset the value to a config-defined one. test.use({ baseURL: undefined }); test(can navigate to intro from the home page, async ({ page }) { // This test will use https://playwright.dev base url as defined in the config. }); });这里的关键技巧是test.use({ baseURL: undefined })会把该文件级设置移除从而回退到上一层config 顶层的值。如果你希望把值彻底清空为undefined即连 config 中的默认值也不使用则需使用长格式的 fixture 语法import { test } from playwright/test; // Completely unset baseURL for this file. test.use({ baseURL: [async ({}, use) use(undefined), { scope: test }], }); test(no base url, async ({ page }) { // This test will not have a base url. });这段长格式声明覆盖了整个测试文件的baseURLfixture使其始终产出undefined从而完全绕过 config 中的默认baseURL。由此可以推导出更通用的规则凡是形如option: [async ({}, use) use(value), { scope: test }]的长格式写法都能在文件或 describe 粒度直接接管某个 fixture 选项的默认来源。典型配置模板把知识组合进一个真实项目参考仓库中 examples/github-api 与 examples/todomvc 的写法一个同时覆盖“仿真 网络 录制 多项目”的use段落通常长这样import { defineConfig, devices } from playwright/test; export default defineConfig({ testDir: ./tests, retries: 2, reporter: [[html, { open: never }]], use: { baseURL: process.env.PLAYWRIGHT_TEST_BASE_URL || http://localhost:3000, trace: on-first-retry, screenshot: only-on-failure, video: retain-on-failure, locale: en-GB, timezoneId: Europe/Paris, viewport: { width: 1280, height: 720 }, httpCredentials: { username: user, password: pass }, launchOptions: { slowMo: 0 }, }, projects: [ { name: chromium, use: { ...devices[Desktop Chrome] } }, { name: firefox, use: { ...devices[Desktop Firefox] } }, { name: mobile-safari, use: { ...devices[iPhone 13] } }, ], });顶层的retries: 2与use中的trace: on-first-retry组合可精确实现“只对第一次重试录 trace”——这与上文 trace 模式表中retries: 2的推演场景一一对应把baseURL交给环境变量让 CI 与本地共用同一份配置不同浏览器/设备用projects表达配合 docs/src/test-projects.md 可进一步做设备矩阵与并行分片。小结use配置块是 Playwright 测试项目中承上启下的枢纽向上它承接 config 顶层与 project 的定义向下它把 BrowserType.launch / Browser.newContext / BrowserType.connect 三套 API 的参数统一收口。从 源码实现 可以看到它依赖一套带option: true的 fixture 体系完成声明式默认值管理又通过_combinedContextOptions与runBeforeCreateBrowserContext实现“显式优先、use 兜底”的上下文合并语义录制类的trace/video选项则在 “shouldCapture”何时录与 “shouldPreserve”录了留不留两阶段分别决策。配合全局 → 项目 → 文件 → describe → 单测的覆盖链与“赋undefined回退 / 长格式彻底置空”两种重置手法你可以在几乎不写额外代码的前提下把整套浏览器行为声明得清晰、稳定且易于在多个项目与 CI 环境间复用。延伸阅读项目projects与设备矩阵配置浏览器与渠道channel选择超时体系与 actionTimeout重试机制对录制模式的影响仿真设备、地理定位、时区与语言网络认证、代理与请求拦截下载处理、截图、视频 与 Trace Viewer【免费下载链接】playwrightPlaywright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.项目地址: https://gitcode.com/GitHub_Trending/pl/playwright创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考