Мокирование API

Введение​

Веб-API обычно реализуются в виде HTTP-конечных точек. Playwright предоставляет API для мокирования и изменения сетевого трафика — как HTTP, так и HTTPS. Можно отслеживать, изменять и мокировать любые запросы, которые выполняет страница, включая запросы XHR и fetch. С помощью Playwright также можно выполнять мокирование на основе HAR-файлов, содержащих множество сетевых запросов, сделанных страницей.

Мокирование запросов API​

Следующий код перехватит все вызовы */**/api/v1/fruits и вместо них вернёт пользовательский ответ. Запросы к API выполняться не будут. Тест открывает URL, использующий мокируемый маршрут, и проверяет, что на странице присутствуют тестовые данные.

test("mocks a fruit and doesn't call api", async ({ page }) => {
  // Mock the api call before navigating
  await page.route('*/**/api/v1/fruits', async route => {
    const json = [{ name: 'Strawberry', id: 21 }];
    await route.fulfill({ json });
  });
  // Go to the page
  await page.goto('https://demo.playwright.dev/api-mocking');

  // Assert that the Strawberry fruit is visible
  await expect(page.getByText('Strawberry')).toBeVisible();
});

Из трассировки примера теста видно, что вызов API не выполнялся, но запросу был возвращён ответ с тестовыми данными.

Подробнее о расширенных возможностях работы с сетью.

Изменение ответов API​

Иногда необходимо выполнить запрос к API, но при этом изменить ответ, чтобы обеспечить воспроизводимость тестирования. В таком случае вместо мокирования запроса можно выполнить его и вернуть ответ в изменённом виде.

В приведённом ниже примере мы перехватываем вызов API фруктов и добавляем в данные новый фрукт — «локват». Затем открываем URL и проверяем, что эти данные присутствуют:

test('gets the json from api and adds a new fruit', async ({ page }) => {
  // Get the response and add to it
  await page.route('*/**/api/v1/fruits', async route => {
    const response = await route.fetch();
    const json = await response.json();
    json.push({ name: 'Loquat', id: 100 });
    // Fulfill using the original response, while patching the response body
    // with the given JSON object.
    await route.fulfill({ response, json });
  });

  // Go to the page
  await page.goto('https://demo.playwright.dev/api-mocking');

  // Assert that the new fruit is visible
  await expect(page.getByText('Loquat', { exact: true })).toBeVisible();
});

В трассировке теста видно, что вызов API был выполнен, а ответ изменён.

Изучив ответ, мы видим, что новый фрукт добавлен в список.

Подробнее о расширенных возможностях работы с сетью.

Мокирование с помощью HAR-файлов​

HAR-файл — это файл HTTP Archive, содержащий записи обо всех сетевых запросах, выполняемых при загрузке страницы. Он содержит сведения о заголовках запросов и ответов, файлах cookie, содержимом, времени выполнения и многом другом. HAR-файлы можно использовать для мокирования сетевых запросов в тестах. Для этого необходимо:

1. Записать HAR-файл.
2. Добавить HAR-файл в систему контроля версий вместе с тестами.
3. Настроить маршрутизацию запросов в тестах с помощью сохранённых HAR-файлов.

Запись HAR-файла​

Для записи HAR-файла используется метод page.routeFromHAR() или browserContext.routeFromHAR(). Метод принимает путь к HAR-файлу и необязательный объект параметров. В объекте параметров можно указать URL, чтобы из HAR-файла обслуживались только запросы, URL которых соответствует заданному шаблону glob. Если URL не указан, из HAR-файла будут обслуживаться все запросы.

Если установить параметр update в значение true, HAR-файл будет создан или обновлён с фактическими данными сети, а не будет использоваться для обслуживания запросов. Используйте этот параметр при создании теста, чтобы заполнить HAR реальными данными.

Кроме того, можно записывать HAR-файлы с помощью параметра recordHar метода browser.newContext() при создании контекста браузера. Это позволяет записывать весь сетевой трафик в контексте до его закрытия.

Изменение HAR-файла​

После записи HAR-файла его можно изменить: откройте хешированный файл .txt в папке 'hars' и отредактируйте JSON. Этот файл следует добавить в систему контроля версий. При каждом запуске этого теста с параметром update: true HAR-файл будет обновляться данными запроса из API.

[
  {
    "name": "Playwright",
    "id": 100
  },
  // ... other fruits
]

Воспроизведение из HAR​

Теперь, когда HAR-файл записан, а тестовые данные изменены, его можно использовать для предоставления соответствующих ответов в тесте. Для этого отключите или просто удалите параметр update. В этом случае тест будет выполняться на основе HAR-файла, а не обращаться к API.

test('gets the json from HAR and checks the new fruit has been added', async ({ page }) => {
  // Replay API requests from HAR.
  // Either use a matching response from the HAR,
  // or abort the request if nothing matches.
  await page.routeFromHAR('./hars/fruit.har', {
    url: '*/**/api/v1/fruits',
    update: false,
  });

  // Go to the page
  await page.goto('https://demo.playwright.dev/api-mocking');

  // Assert that the Playwright fruit is visible
  await expect(page.getByText('Playwright', { exact: true })).toBeVisible();
});

В трассировке теста видно, что ответ был получен из HAR-файла, а вызов API не выполнялся.

Изучив ответ, мы видим, что в JSON добавлен новый фрукт. Это было сделано вручную — путём обновления хешированного файла .txt в папке hars.

При воспроизведении HAR-файла URL и HTTP-метод сопоставляются строго. Для запросов POST также выполняется строгое сопоставление данных POST-запроса. Если запросу соответствуют несколько записей, выбирается запись с наибольшим количеством совпадающих заголовков. Запись, приводящая к перенаправлению, будет обработана автоматически.

Как и при записи, если имя HAR-файла заканчивается на .zip, он считается архивом, содержащим HAR-файл и сетевые данные, сохранённые в виде отдельных записей. Также можно распаковать этот архив, вручную отредактировать данные или журнал HAR и указать путь к распакованному HAR-файлу. Все данные будут найдены относительно расположения распакованного HAR-файла в файловой системе.

Запись HAR с помощью CLI​

Для записи HAR-файла теста мы рекомендуем использовать параметр update. Однако HAR-файл также можно записать с помощью CLI Playwright.

Откройте браузер с помощью CLI Playwright и укажите параметр --save-har, чтобы создать HAR-файл. При необходимости используйте --save-har-glob, чтобы сохранить только интересующие вас запросы, например запросы к конечным точкам API. Если имя HAR-файла заканчивается на .zip, артефакты записываются в отдельные файлы и сжимаются в один zip.

# Save API requests from example.com as "example.har" archive.
npx playwright open --save-har=example.har --save-har-glob="**/api/**" https://example.com

Подробнее о расширенных возможностях работы с сетью.

Мокирование WebSocket​

Следующий код перехватывает WebSocket-соединения и мокирует всё взаимодействие через WebSocket вместо подключения к серверу. В этом примере на "request" отправляется "response".

await page.routeWebSocket('wss://example.com/ws', ws => {
  ws.onMessage(message => {
    if (message === 'request')
      ws.send('response');
  });
});

Также можно подключиться к настоящему серверу, перехватывать сообщения между ним и страницей, а затем изменять или блокировать их. Ниже приведён пример, в котором некоторые сообщения, отправляемые страницей серверу, изменяются, а остальные остаются без изменений.

await page.routeWebSocket('wss://example.com/ws', ws => {
  const server = ws.connectToServer();
  ws.onMessage(message => {
    if (message === 'request')
      server.send('request2');
    else
      server.send(message);
  });
});

Подробнее см. в документации по WebSocketRoute.