APIRequestContext

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

每个 Playwright 浏览器上下文都有一个关联的 APIRequestContext，可通过 BrowserContext.request() 或 Page.request() 访问（这些方法返回

同一个实例 — page.request 是 page.context().request 的简写）。你也可以使用 APIRequest.newContext() 创建一个独立的、隔离的实例。

Cookie 管理

由 BrowserContext.request() 和

Page.request() 返回的 APIRequestContext 使用与其 BrowserContext 相同的 cookie jar

如果你希望 API 请求不与浏览器共享 cookie，请通过 APIRequest.newContext() 创建一个隔离的上下文。这样的 APIRequestContext 对象将拥有自己独立的 cookie 存储。

---

方法

delete

添加于：v1.16 apiRequestContext.delete

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

用法

APIRequestContext.delete(url);
APIRequestContext.delete(url, options);

参数

• url String#

  目标 URL。

• options RequestOptions （可选）新增于: v1.18#

  可选的请求参数。

返回

• APIResponse#

---

dispose

添加于：v1.16 apiRequestContext.dispose

所有由 APIRequestContext.get() 及类似方法返回的响应都存储在内存中，以便你稍后调用 APIResponse.body()。此方法会丢弃其所有资源，对已销毁（disposed）的 APIRequestContext 调用任何方法都会抛出异常。

用法

APIRequestContext.dispose();
APIRequestContext.dispose(options);

参数

• options ApiRequestContext.DisposeOptions （可选）

  • setReason String (可选)新增于: v1.45#

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

返回

• void#

---

fetch

添加于：v1.16 apiRequestContext.fetch

发送 HTTP(S) 请求并返回其响应。该方法将从上下文中填充请求 cookie，并从响应中更新上下文 cookie。该方法将自动遵循重定向。

用法

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

Map<String, Object> data = new HashMap();
data.put("title", "Book Title");
data.put("body", "John Doe");
request.fetch("https://example.com/api/createBook", RequestOptions.create().setMethod("post").setData(data));

在请求主体中发送文件(s)的常用方法是将它们作为表单字段与 multipart/form-data 编码一起上传，通过指定 multipart 参数。

// Pass file path to the form data constructor:
Path file = Paths.get("team.csv");
APIResponse response = request.fetch("https://example.com/api/uploadTeamList",
  RequestOptions.create().setMethod("post").setMultipart(
    FormData.create().set("fileField", file)));

// Or you can pass the file content directly as FilePayload object:
FilePayload filePayload = new FilePayload("f.js", "text/javascript",
      "console.log(2022);".getBytes(StandardCharsets.UTF_8));
APIResponse response = request.fetch("https://example.com/api/uploadScript",
  RequestOptions.create().setMethod("post").setMultipart(
    FormData.create().set("fileField", filePayload)));

参数

• urlOrRequest String | Request#

  目标 URL 或从中获取所有参数的请求。

• options RequestOptions （可选）新增于: v1.18#

  可选的请求参数。

返回

• APIResponse#

---

get

添加于：v1.16 apiRequestContext.get

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

用法

请求参数可以通过 params 选项配置，它们将被序列化为 URL 搜索参数。

request.get("https://example.com/api/getText", RequestOptions.create()
  .setQueryParam("isbn", "1234")
  .setQueryParam("page", 23));

参数

• url String#

  目标 URL。

• options RequestOptions （可选）新增于: v1.18#

  可选的请求参数。

返回

• APIResponse#

---

head

添加于：v1.16 apiRequestContext.head

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

用法

APIRequestContext.head(url);
APIRequestContext.head(url, options);

参数

• url String#

  目标 URL。

• options RequestOptions （可选）新增于: v1.18#

  可选的请求参数。

返回

• APIResponse#

---

patch

添加于：v1.16 apiRequestContext.patch

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

用法

APIRequestContext.patch(url);
APIRequestContext.patch(url, options);

参数

• url String#

  目标 URL。

• options RequestOptions （可选）新增于: v1.18#

  可选的请求参数。

返回

• APIResponse#

---

post

添加于：v1.16 apiRequestContext.post

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

用法

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

Map<String, Object> data = new HashMap();
data.put("title", "Book Title");
data.put("body", "John Doe");
request.post("https://example.com/api/createBook", RequestOptions.create().setData(data));

要向服务器发送表单数据，请使用 form 选项。其值将以 application/x-www-form-urlencoded 编码编码到请求主体中（有关如何使用 multipart/form-data 表单编码发送文件，请参见下文）。

request.post("https://example.com/api/findBook", RequestOptions.create().setForm(
    FormData.create().set("title", "Book Title").set("body", "John Doe")
));

在请求体中发送文件的常用方法是将其作为具有 multipart/form-data 编码的表单字段上传。使用 FormData 构建请求体，并将其作为 multipart 参数传递给请求

// Pass file path to the form data constructor:
Path file = Paths.get("team.csv");
APIResponse response = request.post("https://example.com/api/uploadTeamList",
  RequestOptions.create().setMultipart(
    FormData.create().set("fileField", file)));

// Or you can pass the file content directly as FilePayload object:
FilePayload filePayload1 = new FilePayload("f1.js", "text/javascript",
      "console.log(2022);".getBytes(StandardCharsets.UTF_8));
APIResponse response = request.post("https://example.com/api/uploadScript",
  RequestOptions.create().setMultipart(
    FormData.create().set("fileField", filePayload)));

参数

• url String#

  目标 URL。

• options RequestOptions （可选）新增于: v1.18#

  可选的请求参数。

返回

• APIResponse#

---

put

添加于：v1.16 apiRequestContext.put

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

用法

APIRequestContext.put(url);
APIRequestContext.put(url, options);

参数

• url String#

  目标 URL。

• options RequestOptions （可选）新增于: v1.18#

  可选的请求参数。

返回

• APIResponse#

---

storageState

添加于：v1.16 apiRequestContext.storageState

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

用法

APIRequestContext.storageState();
APIRequestContext.storageState(options);

参数

• options ApiRequestContext.StorageStateOptions （可选）

  • setIndexedDB boolean （可选）添加于: v1.51#

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

  • setPath Path （可选）#

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

返回

• String#

---

属性

tracing()

添加于: v1.60 apiRequestContext.tracing()

用法

APIRequestContext.tracing()

返回

• Tracing