Playwright 请求 Mock 实战：使用 playwright-cli 拦截、伪造、修改与阻断网络请求

Playwright 请求 Mock 实战使用 playwright-cli 拦截、伪造、修改与阻断网络请求【免费下载链接】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导读在 Web 开发与测试中接口尚未就绪、需要模拟异常场景、或想在真实响应上做小改动都是最常见的诉求。本篇文章围绕当前仓库中playwright-cli技能文档 request-mocking.md 展开完整讲解 Playwright CLI 模式下如何用一条命令对页面网络流量进行拦截、Mock、修改与阻断。读完你不仅能熟练使用route/route-list/unroute命令还能借助run-code编写条件响应、改写真实响应、模拟断网与延迟等高级拦截逻辑并理解其底层通过 page/context.route 注册处理器的工作机制。playwright-cli是一套面向浏览器自动化代理与 LLM Agent 的命令行技能定义在 SKILL.md其中网络Network类命令属于其能力分类之一。整套技能的安装与调用方式遵循该文件若全局playwright-cli不可用可先通过npx playwright cli使用本地版本或执行npm install -g playwright/clilatest安装全局命令。CLI Route 命令一条命令搞定最常见 Mock原文档给出了五类最常用的命令形态分别覆盖自定义状态码、JSON Body、自定义请求头、移除请求头、路由的增删查。下面逐条给出并做参数补充说明。用自定义状态码模拟失败playwright-cli route **/*.jpg --status404命中**/*.jpg的图片请求将不再发往服务器而是直接返回 404。--status指定 HTTP 状态码默认值为 200。用 JSON 文本伪造接口响应playwright-cli route **/api/users --body[{id:1,name:Alice}] --content-typeapplication/json--body是响应体纯文本或 JSON 字符串建议同时用--content-type显式声明 Content-Type避免页面端 JSON 解析失败。两个参数都没有被限制为 JSON因此也可以返回text/html、text/plain等任意文本。附加自定义响应头 / 移除请求头# 响应携带自定义头 playwright-cli route **/api/data --body{ok:true} --headerX-Custom: value # 从实际发出的请求里剥离敏感头cookie、authorization 等 playwright-cli route **/* --remove-headercookie,authorization--header使用Name: Value格式、可重复传入多条--remove-header接受逗号分隔的头名列表。注意这两者的语义差别很大--header作用于Mock 响应的响应头而--remove-header实际是在放行真实请求前删除该请求的请求头。从源码看这两种有 body/status 就 fulfill、否则改头后 continue的分支逻辑正是 CLI 封装层的关键设计。其声明位于 cli-daemon/commands.tsroute命令的 zod 参数与选项校验真正的路由处理器实现在 tools/backend/route.ts若提供了body或status则调用route.fulfill({ status, contentType, body })直接以 Mock 数据应答请求不会再到达服务器否则基于route.request().headers()复制当前请求头叠加--header添加的头、删除--remove-header指定的头删除时统一按小写键匹配再通过route.continue({ headers })放行。--remove-header因此在拦截器场景下很有用例如想验证不带 Cookie 访问或剔除 Authorization 后是否仍能鉴权时不必改应用代码即可模拟。removeHeaders在命令层被定义为一个原始字符串commands.ts到 route.ts 内部才按逗号split并trim所以书写时要确保逗号与名称之间没有多余空格。查看与移除已注册路由# 列出当前所有生效路由 playwright-cli route-list # 按模式移除某一条或一类路由 playwright-cli unroute **/*.jpg # 不带模式参数时移除全部路由 playwright-cli unrouteroute-list在命令层被标记为raw: truecommands.ts其输出逻辑会把每条路由格式化为序号. pattern (status..., body..., contentType..., addHeaders..., removeHeaders...)其中 body 超过 50 字符会被截断展示route.ts。没有路由时输出No active routes。unroute的匹配基于完全相同的模式字符串由 context.ts 中的removeRoute(pattern)过滤内部路由表_routes对每个同名模式调用browserContext.unroute(pattern, handler)精确解绑省略 pattern 时则遍历清空并返回移除总数。因此与route注册时使用逐字一致的 pattern包括通配符写法才能保证命中预期的那条规则。这些行为都有自动化测试覆盖见 cli-route.spec.ts其中验证了空列表时route-list无输出注册后route-list显示status200unroute **/api/users恰好移除 1 条而另一条**/api/posts保留不带参数的unroute提示Removed all 2 route。URL 匹配模式glob 语法route命令的第一个位置参数pattern使用 Playwright 全局匹配语法本质上是把该 glob 模式交给browserContext.route(pattern, handler)去匹配。文档给出的四类范式如下**/api/users - 精确匹配路径段 **/api/*/details - 路径中的单级通配符 **/*.{png,jpg,jpeg} - 按文件扩展名匹配 **/search?q* - 匹配带查询参数的 URL要点说明**匹配任意层级的路径*在路径段内匹配任意字符?可匹配单个字符。{png,jpg,jpeg}花括号枚举常用于按资源类型统一拦截例如**/*.{png,jpg,jpeg}可一次覆盖绝大多数图片格式。pattern 支持拼入查询串如**/search?q*适合只拦截特定参数的请求。在 commands.ts 中 pattern 被描述为**/api/users这类 URL 通配实际使用时可从最宽的**到尽量窄的具体 URL按需收敛规则越具体误伤越少。用 run-code 实现高级拦截route命令覆盖的是固定响应 / 放行改头这两种最常见形态。当需要基于请求内容决定响应、改写真实响应、模拟网络故障、引入延迟等按请求动态决策的逻辑时文档给出了一套统一的进阶手段playwright-cli run-code传入一个async page { ... }函数在函数体内使用 Playwright 标准的page.routeAPI。它与路由命令共处同一能力体系中使用方式详见 running-code.md命令行还支持把脚本写入文件后通过run-code --filenamescript.js执行。根据请求内容返回条件响应playwright-cli run-code async page { await page.route(**/api/login, route { const body route.request().postDataJSON(); if (body.username admin) { route.fulfill({ body: JSON.stringify({ token: mock-token }) }); } else { route.fulfill({ status: 401, body: JSON.stringify({ error: Invalid }) }); } }); }这里通过route.request().postDataJSON()读取 POST 请求体并反序列化然后按业务条件分流管理员账号返回一个伪造的token状态码默认 200其他账号则用status: 401模拟鉴权失败。这相当于把上文的静态 Mock 升级为假后端非常适合在真实登录服务不可用时驱动整条登录流程的测试。放行并改写真实响应playwright-cli run-code async page { await page.route(**/api/user, async route { const response await route.fetch(); const json await response.json(); json.isPremium true; await route.fulfill({ response, json }); }); }此模式先用route.fetch()向服务器真实发起请求拿到response再对响应体做增量修改示例把isPremium置为true最后调用route.fulfill({ response, json })把原始响应 修改后的 JSON 体一同返回给页面。相比--body的整体替换这种沿用真实状态码与响应头、只改业务字段的拦截方式更贴近真实环境是验证会员权益、折扣价等灰度逻辑时的常用手段。模拟网络故障与错误码playwright-cli run-code async page { await page.route(**/api/offline, route route.abort(internetdisconnected)); } # 可选错误码connectionrefused, timedout, connectionreset, internetdisconnectedroute.abort(errorCode)会直接中断请求并让页面侧收到对应类型的网络错误。文档列出的可用错误码包括connectionrefused连接被拒、timedout超时、connectionreset连接被重置与internetdisconnected断网。这为演练页面在弱网、断网、服务不可用时的降级与错误提示提供了零成本复现手段同时也可借此验证应用是否会把错误信息误暴露给用户。注入响应延迟playwright-cli run-code async page { await page.route(**/api/slow, async route { await new Promise(r setTimeout(r, 3000)); route.fulfill({ body: JSON.stringify({ data: loaded }) }); }); }在 handler 中先await一个 3 秒的定时器再fulfill即可精确制造慢接口。通过调节setTimeout的时长可以复现 loading 态闪现、超时竞态、按钮防重复提交等与响应耗时相关的交互问题。底层原理路由如何注册、生效与注销把 CLI 命令与实现一一对应可以看清整条链路的全貌参数声明与校验route、route-list、unroute三条 CLI 命令在 cli-daemon/commands.ts 中声明分别映射到底层工具browser_route、browser_route_list、browser_unroute。处理器构造tools/backend/route.ts 中browser_route会把 CLI 选项翻译为一条RouteEntry内含pattern、status、body、contentType、addHeaders、removeHeaders以及真正执行拦截/放行的handler闭包。注册到浏览器上下文context.addRoute(entry)内部调用browserContext.route(pattern, handler)把处理器挂到 BrowserContext 的网络拦截层使该浏览器上下文内所有标签页的请求都受此规则影响context.ts。请求命中后的分派命中 pattern 的请求进入 handler按上文所述有 body/status → fulfill否则改请求头后 continue的策略处理。查询与清理browser_route_list遍历context.routes()输出明细unroute则通过context.removeRoute(pattern)精确解绑同名处理器或全量清空context.ts。值得注意的两点路由挂在BrowserContext上而非单个 Page 上browserContext.route因此对后续新打开的标签页同样生效如需一次性路由应在高级脚本中改用page.route其随页面关闭自动失效。一个 pattern 允许注册多条规则route-list会逐条编号展示注册多条相同 pattern 时unroute pattern会把它们全部移除并返回移除条数cli-route.spec.ts 对此有对应断言。使用建议与注意事项能静态就不写码仅需固定状态码、固定 body、固定响应头或删请求头时优先用route命令涉及动态判断、真实响应改写、延迟、abort 时才引入run-code二者对应的正是文档划分的CLI Route Commands与Advanced Mocking with run-code两层。pattern 一致性unroute是按模式字符串精确匹配的注销时需与route注册的 pattern 完全一致参考 context.ts 的过滤逻辑。善用route-list排查忘记自己注册过哪些规则、或响应行为诡异时先执行playwright-cli route-list观察每条规则的status/contentType/body超长截断等详情再用unroute pattern精确摘除避免 Mock 残留干扰后续操作。Mock 范围注意route系列作用于浏览器上下文适合整场会话级别的稳定 Mock若只想在特定页面流程内临时生效建议使用run-codepage.route并在流程结束时page.unroute主动清理。命令不可用时按 SKILL.md 的安装说明先尝试npx playwright cli或在具备网络条件下以npm install -g playwright/clilatest安装全局命令。结合 request-mocking.md、commands.ts 与 route.ts 对照阅读即可在动手时快速定位某条命令背后到底做了什么把请求 Mock 从试出来的技巧变成可预测、可排查的工程能力。【免费下载链接】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），仅供参考