跳至主要内容

APIRequestContext

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

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

Cookie管理

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

如果您希望API请求不干扰浏览器cookie，您应该通过调用APIRequest.newContext()来创建一个新的APIRequestContext。这样的APIRequestContext对象将拥有自己独立的cookie存储空间。

方法​

删除​

Added in: v1.16 apiRequestContext.delete

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

用法

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

参数

返回

dispose​

Added in: v1.16 apiRequestContext.dispose

由APIRequestContext.get()及类似方法返回的所有响应都存储在内存中，以便您稍后可以调用APIResponse.body()。此方法会释放其所有资源，对已释放的APIRequestContext调用任何方法都将抛出异常。

用法

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

参数

  • options ApiRequestContext.DisposeOptions (optional)

    • setReason String (可选) 添加于: v1.45#

      要报告给因上下文释放而中断的操作的原因。

返回

fetch​

Added in: 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参数来实现：

// 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或Request，用于获取所有参数。

  • options RequestOptions (可选) 添加于: v1.18#

    可选的请求参数。

返回

获取​

Added in: 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));

参数

返回

头部​

Added in: v1.16 apiRequestContext.head

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

用法

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

参数

返回

补丁​

Added in: v1.16 apiRequestContext.patch

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

用法

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

参数

返回

发布​

Added in: 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)));

参数

返回

put​

Added in: v1.16 apiRequestContext.put

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

用法

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

参数

返回

storageState​

Added in: v1.16 apiRequestContext.storageState

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

用法

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

参数

  • options ApiRequestContext.StorageStateOptions (optional)

    • setIndexedDB boolean (可选) 新增于: v1.51#

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

    • setPath Path (可选)#

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

返回