APIRequestContext

此 API 用于 Web API 测试。您可以使用它来触发 API 端点、配置微服务、准备环境或服务以进行端到端 (e2e) 测试。

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

Cookie 管理

APIRequestContext 返回由 browser_context.request 和 page.request 与相应的 BrowserContext 共享 cookie 存储。每个 API 请求都会包含从浏览器上下文填充的 Cookie 头。如果 API 响应包含 Set-Cookie 头，它将自动更新 BrowserContext 的 cookie，并且从页面发出的请求将使用这些 cookie。这意味着如果您使用此 API 登录，您的端到端 (e2e) 测试也将处于登录状态，反之亦然。

如果您希望 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:
    # This will launch a new browser, create a context and page. When making HTTP
    # requests with the internal APIRequestContext (e.g. `context.request` or `page.request`)
    # it will automatically set the cookies to the browser page and vice versa.
    browser = p.chromium.launch()
    context = browser.new_context(base_url="https://api.github.com")
    api_request_context = context.request
    page = context.new_page()

    # Alternatively you can create a APIRequestContext manually without having a browser context attached:
    # api_request_context = p.request.new_context(base_url="https://api.github.com")


    # Create a repository.
    response = api_request_context.post(
        "/user/repos",
        headers={
            "Accept": "application/vnd.github.v3+json",
            # Add GitHub personal access token.
            "Authorization": f"token {API_TOKEN}",
        },
        data={"name": REPO},
    )
    assert response.ok
    assert response.json()["name"] == REPO

    # Delete a repository.
    response = api_request_context.delete(
        f"/repos/{USER}/{REPO}",
        headers={
            "Accept": "application/vnd.github.v3+json",
            # Add GitHub personal access token.
            "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):
    # This will launch a new browser, create a context and page. When making HTTP
    # requests with the internal APIRequestContext (e.g. `context.request` or `page.request`)
    # it will automatically set the cookies to the browser page and vice versa.
    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()

    # Alternatively you can create a APIRequestContext manually without having a browser context attached:
    # api_request_context = await playwright.request.new_context(base_url="https://api.github.com")

    # Create a repository.
    response = await api_request_context.post(
        "/user/repos",
        headers={
            "Accept": "application/vnd.github.v3+json",
            # Add GitHub personal access token.
            "Authorization": f"token {API_TOKEN}",
        },
        data={"name": REPO},
    )
    assert response.ok
    assert response.json()["name"] == REPO

    # Delete a repository.
    response = await api_request_context.delete(
        f"/repos/{USER}/{REPO}",
        headers={
            "Accept": "application/vnd.github.v3+json",
            # Add GitHub personal access token.
            "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#

  提供一个将被使用 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 (可选)添加于: 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

    文件内容

  提供一个将被使用 multipart/form-data 编码序列化为 HTML 表单的对象，并作为此请求体发送。如果指定此参数，则除非明确提供，content-type 头将被设置为 multipart/form-data。文件值可以作为类似文件的对象传递，包含文件名、mime 类型及其内容。

• 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": "Book Title",
    "body": "John Doe",
}
api_request_context.fetch("https://example.com/api/createBook", method="post", data=data)

在请求体中发送文件(s) 的常见方式是使用 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] (可选)#

  提供一个将被使用 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 (可选)添加于: v1.26#

  将自动遵循的最大请求重定向次数。如果超出此次数将抛出错误。默认为 20。传递 0 表示不遵循重定向。

• max_retries int (可选)添加于: v1.46#

  网络错误应重试的最大次数。目前仅对 ECONNRESET 错误进行重试。不基于 HTTP 响应码进行重试。如果超出限制将抛出错误。默认为 0 - 不重试。

• method str (可选)#

  如果设置，改变获取方法（例如 PUT 或 POST）。如果未指定，使用 GET 方法。

• multipart Dict[str, str | float | bool | [ReadStream] | Dict] (可选)#

  • name str

    文件名

  • mimeType str

    文件类型

  • buffer bytes

    文件内容

  提供一个将被使用 multipart/form-data 编码序列化为 HTML 表单的对象，并作为此请求体发送。如果指定此参数，则除非明确提供，content-type 头将被设置为 multipart/form-data。文件值可以作为类似文件的对象传递，包含文件名、mime 类型及其内容。

• 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#

  提供一个将被使用 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 (可选)添加于: 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

    文件内容

  提供一个将被使用 multipart/form-data 编码序列化为 HTML 表单的对象，并作为此请求体发送。如果指定此参数，则除非明确提供，content-type 头将被设置为 multipart/form-data。文件值可以作为类似文件的对象传递，包含文件名、mime 类型及其内容。

• 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#

  提供一个将被使用 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 (可选)添加于: 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

    文件内容

  提供一个将被使用 multipart/form-data 编码序列化为 HTML 表单的对象，并作为此请求体发送。如果指定此参数，则除非明确提供，content-type 头将被设置为 multipart/form-data。文件值可以作为类似文件的对象传递，包含文件名、mime 类型及其内容。

• 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] (可选)#

  提供一个将被使用 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 (可选)添加于: 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

    文件内容

  提供一个将被使用 multipart/form-data 编码序列化为 HTML 表单的对象，并作为此请求体发送。如果指定此参数，则除非明确提供，content-type 头将被设置为 multipart/form-data。文件值可以作为类似文件的对象传递，包含文件名、mime 类型及其内容。

• 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": "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)

在请求体中发送文件(s) 的常见方式是使用 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] (可选)#

  提供一个将被使用 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 (可选)添加于: 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

    文件内容

  提供一个将被使用 multipart/form-data 编码序列化为 HTML 表单的对象，并作为此请求体发送。如果指定此参数，则除非明确提供，content-type 头将被设置为 multipart/form-data。文件值可以作为类似文件的对象传递，包含文件名、mime 类型及其内容。

• 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] (可选)#

  提供一个将被使用 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 (可选)添加于: 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

    文件内容

  提供一个将被使用 multipart/form-data 编码序列化为 HTML 表单的对象，并作为此请求体发送。如果指定此参数，则除非明确提供，content-type 头将被设置为 multipart/form-data。文件值可以作为类似文件的对象传递，包含文件名、mime 类型及其内容。

• params Dict[str, str | float | bool] | str (可选)#

  随 URL 发送的查询参数。

• timeout float (可选)#

  请求超时时间（毫秒）。默认为 30000 (30 秒)。传递 0 表示禁用超时。

返回值

• APIResponse#

---

storage_state

添加于: v1.16 apiRequestContext.storage_state

返回此请求上下文的存储状态，包含当前 cookie 和（如果传递给构造函数）本地存储快照。

用法

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

参数

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

  设为 true 以在存储状态快照中包含 IndexedDB。

• path Union[str, pathlib.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