Запись и воспроизведение вызовов API в тестах Playwright, включая серверные запросы

Записать один раз.
Воспроизводить вечно.

Записывает ответы API, которые ваше приложение получает во время локального прогона Playwright, включая WebSocket, а затем воспроизводит их в CI с выключенным бэкендом.

npm i -D test-proxy-recorder Поставить звезду на GitHub

v2.1.0 · MIT · TypeScript · Node ≥ 20 · SSR в Next.js и TanStack Start, 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, вызовы из браузера через базовый URL API, общий с сервером, WebSocket), воспроизводится из файла .mock.json теста. Вызовы из браузера к другим хостам, которые совпадают с шаблоном url в вашей фикстуре, воспроизводятся из файла .har теста.

Прокси

.mock.json

Next.js / TanStack Start SSR → прокси → реальный API

Для full-stack-приложений, где сервер вызывает API.

Находится между вашим сервером и API. Записывает серверные запросы: fetch из Server Components и SSR, route handlers и всё, что вызывает ваш backend-for-frontend.

Серверные запросы каждого теста несут id этого теста, поэтому тесты, запущенные параллельно, никогда не делят одну запись.

HAR

.har

браузер → перехват HAR → реальный API

Для SPA, расширений и приложений только для браузера.

Перехватывает запросы в самом браузере и сохраняет файл HTTP Archive (HAR). Записывает клиентские fetch вызовы, трафик API расширений Chrome, аналитику и сторонние API — всё, что совпадает с шаблоном url в вашей фикстуре.

По сравнению с обычным routeFromHAR добавляет отдельный HAR на каждый тест и маскирует заголовки аутентификации.

Как выглядит запись

Один файл на тест
Каждый тест пишет собственный файл, названный по имени теста, поэтому npx playwright test -g "adds a todo" заново записывает только его. Тесты записываются на параллельных воркерах так же, как воспроизводятся, если только они не делят одну базу данных или один аккаунт.
Идентификатор теста
Playwright отправляет x-test-rcrd-id с каждым запросом, который делает тест, а registerProxyFetch() копирует его в собственные fetch-запросы вашего сервера. По нему прокси записывает каждый тест в его собственный файл и воспроизводит его оттуда, даже когда тесты идут параллельно.
Секреты
Заголовки Authorization, Cookie и Set-Cookie заменяются на [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. Полный файл также содержит GET, который шёл следом, все заголовки и метку времени для каждого запроса.

Где он уместен

Инструменты для моков хороши в разных задачах. Приведённая ниже комбинация — запись реального трафика через SSR, браузер и WebSocket без моков, написанных вручную, — это ниша, которую остальные оставляют незакрытой.

Сравнение возможностей test-proxy-recorder с routeFromHAR в Playwright, MSW, Polly.js, playwright-network-cache и Mocky Balboa.
Возможностьtest-proxy-recorderPlaywright routeFromHARMSWPolly.jsplaywright-network-cacheMocky Balboa
Запись реального трафикаДаДаНетДаДаНет
Серверная сторона (SSR)ДаНетДаЧастичноНетДа
Сторона браузераДаДаДаДаДаДа
WebSocketДаНетДаНетНетНет
Нативно для PlaywrightДаДаДаНетДаДа
ПоддерживаетсяДаДаДаНетДаДа

Polly.js записывает внутри того процесса, в котором запущен, поэтому для серверных запросов его нужно запускать внутри сервера вашего приложения. MSW и Mocky Balboa тоже мокают серверные запросы, но ответы вы пишете сами. Полное сравнение — с источниками и с тем, когда стоит выбрать другой инструмент, — приведено в документации.

Цена за это — более сложная первоначальная настройка, чем у инструментов, работающих только в браузере: рядом с тестами работает процесс прокси, а для серверных запросов базовый URL API вашего приложения на время тестовых прогонов указывает на него.

Работает с вашим реальным провайдером аутентификации

Входите через 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, процесс прокси (он работает только во время тестов) и записи, закоммиченные в git.
  • В приложении, только для серверных запросов: направьте базовый URL API на прокси на время тестовых прогонов и вызовите registerProxyFetch() один раз — в app/layout.tsx в Next.js или в src/router.tsx в TanStack Start. Этот вызов копирует id теста в каждый серверный fetch и ничего не делает в продакшене, если не задана переменная TEST_PROXY_RECORDER_ENABLED.
  • С промптом для агента: @tanstack/intent добавляет в конфигурационный файл вашего агента (например, CLAUDE.md) указания о том, как загружать навыки этой библиотеки.
  • Тестируете развёрнутое окружение? HAR записывает его вызовы из браузера без изменений в приложении, но сами страницы по-прежнему загружаются с того сервера. Чтобы воспроизводить ещё и серверные вызовы, запускайте приложение в CI рядом с прокси.

Вставьте это в Claude Code, Cursor или другого AI-кодинг-агента. Сначала агент запускает @tanstack/intent, который добавляет в конфигурационный файл агента (например, CLAUDE.md) указания, чтобы агент загружал навыки настройки этой библиотеки. Затем агент устанавливает пакет, находит 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 с указанием запроса и теста. Если вызов сделан больше раз, чем был записан, он снова получает последний ответ, а в логе прокси появляется предупреждение. В браузере Playwright прерывает запрос, которого нет в HAR, но который подходит под шаблон url из вызова before() в вашей фикстуре; остальные запросы уходят в сеть.
Когда воспроизведение обращается к реальному API?
Воспроизведение обращается к реальному API, только когда прокси выходит из режима воспроизведения, а режим у прокси один для всех запущенных тестов. Он выходит из этого режима через 120 секунд после старта последнего теста или когда хук для каждого теста вызывает teardown(). Если в CI бэкенд не запущен, такой вызов завершается ошибкой, а не проходит. Таймаут сессии и тередаун →
Что происходит, когда API меняется?
Если у вас типизированный клиент API, то после его обновления под изменённое поле воспроизводимые тесты, которые используют это поле, падают, потому что в записях всё ещё старое поле. Это указывает вам на изменение, а повторная запись исправляет тесты с меньшими усилиями, чем правка моков, написанных вручную.
Как тестировать ошибки и крайние случаи?
В браузере обработчик page.route() перекрывает запись, если зарегистрировать его после before() — а серверные ответы редактируются в файле .mock.json. Подмена ответа →

Хватит писать моки вручную

Ваш API уже даёт правильные ответы. Запишите их.

npm i -D test-proxy-recorder Поставить звезду на GitHub

Если это сэкономило вам полдня, звезда займёт одну секунду — именно так следующий человек найдёт проект, а соло-мейнтейнер поймёт, что нужно продолжать. Наткнулись на проблему или есть идея? Создайте issue или присоединяйтесь к Discord.