模拟 API

简介

Web 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 的调用，并将一个名为“Loquat”的新水果添加到数据中。然后，我们转到 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 归档 文件，其中包含页面加载时发出的所有网络请求的记录。它包含有关请求和响应标头、cookie、内容、计时等的信息。您可以使用 HAR 文件在测试中模拟网络请求。您需要

1. 记录 HAR 文件。
2. 将 HAR 文件与测试一起提交。
3. 在测试中使用保存的 HAR 文件路由请求。

记录 HAR 文件

要记录 HAR 文件，我们使用 page.routeFromHAR() 或 browserContext.routeFromHAR() 方法。此方法接受 HAR 文件的路径和一个可选的选项对象。选项对象可以包含 URL，以便仅从 HAR 文件中提供与指定通配符模式匹配的 URL 的请求。如果没有指定，则所有请求都将从 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”文件夹内的哈希 .txt 文件并编辑 JSON 来修改它。此文件应提交到您的源代码控制中。每当您使用 update: true 运行此测试时，它将使用 API 中的请求更新您的 HAR 文件。

[
  {
    "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 中，这是通过手动更新 hars 文件夹内的哈希 .txt 文件来完成的。

HAR 回放严格匹配 URL 和 HTTP 方法。对于 POST 请求，它还严格匹配 POST 负载。如果多个记录匹配一个请求，则选择匹配标头最多的那个。导致重定向的条目将自动跟随。

与记录类似，如果给定的 HAR 文件名以 .zip 结尾，则它被视为包含 HAR 文件以及作为单独条目存储的网络负载的归档文件。您也可以提取此归档文件，手动编辑负载或 HAR 日志，并指向提取的 har 文件。所有负载都将相对于文件系统上的提取的 har 文件解析。

使用 CLI 记录 HAR

我们建议使用 update 选项来记录您的测试的 HAR 文件。但是，您也可以使用 Playwright CLI 记录 HAR。

使用 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

阅读更多关于 高级网络 的内容。

模拟 WebSockets

以下代码将拦截 WebSocket 连接，并模拟整个 WebSocket 上的通信，而不是连接到服务器。此示例使用 "response" 响应 "request"。

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。