API 测试

介绍

¥Introduction

Playwright 可用于访问应用的 REST API。

¥Playwright can be used to get access to the REST API of your application.

有时你可能希望直接从 Python 向服务器发送请求，而无需加载页面并在其中运行 JS 代码。一些它可能派上用场的例子：

¥Sometimes you may want to send requests to the server directly from Python without loading a page and running js code in it. A few examples where it may come in handy:

测试你的服务器 API。

¥Test your server API.
在测试中访问 Web 应用之前准备服务器端状态。

¥Prepare server side state before visiting the web application in a test.
在浏览器中运行某些操作后验证服务器端后置条件。

¥Validate server side post-conditions after running some actions in the browser.

所有这些都可以通过 APIRequestContext 方法来实现。

¥All of that could be achieved via APIRequestContext methods.

以下示例依赖于 pytest-playwright 包，该包将 Playwright Fixture 添加到 Pytest 测试运行器中。

¥The following examples rely on the pytest-playwright package which add Playwright fixtures to the Pytest test-runner.

编写 API 测试

¥Writing API Test

APIRequestContext 可以通过网络发送各种 HTTP(S)请求。

¥APIRequestContext can send all kinds of HTTP(S) requests over network.

以下示例演示如何使用 Playwright 通过 GitHub API 测试问题创建。测试套件将执行以下操作：

¥The following example demonstrates how to use Playwright to test issues creation via GitHub API. The test suite will do the following:

在运行测试之前创建一个新的存储库。

¥Create a new repository before running tests.
创建一些问题并验证服务器状态。

¥Create a few issues and validate server state.
运行测试后删除存储库。

¥Delete the repository after running tests.

配置

¥Configure

GitHub API 需要授权，因此我们将为所有测试配置一次令牌。同时，我们还将设置 baseURL 以简化测试。

¥GitHub API requires authorization, so we'll configure the token once for all tests. While at it, we'll also set the baseURL to simplify the tests.

import os
from typing import Generator

import pytest
from playwright.sync_api import Playwright, APIRequestContext

GITHUB_API_TOKEN = os.getenv("GITHUB_API_TOKEN")
assert GITHUB_API_TOKEN, "GITHUB_API_TOKEN is not set"


@pytest.fixture(scope="session")
def api_request_context(
    playwright: Playwright,
) -> Generator[APIRequestContext, None, None]:
    headers = {
        # We set this header per GitHub guidelines.
        "Accept": "application/vnd.github.v3+json",
        # Add authorization token to all requests.
        # Assuming personal access token available in the environment.
        "Authorization": f"token {GITHUB_API_TOKEN}",
    }
    request_context = playwright.request.new_context(
        base_url="https://api.github.com", extra_http_headers=headers
    )
    yield request_context
    request_context.dispose()

编写测试

¥Write tests

现在我们初始化了请求对象，可以添加一些将在存储库中创建新问题的测试。

¥Now that we initialized request object we can add a few tests that will create new issues in the repository.

import os
from typing import Generator

import pytest
from playwright.sync_api import Playwright, APIRequestContext

GITHUB_API_TOKEN = os.getenv("GITHUB_API_TOKEN")
assert GITHUB_API_TOKEN, "GITHUB_API_TOKEN is not set"

GITHUB_USER = os.getenv("GITHUB_USER")
assert GITHUB_USER, "GITHUB_USER is not set"

GITHUB_REPO = "test"

# ...

def test_should_create_bug_report(api_request_context: APIRequestContext) -> None:
    data = {
        "title": "[Bug] report 1",
        "body": "Bug description",
    }
    new_issue = api_request_context.post(f"/repos/{GITHUB_USER}/{GITHUB_REPO}/issues", data=data)
    assert new_issue.ok

    issues = api_request_context.get(f"/repos/{GITHUB_USER}/{GITHUB_REPO}/issues")
    assert issues.ok
    issues_response = issues.json()
    issue = list(filter(lambda issue: issue["title"] == "[Bug] report 1", issues_response))[0]
    assert issue
    assert issue["body"] == "Bug description"

def test_should_create_feature_request(api_request_context: APIRequestContext) -> None:
    data = {
        "title": "[Feature] request 1",
        "body": "Feature description",
    }
    new_issue = api_request_context.post(f"/repos/{GITHUB_USER}/{GITHUB_REPO}/issues", data=data)
    assert new_issue.ok

    issues = api_request_context.get(f"/repos/{GITHUB_USER}/{GITHUB_REPO}/issues")
    assert issues.ok
    issues_response = issues.json()
    issue = list(filter(lambda issue: issue["title"] == "[Feature] request 1", issues_response))[0]
    assert issue
    assert issue["body"] == "Feature description"

设置和拆卸

¥Setup and teardown

这些测试假设存储库存在。你可能想在运行测试之前创建一个新的测试，然后将其删除。为此使用会话夹具。yield 之前的部分是所有事件之前，之后的部分是所有事件之后。

¥These tests assume that repository exists. You probably want to create a new one before running tests and delete it afterwards. Use a session fixture for that. The part before yield is the before all and after is the after all.

# ...
@pytest.fixture(scope="session", autouse=True)
def create_test_repository(
    api_request_context: APIRequestContext,
) -> Generator[None, None, None]:
    # Before all
    new_repo = api_request_context.post("/user/repos", data={"name": GITHUB_REPO})
    assert new_repo.ok
    yield
    # After all
    deleted_repo = api_request_context.delete(f"/repos/{GITHUB_USER}/{GITHUB_REPO}")
    assert deleted_repo.ok

完整测试示例

¥Complete test example

以下是一个完整的 API 测试示例：

¥Here is the complete example of an API test:

from enum import auto
import os
from typing import Generator

import pytest
from playwright.sync_api import Playwright, Page, APIRequestContext, expect

GITHUB_API_TOKEN = os.getenv("GITHUB_API_TOKEN")
assert GITHUB_API_TOKEN, "GITHUB_API_TOKEN is not set"

GITHUB_USER = os.getenv("GITHUB_USER")
assert GITHUB_USER, "GITHUB_USER is not set"

GITHUB_REPO = "test"


@pytest.fixture(scope="session")
def api_request_context(
    playwright: Playwright,
) -> Generator[APIRequestContext, None, None]:
    headers = {
        # We set this header per GitHub guidelines.
        "Accept": "application/vnd.github.v3+json",
        # Add authorization token to all requests.
        # Assuming personal access token available in the environment.
        "Authorization": f"token {GITHUB_API_TOKEN}",
    }
    request_context = playwright.request.new_context(
        base_url="https://api.github.com", extra_http_headers=headers
    )
    yield request_context
    request_context.dispose()


@pytest.fixture(scope="session", autouse=True)
def create_test_repository(
    api_request_context: APIRequestContext,
) -> Generator[None, None, None]:
    # Before all
    new_repo = api_request_context.post("/user/repos", data={"name": GITHUB_REPO})
    assert new_repo.ok
    yield
    # After all
    deleted_repo = api_request_context.delete(f"/repos/{GITHUB_USER}/{GITHUB_REPO}")
    assert deleted_repo.ok


def test_should_create_bug_report(api_request_context: APIRequestContext) -> None:
    data = {
        "title": "[Bug] report 1",
        "body": "Bug description",
    }
    new_issue = api_request_context.post(
        f"/repos/{GITHUB_USER}/{GITHUB_REPO}/issues", data=data
    )
    assert new_issue.ok

    issues = api_request_context.get(f"/repos/{GITHUB_USER}/{GITHUB_REPO}/issues")
    assert issues.ok
    issues_response = issues.json()
    issue = list(
        filter(lambda issue: issue["title"] == "[Bug] report 1", issues_response)
    )[0]
    assert issue
    assert issue["body"] == "Bug description"


def test_should_create_feature_request(api_request_context: APIRequestContext) -> None:
    data = {
        "title": "[Feature] request 1",
        "body": "Feature description",
    }
    new_issue = api_request_context.post(
        f"/repos/{GITHUB_USER}/{GITHUB_REPO}/issues", data=data
    )
    assert new_issue.ok

    issues = api_request_context.get(f"/repos/{GITHUB_USER}/{GITHUB_REPO}/issues")
    assert issues.ok
    issues_response = issues.json()
    issue = list(
        filter(lambda issue: issue["title"] == "[Feature] request 1", issues_response)
    )[0]
    assert issue
    assert issue["body"] == "Feature description"

通过 API 调用准备服务器状态

¥Prepare server state via API calls

以下测试通过 API 创建一个新问题，然后导航到项目中所有问题的列表以检查它是否出现在列表顶部。检查使用 LocatorAssertions 执行。

¥The following test creates a new issue via API and then navigates to the list of all issues in the project to check that it appears at the top of the list. The check is performed using LocatorAssertions.

def test_last_created_issue_should_be_first_in_the_list(api_request_context: APIRequestContext, page: Page) -> None:
    def create_issue(title: str) -> None:
        data = {
            "title": title,
            "body": "Feature description",
        }
        new_issue = api_request_context.post(
            f"/repos/{GITHUB_USER}/{GITHUB_REPO}/issues", data=data
        )
        assert new_issue.ok
    create_issue("[Feature] request 1")
    create_issue("[Feature] request 2")
    page.goto(f"https://github.com/{GITHUB_USER}/{GITHUB_REPO}/issues")
    first_issue = page.locator("a[data-hovercard-type='issue']").first
    expect(first_issue).to_have_text("[Feature] request 2")

¥Check the server state after running user actions

以下测试通过浏览器中的用户界面创建一个新问题，然后通过 API 检查该问题是否已创建：

¥The following test creates a new issue via user interface in the browser and then checks via API if it was created:

def test_last_created_issue_should_be_on_the_server(api_request_context: APIRequestContext, page: Page) -> None:
    page.goto(f"https://github.com/{GITHUB_USER}/{GITHUB_REPO}/issues")
    page.locator("text=New issue").click()
    page.locator("[aria-label='Title']").fill("Bug report 1")
    page.locator("[aria-label='Comment body']").fill("Bug description")
    page.locator("text=Submit new issue").click()
    issue_id = page.url.split("/")[-1]

    new_issue = api_request_context.get(f"https://github.com/{GITHUB_USER}/{GITHUB_REPO}/issues/{issue_id}")
    assert new_issue.ok
    assert new_issue.json()["title"] == "[Bug] report 1"
    assert new_issue.json()["body"] == "Bug description"

重用身份验证状态

¥Reuse authentication state

Web 应用使用基于 cookie 或基于令牌的身份验证，其中经过身份验证的状态存储为 cookies。Playwright 提供了 api_request_context.storage_state() 方法，可用于从经过身份验证的上下文中检索存储状态，然后使用该状态创建新的上下文。

¥Web apps use cookie-based or token-based authentication, where authenticated state is stored as cookies. Playwright provides api_request_context.storage_state() method that can be used to retrieve storage state from an authenticated context and then create new contexts with that state.

存储状态可以在 BrowserContext 和 APIRequestContext 之间互换。你可以使用它通过 API 调用登录，然后创建一个已存在 cookie 的新上下文。以下代码片段从经过身份验证的 APIRequestContext 检索状态，并使用该状态创建一个新的 BrowserContext。

¥Storage state is interchangeable between BrowserContext and APIRequestContext. You can use it to log in via API calls and then create a new context with cookies already there. The following code snippet retrieves state from an authenticated APIRequestContext and creates a new BrowserContext with that state.

request_context = playwright.request.new_context(http_credentials={"username": "test", "password": "test"})
request_context.get("https://api.example.com/login")
# Save storage state into a variable.
state = request_context.storage_state()

# Create a new context with the saved storage state.
context = browser.new_context(storage_state=state)

介绍​

编写 API 测试​

配置​

编写测试​

设置和拆卸​

完整测试示例​

通过 API 调用准备服务器状态​

运行用户操作后检查服务器状态​

重用身份验证状态​

介绍