APIRequestContext

此 API 用于 Web API 测试。你可以使用它来触发 API 端点、配置微服务、为端到端（e2e）测试准备环境或服务。

每个 Playwright 浏览器上下文都关联有 APIRequestContext 实例，该实例与浏览器上下文共享 cookie 存储，并且可以通过 BrowserContext.request() 或 Page.request() 进行访问。也可以通过调用 APIRequest.newContext() 手动创建一个新的 APIRequestContext 实例。

Cookie 管理

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

如果你希望 API 请求不干扰浏览器的 cookie，你应该通过调用 APIRequest.newContext() 创建一个新的 APIRequestContext。这样的 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()。此方法会释放其所有资源，对已释放的 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));

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

// 将文件路径传递给表单数据构造函数：
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)));

// 或者你可以直接将文件内容作为 FilePayload 对象传递：
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 参数传递给请求：

// 将文件路径传递给表单数据构造函数：
Path file = Paths.get("team.csv");
APIResponse response = request.post("https://example.com/api/uploadTeamList",
  RequestOptions.create().setMultipart(
    FormData.create().set("fileField", file)));

// 或者，你可以直接将文件内容作为 FilePayload 对象传递：
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

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

用法

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

参数

options ApiRequestContext.StorageStateOptions （可选）
- setIndexedDB boolean （可选）新增于：v1.51#
  
  设置为 true 以在存储状态快照中包含 IndexedDB。
- setPath Path （可选）#
  
  存储状态保存的文件路径。如果 setPath 是相对路径，则相对于当前工作目录进行解析。如果未提供路径，仍会返回存储状态，但不会保存到磁盘。

返回值

String #

方法​

delete​

用法​

参数​

返回值​

dispose​

用法​

参数​

fetch​

get​

参数​

返回值​

head​

用法​

参数​

返回值​

patch​

post​

用法​

参数​

返回值​

put​

用法​

参数​

返回值​

storageState​

方法

delete

用法

参数

返回值

dispose

用法

参数

fetch

get

参数

返回值

head

用法

参数

返回值

patch

post

用法

参数

返回值

put

用法

参数

返回值

storageState