APIRequestContext

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

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

Cookie 管理

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

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

• apiRequestContext.delete(url[, options])
• apiRequestContext.dispose()
• apiRequestContext.fetch(urlOrRequest[, options])
• apiRequestContext.get(url[, options])
• apiRequestContext.head(url[, options])
• apiRequestContext.patch(url[, options])
• apiRequestContext.post(url[, options])
• apiRequestContext.put(url[, options])
• apiRequestContext.storageState([options])

apiRequestContext.delete(url[, options])

Added in: v1.16

• url <string> 目标 URL。#
• options? <Object>
  • data? <string|Buffer|Serializable> 允许设置请求的 post 数据。如果 data 参数是一个对象，它将被序列化为 json 字符串，并且如果未显式设置，content-type 头将被设置为 application/json。否则，如果未显式设置，content-type 头将被设置为 application/octet-stream。Added in: v1.17#
  • failOnStatusCode? <boolean> 是否在响应代码不是 2xx 和 3xx 时抛出异常。默认情况下，所有状态代码都会返回响应对象。#
  • form? <Object<string, string|number|boolean>> 提供一个对象，该对象将使用 application/x-www-form-urlencoded 编码序列化为 html 表单，并作为此请求体发送。如果指定了此参数，除非显式提供，否则 content-type 头将被设置为 application/x-www-form-urlencoded。Added in: v1.17#
  • headers? <Object<string, string>> 允许设置 HTTP 头。#
  • ignoreHTTPSErrors? <boolean> 发送网络请求时是否忽略 HTTPS 错误。默认为 false。#
  • maxRedirects? <number> 自动跟随的最大请求重定向数。如果超过该数字，将抛出错误。默认为 20。传递 0 以不跟随重定向。Added in: v1.26#
  • multipart? <Object<string, string|number|boolean|[ReadStream]|Object>> 提供一个对象，该对象将使用 multipart/form-data 编码序列化为 html 表单，并作为此请求体发送。如果指定了此参数，除非显式提供，否则 content-type 头将被设置为 multipart/form-data。文件值可以作为 fs.ReadStream 传递，也可以作为包含文件名、mime 类型及其内容的文件类对象传递。Added in: v1.17#
    • name <string> 文件名
    • mimeType <string> 文件类型
    • buffer <Buffer> 文件内容
  • params? <Object<string, string|number|boolean>> 要随 URL 发送的查询参数。#
  • timeout? <number> 请求超时（以毫秒为单位）。默认为 30000（30 秒）。传递 0 以禁用超时。#
• returns: <Promise<APIResponse>>#

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

apiRequestContext.dispose()

Added in: v1.16

• returns: <Promise<void>>#

apiRequestContext.get(url[, options]) 和类似方法返回的所有响应都存储在内存中，以便您稍后可以调用 apiResponse.body()。此方法丢弃所有存储的响应，并使 apiResponse.body() 抛出 "Response disposed" 错误。

apiRequestContext.fetch(urlOrRequest[, options])

Added in: v1.16

• urlOrRequest <string|Request> 目标 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>> 提供一个对象，该对象将使用 application/x-www-form-urlencoded 编码序列化为 html 表单，并作为此请求体发送。如果指定了此参数，除非显式提供，否则 content-type 头将被设置为 application/x-www-form-urlencoded。#
  • headers? <Object<string, string>> 允许设置 HTTP 头。#
  • ignoreHTTPSErrors? <boolean> 发送网络请求时是否忽略 HTTPS 错误。默认为 false。#
  • maxRedirects? <number> 自动跟随的最大请求重定向数。如果超过该数字，将抛出错误。默认为 20。传递 0 以不跟随重定向。Added in: v1.26#
  • method? <string> 如果设置，则更改 fetch 方法（例如 PUT 或 POST）。如果未指定，则使用 GET 方法。#
  • multipart? <Object<string, string|number|boolean|[ReadStream]|Object>> 提供一个对象，该对象将使用 multipart/form-data 编码序列化为 html 表单，并作为此请求体发送。如果指定了此参数，除非显式提供，否则 content-type 头将被设置为 multipart/form-data。文件值可以作为 fs.ReadStream 传递，也可以作为包含文件名、mime 类型及其内容的文件类对象传递。#
    • name <string> 文件名
    • mimeType <string> 文件类型
    • buffer <Buffer> 文件内容
  • params? <Object<string, string|number|boolean>> 要随 URL 发送的查询参数。#
  • timeout? <number> 请求超时（以毫秒为单位）。默认为 30000（30 秒）。传递 0 以禁用超时。#
• returns: <Promise<APIResponse>>#

发送 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 编码的表单字段。您可以使用 Playwright API 实现此目的，如下所示：

// 打开文件作为流并将其传递给请求：
const stream = fs.createReadStream('team.csv');
await request.fetch('https://example.com/api/uploadTeamList', {
  method: 'post',
  multipart: {
    fileField: stream
  }
});

// 或者您可以直接将文件内容作为对象传递：
await request.fetch('https://example.com/api/uploadScript', {
  method: 'post',
  multipart: {
    fileField: {
      name: 'f.js',
      mimeType: 'text/javascript',
      buffer: Buffer.from('console.log(2022);')
    }
  }
});

apiRequestContext.get(url[, options])

Added in: v1.16

• url <string> 目标 URL。#
• options? <Object>
  • data? <string|Buffer|Serializable> 允许设置请求的 post 数据。如果 data 参数是一个对象，它将被序列化为 json 字符串，并且如果未显式设置，content-type 头将被设置为 application/json。否则，如果未显式设置，content-type 头将被设置为 application/octet-stream。Added in: v1.26#
  • failOnStatusCode? <boolean> 是否在响应代码不是 2xx 和 3xx 时抛出异常。默认情况下，所有状态代码都会返回响应对象。#
  • form? <Object<string, string|number|boolean>> 提供一个对象，该对象将使用 application/x-www-form-urlencoded 编码序列化为 html 表单，并作为此请求体发送。如果指定了此参数，除非显式提供，否则 content-type 头将被设置为 application/x-www-form-urlencoded。Added in: v1.26#
  • headers? <Object<string, string>> 允许设置 HTTP 头。#
  • ignoreHTTPSErrors? <boolean> 发送网络请求时是否忽略 HTTPS 错误。默认为 false。#
  • maxRedirects? <number> 自动跟随的最大请求重定向数。如果超过该数字，将抛出错误。默认为 20。传递 0 以不跟随重定向。Added in: v1.26#
  • multipart? <Object<string, string|number|boolean|[ReadStream]|Object>> 提供一个对象，该对象将使用 multipart/form-data 编码序列化为 html 表单，并作为此请求体发送。如果指定了此参数，除非显式提供，否则 content-type 头将被设置为 multipart/form-data。文件值可以作为 fs.ReadStream 传递，也可以作为包含文件名、mime 类型及其内容的文件类对象传递。Added in: v1.26#
    • name <string> 文件名
    • mimeType <string> 文件类型
    • buffer <Buffer> 文件内容
  • params? <Object<string, string|number|boolean>> 要随 URL 发送的查询参数。#
  • timeout? <number> 请求超时（以毫秒为单位）。默认为 30000（30 秒）。传递 0 以禁用超时。#
• returns: <Promise<APIResponse>>#

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

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

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

apiRequestContext.head(url[, options])

Added in: v1.16

• url <string> 目标 URL。#
• options? <Object>
  • data? <string|Buffer|Serializable> 允许设置请求的 post 数据。如果 data 参数是一个对象，它将被序列化为 json 字符串，并且如果未显式设置，content-type 头将被设置为 application/json。否则，如果未显式设置，content-type 头将被设置为 application/octet-stream。Added in: v1.26#
  • failOnStatusCode? <boolean> 是否在响应代码不是 2xx 和 3xx 时抛出异常。默认情况下，所有状态代码都会返回响应对象。#
  • form? <Object<string, string|number|boolean>> 提供一个对象，该对象将使用 application/x-www-form-urlencoded 编码序列化为 html 表单，并作为此请求体发送。如果指定了此参数，除非显式提供，否则 content-type 头将被设置为 application/x-www-form-urlencoded。Added in: v1.26#
  • headers? <Object<string, string>> 允许设置 HTTP 头。#
  • ignoreHTTPSErrors? <boolean> 发送网络请求时是否忽略 HTTPS 错误。默认为 false。#
  • maxRedirects? <number> 自动跟随的最大请求重定向数。如果超过该数字，将抛出错误。默认为 20。传递 0 以不跟随重定向。Added in: v1.26#
  • multipart? <Object<string, string|number|boolean|[ReadStream]|Object>> 提供一个对象，该对象将使用 multipart/form-data 编码序列化为 html 表单，并作为此请求体发送。如果指定了此参数，除非显式提供，否则 content-type 头将被设置为 multipart/form-data。文件值可以作为 fs.ReadStream 传递，也可以作为包含文件名、mime 类型及其内容的文件类对象传递。Added in: v1.26#
    • name <string> 文件名
    • mimeType <string> 文件类型
    • buffer <Buffer> 文件内容
  • params? <Object<string, string|number|boolean>> 要随 URL 发送的查询参数。#
  • timeout? <number> 请求超时（以毫秒为单位）。默认为 30000（30 秒）。传递 0 以禁用超时。#
• returns: <Promise<APIResponse>>#

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

apiRequestContext.patch(url[, options])

Added in: v1.16

• 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>> 提供一个对象，该对象将使用 application/x-www-form-urlencoded 编码序列化为 html 表单，并作为此请求体发送。如果指定了此参数，除非显式提供，否则 content-type 头将被设置为 application/x-www-form-urlencoded。#
  • headers? <Object<string, string>> 允许设置 HTTP 头。#
  • ignoreHTTPSErrors? <boolean> 发送网络请求时是否忽略 HTTPS 错误。默认为 false。#
  • maxRedirects? <number> 自动跟随的最大请求重定向数。如果超过该数字，将抛出错误。默认为 20。传递 0 以不跟随重定向。Added in: v1.26#
  • multipart? <Object<string, string|number|boolean|[ReadStream]|Object>> 提供一个对象，该对象将使用 multipart/form-data 编码序列化为 html 表单，并作为此请求体发送。如果指定了此参数，除非显式提供，否则 content-type 头将被设置为 multipart/form-data。文件值可以作为 fs.ReadStream 传递，也可以作为包含文件名、mime 类型及其内容的文件类对象传递。#
    • name <string> 文件名
    • mimeType <string> 文件类型
    • buffer <Buffer> 文件内容
  • params? <Object<string, string|number|boolean>> 要随 URL 发送的查询参数。#
  • timeout? <number> 请求超时（以毫秒为单位）。默认为 30000（30 秒）。传递 0 以禁用超时。#
• returns: <Promise<APIResponse>>#

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

apiRequestContext.post(url[, options])

Added in: v1.16

• 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>> 提供一个对象，该对象将使用 application/x-www-form-urlencoded 编码序列化为 html 表单，并作为此请求体发送。如果指定了此参数，除非显式提供，否则 content-type 头将被设置为 application/x-www-form-urlencoded。#
  • headers? <Object<string, string>> 允许设置 HTTP 头。#
  • ignoreHTTPSErrors? <boolean> 发送网络请求时是否忽略 HTTPS 错误。默认为 false。#
  • maxRedirects? <number> 自动跟随的最大请求重定向数。如果超过该数字，将抛出错误。默认为 20。传递 0 以不跟随重定向。Added in: v1.26#
  • multipart? <Object<string, string|number|boolean|[ReadStream]|Object>> 提供一个对象，该对象将使用 multipart/form-data 编码序列化为 html 表单，并作为此请求体发送。如果指定了此参数，除非显式提供，否则 content-type 头将被设置为 multipart/form-data。文件值可以作为 fs.ReadStream 传递，也可以作为包含文件名、mime 类型及其内容的文件类对象传递。#
    • name <string> 文件名
    • mimeType <string> 文件类型
    • buffer <Buffer> 文件内容
  • params? <Object<string, string|number|boolean>> 要随 URL 发送的查询参数。#
  • timeout? <number> 请求超时（以毫秒为单位）。默认为 30000（30 秒）。传递 0 以禁用超时。#
• returns: <Promise<APIResponse>>#

发送 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 编码。您可以使用 Playwright API 实现此目的，如下所示：

// 打开文件作为流并将其传递给请求：
const stream = fs.createReadStream('team.csv');
await request.post('https://example.com/api/uploadTeamList', {
  multipart: {
    fileField: stream
  }
});

// 或者您可以直接将文件内容作为对象传递：
await request.post('https://example.com/api/uploadScript', {
  multipart: {
    fileField: {
      name: 'f.js',
      mimeType: 'text/javascript',
      buffer: Buffer.from('console.log(2022);')
    }
  }
});

apiRequestContext.put(url[, options])

Added in: v1.16

• 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>> 提供一个对象，该对象将使用 application/x-www-form-urlencoded 编码序列化为 html 表单，并作为此请求体发送。如果指定了此参数，除非显式提供，否则 content-type 头将被设置为 application/x-www-form-urlencoded。#
  • headers? <Object<string, string>> 允许设置 HTTP 头。#
  • ignoreHTTPSErrors? <boolean> 发送网络请求时是否忽略 HTTPS 错误。默认为 false。#
  • maxRedirects? <number> 自动跟随的最大请求重定向数。如果超过该数字，将抛出错误。默认为 20。传递 0 以不跟随重定向。Added in: v1.26#
  • multipart? <Object<string, string|number|boolean|[ReadStream]|Object>> 提供一个对象，该对象将使用 multipart/form-data 编码序列化为 html 表单，并作为此请求体发送。如果指定了此参数，除非显式提供，否则 content-type 头将被设置为 multipart/form-data。文件值可以作为 fs.ReadStream 传递，也可以作为包含文件名、mime 类型及其内容的文件类对象传递。#
    • name <string> 文件名
    • mimeType <string> 文件类型
    • buffer <Buffer> 文件内容
  • params? <Object<string, string|number|boolean>> 要随 URL 发送的查询参数。#
  • timeout? <number> 请求超时（以毫秒为单位）。默认为 30000（30 秒）。传递 0 以禁用超时。#
• returns: <Promise<APIResponse>>#

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

apiRequestContext.storageState([options])

Added in: v1.16

• options? <Object>
  • path? <string> 保存存储状态的文件路径。如果 path 是相对路径，则相对于当前工作目录进行解析。如果未提供路径，则仍返回存储状态，但不会保存到磁盘。#
• returns: <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>

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