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 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 | Serializable (可选)新增于: v1.17#
  
  允许设置请求的 POST 数据。如果数据参数是一个对象，它将被序列化为 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',
  }
});

在请求主体中发送文件(s)的常用方法是将它们作为表单字段与 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 或从中获取所有参数的请求。
options Object (可选)
- data string | Buffer | Serializable (可选)#
  
  允许设置请求的 POST 数据。如果数据参数是一个对象，它将被序列化为 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 | Serializable (可选)新增于: v1.26#
  
  允许设置请求的 POST 数据。如果数据参数是一个对象，它将被序列化为 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 | Serializable (可选)新增于: v1.26#
  
  允许设置请求的 POST 数据。如果数据参数是一个对象，它将被序列化为 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 | Serializable (可选)#
  
  允许设置请求的 POST 数据。如果数据参数是一个对象，它将被序列化为 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',
  }
});

在请求主体中发送文件(s)的常用方法是将它们作为表单字段与 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 | Serializable (可选)#
  
  允许设置请求的 POST 数据。如果数据参数是一个对象，它将被序列化为 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 请求并返回其响应。该方法将从上下文中填充请求 cookie，并从响应中更新上下文 cookie。该方法将自动遵循重定向。

用法

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

参数

url string #

目标 URL。
options Object (可选)
- data string | Buffer | Serializable (可选)#
  
  允许设置请求的 POST 数据。如果数据参数是一个对象，它将被序列化为 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>#

storageState

添加于：v1.16

apiRequestContext.storageState

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

用法

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