Моделирование API

Введение​

Веб-API обычно реализуются в виде конечных точек HTTP. Playwright предоставляет API для моделирования и модификации сетевого трафика, как HTTP, так и HTTPS. Любые запросы, которые выполняет страница, включая XHR и fetch-запросы, могут отслеживаться, модифицироваться и моделироваться. С помощью Playwright вы также можете моделировать API, используя файлы 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, который содержит запись всех сетевых запросов, выполняемых при загрузке страницы. Он содержит информацию о заголовках запроса и ответа, куки, содержимом, времени и многом другом. Вы можете использовать файлы HAR для моделирования сетевых запросов в ваших тестах. Вам нужно:

1. Записать файл HAR.
2. Включить файл HAR вместе с тестами.
3. Направить запросы, используя сохраненные файлы HAR в тестах.

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

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

Установка параметра update в значение true создаст или обновит файл HAR с фактической сетевой информацией вместо обработки запросов из файла HAR. Используйте его при создании теста для заполнения HAR реальными данными.

test('records or updates the HAR file', async ({ page }) => {
  // Get the response from the HAR file
  await page.routeFromHAR('./hars/fruit.har', {
    url: '*/**/api/v1/fruits',
    update: true,
  });

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

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

Модификация файла HAR​

После записи файла HAR вы можете его изменить, открыв зашифрованный текстовый файл внутри папки «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​

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

Откройте браузер с помощью Playwright CLI и передайте опцию --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.