Перейти к содержимому

Как работают запись и воспроизведение: прокси для SSR, HAR для браузера

test-proxy-recorder поддерживает два механизма записи в зависимости от того, откуда исходят ваши запросы. Оба можно использовать вместе или независимо.

МеханизмЧто записываетСценарий использования
Прокси (.mock.json)Серверные запросы (SSR-фетчи из Next.js и т. п.)Full-stack приложения, где сервер вызывает API
HAR (.har)Запросы на стороне браузера (браузерный fetch, расширения, SPA)SPA, расширения Chrome, сторонние API
Server-side (proxy) Browser-side (HAR)
Next.js SSR ──> Proxy ──> Real API Browser ──> HAR intercept ──> Real API
│ │
└──> .mock.json └──> .har

Каждый тест при старте задаёт режим своей сессии, а каждый запрос несёт id своего теста в заголовке x-test-rcrd-id, поэтому у тестов, выполняющихся одновременно, у каждого свой режим и свой файл. В режиме record прокси пересылает запросы на реальный бэкенд и сохраняет ответы в файл этого теста; в режиме replay он отдаёт сохранённые ответы с диска, из записи этого теста; в режиме transparent пересылает без записи. Версии до 2.0.1 включительно держали одну сессию записи на все запросы, поэтому прогон записи на них требует одного воркера. Прокси запускается в режиме transparent, поэтому приложение, запущенное через него вне тестов, обращается к своему бэкенду как обычно. О том, как переключаются режимы, см. эндпоинт управления.

Как воспроизведение сопоставляет запросы

Заголовок раздела «Как воспроизведение сопоставляет запросы»

Прокси и файл HAR ищут записанный ответ по-разному.

При воспроизведенииПрокси (.mock.json)HAR (.har)
Что сопоставляетсяМетод, путь, MD5-хеш строки запроса и тело запроса, причём граница multipart не учитывается. GET и HEAD сопоставляются без тела. Заголовки не сравниваются.Метод, URL и тело, затем элементы с наибольшим числом общих заголовков запроса, так как одинаковые URL и тело могут означать разные операции, которые различаются по заголовку. Если такого тела нет ни в одном элементе, сопоставление идёт по методу и URL, а граница multipart (boundary) не учитывается.
Тот же запрос повторноСледующая запись с тем же телом, в порядке записи.Следующая запись, в порядке записи, с одним правилом для изменяющих запросов (см. ниже).
Записи нет404 с телом JSON, в котором указан запрос, а playwrightProxy.before() закрывает страницу, так что тест сразу падает (failOnMissingRecording: false это отключает).Запрос прерывается, и в лог пишется [Client-Side Replay] No recorded response for <method> <url>.
Обращение к реальному APIТолько в режиме transparent.Только у запросов, которые не совпадают с url.

Ключ состоит из метода, пути и первых 16 шестнадцатеричных символов MD5-хеша строки запроса. У GET /todos?page=2 ключ GET_todos_46589c7afd19c014.json, поэтому строка запроса, которая хоть чем-то отличается, даже порядком параметров, даёт другой ключ.

Затем вызовы с одинаковым ключом сопоставляются по телу запроса, поэтому вызовы, отправленные параллельно, которые на каждом прогоне приходят к прокси в другом порядке, всё равно получают свои ответы. Перед сравнением прокси применяет к обоим телам своё маскирование тела (bodyPatterns) и убирает границу multipart, так что замаскированный секрет или граница, которая меняется от запроса к запросу, не мешают совпадению. Вызовы GET и HEAD сопоставляются только по ключу.

Вызов, тела которого нет ни в одной записи, обрабатывается как запрос без записи (см. ниже), и в причине указано тело: No recording for POST /embeddings with this request body in session <id> (2 recorded with other bodies). Прокси никогда не отвечает на него записью, сделанной для другого тела, потому что это скрыло бы изменение в том, что отправило приложение. Держите тела одинаковыми между прогонами: текущая дата или случайный id в теле ломают воспроизведение.

Вызовы с одинаковыми ключом и телом обслуживаются в том порядке, в котором были записаны. Вызов сверх последней записи с его телом снова получает ответ этой записи, а прокси пишет в лог [REPLAY WARNING] All N recordings matching this request already served for <key> (session: <id>), reusing last one, где N — число записей с этим телом.

Запрос без записи не доходит до реального API. Прокси пишет в лог строки [REPLAY ERROR] и отвечает 404:

{
"error": "No recording found",
"message": "No recording found for GET_todos_46589c7afd19c014.json at GET localhost:8100/todos?page=2",
"key": "GET_todos_46589c7afd19c014.json",
"sessionId": "todos__shows-the-list"
}

Прокси отправляет запросы на реальный бэкенд только в режиме transparent. Прогон воспроизведения попадает туда двумя путями: playwrightProxy.teardown() выполняется, пока тесты ещё идут, или таймаут сессии (по умолчанию 120000 мс) истекает до следующего вызова playwrightProxy.before(). Оба случая разобраны в FAQ.

Если вы передаёте url, playwrightProxy.before() записывает подходящие запросы браузера средствами записи HAR в Playwright:

await page.routeFromHAR(harPath, { url, update: true, updateContent: 'embed' });

Воспроизведение выполняет собственный обработчик библиотеки на page.route(), который читает этот файл, а не page.routeFromHAR(). Воспроизведение Playwright на каждый повтор запроса отдаёт первый подходящий элемент HAR (microsoft/playwright#18288), поэтому GET после POST показывал список в состоянии до POST. Обработчик библиотеки вместо этого отдаёт каждую запись один раз, в порядке записи, и повторно использует запись, только когда страница запрашивает чаще, чем при записи. Порядок читающих запросов относительно изменяющих задаёт одно правило. После того как воспроизведён изменяющий запрос к пути (любой метод, кроме GET, HEAD и OPTIONS, так что сюда попадает и GraphQL-запрос типа query), читающий запрос к этому пути или к вложенному в него пути предпочитает копии, записанные после изменяющего запроса. Если для читающего запроса не осталось копий до следующего такого изменяющего запроса, повторно используется последняя копия перед этим изменяющим запросом. Это правило сохраняет воспроизведение верным, когда приложение читает данные другое число раз, чем при записи, — например, при двойном запросе в строгом режиме React (strict mode). Записанный редирект отрабатывается внутри .har, потому что последующий запрос браузера никогда не доходит до page.route(): fetch получает конечный ответ, а навигация отправляется дальше, на цель редиректа.

Запрос, который совпадает с url, но отсутствует в .har, прерывается. Запросы, не совпадающие с url, не перехватываются, а в режиме transparent не перехватывается ни один запрос. Они уходят в реальную сеть.

Исключение — запросы к самому прокси (localhost:8100). before() регистрирует для них собственный обработчик после обработчика HAR, а Playwright первым запускает обработчик, зарегистрированный позже. Этот обработчик передаёт их прокси, который воспроизводит их из .mock.json, как и серверные запросы.