APIRequestContext

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

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

Cookie 管理

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

如果您希望 API 请求不干扰浏览器 cookies，应通过调用 apiRequest.newContext() 创建新的 APIRequestContext。这样的 APIRequestContext 对象将拥有独立的 cookie 存储。

方法

delete

添加于: v1.16

apiRequestContext.delete

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

用法

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

参数

url string #

目标 URL。
options Object (可选)
- data string | Buffer | Serializable (可选) 添加于: 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) 请求并返回响应。该方法会从上下文中获取请求 cookies 并根据响应更新上下文 cookies。该方法会自动跟随重定向。

用法

可以直接传递 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');
// 发送两个同名的文件字段
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 | Serializable (可选)#
  
  允许设置请求的 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 请求并返回响应。该方法会从上下文中填充请求 cookies，并根据响应更新上下文 cookies。该方法会自动跟随重定向。

用法

请求参数可以通过 params 选项配置，它们会被序列化为 URL 查询参数：

// 以对象形式传递参数
await request.get('https://example.com/api/getText', {
  params: {
    'isbn': '1234',
    'page': 23,
  }
});

// 以 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 });

// 以字符串形式传递参数
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 | Serializable (可选) 添加于: 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-type 及其内容的类文件对象传递。
- params Object<string, string | number | boolean> | URLSearchParams | string (可选)#
  
  随 URL 发送的查询参数。
- timeout number (可选)#
  
  请求超时时间（毫秒）。默认为 30000（30 秒）。传递 0 表示禁用超时。

Promise<APIResponse>#

head

添加于: v1.16

apiRequestContext.head

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

用法

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

参数

url string #

目标 URL。
options Object (可选)
- data string | Buffer | Serializable (可选) 添加于: 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-type 及其内容的类文件对象传递。
- params Object<string, string | number | boolean> | URLSearchParams | string (可选)#
  
  随 URL 发送的查询参数。
- timeout number (可选)#
  
  请求超时时间（毫秒）。默认为 30000（30 秒）。传递 0 表示禁用超时。

Promise<APIResponse>#

patch

v1.16 版本新增

apiRequestContext.patch

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

用法

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

参数

url string #

目标 URL。
options Object (可选)
- data string | Buffer | Serializable (可选)#
  
  允许设置请求的 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 请求并返回响应。该方法会从上下文中填充请求的 cookies，并根据响应更新上下文中的 cookies。该方法会自动跟随重定向。

用法

可以直接将 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');
// 发送两个同名的文件字段。
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 | Serializable (可选)#
  
  允许设置请求的 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>#

put

添加于: v1.16

apiRequestContext.put

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

用法

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

参数

url string #

目标 URL。
options Object (可选)
- data string | Buffer | Serializable (可选)#
  
  允许设置请求的 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-type 及其内容的类文件对象传递。
- params Object<string, string | number | boolean> | URLSearchParams | string (可选)#
  
  随 URL 发送的查询参数。
- timeout number (可选)#
  
  请求超时时间（毫秒）。默认为 30000（30 秒）。传递 0 表示禁用超时。

返回值

Promise<APIResponse>#

storageState

添加于: v1.16

apiRequestContext.storageState

返回此请求上下文的存储状态，包含当前 cookies 和本地存储快照（如果构造函数中传入了该参数）。

用法

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

参数

options Object (可选)
- indexedDB boolean (可选) 添加于: v1.51#
  
  设置为 true 以在存储状态快照中包含 IndexedDB。
- path string (可选)#
  
  存储状态保存的文件路径。如果 path 是相对路径，则相对于当前工作目录解析。如果不提供路径，仍会返回存储状态，但不会保存到磁盘。

返回值

Promise<Object>#
- cookies Array<Object>
  - name string
  - value string
  - domain string
  - path string
  - expires number
    
    以秒为单位的 Unix 时间戳。
  - httpOnly boolean
  - secure boolean
  - sameSite "Strict" | "Lax" | "None"
- origins Array<Object>
  - origin string
  - localStorage Array<Object>
    - name string
    - value string

方法​

delete​

dispose​

fetch​

get​

head​

patch​

post​

put​

storageState​

方法

delete

dispose

fetch

get

head

patch

post

put

storageState