Playwright 网络拦截（Route & Request Interception）（2025 年最新版）
网络拦截是 Playwright 最强大的功能之一，允许你拦截、修改、mock 或中止浏览器发出的任何网络请求（XHR、fetch、API 调用、图片、CSS 等）。常用于：
- Mock API 响应（加速测试、避免真实后端依赖）
- 测试错误场景（404、500、超时）
- 修改请求头/参数
- 模拟网络延迟或离线
- 捕获 API 数据进行断言
Playwright 使用page.route()和route.handler()实现拦截，支持通配符匹配。
1.基本用法：拦截并 Mock 响应
// tests/mock-api.spec.tsimport{test,expect}from'@playwright/test';test('Mock API 返回固定数据',async({page})=>{// 拦截所有 /api/users 请求awaitpage.route('**/api/users',asyncroute=>{// Mock 一个成功的 JSON 响应awaitroute.fulfill({status:200,contentType:'application/json',headers:{'Access-Control-Allow-Origin':'*'},// 可选：处理 CORSbody:JSON.stringify([{id:1,name:'Mock 用户1'},{id:2,name:'Mock 用户2'},]),});});awaitpage.goto('https://your-app.com/users');// 页面会显示我们 mock 的数据awaitexpect(page.getByRole('heading')).toHaveText('用户列表');awaitexpect(page.getByText('Mock 用户1')).toBeVisible();});2.常见拦截模式
| 场景 | 代码示例 | 说明 |
|---|---|---|
| 继续原请求（不修改） | await route.continue(); | 默认行为，常用于日志记录 |
| 修改请求（添加头/参数） | ```await | |
| 中止请求（模拟失败） | await route.abort('failed');或await route.abort(); | 触发 network error |
| 模拟错误响应 | await route.fulfill({<br> status: 500,<br> body: 'Server Error'<br>}); | 返回 4xx/5xx |
| 重定向 | await route.fulfill({ status: 301, headers: { location: '/new-url' } }); | 模拟重定向 |
| 模拟网络延迟 | await page.route('**/*', async route => {<br> await new Promise(r => setTimeout(r, 2000)); // 延迟 2s<br> await route.continue();<br>}); | 测试 loading 状态 |
| 拦截特定类型资源 | await page.route('**/*.{png,jpg,jpeg}', route => route.abort()); | 阻塞图片加载（加速测试） |
3.高级：根据请求动态决定
awaitpage.route('**/api/**',asyncroute=>{constmethod=route.request().method();if(method==='GET'&&route.request().url().includes('users/1')){awaitroute.fulfill({json:{id:1,name:'特殊用户',vip:true}});// shorthand for JSON}elseif(method==='POST'){// 记录请求体用于断言constpostData=route.request().postDataJSON();console.log('收到 POST 数据:',postData);awaitroute.fulfill({status:201,json:{success:true}});}else{awaitroute.continue();}});4.捕获响应进行断言
// 等待特定响应并验证const[response]=awaitPromise.all([page.waitForResponse('**/api/login'),page.getByRole('button',{name:'登录'}).click(),]);expect(response.status()).toBe(200);constjson=awaitresponse.json();expect(json.token).toBeTruthy();5.拦截 WebSocket（Playwright v1.30+ 支持）
awaitpage.route('wss://example.com/socket',route=>{// WebSocket 拦截目前有限制，通常用 route.continue() + page.on('websocket')route.continue();});page.on('websocket',ws=>{console.log(`WebSocket 打开:${ws.url()}`);ws.on('framesent',frame=>console.log('发送:',frame));});6.Python 版示例（Mock API）
defhandle_route(route):if"api/users"inroute.request.url:route.fulfill(status=200,content_type="application/json",body='[{"id":1,"name":"Mock 用户"}]')else:route.continue_()page.route("**/api/**",handle_route)page.goto("https://your-app.com")最佳实践总结
- 匹配规则：使用
**/通配符（如**/api/**）覆盖所有子路径。 - 优先级：先定义具体路由，后定义通用路由（后定义的优先）。
- 清理：测试结束无需手动 unroute，Playwright 会自动清理。
- 生产测试：结合
route.fulfill()mock 不稳定第三方 API。 - 调试：用
page.on('request')和page.on('response')打印日志观察拦截效果。
网络拦截能让你完全掌控测试环境，避免外部依赖导致的 flaky 测试。下一步建议：实现一个完整的登录流程，使用网络拦截 mock 登录 API 并验证返回 token。
需要更复杂的场景（如文件下载拦截、GraphQL Mock、多环境切换），随时告诉我！
