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

Mock APIs

Введение​

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

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

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

// Перехват маршрута к API фруктов
await page.RouteAsync("*/**/api/v1/fruits", async route => {
  var json = new[] { new { name = "Strawberry", id = 21 } };
  // выполнить маршрут с мокированными данными
  await route.FulfillAsync(new()
  {
    Json = json
  });
});

// Перейти на страницу
await page.GotoAsync("https://demo.playwright.dev/api-mocking");

// Убедиться, что фрукт Strawberry виден
await Expect(page.GetByTextAsync("Strawberry")).ToBeVisibleAsync();

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

Подробнее о продвинутой работе с сетью.

Модификация ответов API​

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

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

await page.RouteAsync("*/**/api/v1/fruits", async (route) => {
    var response = await route.FetchAsync();
    var fruits = await response.JsonAsync<Fruit[]>();
    fruits.Add(new Fruit() { Name = "Loquat", Id = 100 });
    // Выполнить с использованием оригинального ответа, изменяя тело ответа
    // с данным JSON объектом.
    await route.FulfillAsync(new ()
    {
      Response = response,
      Json = fruits
    });
  }
);
// Перейти на страницу
await page.GotoAsync("https://demo.playwright.dev/api-mocking");

// Убедиться, что фрукт Loquat виден
await Expect(page.GetByTextAsync("Loquat", new () { Exact = true })).ToBeVisibleAsync();

В трассировке нашего теста видно, что API был вызван и ответ был изменен. трассировка теста, показывающая вызов и выполнение API

При проверке ответа видно, что наш новый фрукт был добавлен в список. трассировка теста, показывающая мокированный ответ

Подробнее о продвинутой работе с сетью.

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

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

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

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

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

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

// Получить ответ из HAR-файла
await page.RouteFromHARAsync("./hars/fruit.har", new () {
  Url = "*/**/api/v1/fruits",
  Update = true,
});

// Перейти на страницу
await page.GotoAsync("https://demo.playwright.dev/api-mocking");

// Убедиться, что фрукт виден
await Expect(page.GetByText("Strawberry")).ToBeVisibleAsync();

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

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

[
  {
    "name": "Playwright",
    "id": 100
  },
  // ... другие фрукты
]

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

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

// Воспроизведение API-запросов из HAR.
// Либо используйте соответствующий ответ из HAR,
// либо прервите запрос, если ничего не соответствует.
await page.RouteFromHARAsync("./hars/fruit.har", new ()
  {
    Url = "*/**/api/v1/fruits",
    Update = false,
  }
);

// Перейти на страницу
await page.GotoAsync("https://demo.playwright.dev/api-mocking");

// Убедиться, что фрукт Playwright виден
await page.ExpectByTextAsync("Playwright", new() { Exact = true }).ToBeVisibleAsync();

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

Если мы проверим ответ, мы увидим, что наш новый фрукт был добавлен в JSON, что было сделано путем ручного обновления хешированного .txt файла внутри папки hars. трассировка, показывающая ответ из HAR-файла

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

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

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

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

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

# Сохранить API-запросы с example.com как архив "example.har".
pwsh bin/Debug/netX/playwright.ps1 open --save-har=example.har --save-har-glob="**/api/**" https://example.com

Подробнее о продвинутой работе с сетью.

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

Следующий код перехватит соединения WebSocket и замокирует всю коммуникацию через WebSocket, вместо подключения к серверу. Этот пример отвечает на "request" с "response".

await page.RouteWebSocketAsync("wss://example.com/ws", ws => {
  ws.OnMessage(frame => {
    if (frame.Text == "request")
      ws.Send("response");
  });
});

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

await page.RouteWebSocketAsync("wss://example.com/ws", ws => {
  var server = ws.ConnectToServer();
  ws.OnMessage(frame => {
    if (frame.Text == "request")
      server.Send("request2");
    else
      server.Send(frame.Text);
  });
});

Для получения более подробной информации смотрите WebSocketRoute.