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 存储。

---

方法

delete

新增于：v1.16 apiRequestContext.delete

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

用法

await apiRequestContext.delete(url);
await apiRequestContext.delete(url, options);

参数

• url string#

  目标 URL。

• options Object (可选)

  • data string | Buffer | 可序列化 (可选)新增于：v1.17#

    允许设置请求的 post 数据。如果 data 参数是一个对象，它将被序列化为 json 字符串，并且如果未明确设置，content-type 头部将被设置为 application/json。否则，如果未明确设置，content-type 头部将被设置为 application/octet-stream。

  • failOnStatusCode boolean (可选)#

    是否在响应状态码不是 2xx 和 3xx 时抛出错误。默认情况下，对所有状态码都返回响应对象。

  • form Object<string, string | number | boolean> | FormData (可选)新增于：v1.17#

    提供一个对象，该对象将使用 application/x-www-form-urlencoded 编码序列化为 HTML 表单，并作为此请求的正文发送。如果指定此参数，除非明确提供，否则 content-type 头部将被设置为 application/x-www-form-urlencoded。

  • headers Object<string, string> (可选)#

    允许设置 HTTP 头部。这些头部将应用于获取的请求以及由此引发的任何重定向。

  • ignoreHTTPSErrors boolean (可选)#

    发送网络请求时是否忽略 HTTPS 错误。默认为 false。

  • maxRedirects number (可选)新增于：v1.26#

    自动跟随的最大请求重定向次数。如果超过此次数将抛出错误。默认为 20。传递 0 则不跟随重定向。

  • maxRetries number (可选)新增于：v1.46#

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

  • multipart FormData | Object<string, string | number | boolean | ReadStream | Object> (可选)新增于：v1.17#

    • name string

      文件名

    • mimeType string

      文件类型

    • buffer Buffer

      文件内容

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

  • params Object<string, string | number | boolean> | URLSearchParams | string (可选)#

    要与 URL 一起发送的查询参数。

  • timeout number (可选)#

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

返回

• Promise<APIResponse>#

---

dispose

新增于：v1.16 apiRequestContext.dispose

所有由 apiRequestContext.get() 和类似方法返回的响应都存储在内存中，以便您稍后调用 apiResponse.body()。此方法会丢弃其所有资源，在已处置的 APIRequestContext 上调用任何方法将抛出异常。

用法

await apiRequestContext.dispose();
await apiRequestContext.dispose(options);

参数

• options Object (可选)

  • reason string (可选)新增于：v1.45#

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

返回

• Promise<void>#

---

fetch

新增于：v1.16 apiRequestContext.fetch

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

用法

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

await request.fetch('https://example.com/api/createBook', {
  method: 'post',
  data: {
    title: 'Book Title',
    author: 'John Doe',
  }
});

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

const form = new FormData();
form.set('name', 'John');
form.append('name', 'Doe');
// Send two file fields with the same name.
form.append('file', new File(['console.log(2024);'], 'f1.js', { type: 'text/javascript' }));
form.append('file', new File(['hello'], 'f2.txt', { type: 'text/plain' }));
await request.fetch('https://example.com/api/uploadForm', {
  multipart: form
});

参数

• urlOrRequest string | Request#

  目标 URL 或从中获取所有参数的 Request 对象。

• options Object (可选)

  • data string | Buffer | 可序列化 (可选)#

    允许设置请求的 post 数据。如果 data 参数是一个对象，它将被序列化为 json 字符串，并且如果未明确设置，content-type 头部将被设置为 application/json。否则，如果未明确设置，content-type 头部将被设置为 application/octet-stream。

  • failOnStatusCode boolean (可选)#

    是否在响应状态码不是 2xx 和 3xx 时抛出错误。默认情况下，对所有状态码都返回响应对象。

  • form Object<string, string | number | boolean> | FormData (可选)#

    提供一个对象，该对象将使用 application/x-www-form-urlencoded 编码序列化为 HTML 表单，并作为此请求的正文发送。如果指定此参数，除非明确提供，否则 content-type 头部将被设置为 application/x-www-form-urlencoded。

  • headers Object<string, string> (可选)#

    允许设置 HTTP 头部。这些头部将应用于获取的请求以及由此引发的任何重定向。

  • ignoreHTTPSErrors boolean (可选)#

    发送网络请求时是否忽略 HTTPS 错误。默认为 false。

  • maxRedirects number (可选)新增于：v1.26#

    自动跟随的最大请求重定向次数。如果超过此次数将抛出错误。默认为 20。传递 0 则不跟随重定向。

  • maxRetries number (可选)新增于：v1.46#

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

  • method string (可选)#

    如果设置，则更改 fetch 方法（例如 PUT 或 POST）。如果未指定，则使用 GET 方法。

  • multipart FormData | Object<string, string | number | boolean | ReadStream | Object> (可选)#

    • name string

      文件名

    • mimeType string

      文件类型

    • buffer Buffer

      文件内容

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

  • params Object<string, string | number | boolean> | URLSearchParams | string (可选)#

    要与 URL 一起发送的查询参数。

  • timeout number (可选)#

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

返回

• Promise<APIResponse>#

---

get

新增于：v1.16 apiRequestContext.get

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

用法

可以使用 params 选项配置请求参数，它们将被序列化到 URL 查询参数中

// Passing params as object
await request.get('https://example.com/api/getText', {
  params: {
    'isbn': '1234',
    'page': 23,
  }
});

// Passing params as URLSearchParams
const searchParams = new URLSearchParams();
searchParams.set('isbn', '1234');
searchParams.append('page', 23);
searchParams.append('page', 24);
await request.get('https://example.com/api/getText', { params: searchParams });

// Passing params as string
const queryString = 'isbn=1234&page=23&page=24';
await request.get('https://example.com/api/getText', { params: queryString });

参数

• url string#

  目标 URL。

• options Object (可选)

  • data string | Buffer | 可序列化 (可选)新增于：v1.26#

    允许设置请求的 post 数据。如果 data 参数是一个对象，它将被序列化为 json 字符串，并且如果未明确设置，content-type 头部将被设置为 application/json。否则，如果未明确设置，content-type 头部将被设置为 application/octet-stream。

  • failOnStatusCode boolean (可选)#

    是否在响应状态码不是 2xx 和 3xx 时抛出错误。默认情况下，对所有状态码都返回响应对象。

  • form Object<string, string | number | boolean> | FormData (可选)新增于：v1.26#

    提供一个对象，该对象将使用 application/x-www-form-urlencoded 编码序列化为 HTML 表单，并作为此请求的正文发送。如果指定此参数，除非明确提供，否则 content-type 头部将被设置为 application/x-www-form-urlencoded。

  • headers Object<string, string> (可选)#

    允许设置 HTTP 头部。这些头部将应用于获取的请求以及由此引发的任何重定向。

  • ignoreHTTPSErrors boolean (可选)#

    发送网络请求时是否忽略 HTTPS 错误。默认为 false。

  • maxRedirects number (可选)新增于：v1.26#

    自动跟随的最大请求重定向次数。如果超过此次数将抛出错误。默认为 20。传递 0 则不跟随重定向。

  • maxRetries number (可选)新增于：v1.46#

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

  • multipart FormData | Object<string, string | number | boolean | ReadStream | Object> (可选)新增于：v1.26#

    • name string

      文件名

    • mimeType string

      文件类型

    • buffer Buffer

      文件内容

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

  • params Object<string, string | number | boolean> | URLSearchParams | string (可选)#

    要与 URL 一起发送的查询参数。

  • timeout number (可选)#

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

返回

• Promise<APIResponse>#

---

head

新增于：v1.16 apiRequestContext.head

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

用法

await apiRequestContext.head(url);
await apiRequestContext.head(url, options);

参数

• url string#

  目标 URL。

• options Object (可选)

  • data string | Buffer | 可序列化 (可选)新增于：v1.26#

    允许设置请求的 post 数据。如果 data 参数是一个对象，它将被序列化为 json 字符串，并且如果未明确设置，content-type 头部将被设置为 application/json。否则，如果未明确设置，content-type 头部将被设置为 application/octet-stream。

  • failOnStatusCode boolean (可选)#

    是否在响应状态码不是 2xx 和 3xx 时抛出错误。默认情况下，对所有状态码都返回响应对象。

  • form Object<string, string | number | boolean> | FormData (可选)新增于：v1.26#

    提供一个对象，该对象将使用 application/x-www-form-urlencoded 编码序列化为 HTML 表单，并作为此请求的正文发送。如果指定此参数，除非明确提供，否则 content-type 头部将被设置为 application/x-www-form-urlencoded。

  • headers Object<string, string> (可选)#

    允许设置 HTTP 头部。这些头部将应用于获取的请求以及由此引发的任何重定向。

  • ignoreHTTPSErrors boolean (可选)#

    发送网络请求时是否忽略 HTTPS 错误。默认为 false。

  • maxRedirects number (可选)新增于：v1.26#

    自动跟随的最大请求重定向次数。如果超过此次数将抛出错误。默认为 20。传递 0 则不跟随重定向。

  • maxRetries number (可选)新增于：v1.46#

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

  • multipart FormData | Object<string, string | number | boolean | ReadStream | Object> (可选)新增于：v1.26#

    • name string

      文件名

    • mimeType string

      文件类型

    • buffer Buffer

      文件内容

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

  • params Object<string, string | number | boolean> | URLSearchParams | string (可选)#

    要与 URL 一起发送的查询参数。

  • timeout number (可选)#

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

返回

• Promise<APIResponse>#

---

patch

新增于：v1.16 apiRequestContext.patch

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

用法

await apiRequestContext.patch(url);
await apiRequestContext.patch(url, options);

参数

• url string#

  目标 URL。

• options Object (可选)

  • data string | Buffer | 可序列化 (可选)#

    允许设置请求的 post 数据。如果 data 参数是一个对象，它将被序列化为 json 字符串，并且如果未明确设置，content-type 头部将被设置为 application/json。否则，如果未明确设置，content-type 头部将被设置为 application/octet-stream。

  • failOnStatusCode boolean (可选)#

    是否在响应状态码不是 2xx 和 3xx 时抛出错误。默认情况下，对所有状态码都返回响应对象。

  • form Object<string, string | number | boolean> | FormData (可选)#

    提供一个对象，该对象将使用 application/x-www-form-urlencoded 编码序列化为 HTML 表单，并作为此请求的正文发送。如果指定此参数，除非明确提供，否则 content-type 头部将被设置为 application/x-www-form-urlencoded。

  • headers Object<string, string> (可选)#

    允许设置 HTTP 头部。这些头部将应用于获取的请求以及由此引发的任何重定向。

  • ignoreHTTPSErrors boolean (可选)#

    发送网络请求时是否忽略 HTTPS 错误。默认为 false。

  • maxRedirects number (可选)新增于：v1.26#

    自动跟随的最大请求重定向次数。如果超过此次数将抛出错误。默认为 20。传递 0 则不跟随重定向。

  • maxRetries number (可选)新增于：v1.46#

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

  • multipart FormData | Object<string, string | number | boolean | ReadStream | Object> (可选)#

    • name string

      文件名

    • mimeType string

      文件类型

    • buffer Buffer

      文件内容

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

  • params Object<string, string | number | boolean> | URLSearchParams | string (可选)#

    要与 URL 一起发送的查询参数。

  • timeout number (可选)#

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

返回

• Promise<APIResponse>#

---

post

新增于：v1.16 apiRequestContext.post

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

用法

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

await request.post('https://example.com/api/createBook', {
  data: {
    title: 'Book Title',
    author: 'John Doe',
  }
});

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

await request.post('https://example.com/api/findBook', {
  form: {
    title: 'Book Title',
    author: 'John Doe',
  }
});

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

const form = new FormData();
form.set('name', 'John');
form.append('name', 'Doe');
// Send two file fields with the same name.
form.append('file', new File(['console.log(2024);'], 'f1.js', { type: 'text/javascript' }));
form.append('file', new File(['hello'], 'f2.txt', { type: 'text/plain' }));
await request.post('https://example.com/api/uploadForm', {
  multipart: form
});

参数

• url string#

  目标 URL。

• options Object (可选)

  • data string | Buffer | 可序列化 (可选)#

    允许设置请求的 post 数据。如果 data 参数是一个对象，它将被序列化为 json 字符串，并且如果未明确设置，content-type 头部将被设置为 application/json。否则，如果未明确设置，content-type 头部将被设置为 application/octet-stream。

  • failOnStatusCode 布尔值 (可选)#

    是否在响应状态码不是 2xx 和 3xx 时抛出错误。默认情况下，对所有状态码都返回响应对象。

  • form 对象<字符串, 字符串 | 数字 | 布尔值> | FormData (可选)#

    提供一个对象，该对象将使用 application/x-www-form-urlencoded 编码序列化为 HTML 表单，并作为此请求的正文发送。如果指定此参数，除非明确提供，否则 content-type 头部将被设置为 application/x-www-form-urlencoded。

  • headers 对象<字符串, 字符串> (可选)#

    允许设置 HTTP 头部。这些头部将应用于获取的请求以及由此引发的任何重定向。

  • ignoreHTTPSErrors 布尔值 (可选)#

    发送网络请求时是否忽略 HTTPS 错误。默认为 false。

  • maxRedirects number (可选)新增于：v1.26#

    自动跟随的最大请求重定向次数。如果超过此次数将抛出错误。默认为 20。传递 0 则不跟随重定向。

  • maxRetries number (可选)新增于：v1.46#

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

  • multipart FormData | 对象<字符串, 字符串 | 数字 | 布尔值 | ReadStream | 对象> (可选)#

    • name string

      文件名

    • mimeType string

      文件类型

    • buffer Buffer

      文件内容

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

  • params 对象<字符串, 字符串 | 数字 | 布尔值> | URLSearchParams | 字符串 (可选)#

    要与 URL 一起发送的查询参数。

  • timeout 数字 (可选)#

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

返回

• Promise<APIResponse>#

---

put

新增于：v1.16 apiRequestContext.put

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

用法

await apiRequestContext.put(url);
await apiRequestContext.put(url, options);

参数

• url 字符串#

  目标 URL。

• options Object (可选)

  • data 字符串 | Buffer | 可序列化 (可选)#

    允许设置请求的 post 数据。如果 data 参数是一个对象，它将被序列化为 json 字符串，并且如果未明确设置，content-type 头部将被设置为 application/json。否则，如果未明确设置，content-type 头部将被设置为 application/octet-stream。

  • failOnStatusCode 布尔值 (可选)#

    是否在响应状态码不是 2xx 和 3xx 时抛出错误。默认情况下，对所有状态码都返回响应对象。

  • form 对象<字符串, 字符串 | 数字 | 布尔值> | FormData (可选)#

    提供一个对象，该对象将使用 application/x-www-form-urlencoded 编码序列化为 HTML 表单，并作为此请求的正文发送。如果指定此参数，除非明确提供，否则 content-type 头部将被设置为 application/x-www-form-urlencoded。

  • headers 对象<字符串, 字符串> (可选)#

    允许设置 HTTP 头部。这些头部将应用于获取的请求以及由此引发的任何重定向。

  • ignoreHTTPSErrors 布尔值 (可选)#

    发送网络请求时是否忽略 HTTPS 错误。默认为 false。

  • maxRedirects number (可选)新增于：v1.26#

    自动跟随的最大请求重定向次数。如果超过此次数将抛出错误。默认为 20。传递 0 则不跟随重定向。

  • maxRetries number (可选)新增于：v1.46#

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

  • multipart FormData | 对象<字符串, 字符串 | 数字 | 布尔值 | ReadStream | 对象> (可选)#

    • name string

      文件名

    • mimeType string

      文件类型

    • buffer Buffer

      文件内容

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

  • params 对象<字符串, 字符串 | 数字 | 布尔值> | URLSearchParams | 字符串 (可选)#

    要与 URL 一起发送的查询参数。

  • timeout 数字 (可选)#

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

返回

• Promise<APIResponse>#

---

storageState

新增于：v1.16 apiRequestContext.storageState

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

用法

await apiRequestContext.storageState();
await apiRequestContext.storageState(options);

参数

• options Object (可选)

  • indexedDB 布尔值 (可选)新增于：v1.51#

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

  • path 字符串 (可选)#

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

返回

• Promise<对象>#
  • cookies 数组<对象>

    • name string

    • value 字符串

    • domain 字符串

    • path 字符串

    • expires 数字

      以秒为单位的 Unix 时间。

    • httpOnly 布尔值

    • secure 布尔值

    • sameSite "Strict" | "Lax" | "None"

  • origins 数组<对象>

    • origin 字符串

    • localStorage 数组<对象>

      • name string

      • value 字符串