在 Playwright 测试中录制与回放 API 调用,包括服务端请求

录制一次。
永久回放。

录制本地 Playwright 运行期间你的应用收到的 API 响应(包括 WebSocket),随后在 CI 上回放,后端保持关闭。

npm i -D test-proxy-recorder 在 GitHub 上加星

v2.1.0 · MIT · TypeScript · Node ≥ 20 · Next.js 与 TanStack Start SSR、SPA、Chrome 扩展、WebSocket

REC · MODE=record · local run

saved todos__adds-a-todo.mock.json

REPLAY · MODE=replay · CI

200 OK · 3 ms · from disk

看它录制,再回放

一次 Playwright 运行把真实响应录制到磁盘;翻转到回放,同一套件在后端关闭的情况下通过。

两种录制方式

请求从两个地方发出,所以有两种录制方式,并且两种方式下代理进程都会运行。发往代理的一切请求(服务端 fetch、经由与服务器共用的 API 基础 URL 发出的浏览器调用、WebSocket)都从该测试的 .mock.json 回放。发往其他主机、且匹配你的 fixture 中 url 模式的浏览器调用,则从该测试的 .har 回放。

代理

.mock.json

Next.js / TanStack Start SSR → 代理 → 真实 API

适用于服务器调用 API 的全栈应用。

位于你的服务器与 API 之间。录制服务端请求:Server Component 和 SSR 发出的 fetch、route handler,以及你的 backend-for-frontend 所调用的任何内容。

每个测试的服务端请求都带有该测试的 id,因此并行运行的测试绝不会共用同一份录制。

HAR

.har

浏览器 → HAR 拦截 → 真实 API

适用于 SPA、扩展和纯浏览器应用。

在浏览器内部进行拦截,并保存一个 HTTP Archive(HAR)文件。录制客户端 fetch 调用、Chrome 扩展 API 流量、分析数据和第三方 API,只要它们匹配你的 fixture 中的 url 模式。

与直接使用 routeFromHAR 相比,它为每个测试单独生成一个 HAR,并涂抹认证 header。

录制文件是什么样的

每个测试一个文件
每个测试都写入自己的文件,并以测试名命名,因此 npx playwright test -g "adds a todo" 只会重新录制这一个测试。测试在并行 worker 上录制,就像回放时一样,除非它们共用同一个数据库或账号。
测试的 id
Playwright 会在测试发出的每个请求上附带 x-test-rcrd-id header,而 registerProxyFetch() 会把它复制到你的服务器自己发出的 fetch 上。代理读取这个 id,把每个测试录制到它自己的文件中,并从该文件回放,即使测试并行运行也是如此。
机密
Authorization、Cookie 和 Set-Cookie header 的值会变成 [REDACTED]:.mock.json 文件在写入之前就已替换,.har 文件则在运行结束时替换。响应体中的机密需要你自己添加匹配模式。 机密涂抹 →
e2e/recordings/todos__adds-a-todo.mock.json
{
"id": "todos__adds-a-todo",
"recordings": [
{
"request": {
"method": "POST",
"url": "/todos",
"headers": {
"authorization": "[REDACTED]",
"x-test-rcrd-id": "todos__adds-a-todo"
},
"body": "{\"title\":\"Buy groceries\"}"
},
"response": {
"statusCode": 201,
"body": "{\"id\":7,\"title\":\"Buy groceries\",\"done\":false}"
},
"key": "POST_todos.json",
"sequence": 0
}
]
}
一份真实录制的片段(完整文件 2.6 KB):某个测试发出的 POST 请求,其 Authorization header 已被涂抹。完整文件还包含随后的 GET 请求、全部 header,以及每个请求的时间戳。

它适合什么场景

不同的 mock 工具擅长不同的工作。下面的组合 —— 跨 SSR、浏览器和 WebSocket 录制真实流量,且不手写 mock —— 正是其他工具留下的空白。

test-proxy-recorder 与 Playwright routeFromHAR、MSW、Polly.js、playwright-network-cache 和 Mocky Balboa 的特性对比。
特性test-proxy-recorderPlaywright routeFromHARMSWPolly.jsplaywright-network-cacheMocky Balboa
录制真实流量是是否是是否
服务端(SSR)是否是部分否是
浏览器端是是是是是是
WebSocket是否是否否否
Playwright 原生是是是否是是
维护中是是是否是是

Polly.js 在它所运行的进程内部录制,所以对于服务端请求,它必须运行在你的应用服务器内部。MSW 和 Mocky Balboa 也能 mock 服务端请求,但响应要你自己编写。完整的对比(附来源,以及何时该选用其他工具)见 文档。

代价是首次搭建比纯浏览器端的工具更费事:需要在测试旁运行一个代理进程;对于服务端请求,测试运行期间还要把应用的 API 基础 URL 指向它。

与你的真实认证提供方配合工作

通过 Cognito、Auth0、Clerk 或 WorkOS 登录 —— 每次运行都真实进行。只有你应用的 API 会被录制;认证保持在线,你的数据离线处理。

// e2e/auth.setup.ts — log in for real, once. Never recorded.
import { test as setup } from '@playwright/test';
import { setProxyMode } from 'test-proxy-recorder';
setup('authenticate', async ({ page }) => {
await setProxyMode('transparent'); // login bypasses the recorder
await page.goto('/login');
await page.getByTestId('email').fill(process.env.TEST_EMAIL!);
await page.getByTestId('password').fill(process.env.TEST_PASSWORD!);
await page.getByTestId('signinButton').click();
await page.waitForURL('/dashboard');
// Reused by every test — they start already signed in.
await page.context().storageState({ path: 'e2e/.auth/state.json' });
});

快速开始

用一条命令脚手架生成所有内容,把 API 指向代理,然后录制并提交。纯浏览器应用? init 会替你跳过 SSR 步骤。

你的仓库会有哪些变化

  • 在你的测试套件中:一个 Playwright fixture、代理进程(只在测试期间运行),以及提交到 git 的录制文件。
  • 在你的应用中(仅限服务端请求):测试运行期间把 API 基础 URL 指向代理,并在 Next.js 的 app/layout.tsx 或 TanStack Start 的 src/router.tsx 中调用一次 registerProxyFetch() 函数。它会把测试的 id 复制到每个服务端 fetch 上;除非设置了 TEST_PROXY_RECORDER_ENABLED,否则它在生产环境中什么也不做。
  • 使用 agent 提示词时:@tanstack/intent 会在 agent 的配置文件(例如 CLAUDE.md)中加入加载本库技能的指引。
  • 测试的是已部署的环境?HAR 无需改动应用就能录制其浏览器调用,但页面本身仍从那台服务器加载。若还要回放服务端调用,请在 CI 中把应用和代理放在一起运行。

把它粘贴到 Claude Code、Cursor 或其他编码 agent 中。它会先运行 @tanstack/intent,在 agent 的配置文件(例如 CLAUDE.md)中加入指引,让 agent 加载本库的设置技能。然后它会安装这个包,从应用的配置中找到你的后端 URL,运行 init 并根据它的输出完成剩下的接入工作。

Set up test-proxy-recorder for end-to-end tests in this project, then follow the instructions that `init` prints. Run these commands:
npx @tanstack/intent@latest install
npm install --save-dev test-proxy-recorder
Then run init, passing this project's backend API base URL as the target — find it yourself from the app's env/config (the URL the app calls in dev); don't assume the default:
npx test-proxy-recorder init <your-backend-api-url> --port 8100 --dir ./e2e/recordings
Then complete the app-specific steps init prints: point the app's API base URL at the proxy in dev/test only, tag server-side fetches (Next.js), add a smoke test, and verify record → replay.

完整设置指南 →

关于回放的问题

请求如何匹配?
代理按方法、路径、完全一致的查询字符串和请求体匹配服务端调用,因此并行发送的调用各自得到自己的响应;重复的调用按录制顺序依次应答。浏览器调用同样按方法、URL 和请求体匹配。每次运行都会变化的查询字符串或请求体(例如时间戳)永远无法匹配,而且没有任何选项可以忽略某个值,所以测试期间请让这类值保持固定。 回放如何匹配请求 →
缺少录制时会怎样?
代理会返回 404,并指明是哪个请求、哪个测试。某个调用的次数超过录制的次数时,会再次得到最后一个响应,同时代理日志中会出现一条警告。在浏览器中,如果某个调用匹配 url 模式(即你的 fixture 传给 before() 的模式),但不在 HAR 中,Playwright 会中止它;其他调用则会发往网络。
回放何时会访问真实 API?
只有在代理离开回放模式之后,回放才会访问真实 API,而代理对所有正在运行的测试只保持一种模式。代理在两种情况下离开回放模式:最后一个测试启动 120 秒后,或者测试中的某个钩子调用了 teardown()。CI 中没有运行后端时,这样的调用会失败,而不是通过。 会话超时与 teardown →
API 变化时会怎样?
如果使用带类型的 API 客户端,为某个变化的字段更新客户端后,用到该字段的回放测试会失败,因为录制中仍是旧字段。这会指出变化所在,而重新录制即可修复这些测试,比修改手写 mock 省力。
如何测试错误和边界情况?
在浏览器中,用 page.route() 在 before() 之后注册的路由处理函数会覆盖录制。服务端响应则在 .mock.json 文件中编辑。 强制指定响应 →

停止手写 mock

你的 API 已经给出正确答案。把它们录制下来。

npm i -D test-proxy-recorder 在 GitHub 上加星

如果它帮你省下了一个下午,点一颗 star 只要一秒钟 —— 这就是下一个人找到它的方式,也是在告诉一个独自维护的人继续做下去。遇到卡壳或有想法? 提交 issue 或 加入 Discord。