APIRequestContext

该 API 用于 Web API 测试。你可以用它来触发 API 接口、配置微服务、为你的端到端测试准备环境或服务。

每个 Playwright 浏览器上下文都关联有一个 APIRequestContext 实例，该实例与浏览器上下文共享 Cookie 存储，并可通过 browser_context.request 或 page.request 访问。你也可以通过调用 api_request.new_context() 手动创建一个新的 APIRequestContext 实例。

Cookie 管理

通过 browser_context.request 和 page.request 返回的 APIRequestContext 会与对应的 BrowserContext 共享 Cookie 存储。每个 API 请求都会自动带上来自浏览器上下文的 Cookie 头。如果 API 响应包含 Set-Cookie 头，则会自动更新 BrowserContext 的 Cookie，页面发起的请求也会获取到这些 Cookie。这意味着如果你通过该 API 登录，你的端到端测试也会处于登录状态，反之亦然。

如果你希望 API 请求不影响浏览器的 Cookie，应通过调用 api_request.new_context() 创建一个新的 APIRequestContext。这种 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 p:
    # 这将启动一个新的浏览器，创建一个上下文和页面。当使用内部 APIRequestContext（例如 `context.request` 或 `page.request`）发起 HTTP 请求时，
    # 会自动将 Cookie 设置到浏览器页面，反之亦然。
    browser = p.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 = p.request.new_context(base_url="https://api.github.com")


    # 创建一个仓库。
    response = api_request_context.post(
        "/user/repos",
        headers={
            "Accept": "application/vnd.github.v3+json",
            # 添加 GitHub 个人访问令牌。
            "Authorization": f"token {API_TOKEN}",
        },
        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",
            # 添加 GitHub 个人访问令牌。
            "Authorization": f"token {API_TOKEN}",
        },
    )
    assert response.ok
    assert await response.body() == '{"status": "ok"}'

import os
import asyncio
from playwright.async_api import async_playwright, Playwright

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

async def run(playwright: Playwright):
    # 这将启动一个新的浏览器，创建一个上下文和页面。当使用内部 APIRequestContext（例如 `context.request` 或 `page.request`）发起 HTTP 请求时，
    # 会自动将 Cookie 设置到浏览器页面，反之亦然。
    browser = await playwright.chromium.launch()
    context = await browser.new_context(base_url="https://api.github.com")
    api_request_context = context.request
    page = await context.new_page()

    # 你也可以手动创建一个没有绑定浏览器上下文的 APIRequestContext：
    # api_request_context = await playwright.request.new_context(base_url="https://api.github.com")

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

    # 删除一个仓库。
    response = await api_request_context.delete(
        f"/repos/{USER}/{REPO}",
        headers={
            "Accept": "application/vnd.github.v3+json",
            # 添加 GitHub 个人访问令牌。
            "Authorization": f"token {API_TOKEN}",
        },
    )
    assert response.ok
    assert await response.body() == '{"status": "ok"}'

async def main():
    async with async_playwright() as playwright:
        await run(playwright)

asyncio.run(main())

方法

delete

新增于: v1.16

apiRequestContext.delete

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

用法

api_request_context.delete(url)
api_request_context.delete(url, **kwargs)

参数

url str #

目标 URL。
data str | bytes | Dict (可选) 新增于: v1.17#

允许设置请求的 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] (可选) 新增于: v1.17#

提供一个对象，会被序列化为 html 表单并使用 application/x-www-form-urlencoded 编码作为请求体发送。如果指定了该参数，content-type 头会被设置为 application/x-www-form-urlencoded，除非已显式提供。
headers Dict[str, str] (可选)#

允许设置 HTTP 头。这些头会应用于请求及其自动跟随的所有重定向。
ignore_https_errors bool (可选)#

发送网络请求时是否忽略 HTTPS 错误。默认为 false。
max_redirects int (可选) 新增于: v1.26#

自动跟随的最大重定向次数。如果超过该数量会抛出错误。默认为 20。传递 0 表示不跟随重定向。
max_retries int (可选) 新增于: v1.46#

网络错误最大重试次数。目前仅会重试 ECONNRESET 错误。不会根据 HTTP 响应码重试。如果超过限制会抛出错误。默认为 0，即不重试。
multipart Dict[str, str | float | bool | [ReadStream] | Dict] (可选) 新增于: v1.17#
- name str
  
  文件名
- mimeType str
  
  文件类型
- buffer bytes
  
  文件内容
提供一个对象，会被序列化为 html 表单并使用 multipart/form-data 编码作为请求体发送。如果指定了该参数，content-type 头会被设置为 multipart/form-data，除非已显式提供。文件值可以作为包含文件名、mime-type 和内容的类文件对象传递。
params Dict[str, str | float | bool] | str (可选)#

要与 URL 一起发送的查询参数。
timeout float (可选)#

请求超时时间（毫秒）。默认为 30000（30 秒）。传递 0 表示不设置超时。

返回值

APIResponse #

dispose

新增于: v1.16

apiRequestContext.dispose

通过 api_request_context.get() 及类似方法返回的所有响应都会存储在内存中，以便你之后可以调用 api_response.body()。该方法会释放所有资源，调用已释放的 APIRequestContext 的任何方法都会抛出异常。

用法

api_request_context.dispose()
api_request_context.dispose(**kwargs)

参数

reason str (可选) 新增于: v1.45#

上下文释放时中断操作的原因说明。

返回值

NoneType #

fetch

新增于: v1.16

apiRequestContext.fetch

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

用法

可以直接将 JSON 对象传递给请求：

data = {
    "title": "书名",
    "body": "张三",
}
api_request_context.fetch("https://example.com/api/createBook", method="post", data=data)

常见的在请求体中发送文件的方法是通过 multipart/form-data 编码，将文件作为表单字段上传，需指定 multipart 参数：

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

参数

url_or_request str | Request #

目标 URL 或用于获取所有参数的 Request 对象。
data str | bytes | Dict (可选)#

允许设置请求的 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] (可选)#

提供一个对象，会被序列化为 html 表单并使用 application/x-www-form-urlencoded 编码作为请求体发送。如果指定了该参数，content-type 头会被设置为 application/x-www-form-urlencoded，除非已显式提供。
headers Dict[str, str] (可选)#

允许设置 HTTP 头。这些头会应用于请求及其自动跟随的所有重定向。
ignore_https_errors bool (可选)#

发送网络请求时是否忽略 HTTPS 错误。默认为 false。
max_redirects int (可选) 新增于: v1.26#

自动跟随的最大重定向次数。如果超过该数量会抛出错误。默认为 20。传递 0 表示不跟随重定向。
max_retries int (可选) 新增于: v1.46#

网络错误最大重试次数。目前仅会重试 ECONNRESET 错误。不会根据 HTTP 响应码重试。如果超过限制会抛出错误。默认为 0，即不重试。
method str (可选)#

如果设置，则更改 fetch 方法（如 PUT 或 POST）。如果未指定，则使用 GET 方法。
multipart Dict[str, str | float | bool | [ReadStream] | Dict] (可选)#
- name str
  
  文件名
- mimeType str
  
  文件类型
- buffer bytes
  
  文件内容
提供一个对象，会被序列化为 html 表单并使用 multipart/form-data 编码作为请求体发送。如果指定了该参数，content-type 头会被设置为 multipart/form-data，除非已显式提供。文件值可以作为包含文件名、mime-type 和内容的类文件对象传递。
params Dict[str, str | float | bool] | str (可选)#

要与 URL 一起发送的查询参数。
timeout float (可选)#

请求超时时间（毫秒）。默认为 30000（30 秒）。传递 0 表示不设置超时。

返回值

APIResponse #

get

新增于: v1.16

apiRequestContext.get

发送 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)

参数

url str #

目标 URL。
data str | bytes | Dict (可选) 新增于: v1.26#

允许设置请求的 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] (可选) 新增于: v1.26#

提供一个对象，会被序列化为 html 表单并使用 application/x-www-form-urlencoded 编码作为请求体发送。如果指定了该参数，content-type 头会被设置为 application/x-www-form-urlencoded，除非已显式提供。
headers Dict[str, str] (可选)#

允许设置 HTTP 头。这些头会应用于请求及其自动跟随的所有重定向。
ignore_https_errors bool (可选)#

发送网络请求时是否忽略 HTTPS 错误。默认为 false。
max_redirects int (可选) 新增于: v1.26#

自动跟随的最大重定向次数。如果超过该数量会抛出错误。默认为 20。传递 0 表示不跟随重定向。
max_retries int (可选) 新增于: v1.46#

网络错误最大重试次数。目前仅会重试 ECONNRESET 错误。不会根据 HTTP 响应码重试。如果超过限制会抛出错误。默认为 0，即不重试。
multipart Dict[str, str | float | bool | [ReadStream] | Dict] (可选) 新增于: v1.26#
- name str
  
  文件名
- mimeType str
  
  文件类型
- buffer bytes
  
  文件内容
提供一个对象，会被序列化为 html 表单并使用 multipart/form-data 编码作为请求体发送。如果指定了该参数，content-type 头会被设置为 multipart/form-data，除非已显式提供。文件值可以作为包含文件名、mime-type 和内容的类文件对象传递。
params Dict[str, str | float | bool] | str (可选)#

要与 URL 一起发送的查询参数。
timeout float (可选)#

请求超时时间（毫秒）。默认为 30000（30 秒）。传递 0 表示不设置超时。

返回值

APIResponse #

head

新增于: v1.16

apiRequestContext.head

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

用法

api_request_context.head(url)
api_request_context.head(url, **kwargs)

参数

url str #

目标 URL。
data str | bytes | Dict (可选) 新增于: v1.26#

允许设置请求的 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] (可选) 新增于: v1.26#

提供一个对象，会被序列化为 html 表单并使用 application/x-www-form-urlencoded 编码作为请求体发送。如果指定了该参数，content-type 头会被设置为 application/x-www-form-urlencoded，除非已显式提供。
headers Dict[str, str] (可选)#

允许设置 HTTP 头。这些头会应用于请求及其自动跟随的所有重定向。
ignore_https_errors bool (可选)#

发送网络请求时是否忽略 HTTPS 错误。默认为 false。
max_redirects int (可选) 新增于: v1.26#

自动跟随的最大重定向次数。如果超过该数量会抛出错误。默认为 20。传递 0 表示不跟随重定向。
max_retries int (可选) 新增于: v1.46#

网络错误最大重试次数。目前仅会重试 ECONNRESET 错误。不会根据 HTTP 响应码重试。如果超过限制会抛出错误。默认为 0，即不重试。
multipart Dict[str, str | float | bool | [ReadStream] | Dict] (可选) 新增于: v1.26#
- name str
  
  文件名
- mimeType str
  
  文件类型
- buffer bytes
  
  文件内容
提供一个对象，会被序列化为 html 表单并使用 multipart/form-data 编码作为请求体发送。如果指定了该参数，content-type 头会被设置为 multipart/form-data，除非已显式提供。文件值可以作为包含文件名、mime-type 和内容的类文件对象传递。
params Dict[str, str | float | bool] | str (可选)#

要与 URL 一起发送的查询参数。
timeout float (可选)#

请求超时时间（毫秒）。默认为 30000（30 秒）。传递 0 表示不设置超时。

返回值

APIResponse #

patch

新增于: v1.16

apiRequestContext.patch

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

用法

api_request_context.patch(url)
api_request_context.patch(url, **kwargs)

参数

url str #

目标 URL。
data str | bytes | Dict (可选)#

允许设置请求的 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] (可选)#

提供一个对象，会被序列化为 html 表单并使用 application/x-www-form-urlencoded 编码作为请求体发送。如果指定了该参数，content-type 头会被设置为 application/x-www-form-urlencoded，除非已显式提供。
headers Dict[str, str] (可选)#

允许设置 HTTP 头。这些头会应用于请求及其自动跟随的所有重定向。
ignore_https_errors bool (可选)#

发送网络请求时是否忽略 HTTPS 错误。默认为 false。
max_redirects int (可选) 新增于: v1.26#

自动跟随的最大重定向次数。如果超过该数量会抛出错误。默认为 20。传递 0 表示不跟随重定向。
max_retries int (可选) 新增于: v1.46#

网络错误最大重试次数。目前仅会重试 ECONNRESET 错误。不会根据 HTTP 响应码重试。如果超过限制会抛出错误。默认为 0，即不重试。
multipart Dict[str, str | float | bool | [ReadStream] | Dict] (可选)#
- name str
  
  文件名
- mimeType str
  
  文件类型
- buffer bytes
  
  文件内容
提供一个对象，会被序列化为 html 表单并使用 multipart/form-data 编码作为请求体发送。如果指定了该参数，content-type 头会被设置为 multipart/form-data，除非已显式提供。文件值可以作为包含文件名、mime-type 和内容的类文件对象传递。
params Dict[str, str | float | bool] | str (可选)#

要与 URL 一起发送的查询参数。
timeout float (可选)#

请求超时时间（毫秒）。默认为 30000（30 秒）。传递 0 表示不设置超时。

返回值

APIResponse #

post

新增于: v1.16

apiRequestContext.post

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

用法

可以直接将 JSON 对象传递给请求：

data = {
    "title": "书名",
    "body": "张三",
}
api_request_context.post("https://example.com/api/createBook", data=data)

如果需要以表单方式发送数据到服务器，可以使用 form 选项。其值会被编码为 application/x-www-form-urlencoded 格式的请求体（见下方如何使用 multipart/form-data 表单编码上传文件）：

formData = {
    "title": "书名",
    "body": "张三",
}
api_request_context.post("https://example.com/api/findBook", form=formData)

常见的在请求体中发送文件的方法是通过 multipart/form-data 编码，将文件作为表单字段上传。使用 [FormData] 构造请求体，并作为 multipart 参数传递给请求：

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

参数

url str #

目标 URL。
data str | bytes | Dict (可选)#

允许设置请求的 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] (可选)#

提供一个对象，会被序列化为 html 表单并使用 application/x-www-form-urlencoded 编码作为请求体发送。如果指定了该参数，content-type 头会被设置为 application/x-www-form-urlencoded，除非已显式提供。
headers Dict[str, str] (可选)#

允许设置 HTTP 头。这些头会应用于请求及其自动跟随的所有重定向。
ignore_https_errors bool (可选)#

发送网络请求时是否忽略 HTTPS 错误。默认为 false。
max_redirects int (可选) 新增于: v1.26#

自动跟随的最大重定向次数。如果超过该数量会抛出错误。默认为 20。传递 0 表示不跟随重定向。
max_retries int (可选) 新增于: v1.46#

网络错误最大重试次数。目前仅会重试 ECONNRESET 错误。不会根据 HTTP 响应码重试。如果超过限制会抛出错误。默认为 0，即不重试。
multipart Dict[str, str | float | bool | [ReadStream] | Dict] (可选)#
- name str
  
  文件名
- mimeType str
  
  文件类型
- buffer bytes
  
  文件内容
提供一个对象，会被序列化为 html 表单并使用 multipart/form-data 编码作为请求体发送。如果指定了该参数，content-type 头会被设置为 multipart/form-data，除非已显式提供。文件值可以作为包含文件名、mime-type 和内容的类文件对象传递。
params Dict[str, str | float | bool] | str (可选)#

要与 URL 一起发送的查询参数。
timeout float (可选)#

请求超时时间（毫秒）。默认为 30000（30 秒）。传递 0 表示不设置超时。

返回值

APIResponse #

put

新增于: v1.16

apiRequestContext.put

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

用法

api_request_context.put(url)
api_request_context.put(url, **kwargs)

参数

url str #

目标 URL。
data str | bytes | Dict (可选)#

允许设置请求的 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] (可选)#

提供一个对象，会被序列化为 html 表单并使用 application/x-www-form-urlencoded 编码作为请求体发送。如果指定了该参数，content-type 头会被设置为 application/x-www-form-urlencoded，除非已显式提供。
headers Dict[str, str] (可选)#

允许设置 HTTP 头。这些头会应用于请求及其自动跟随的所有重定向。
ignore_https_errors bool (可选)#

发送网络请求时是否忽略 HTTPS 错误。默认为 false。
max_redirects int (可选) 新增于: v1.26#

自动跟随的最大重定向次数。如果超过该数量会抛出错误。默认为 20。传递 0 表示不跟随重定向。
max_retries int (可选) 新增于: v1.46#

网络错误最大重试次数。目前仅会重试 ECONNRESET 错误。不会根据 HTTP 响应码重试。如果超过限制会抛出错误。默认为 0，即不重试。
multipart Dict[str, str | float | bool | [ReadStream] | Dict] (可选)#
- name str
  
  文件名
- mimeType str
  
  文件类型
- buffer bytes
  
  文件内容
提供一个对象，会被序列化为 html 表单并使用 multipart/form-data 编码作为请求体发送。如果指定了该参数，content-type 头会被设置为 multipart/form-data，除非已显式提供。文件值可以作为包含文件名、mime-type 和内容的类文件对象传递。
params Dict[str, str | float | bool] | str (可选)#

要与 URL 一起发送的查询参数。
timeout float (可选)#

请求超时时间（毫秒）。默认为 30000（30 秒）。传递 0 表示不设置超时。

返回值

APIResponse #

storage_state

新增于: v1.16

apiRequestContext.storage_state

返回该请求上下文的存储状态，包含当前的 cookies 以及如果在构造函数中传入了 local storage，则包含 local storage 快照。

用法

api_request_context.storage_state()
api_request_context.storage_state(**kwargs)

参数

indexed_db bool (可选) 新增于: v1.51#

设为 true 时，存储状态快照中会包含 IndexedDB。
path Union[str, pathlib.Path] (可选)#

存储状态保存到的文件路径。如果 path 是相对路径，则会相对于当前工作目录解析。如果未提供 path，则仍会返回存储状态，但不会保存到磁盘。

返回值

Dict#
- cookies List[Dict]
  - name str
  - value str
  - domain str
  - path str
  - expires float
    
    Unix 时间（秒）。
  - httpOnly bool
  - secure bool
  - sameSite "Strict" | "Lax" | "None"
- origins List[Dict]
  - origin str
  - localStorage List[Dict]
    - name str
    - value str

方法​

delete​

dispose​

fetch​

get​

head​

patch​

post​

put​

storage_state​

方法

delete

dispose

fetch

get

head

patch

post

put

storage_state