Skip to main content

APIRequestContext

此 API 用于 Web 接口测试，可用于触发服务端接口、配置微服务、为端到端测试准备环境或服务。

每个 Playwright 浏览器上下文都会关联一个 APIRequestContext 实例（可通过 browser_context.request 或 page.request 获取），它与浏览器上下文共享 cookie 存储。也可以通过 api_request.new_context(**kwargs) 手动创建新的 APIRequestContext。

Cookie 管理

通过 browser_context.request 和 page.request 获取的 APIRequestContext 与其所属 BrowserContext 共享 cookie 存储。每个 API 请求都会自动携带浏览器上下文中的 Cookie 头；若 API 响应包含 Set-Cookie 头，则会回写到 BrowserContext，页面发出的请求也会使用这些 cookie。也就是说，如果通过该 API 完成登录，端到端测试中的页面同样处于登录状态，反之亦然。

若希望 API 请求与浏览器 cookie 相互隔离，请调用 api_request.new_context(**kwargs) 创建新的 APIRequestContext，它拥有独立的 cookie 存储。

import os
from playwright.sync_api import sync_playwright

REPO = "test-repo-1"
USER = "github-username"
API_TOKEN = os.getenv("GITHUB_API_TOKEN")

with sync_playwright() as playwright:
    # 启动浏览器、创建上下文与页面。使用 context.request / page.request 发起的 HTTP
    # 请求会在浏览器页面与 APIRequestContext 之间自动同步 Cookie。
    browser = playwright.chromium.launch()
    context = browser.new_context(base_url="https://api.github.com")
    api_request_context = context.request
    page = context.new_page()

    # 也可以直接创建独立的 APIRequestContext（不依赖浏览器上下文）：
    # api_request_context = playwright.request.new_context(base_url="https://api.github.com")

    # 创建仓库。
    response = api_request_context.post(
        "/user/repos",
        headers={
            "Accept": "application/vnd.github.v3+json",
            "Authorization": f"token {API_TOKEN}",  # GitHub 个人访问令牌
        },
        data={"name": REPO},
    )
    assert response.ok
    assert response.json()["name"] == REPO

    # 删除仓库。
    response = api_request_context.delete(
        f"/repos/{USER}/{REPO}",
        headers={
            "Accept": "application/vnd.github.v3+json",
            "Authorization": f"token {API_TOKEN}",
        },
    )
    assert response.ok
    assert response.body() == '{"status": "ok"}'

api_request_context.delete(url, **kwargs)​

Added in: v1.16
  • url <str> 目标 URL。#
  • data <str|bytes|Serializable> 请求正文。如果传入对象，会序列化为 JSON，并在未显式设置时自动添加 application/json 的 content-type；其它类型则默认使用 application/octet-stream。Added in: v1.17#
  • fail_on_status_code <bool> 非 2xx/3xx 状态码是否抛错，默认所有状态码都返回响应对象。#
  • form <Dict[str, str|float|bool]> 以 application/x-www-form-urlencoded 编码发送表单，并在未显式设置时自动补全对应 content-type。Added in: v1.17#
  • headers <Dict[str, str]> 自定义 HTTP 头。#
  • ignore_https_errors <bool> 发送请求时是否忽略 HTTPS 错误，默认 false。#
  • max_redirects <int> 自动跟随的最大重定向次数，超出将抛错。默认 20，传 0 表示不自动跟随。Added in: v1.26#
  • multipart <Dict[str, str|float|bool|[ReadStream]|Dict]> 以 multipart/form-data 编码发送表单；未显式指定时自动设置 content-type。可通过 fs.ReadStream 或包含文件名、mime-type、内容的对象传递文件。Added in: v1.17#
    • name <str> 文件名
    • mimeType <str> 文件类型
    • buffer <bytes> 文件内容
  • params <Dict[str, str|float|bool]> URL 查询参数。#
  • timeout <float> 请求超时时间（毫秒），默认 30000；传 0 关闭超时。#
  • 返回值: <APIResponse>#

发送 HTTP(S) DELETE 请求并返回响应。请求会自动从上下文获取 cookie，并将响应中的 cookie 回写到上下文，同时自动跟随重定向。

api_request_context.dispose()​

Added in: v1.16

api_request_context.get(url, **kwargs) 等方法返回的响应会缓存在内存中，以便后续调用 api_response.body()。调用本方法会清空所有缓存，并使得后续的 api_response.body() 抛出 “Response disposed” 错误。

api_request_context.fetch(url_or_request, **kwargs)​

Added in: v1.16
  • url_or_request <str|Request> 目标 URL，或用于继承参数的 Request 对象。#
  • data <str|bytes|Serializable> 请求正文，若传入对象将序列化为 JSON，默认补充 application/json 的 content-type；其他类型默认 application/octet-stream。#
  • fail_on_status_code <bool> 非 2xx/3xx 状态码是否抛错，默认所有状态码都返回响应对象。#
  • form <Dict[str, str|float|bool]> 以 application/x-www-form-urlencoded 编码发送表单，并在未显式指定时自动设置 content-type。#
  • headers <Dict[str, str]> 自定义 HTTP 头。#
  • ignore_https_errors <bool> 是否忽略 HTTPS 错误，默认 false。#
  • max_redirects <int> 自动跟随的最大重定向次数，超出抛错。默认 20，传 0 表示不跟随。Added in: v1.26#
  • method <str> 指定请求方法，如 PUT 或 POST，默认 GET。#
  • multipart <Dict[str, str|float|bool|[ReadStream]|Dict]> 以 multipart/form-data 编码发送表单；如未设置会自动补齐 content-type。文件字段可传 fs.ReadStream 或包含文件名、MIME、内容的对象。#
    • name <str> 文件名
    • mimeType <str> 文件类型
    • buffer <bytes> 文件内容
  • params <Dict[str, str|float|bool]> URL 查询参数。#
  • timeout <float> 请求超时时间（毫秒），默认 30000，传 0 关闭超时。#
  • 返回值: <APIResponse>#

发送 HTTP(S) 请求并返回响应。会自动从上下文注入 cookie，并将响应携带的 cookie 写回上下文，同时自动跟随重定向。

可以直接传入 JSON 对象作为请求体：

data = {
    "title": "Book Title",
    "body": "John Doe",
}
api_request_context.fetch("https://example.com/api/createBook", method="post", data=data)

使用 multipart/form-data 上传文件时，可按如下方式构造表单：

api_request_context.fetch(
  "https://example.com/api/uploadScrip'",
  method="post",
  multipart={
    "fileField": {
      "name": "f.js",
      "mimeType": "text/javascript",
      "buffer": b"console.log(2022);",
    },
  })

api_request_context.get(url, **kwargs)​

Added in: v1.16
  • url <str> 目标 URL。#
  • data <str|bytes|Serializable> 允许设置请求的 POST 数据。如果 data 参数是一个对象，它将被序列化为 JSON 字符串，并且若未显式设置，content-type 头部将自动设为 application/json；否则，若未显式设置，content-type 将设为 application/octet-stream。新增于：v1.26#
  • fail_on_status_code <bool> 是否在响应状态码不是 2xx 或 3xx 时抛出异常。默认情况下，无论状态码为何，都会返回响应对象。#
  • form <Dict[str, str|float|bool]> 提供一个对象，该对象将使用 application/x-www-form-urlencoded 编码序列化为 HTML 表单并作为请求体发送。若指定此参数且未显式提供 content-type 头部，则会自动设为 application/x-www-form-urlencoded。新增于：v1.26#
  • headers <Dict[str, str]> 允许设置 HTTP 请求头。#
  • ignore_https_errors <bool> 发送网络请求时是否忽略 HTTPS 错误。默认值为 false。#
  • max_redirects <int> 自动跟随的最大重定向次数。若超过该次数，将抛出错误。默认值为 20。传入 0 表示不跟随重定向。新增于：v1.26#
  • multipart <Dict[str, str|float|bool|[ReadStream]|Dict]> 提供一个对象，该对象将使用 multipart/form-data 编码序列化为 HTML 表单并作为请求体发送。若指定此参数且未显式提供 content-type 头部，则会自动设为 multipart/form-data。文件值可以以 fs.ReadStream 形式传入，也可以传入包含文件名、MIME 类型和内容的类文件对象。新增于：v1.26#
    • name <str> 文件名
    • mimeType <str> 文件类型
    • buffer <bytes> 文件内容
  • params <Dict[str, str|float|bool]> 要随 URL 一起发送的查询参数。#
  • timeout <float> 请求超时时间（单位：毫秒）。默认值为 30000（30 秒）。传入 0 表示禁用超时。#
  • 返回值: <APIResponse>#

发送 HTTP(S) GET 请求并返回其响应。该方法会从上下文中自动填充请求 Cookie，并根据响应更新上下文中的 Cookie。此外，该方法会自动跟随重定向。

可通过 params 选项配置请求参数，这些参数将被序列化为 URL 的查询字符串：

query_params = {
  "isbn": "1234",
  "page": "23"
}
api_request_context.get("https://example.com/api/getText", params=query_params)

api_request_context.head(url, **kwargs)​

Added in: v1.16
  • url <str> 目标 URL。#
  • data <str|bytes|Serializable> 允许设置请求的 POST 数据。如果 data 参数是一个对象，它将被序列化为 JSON 字符串，并且若未显式设置，content-type 请求头将被设为 application/json；否则，若未显式设置，content-type 将被设为 application/octet-stream。新增于：v1.26#
  • fail_on_status_code <bool> 是否在响应状态码不是 2xx 或 3xx 时抛出异常。默认情况下，所有状态码都会返回响应对象。#
  • form <Dict[str, str|float|bool]> 提供一个对象，该对象将使用 application/x-www-form-urlencoded 编码序列化为 HTML 表单并作为请求体发送。若指定了此参数，除非显式提供，content-type 请求头将被设为 application/x-www-form-urlencoded。新增于：v1.26#
  • headers <Dict[str, str]> 允许设置 HTTP 请求头。#
  • ignore_https_errors <bool> 发送网络请求时是否忽略 HTTPS 错误。默认值为 false。#
  • max_redirects <int> 自动跟随的最大重定向次数。若超过该次数将抛出错误。默认值为 20。传入 0 表示不跟随重定向。新增于：v1.26#
  • multipart <Dict[str, str|float|bool|[ReadStream]|Dict]> 提供一个对象，该对象将使用 multipart/form-data 编码序列化为 HTML 表单并作为请求体发送。若指定了此参数，除非显式提供，content-type 请求头将被设为 multipart/form-data。文件值可以传入 fs.ReadStream，也可以传入包含文件名、MIME 类型和内容的类文件对象。新增于：v1.26#
    • name <str> 文件名
    • mimeType <str> 文件类型
    • buffer <bytes> 文件内容
  • params <Dict[str, str|float|bool]> 要随 URL 一起发送的查询参数。#
  • timeout <float> 请求超时时间（毫秒）。默认值为 30000（30 秒）。传入 0 表示禁用超时。#
  • 返回值: <APIResponse>#

发送 HTTP(S) HEAD 请求并返回响应，同样会自动处理上下文 cookie 并跟随重定向。

api_request_context.patch(url, **kwargs)​

Added in: v1.16
  • url <str> 目标 URL。#
  • data <str|bytes|Serializable> 允许设置请求的 POST 数据。如果 data 参数是一个对象，它将被序列化为 JSON 字符串，并且若未显式设置，content-type 请求头将被设为 application/json；否则，若未显式设置，content-type 将被设为 application/octet-stream。#
  • fail_on_status_code <bool> 是否在响应状态码不是 2xx 或 3xx 时抛出异常。默认情况下，所有状态码都会返回响应对象。#
  • form <Dict[str, str|float|bool]> 提供一个对象，该对象将使用 application/x-www-form-urlencoded 编码序列化为 HTML 表单并作为请求体发送。若指定了此参数，除非显式提供，content-type 请求头将被设为 application/x-www-form-urlencoded。#
  • headers <Dict[str, str]> 允许设置 HTTP 请求头。#
  • ignore_https_errors <bool> 发送网络请求时是否忽略 HTTPS 错误。默认值为 false。#
  • max_redirects <int> 自动跟随的最大重定向次数。若超过该次数将抛出错误。默认值为 20。传入 0 表示不跟随重定向。新增于：v1.26#
  • multipart <Dict[str, str|float|bool|[ReadStream]|Dict]> 提供一个对象，该对象将使用 multipart/form-data 编码序列化为 HTML 表单并作为请求体发送。若指定了此参数，除非显式提供，content-type 请求头将被设为 multipart/form-data。文件值可以传入 fs.ReadStream，也可以传入包含文件名、MIME 类型和内容的类文件对象。#
    • name <str> 文件名
    • mimeType <str> 文件类型
    • buffer <bytes> 文件内容
  • params <Dict[str, str|float|bool]> 要随 URL 一起发送的查询参数。#
  • timeout <float> 请求超时时间（毫秒）。默认值为 30000（30 秒）。传入 0 表示禁用超时。#
  • 返回值: <APIResponse>#

发送 HTTP(S) PATCH 请求并返回响应，会自动同步上下文 cookie 并跟随重定向。

api_request_context.post(url, **kwargs)​

Added in: v1.16
  • url <str> 目标 URL。#
  • data <str|bytes|Serializable> 允许设置请求的 POST 数据。如果 data 参数是一个对象，它将被序列化为 JSON 字符串，并且若未显式设置，content-type 头部将自动设为 application/json；否则，若未显式设置，content-type 将设为 application/octet-stream。#
  • fail_on_status_code <bool> 是否在响应状态码不是 2xx 或 3xx 时抛出异常。默认情况下，无论状态码为何，都会返回响应对象。#
  • form <Dict[str, str|float|bool]> 提供一个对象，该对象将使用 application/x-www-form-urlencoded 编码序列化为 HTML 表单并作为请求体发送。若指定此参数且未显式提供 content-type 头部，则会自动设为 application/x-www-form-urlencoded。#
  • headers <Dict[str, str]> 允许设置 HTTP 请求头。#
  • ignore_https_errors <bool> 发送网络请求时是否忽略 HTTPS 错误。默认值为 false。#
  • max_redirects <int> 自动跟随的最大重定向次数。若超过该次数，将抛出错误。默认值为 20。传入 0 表示不跟随重定向。新增于：v1.26#
  • multipart <Dict[str, str|float|bool|[ReadStream]|Dict]> 提供一个对象，该对象将使用 multipart/form-data 编码序列化为 HTML 表单并作为请求体发送。若指定此参数且未显式提供 content-type 头部，则会自动设为 multipart/form-data。文件值可以以 fs.ReadStream 形式传入，也可以传入包含文件名、MIME 类型和内容的类文件对象。#
    • name <str> 文件名
    • mimeType <str> 文件类型
    • buffer <bytes> 文件内容
  • params <Dict[str, str|float|bool]> 要随 URL 一起发送的查询参数。#
  • timeout <float> 请求超时时间（单位：毫秒）。默认值为 30000（30 秒）。传入 0 表示禁用超时。#
  • 返回值: <APIResponse>#

发送 HTTP(S) POST 请求并返回其响应。该方法会从上下文中自动填充请求 Cookie，并根据响应更新上下文中的 Cookie。此外，该方法会自动跟随重定向。

可以直接传入 JSON 对象：

data = {
    "title": "Book Title",
    "body": "John Doe",
}
api_request_context.post("https://example.com/api/createBook", data=data)

若需发送普通表单，可使用 form 选项，值会按照 application/x-www-form-urlencoded 编码（如需上传文件，可参考下文 multipart/form-data 示例）：

formData = {
    "title": "Book Title",
    "body": "John Doe",
}
api_request_context.post("https://example.com/api/findBook", form=formData)

使用 multipart/form-data 上传文件的示例：

api_request_context.post(
  "https://example.com/api/uploadScrip'",
  multipart={
    "fileField": {
      "name": "f.js",
      "mimeType": "text/javascript",
      "buffer": b"console.log(2022);",
    },
  })

api_request_context.put(url, **kwargs)​

Added in: v1.16
  • url <str> 目标 URL。#
  • data <str|bytes|Serializable> 允许设置请求的主体数据。如果 data 参数是一个对象，它将被序列化为 JSON 字符串，并且若未显式设置，content-type 头部将自动设为 application/json；否则，若未显式设置，content-type 将设为 application/octet-stream。#
  • fail_on_status_code <bool> 是否在响应状态码不是 2xx 或 3xx 时抛出异常。默认情况下，无论状态码为何，都会返回响应对象。#
  • form <Dict[str, str|float|bool]> 提供一个对象，该对象将使用 application/x-www-form-urlencoded 编码序列化为 HTML 表单并作为请求体发送。若指定此参数且未显式提供 content-type 头部，则会自动设为 application/x-www-form-urlencoded。#
  • headers <Dict[str, str]> 允许设置 HTTP 请求头。#
  • ignore_https_errors <bool> 发送网络请求时是否忽略 HTTPS 错误。默认值为 false。#
  • max_redirects <int> 自动跟随的最大重定向次数。若超过该次数，将抛出错误。默认值为 20。传入 0 表示不跟随重定向。新增于：v1.26#
  • multipart <Dict[str, str|float|bool|[ReadStream]|Dict]> 提供一个对象，该对象将使用 multipart/form-data 编码序列化为 HTML 表单并作为请求体发送。若指定此参数且未显式提供 content-type 头部，则会自动设为 multipart/form-data。文件值可以以 fs.ReadStream 形式传入，也可以传入包含文件名、MIME 类型和内容的类文件对象。#
    • name <str> 文件名
    • mimeType <str> 文件类型
    • buffer <bytes> 文件内容
  • params <Dict[str, str|float|bool]> 要随 URL 一起发送的查询参数。#
  • timeout <float> 请求超时时间（单位：毫秒）。默认值为 30000（30 秒）。传入 0 表示禁用超时。#
  • 返回值: <APIResponse>#

发送 HTTP(S) PUT 请求并返回其响应。该方法会从上下文中自动填充请求 Cookie，并根据响应更新上下文中的 Cookie。此外，该方法会自动跟随重定向。

api_request_context.storage_state(**kwargs)​

Added in: v1.16
  • path <Union[str, pathlib.Path]> 存储状态文件路径；若为相对路径，则基于当前工作目录解析。即使不提供路径，也会返回存储状态但不会写入磁盘。#
  • 返回值: <Dict>#

返回该请求上下文的存储状态，包含当前 cookie 以及（如果构造时传入）localStorage 快照。