跳转到主要内容

APIRequestContext

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

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

Cookie 管理

browser_context.requestpage.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:
# 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"}'

方法

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 数据。如果数据参数是一个对象,它将被序列化为 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 表示禁用超时。

返回


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#

    报告给因上下文处置而中断的操作的原因。

返回


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 或从中获取所有参数的请求。

  • data str | bytes | Dict (可选)#

    允许设置请求的 POST 数据。如果数据参数是一个对象,它将被序列化为 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 (可选)#

    如果设置,则更改获取方法(例如 PUTPOST)。如果未指定,则使用 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 表示禁用超时。

返回


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 数据。如果数据参数是一个对象,它将被序列化为 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 表示禁用超时。

返回


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 数据。如果数据参数是一个对象,它将被序列化为 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 表示禁用超时。

返回


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 数据。如果数据参数是一个对象,它将被序列化为 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 表示禁用超时。

返回


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)

在请求正文中发送文件(或多个文件)的常见方式是将其作为表单字段与 `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 数据。如果数据参数是一个对象,它将被序列化为 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 表示禁用超时。

返回


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 数据。如果数据参数是一个对象,它将被序列化为 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 表示禁用超时。

返回


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 是相对路径,则它相对于当前工作目录解析。如果没有提供路径,存储状态仍然会返回,但不会保存到磁盘。

返回