Playwright 公共参数参考（params.md）完全解析：超时、动作可操作性、上下文仿真与截图配置一册通

2026-09-06 19:00:49作者：薛曦旖Francesca

本篇以 Playwright 仓库中的 docs/src/api/params.md 为骨架展开。它是整个 Playwright 官方 API 文档的"参数碎片库"：所有类文档（如 Page.goto、Browser.newContext、Locator.getByRole）中反复出现的 timeout、waitUntil、viewport、recordHar 等数百个参数，都以模板形式集中定义于此，再通过占位符注入各 API 页面。读完本文，你将系统掌握 Playwright 的导航等待语义、四层超时体系、动作可操作性（actionability）校验、浏览器启动与上下文仿真选项、定位器过滤、截图控制、请求伪造与测试断言参数，并理解这些参数在底层源码中如何被解析与回退。

一、params.md 在 Playwright 文档体系中的角色与机制

docs/src/api/params.md 全文件约 2060 行，本身并不直接对外呈现，而是充当文档生成期的"宏/模板库"。每一个条目以 ## <参数名> 作为唯一标识，例如 navigation-wait-until、context-option-viewport、screenshot-option-mask。其它 API 类文档（如 class-page.md、class-browser.md、class-frame.md）则通过 %%-<参数名>-%% 占位符引用这些片段。例如 class-browser.md 中写着：

### option: Browser.newContext.-inline- = %%-shared-context-params-list-v1.8-%%

shared-context-params-list-v1.8 这类"列表条目"由 params.md 里的一组子引用拼装而成（见原文 L1087-L1128），其中罗列了 %%-context-option-baseURL-%%、%%-context-option-viewport-%%、%%-context-option-recordvideo-%% 等几十个单参数条目。整个"模板替换"逻辑实现在 utils/doclint/api_parser.js 的 applyTemplates 中：doclint 在构建文档时把 params.md 解析为一个以 %%-<name>-%% 为键的 Map，遇到引用即替换成对应碎片。构建入口见 utils/doclint/cli.js，它会为不同语言的文档目录（api、test-api、electron-api、mobile-api）注入同一份 params.md。

因此，一个参数条目往往带以下元信息，理解它们能帮你快速定位"这条规则对我正在使用的语言是否生效"：

* langs: js, python, java, csharp：限定该参数只出现在指定语言的 API 文档中。未标注代表所有语言通用。
* since: v1.35 / v1.58 / v1.62：标注引入版本。例如 maskColor（截图蒙层颜色）自 v1.35 起，page-agent-*（智能体循环参数）自 v1.58 起，signal（AbortSignal 取消）自 v1.62 起。
* deprecated:：标记废弃及替代建议。例如 logger 被标注为"日志不完整，请改用 tracing"；noWaitAfter 在未来将默认 true。
* alias-java / alias-csharp / alias-python：同一逻辑在不同语言里的名字差异（如 viewport 在 Java/C# 中别名 viewportSize，在 Python 中写作 record_har_path 等）。
* 列表型条目（名字以 -list- 结尾）：用于把一组参数整体注入某个方法。

同时，原文内部还有多种交叉引用机制：带 [method: Page.goto] 形式的方法引用、指向概念页的 [actionability](https://gitcode.com/GitHub_Trending/pl/playwright/blob/46cd5008d12d4e1297793d921e6cc3b595e388da/docs/src/actionability.md?utm_source=gitcode_repo_files) 相对链接（仓库内实际对应 docs/src/actionability.md）、[emulation](https://gitcode.com/GitHub_Trending/pl/playwright/blob/46cd5008d12d4e1297793d921e6cc3b595e388da/docs/src/emulation.md?utm_source=gitcode_repo_files#viewport)（对应 docs/src/emulation.md）、[locators](https://gitcode.com/GitHub_Trending/pl/playwright/blob/46cd5008d12d4e1297793d921e6cc3b595e388da/docs/src/locators.md?utm_source=gitcode_repo_files)（对应 docs/src/locators.md）、以及 [storage state and auth](https://gitcode.com/GitHub_Trending/pl/playwright/blob/46cd5008d12d4e1297793d921e6cc3b595e388da/docs/src/auth.md?utm_source=gitcode_repo_files)（对应 docs/src/auth.md）。

二、导航与等待：`waitUntil` 与四层超时体系

2.1 导航成功判定：`waitUntil` 与加载状态

导航类方法（Page.goto、Page.reload 等）何时算"操作成功"，由 waitUntil 决定，默认值为 load。可选值在 navigation-wait-until 中定义：

取值	语义	使用建议
`domcontentloaded`	等到 `DOMContentLoaded` 事件触发	适合只关心 DOM 就绪
`load`	等到 `load` 事件触发	默认值
`networkidle`	至少 500ms 没有任何网络连接后才算结束	官方明确 DISCOURAGED（不推荐），不要用于测试，应改用 Web 断言（`expect`）评估就绪状态
`commit`	收到网络响应且文档开始加载即结束	最轻量的语义

与之同族的加载状态还出现在 Page.waitForLoadState 的 state 参数（wait-for-load-state-state）中：取值 load / domcontentloaded / networkidle，默认 load；若加载当前文档时该状态已达成，方法会立即返回。注意该参数的 networkidle 同样被标注 DISCOURAGED。

从源码看，Page.waitForLoadState / goto 等在 packages/playwright-core/src/client/frame.ts 中会经由 _navigationTimeout(options) 取超时，并把 waitUntil 连同 URL 等参数发给浏览器进程通道。

2.2 导航与动作超时：默认值、配置文件与 setter 方法

timeout 是所有操作最常用的参数，但它存在语言差异，params.md 为此分别维护了 *-js 与 python/java/csharp 两组碎片：

Python / Java / C#（navigation-timeout、input-timeout、wait-for-function-timeout）：最大毫秒数默认 30000（30 秒），传 0 禁用超时。可通过 BrowserContext.setDefaultNavigationTimeout、BrowserContext.setDefaultTimeout、Page.setDefaultNavigationTimeout、Page.setDefaultTimeout 修改全局默认。
JavaScript（navigation-timeout-js、input-timeout-js、wait-for-function-timeout-js）：文档化默认值为 0（即不单独设超时），可通过配置中的 navigationTimeout / actionTimeout 选项（对应 @playwright/test 的配置体系），或上述四个 setter 统一修改。

两者表述不同，但底层机制一致：所有超时最终都归口到 TimeoutSettings。在 packages/playwright-core/src/client/timeoutSettings.ts 中可以看到完整回退链：方法级显式 timeout 优先 → 上下文的 _defaultNavigationTimeout →（导航场景）_defaultTimeout → 父级设置 → 兜底常量 DEFAULT_PLAYWRIGHT_TIMEOUT。JS 侧配置里的 navigationTimeout/actionTimeout 本质就是在运行时把上述默认值写入 TimeoutSettings（对应 browserContext.ts 的 setDefaultTimeout/setDefaultNavigationTimeout 实现）。当这些默认都未建立时，源码兜底值为 30 秒（见 packages/isomorphic/time.ts，DEFAULT_PLAYWRIGHT_TIMEOUT = 30_000）；把 timeout: 0 传入各方法即走 kNoTimeout 哨兵（timeoutSettings.ts L26），跳过一切截止时间。另外在 inspector 调试模式下（debugMode() === 'inspector'），超时会被置 0，避免调试中断。

2.3 v1.62 起支持 AbortSignal 取消

wait-for-event-signal、input-signal、js-assertions-signal 三个条目表明：自 v1.62 起，等待事件、输入动作与断言都接受可选的 signal（AbortSignal）。信号一旦中止，等待/操作/断言即中断并抛错。要点是：提供 signal 并不会关闭默认超时——想完全取消时间限制仍需显式传 timeout: 0。断言场景下，若信号在重试期间或断言开始前就已中止，断言将直接失败而不再继续重试。

2.4 断言（expect）超时与截图比对容差

断言重试窗口：Java/Python/C# 的 timeout 默认 5000ms（csharp-java-python-assertions-timeout）；JS 默认跟随 TestConfig.expect 中配置的 timeout。
ignoreCase：是否大小写不敏感匹配；显式设置后优先于正则自身的 flag。
截图像素级比对（仅 JS，与 toHaveScreenshot 相关）：maxDiffPixels（允许差异的像素个数）、maxDiffPixelRatio（差异像素占总像素比例，取值 0–1，两者默认未设置、可经 TestConfig.expect 配置）、threshold（YIQ 颜色空间中感知色差阈值，0 严格 / 1 宽松，默认 0.2）。

2.5 等待函数与元素状态

Page.waitForFunction 系列通过轮询执行页面内表达式，相关参数：

polling（JS/Python）：取字符串 'raf' 表示在 requestAnimationFrame 回调中每帧执行；取数字则表示按毫秒为间隔周期执行。默认 raf。
pollingInterval（C#/Java）：同上语义，默认未指定时在 requestAnimationFrame 回调中执行。
waitForSelector 的 state 参数取值：attached（进入 DOM）、detached（离开 DOM）、visible（有非空包围盒且非 visibility:hidden；注意无内容或 display:none 的元素包围盒为空、不算可见）、hidden（脱离 DOM 或包围盒为空或 visibility:hidden，是 visible 的相反面），默认 'visible'。

三、输入动作参数：严格模式、可操作性校验与动作语义

Page.click、Locator.check、dragAndDrop 等"输入类"方法共享大量同名参数，均在 params.md 中以 input-* 前缀集中定义。

3.1 严格模式（strict）与动作强制（force、trial、noWaitAfter）

strict：为 true 时要求选择器解析结果唯一，若命中多个元素则抛异常。
force：是否跳过 actionability（可操作性）检查，默认 false。可操作性检查即点击前 Playwright 对元素做的"可见、稳定、可接收事件、不被遮挡"等一连串校验，force: true 会绕过它们直接派发动作（适合极端场景，一般不推荐）。
trial：置位后方法只执行可操作性检查而不真正执行动作，默认 false，用于"等到元素可以操作了"但又不想操作它。trial 有个变体 input-trial-with-modifiers：执行可操作性检查时仍会按下键盘 modifiers，以便测试那些"按下修饰键才可见"的元素。
noWaitAfter：对于会引发导航的动作，Playwright 默认会等待导航发生、页面开始加载；置为 true 可退出该等待（仅用于如导航到不可访问页面等极端情况），默认 false。已废弃的一个变体 input-no-wait-after-removed 明确说明该选项"已无任何效果"。

3.2 命中点、位移步数与修饰键

selector / source / target：动作目标元素的选择器；若有多个元素命中，取第一个。其中 dragAndDrop 用 source 表示被拖元素、target 表示投放目标。
position（别名 Position）：{x, y} 浮点坐标，表示相对元素 padding box 左上角的点击点；缺省时自动取元素某个可见点。拖放场景还支持 sourcePosition 与 targetPosition，分别指定在源元素/目标元素上的落点。
steps：两种语义略有差别。input-mousemove-steps 用于鼠标移动（如 mouse.move），发送 n 个插值 mousemove 事件模拟从当前光标位置到目的地的轨迹；input-drag-steps 用于拖放，在 mousedown 与 mouseup 之间插值移动事件。两者默认都为 1（只发一个终点位置的 mousemove）。
modifiers：Alt / Control / ControlOrMeta / Meta / Shift 数组。操作期间只按下这些修饰键，结束后恢复此前按键状态；未指定则沿用当前已按下的修饰键。ControlOrMeta 在 Windows/Linux 解析为 Control、在 macOS 解析为 Meta。
button：left/right/middle，默认 left；delay：mousedown 与 mouseup 之间的等待毫秒数，默认 0；clickCount：点击次数，默认 1，对应 DOM 的 UIEvent.detail。
checked：checkbox/radio 的 check/uncheck 目标状态（C# 中别名 checkedState）。
scroll（ScrollMode）：控制动作前是否滚动元素进入视口。默认 "auto"（必要时滚动，包含嵌套可滚动容器）；设为 "none" 则不滚动，元素不在视口内则动作失败，可用于断言"无需额外滚动用户即可触达该元素"。

3.3 文件上传与拖放载荷

files（input-files）：本地文件路径，或内存文件对象（FilePayload：name 文件名、mimeType 文件类型、buffer 内容 Buffer），单个或多个皆可。
payload（drop-payload，别名 DropPayload）：用于 dragAndDrop 之外"拖放数据"类 API，可同时提供 files 与 data。其中 data 是 mime 类型 → 字符串 的映射，模拟剪贴板类内容（如 text/plain、text/html、text/uri-list）；files、data 可二选一或同时提供。

四、浏览器启动参数（BrowserType.launch 一族）

BrowserType.launch、browser.newBrowser 等方法的共享参数集中在 browser-option-*：

args：额外传给浏览器实例的命令行参数（Chromium flags 列表可在 peter.sh 的 Chromium 命令行开关表查到）。原文档显著警告：使用自定义浏览器参数风险自负，部分参数可能破坏 Playwright 功能。
channel：浏览器发行渠道。用 "chromium" 可显式选择新的 headless 模式（见 browsers.md）；用 "chrome"、"chrome-beta"、"chrome-dev"、"chrome-canary"、"msedge"、"msedge-beta"、"msedge-dev"、"msedge-canary" 则启动品牌化的 Google Chrome / Microsoft Edge。
headless：是否无头运行，默认 true。JS/Python 另有 chromiumSandbox：是否启用 Chromium 沙箱，默认 false。
ignoreDefaultArgs（JS/Python）：传 true 表示完全不用 Playwright 自带的默认参数，只用 args；传数组则只过滤掉其中列出的默认参数。官方标注"Dangerous option; use with care"，默认 false。C#/Java 拆成了 ignoreDefaultArgs（数组）与 ignoreAllDefaultArgs（布尔，默认 false）两个参数。
executablePath：指定可执行文件路径以替代内置浏览器（相对路径按当前工作目录解析）。注意：Playwright 只保证对内置 Chromium/Firefox/WebKit 正常工作，换用其它构建风险自负。
downloadsPath：接受下载的落盘目录；不指定则使用临时目录并在浏览器关闭时删除。无论哪种情况，下载文件都会在其所属 BrowserContext 关闭时被清理。
env：注入给浏览器进程的环境变量，默认继承 process.env（C#/Java 文档化类型为字符串映射，Python 额外允许数值与布尔值）。
firefoxUserPrefs（JS/Python/C#/Java）：Firefox 用户偏好（about:config 中的项）。另可用环境变量 PLAYWRIGHT_FIREFOX_POLICIES_JSON 指向自定义 policies.json。
proxy：见下文"网络代理"一节，浏览器级代理设置。
handleSIGINT / handleSIGTERM / handleSIGHUP：收到相应信号时关闭浏览器进程，均默认 true。
timeout：等待浏览器实例启动的最大毫秒数，默认 30000，传 0 禁用。
slowMo：将 Playwright 操作整体放慢指定毫秒数，方便肉眼观察（调试利器，勿用于生产测试）。
artifactsDir：trace、video、downloads、HAR 等产物的保存目录；指定后该目录不会在浏览器关闭时自动清理，不指定则使用临时目录并自动清理。tracesDir：单独指定 trace 的保存目录。
logger（仅 JS）：日志接收器；已废弃，官方建议改用 tracing。

五、BrowserContext 选项（上）：基础行为、视口与媒体仿真

Browser.newContext / browser.newPage / 以及测试中的 use 配置共享 context-option-*，这是 params.md 中占比最大的部分，也是日常用例仿真与测试环境治理的核心。

5.1 基础开关与网络行为

acceptDownloads：是否自动接受全部下载，默认 true。
ignoreHTTPSErrors：发送网络请求时是否忽略 HTTPS 错误，默认 false。
bypassCSP：是否绕过页面 Content-Security-Policy，默认 false。
userAgent：指定该上下文使用的 User-Agent。
javaScriptEnabled：上下文内是否启用 JavaScript，默认 true（禁用 JS 相关讨论见 emulation.md）。
offline：模拟断网，默认 false。
serviceWorkers（ServiceWorkerPolicy，默认 'allow'）：'allow' 允许站点注册 Service Worker；'block' 则阻止一切 Service Worker 注册。对应测试覆盖见 browsercontext-service-worker-policy.spec.ts。
strictSelectors：开启上下文级严格选择器模式——所有"隐含单目标"的选择器操作在命中多个元素时抛异常；不影响 Locator API（Locator 本就永远严格）。默认 false。测试覆盖见 browsercontext-strict.spec.ts。
baseURL：配合 Page.goto、Page.route、Page.waitForURL、Page.waitForRequest、Page.waitForResponse 使用，通过 new URL() 构造函数拼接目标地址。原文示例：
- baseURL: http://localhost:3000 + 导航 /bar.html → http://localhost:3000/bar.html
- baseURL: http://localhost:3000/foo/ + 导航 ./bar.html → http://localhost:3000/foo/bar.html
- baseURL: http://localhost:3000/foo（无尾斜杠）+ 导航 ./bar.html → http://localhost:3000/bar.html
extraHTTPHeaders：附加到每个请求的 HTTP 头，默认无。
permissions：赋予该上下文所有页面的权限列表（如 'geolocation'、'notifications'），默认不给任何权限；详情参见 BrowserContext.grantPermissions。
httpCredentials：HTTP 基本认证凭据。单对象含 username/password，可选 origin（scheme://host:port）限定只对特定源发送，以及 send（'unauthorized'|'always'，默认 'unauthorized'，即收到 401 + WWW-Authenticate 才发送；'always' 则随每个 API 请求携带 Authorization 头，且该开关只影响 APIRequestContext 发出的请求、不影响浏览器内请求）。也支持传数组，为不同源配置不同凭据，数组按请求源匹配第一条命中的条目，无 origin 的条目匹配任意请求。不指定 origin 时，用户名密码会在任何服务器的 401 响应后被发送。

5.2 视口、屏幕与 DPR/触屏仿真

viewport（C#/Java/Python 别名 viewportSize）：{width, height}，为每个页面仿真一致的视口，默认 1280×720；传 null（C# 用 ViewportSize.NoViewport）禁用固定视口仿真。注意文档明示的陷阱：取消预设后视口会跟随操作系统定义的主机窗口尺寸，导致测试执行不确定（non-deterministic）。Python 另有独立布尔参数 noViewport 表达同样语义（有头模式下允许自由调整窗口大小）。详参 emulation.md。
screen（Java/C# 别名 screenSize）：仿真页面内 window.screen 可见的屏幕尺寸，仅在 viewport 被设置时生效。
deviceScaleFactor：设备像素比（dpr），默认 1。
isMobile：是否让 meta viewport 标签生效并启用触屏事件。它是"设备描述符"的一部分，通常无需手设；默认 false，且 Firefox 不支持。
hasTouch：视口是否支持触屏事件，默认 false。
浏览器启动与上下文级都提供 proxy（Proxy 对象）：server（必填；支持 HTTP 与 SOCKS，如 http://myproxy.com:3128 或 socks5://myproxy.com:3128；短格式 myproxy.com:3128 视为 HTTP 代理）、可选 bypass（逗号分隔的绕行域名，如 ".com, chromium.org, .domain.com"）、可选 username/password（HTTP 代理鉴权）。

5.3 CSS 媒体特性仿真：深色模式、动效偏好与强制色彩

为测试深色模式与无障碍偏好，上下文支持仿真 prefers-color-scheme 等媒体特性。通用规律：JS/Java 用 null 表示"恢复系统默认"，而 C#/Python 因类型体系使用字符串 'null'。

上下文参数	仿真目标	取值	默认值
`colorScheme`	`prefers-color-scheme`	`'light'` / `'dark'` / `'no-preference'`	`'light'`
`reducedMotion`	`prefers-reduced-motion`	`'reduce'` / `'no-preference'`	`'no-preference'`
`forcedColors`	`forced-colors`	`'active'` / `'none'`	`'none'`
`contrast`	`prefers-contrast`	`'no-preference'` / `'more'`	`'no-preference'`

这些媒体特性也可在运行期通过 Page.emulateMedia 动态切换。另有 timezoneId（改变上下文时区，默认系统时区，可用 ID 参考 ICU 的 metaZones.txt）、locale（影响 navigator.language、Accept-Language 请求头以及数字/日期格式化，默认系统区域，如 en-GB、de-DE）、geolocation（{latitude}（-90 到 90）、longitude（-180 到 180）、可选 accuracy（非负，默认 0））。定位、时区与区域化的联调场景可参考 emulation.md。

5.4 持久化登录态：storageState

storageState 用于让上下文预置"已登录"信息（Cookie 与 localStorage），来源通常是 BrowserContext.storageState() 的导出结果：

JS/Python：既支持文件路径（path），也支持内联对象，结构为：
- cookies[]：name、value、domain、path（domain 与 path 必填；想让 Cookie 覆盖所有子域需给 domain 加 . 前缀，如 ".example.com"）、expires（Unix 秒）、httpOnly、secure、sameSite（"Strict" | "Lax" | "None"）。
- origins[]：origin + localStorage[]（name、value）。
C#/Java：storageState 为字符串（文件路径）；另有独立的 storageStatePath 参数直接指向已保存的存储状态文件。

反向导出时用 storageState 方法配套的 path 参数（storagestate-option-path）：指定保存文件；相对路径相对当前工作目录解析；不传 path 也会返回存储状态对象，只是不落盘。完整方案（含登录会话复用示例）见 auth.md；测试覆盖可参考 browsercontext-storage-state.spec.ts。

5.5 TLS 客户端认证：clientCertificates

clientCertificates 让服务端可以请求并校验客户端证书。每个元素需满足三选一：同时给 certPath+keyPath、只给 pfxPath，或使用对应内联值变体（cert+key 或 pfx）；证书加密时补 passphrase。origin 必须与请求来源精确匹配（含 https 协议、主机名、可选端口）。

关键细节：仅在至少提供一个客户端证书时认证才会激活；如果想让服务端发来的所有客户端证书请求都被拒绝，就提供一个 origin 不匹配任何目标域名的证书。另有平台特例提示：WebKit on macOS 访问 localhost 不会拾取客户端证书，把 localhost 换成 local.playwright 即可生效。仓库中附带成套的 PEM/PFX 测试夹具（tests/assets/client-certificates）与用例 tests/library/client-certificates.spec.ts。

六、BrowserContext 选项（下）：HAR 录制与视频录制

6.1 录制 HAR

JS 的 recordHar 为对象：path（必填，HAR 落盘路径；以 .zip 结尾时自动默认 content: 'attach'）、可选 omitContent（是否省略请求内容，默认 false，已废弃、建议用 content）、content（HarContentPolicy：omit 不持久化内容 / attach 资源作为独立文件或 ZIP 条目保存 / embed 按 HAR 规范内联内容；默认 .zip 输出为 attach、其它扩展名为 embed）、mode（full|minimal，minimal 只记录回放路由所需信息，省略 sizes/timing/page/cookies/security 等，默认 full）、urlFilter（glob 或正则过滤需要记录的请求；若配置过 baseURL 且传入的是路径，则通过 new URL() 合并）。务必 await BrowserContext.close()，HAR 才会真正落盘。

C#/Java/Python 没有嵌套对象，改成多个平铺参数：recordHarPath、recordHarOmitContent（默认 false）、recordHarContent（默认 embed，Python 别名 record_har_content 等）、recordHarMode（默认 full）、recordHarUrlFilter。

6.2 录制视频

JS 的 recordVideo 为对象：

dir：视频目录；缺省存到 BrowserType.launch 的 artifactsDir。
size：{width, height}。缺省时尺寸等于 viewport 等比缩放到 800×800 内；若未显式配置 viewport，则默认 800×450；页面实际画面过大时会等比缩小以适配指定尺寸。
showActions：若指定则录制期间给被交互元素叠加可视化标注：duration（标注显示时长，默认 500ms）、position（标题叠加位置：top-left/top/top-right/bottom-left/bottom/bottom-right，默认 "top-right"）、fontSize（像素，默认 24）、cursor（pointer（默认）渲染一个从上个动作点动画到下一个的鼠标指针；none 关闭光标装饰）。

同样必须 close() 上下文后视频才会写出。非 JS 语言对应平铺参数 recordVideoDir、recordVideoSize（Java 别名 RecordVideoSize）。

七、定位器与 by-* API 参数

7.1 定位与过滤

selector（输入动作）与 querySelector 族参数都遵循"取第一个命中元素"。find-selector、find-selector-or-locator（后者接受 string | Locator）用于 frame 内元素解析。

locator.getByRole 之外，链式/过滤参数（locator-option-*）是构建健壮定位器的关键：

hasText：匹配任意后代中包含指定文本的元素；字符串匹配为大小写不敏感子串。例："Playwright" 匹配 <article><div>Playwright</div></article>。
has：限定结果到"包含能匹配此相对 locator 的元素"的那些元素。内层 locator 必须相对外层（从外层命中点往下查，而非从文档根开始）。例：找包含 text=Playwright 的 article；但 content 内查找 article div 会失败，因为内层不允许越过 content。外层与内层 locator 必须同属一个 frame，内层不允许包含 FrameLocator。
hasNot / hasNotText：取反过滤——匹配不包含内层 locator / 指定文本的元素。
visible：只匹配可见（或不可见）元素；仅匹配可见元素时优先使用 Locator.visible 快捷方式。

7.2 getByText / getByTestId 等语义化定位

getByText：按文本定位。字符串支持子串与精确两种模式，exact: true 表示大小写敏感、整串匹配（正则则忽略 exact）；任何匹配都会归一化空白（多个空格合并、换行转空格、忽略首尾空白）；type=button/submit 的 input 用 value 而非文本内容参与匹配。文中给出了完整四语言示例：

<div>Hello <span>world</span></div>
<div>Hello</div>

page.getByText('world');            // Matches <span>
page.getByText('Hello world');      // Matches first <div>
page.getByText('Hello', { exact: true });  // Matches second <div>
page.getByText(/Hello/);            // Matches both <div>s
page.getByText(/^hello$/i);         // Matches second <div>

page.get_by_text("world")
page.get_by_text("Hello world")
page.get_by_text("Hello", exact=True)
page.get_by_text(re.compile("Hello"))
page.get_by_text(re.compile("^hello$", re.IGNORECASE))

page.getByText("world");
page.getByText("Hello world");
page.getByText("Hello", new Page.GetByTextOptions().setExact(true));
page.getByText(Pattern.compile("Hello"));
page.getByText(Pattern.compile("^hello$", Pattern.CASE_INSENSITIVE));

page.GetByText("world");
page.GetByText("Hello world");
page.GetByText("Hello", new() { Exact = true });
page.GetByText(new Regex("Hello"));
page.GetByText(new Regex("^hello$", RegexOptions.IgnoreCase));

getByTestId：按 test id 定位。默认属性为 data-testid，可用 Selectors.setTestIdAttribute 更换（getByTestId 的 testId 参数自 v1.27 支持 string | RegExp）。在 @playwright/test 中通过 testIdAttribute 配置项全局替换（源码中的可配置点及注入机制可参见 packages/playwright-core/src/client/selectors.ts 相关实现）。
```
<button data-testid="directions">Itinéraire</button>
```
```
await page.getByTestId('directions').click();
```
```
await page.GetByTestId("directions").ClickAsync();
```
```
page.get_by_test_id("directions").click()
```
```
// playwright.config.ts：更换默认 test id 属性
export default defineConfig({
  use: { testIdAttribute: 'data-pw' }
});
```
getByAltText：按 alt 文本定位图片等元素；getByLabel：按关联 <label>、aria-labelledby 或 aria-label 定位输入控件（<input aria-label="Username"> 与 <label for="password-input">Password:</label><input id="password-input"> 均可用 getByLabel 命中）；getByPlaceholder：按占位符文本定位输入框（可配 exact）；getByTitle：按 title 属性定位元素。
getByRole：按 ARIA role + 可访问名/属性定位（见 locators.md）。可用过滤选项（大部分自 v1.27 起，exact 自 v1.28，description 自 v1.60）：
- role（必填 AriaRole，枚举如 heading、checkbox、button、listitem、row 等）
- name（string | RegExp，匹配可访问名；默认大小写不敏感子串，exact: true 后为大小写敏感整串；正则时忽略 exact）
- description（匹配可访问描述，行为同上）
- checked（通常来自 aria-checked 或原生 checkbox）、disabled（aria-disabled/disabled；与多数属性不同，disabled 沿 DOM 层级继承）、expanded（aria-expanded）、pressed（aria-pressed）、selected（aria-selected）
- level（heading/listitem/row/treeitem 的等级数字，<h1>-<h6> 有默认值）
- includeHidden：默认角色选择器不匹配隐藏元素（按 ARIA tree 排除规则），置 true 后包含
- exact：见上
原文强调：role 选择器不能替代无障碍审计与一致性测试，只是给出关于 ARIA 指南的早期反馈；许多 HTML 元素自带隐式角色，ARIA 指南不建议重复设置默认值的 role/aria-*。

八、截图参数：像素级可控的输出

截图类 API（Page.screenshot、Locator.screenshot、断言 toHaveScreenshot）共享 screenshot-option-*：

type：png（默认）/jpeg/webp；quality：0–100，png 不适用，jpeg 默认 80，webp 默认 100（无损），更低值使用有损压缩。
path：保存路径，类型由扩展名推断；相对路径相对当前工作目录解析；不传则不落盘。
fullPage：截取整个可滚动页面而非当前视口，默认 false。
clip：{x, y, width, height} 裁剪区域（左上角坐标 + 宽高）。
omitBackground：隐藏默认白色背景、允许透明截图；jpeg 不适用，默认 false。
animations（ScreenshotAnimations）："disabled" 时停止 CSS 动画/过渡与 Web Animations——有限动画快进到完成（会触发 transitionend），无限动画取消回初始态并在截图后继续播放。默认值有两种变体：多数 API 默认 "allow"（不动动画）；也有"默认即 disabled"的变体。
scale："css" 每 CSS 像素一个像素（高 DPI 下截图更小）；"device" 每设备像素一个像素（高 DPI 设备截图放大一倍甚至更多）。默认值随 API 不同，多数默认 "device"，另有默认 "css" 的变体。
caret："hide"（默认，隐藏文本光标）/ "initial"（保持原光标行为）。
mask：截图时要打码的 locator 数组，被遮元素用粉红 #FF00FF 色块完全盖住包围盒（可用 maskColor（CSS 颜色，v1.35+）自定义，默认 #FF00FF）；遮罩同样作用于不可见元素，若要只遮可见元素可参见 locators.md 的 visible 过滤。toHaveScreenshot 等视觉回归中通常搭配 mask: [page.getByTestId('dynamic')] 屏蔽动态内容。
style / stylePath：截图期间注入的样式表文本/文件（可隐藏动态元素、制造可复现截图），可穿透 Shadow DOM 并作用于内层 iframe。

九、evaluate 与代码执行参数

expression（Python/Java/C# 的通用形式）：要在浏览器上下文求值的 JavaScript 表达式；若求值结果是函数则自动调用。
JS 端 pageFunction：在页面上下文求值的 function | string，另有 evalOnSelector 变体（接收 Element 参数）与 evalOnSelectorAll 变体（接收元素数组）；worker 与 Electron 场景各自有 worker/主进程上下文的 pageFunction。
exposeFunctions（自某版本引入的新特性，用于 evaluate 与 init script）：为 true 时，arg 里传入的函数会被暴露到页面（底层走 Page.exposeFunction，因此所有 frame 与 world 都能访问），页面侧调用返回 Promise。Page.evaluate 场景下暴露的函数在顶层导航后被清除、默认 false（函数不可序列化，传递会抛错）；init script 场景的函数则随每个新文档重新暴露、跨导航存活，默认 false 时不可序列化的函数被静默丢弃。

十、APIRequestContext / fetch 请求参数

request.get/post、context.request 等的共享参数：

url：目标 URL。
params：查询参数（JS 支持对象/URLSearchParams/字符串；C# 另有 paramsString 直接给序列化后的查询串；Java 通过 options（RequestOptions）聚合）。
headers（JS/Python/C#）：附加 HTTP 头，会随初始请求及其触发的所有重定向一起发送。
data：请求体。传对象时序列化为 JSON 串并自动设 content-type: application/json（若未显式指定）；否则默认 application/octet-stream。
form：以 application/x-www-form-urlencoded 编码的表单体（对象即可）；指定后若未显式提供则自动设置对应 content-type。Python 可用 FormData 表达同名字段多值；C# 的 form 就是 FormData 实例，可通过 APIRequestContext.createFormData 创建。
multipart：以 multipart/form-data 编码（文件值可为 fs.ReadStream 或文件描述对象 {name, mimeType, buffer}）；指定后自动设置对应 content-type。Python 用 FormData 可同字段多文件；C# 亦用 FormData。
timeout：请求超时毫秒数，默认 30000，0 禁用。
failOnStatusCode：非 2xx/3xx 是否抛错，默认不抛（所有状态码都返回响应对象）。
ignoreHTTPSErrors：默认 false。
maxRedirects：自动跟随的最大重定向数，默认 20，超出抛错，0 表示完全不跟随。
maxRetries：网络错误重试次数上限，目前仅 ECONNRESET 被重试，不按 HTTP 状态码重试；默认 0（不重试），超出上限抛错。

十一、select 下拉框选项选择参数

多语言 API 差异较大，但核心语义一致："若 <select> 带 multiple 属性则选中所有匹配项，否则只选中第一个匹配项"；字符串值同时匹配 value 与 label；对象需所有给定属性都匹配才算命中。

JS/Java/C#（values，Java 别名 SelectOption）：string | ElementHandle | Array | { value?, label?, index? } 等组合；每条 SelectOption 的 value/label/index 均可选。
Python（平铺可选参数）：element（ElementHandle 或数组）、index、value、label，均可传数组。

十二、事件与导航等待参数

waitForEvent：event（事件名，同 .on(event) 使用的名字；JS/Python/Java）、Java 侧 callback（Runnable，触发事件的回调）、C# 侧 action（Func<Task>）；predicate：接收事件数据、返回真值即停止等待；timeout（C#/Java/Python 默认 30000）；signal（JS，v1.62，AbortSignal 取消，见 2.3 节）。
等待 URL 的参数 url：JS 支持 string | RegExp | URLPattern | (URL) => boolean；Python/C#/Java 支持 string | RegExp | predicate。注意：无通配符的纯字符串要求"完全等于"该 URL。
waitForLoadState 的 state：见 2.1 节。
移除监听/路由的行为参数（behavior）：
- removeAllListeners 的 behavior（JS，v1.47+）：'default'（不等待正在运行的监听器收尾，其抛错可能成为 unhandled error）/ 'wait'（等当前监听器调用结束）/ 'ignoreErrors'（不等，监听器之后抛出的错误被静默吞掉）。
- unrouteAll 的 behavior（JS/C#/Python，v1.41+）：与上同理，但针对 route handler 的解除（'wait' 等待正在运行的 handler 收尾再解绑）。

十三、响应对象返回字段

params.md 也承载"返回值"碎片：Response.securityDetails() 返回 {issuer, protocol, subjectName, validFrom, validTo}（TLS 证书信息，仅作参考）；Response.serverAddr() 返回 {ipAddress, port}；Request.timing()（别名 Timing）返回资源时序对象：startTime（自 1970-01-01 UTC 起的毫秒）与相对其偏移、不可用为 -1 的各阶段时间（domainLookupStart/End、connectStart、secureConnectionStart、connectEnd、requestStart、responseStart、responseEnd）。

十四、@playwright/test 快照路径模板（snapshotPathTemplate）

params.md 中另有一个测试配置级参数 snapshotPathTemplate（JS），用于模板化控制 toHaveScreenshot、toMatchAriaSnapshot、toMatchSnapshot 生成快照的位置，可按断言在 TestConfig.expect 中分别覆盖：

export default defineConfig({
  testDir: './tests',
  // 单模板统一所有断言
  snapshotPathTemplate: '{testDir}/__screenshots__/{testFilePath}/{arg}{ext}',
  // 按断言分别指定
  expect: {
    toHaveScreenshot: {
      pathTemplate: '{testDir}/__screenshots__{/projectName}/{testFilePath}/{arg}{ext}',
    },
    toMatchAriaSnapshot: {
      pathTemplate: '{testDir}/__snapshots__/{testFilePath}/{arg}{ext}',
    },
  },
});

模板支持的可替换 token 及其示例取值（假设测试文件 tests/page/page-click.spec.ts 中调用 toHaveScreenshot(['foo', 'bar', 'baz.png'])）：

{arg}：快照相对路径（不含扩展名），值为 foo/bar/baz；无参调用时为自动生成名。
{ext}：快照扩展名（带前导点），值为 .png。
{platform}：process.platform 值。
{projectName}：项目名的文件系统净化形式；无项目名时为空串。
{snapshotDir}：项目 snapshotDir；未配置时默认 testDir。
{testDir}：项目 testDir（相对配置文件解析为绝对路径）。
{testFileDir}：从 testDir 到测试文件目录的相对目录，值为 page。
{testFileBaseName} / {testFileName}：测试文件名（去/不去最后一个扩展名），值为 page-click.spec / page-click.spec.ts。
{testFilePath}：testDir 到测试文件的相对路径，值为 page/page-click.spec.ts。
{testName}：净化后的测试标题（含父级 describe、不含文件名），值为 suite-test-should-work。

每个 token 前可加一个仅当 token 非空时才会出现的前缀字符。模板解析为相对路径时基于 configDir 解析；任何平台都可用 / 作分隔符。示例中：未命名项目快照落在 <configDir>/__screenshots__/example.spec.ts/...，命名项目（chromium）则落在 <configDir>/__screenshots__/chromium/example.spec.ts/...。

十五、v1.58 起的"智能体（Agentic）"执行参数

params.md 还收录了一组 v1.58 新增的页面级智能体执行参数（page-agent-*），用于约束"把智能体动作转换为 Playwright 调用"的循环：

cacheKey：所有智能体动作会转换为 Playwright 调用并被缓存，默认以 task 作为全局缓存键；该参数允许显式控制缓存键。
maxTokens：本次任务可消耗的 token 上限，输入+输出 token 超出后停止循环，默认取上下文 agent 属性中的全局值。
maxActions：允许生成的最大智能体动作数，默认取上下文全局值。
maxActionRetries：生成每个动作的最大重试次数，默认取上下文全局值。

十六、实践要点小结

语言默认值差异是踩坑重灾区：Python/Java/C# 的文档化超时默认 30 秒、0 禁用；JS 文档化默认 0、由 @playwright/test 的配置（navigationTimeout/actionTimeout 与 expect.timeout）驱动，无框架裸用时核心兜底是 30 秒（DEFAULT_PLAYWRIGHT_TIMEOUT）。调试 inspector 模式下超时自动关闭。
networkidle 已被官方劝阻：评估页面就绪请使用基于 Web 断言的 expect(...)，而不是等 500ms 无网络。
严格模式是双向的：方法级 strict: true 只约束"选择器命中唯一"，上下文级 strictSelectors 覆盖更多查询，而 Locator API 天生严格。多命中抛错能显著提升选择器质量。
trial/force/noWaitAfter 属于高级逃生舱：优先保证元素满足可操作性（可见、稳定、不被遮挡），trial 可先于动作做"预检"。
仿真型上下文参数需要显式、确定：视口/屏幕/媒体特性尽量显式指定以保测试确定性；清除视口预设（null/NoViewport）会使结果依赖主机窗口，属不推荐路径。
HAR 与视频必须 close() 才落盘；.zip 后缀的 HAR 自动走 attach 内容策略。
截图稳定化三板斧：animations: 'disabled'、mask + maskColor 屏蔽动态元素、style/stylePath 隐藏易变内容，再配合 threshold/maxDiffPixelRatio 设定视觉容差。
任何自定义浏览器 flag、可执行文件与默认参数篡改都伴随兼容性风险，原文用 "Dangerous option; use with care" 反复强调。