跳到主要内容

APIRequestContext

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

每个 Playwright 浏览器上下文都关联有一个 APIRequestContext 实例,该实例与浏览器上下文共享 cookie 存储,并且可以通过 BrowserContext.APIRequestPage.APIRequest 进行访问。也可以通过调用 ApiRequest.NewContextAsync() 手动创建一个新的 APIRequestContext 实例。

Cookie 管理

BrowserContext.APIRequestPage.APIRequest 返回的 APIRequestContext 与相应的 BrowserContext 共享 cookie 存储。每个 API 请求的 Cookie 标头都将填充来自浏览器上下文的值。如果 API 响应包含 Set-Cookie 标头,它将自动更新 BrowserContext 的 cookie,并且从页面发出的请求将获取这些 cookie。这意味着,如果你使用此 API 登录,你的端到端测试也将处于登录状态,反之亦然。

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


方法

CreateFormData

添加于:v1.23 apiRequestContext.CreateFormData

创建一个新的 FormData 实例,该实例用于在发出 HTTP 请求时提供表单和多部分数据。

用法

ApiRequestContext.CreateFormData

返回值


DeleteAsync

新增于:v1.16 apiRequestContext.DeleteAsync

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

用法

await ApiRequestContext.DeleteAsync(url, options);

参数

  • url string#

    目标 URL。

  • options ApiRequestContextDeleteOptions?(可选)

    • Data|DataByte|DataObject string? | byte? | [object]?(可选) 新增于:v1.17#

      允许设置请求的 POST 数据。如果 data 参数是一个对象,它将被序列化为 JSON 字符串,并且如果未显式设置,content-type 标头将被设置为 application/json。否则,如果未显式设置,content-type 标头将被设置为 application/octet-stream

    • FailOnStatusCode bool?(可选)#

      对于非 2xx 和 3xx 的响应代码是否抛出异常。默认情况下,所有状态码都会返回响应对象。

    • Form FormData?(可选) 新增于:v1.17#

      提供一个对象,该对象将使用 application/x-www-form-urlencoded 编码序列化为 HTML 表单,并作为此请求体发送。如果指定了此参数,除非显式提供,否则 content-type 标头将设置为 application/x-www-form-urlencoded

      可以通过 ApiRequestContext.CreateFormData 创建 FormData 的实例。

    • Headers IDictionary?<string, string>(可选)#

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

    • IgnoreHTTPSErrors bool?(可选)#

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

    • MaxRedirects int?(可选) 新增于:v1.26#

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

    • MaxRetries int?(可选) 新增于:v1.46#

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

    • Multipart FormData?(可选) 新增于:v1.17#

      提供一个对象,该对象将使用 multipart/form-data 编码序列化为 HTML 表单,并作为此请求体发送。如果指定了此参数,除非显式提供,否则 content-type 标头将设置为 multipart/form-data。文件值可以作为包含文件名、MIME 类型及其内容的类似文件的对象传递。

      可以通过 ApiRequestContext.CreateFormData 创建 FormData 的实例。

    • Params IDictionary?<string, [object]>(可选)#

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

    • ParamsString string?(可选) 新增于:v1.47#

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

    • Timeout [float]?(可选)#

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

返回值


DisposeAsync

新增于:v1.16 apiRequestContext.DisposeAsync

ApiRequestContext.GetAsync() 及类似方法返回的所有响应都会存储在内存中,以便后续调用 ApiResponse.BodyAsync()。此方法会释放其所有资源,对已释放的 APIRequestContext 调用任何方法都会抛出异常。

用法

await ApiRequestContext.DisposeAsync(options);

参数

  • options ApiRequestContextDisposeOptions?可选
    • Reason string?(可选新增于:v1.45#

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

返回值


FetchAsync

新增于:v1.16 apiRequestContext.FetchAsync

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

用法

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

var data = new Dictionary<string, object>() {
{ "title", "Book Title" },
{ "body", "John Doe" }
};
await Request.FetchAsync("https://example.com/api/createBook", new() { Method = "post", DataObject = data });

在请求体中发送文件的常见方法是使用 multipart/form-data 编码将它们作为表单字段上传,具体方法是指定 multipart 参数:

var file = new FilePayload()
{
Name = "f.js",
MimeType = "text/javascript",
Buffer = System.Text.Encoding.UTF8.GetBytes("console.log(2022);")
};
var multipart = Context.APIRequest.CreateFormData();
multipart.Set("fileField", file);
await Request.FetchAsync("https://example.com/api/uploadScript", new() { Method = "post", Multipart = multipart });

参数

  • urlOrRequest string | Request#

    目标 URL 或用于获取所有参数的 Request

  • options ApiRequestContextFetchOptions?(可选)

    • Data|DataByte|DataObject string? | byte[]? | [object]?(可选)#

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

    • FailOnStatusCode bool?(可选)#

      对于非 2xx 和 3xx 的响应代码是否抛出异常。默认情况下,所有状态码都会返回响应对象。

    • Form FormData?(可选)#

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

      可以通过 ApiRequestContext.CreateFormData 创建 FormData 的实例。

    • Headers IDictionary?<string, string>(可选)#

      允许设置 HTTP 标头。这些标头将应用于所获取的请求以及由其发起的任何重定向。

    • IgnoreHTTPSErrors bool?(可选)#

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

    • MaxRedirects int?(可选) 新增于:v1.26#

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

    • MaxRetries int?(可选) 新增于:v1.46#

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

    • Method string?(可选)#

      如果设置,则更改获取方法(例如 PUTPOST)。如果未指定,则使用 GET 方法。

    • Multipart FormData?(可选)#

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

      可以通过 ApiRequestContext.CreateFormData 创建 FormData 的实例。

    • Params IDictionary?<string, [object]>(可选)#

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

    • ParamsString string?(可选) 新增于:v1.47#

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

    • Timeout [float]?(可选)#

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

返回值


GetAsync

新增于:v1.16 apiRequestContext.GetAsync

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

用法

请求参数可以使用 params 选项进行配置,它们将被序列化为 URL 的查询参数:

var queryParams = new Dictionary<string, object>()
{
{ "isbn", "1234" },
{ "page", 23 },
};
await request.GetAsync("https://example.com/api/getText", new() { Params = queryParams });

参数

  • url string#

    目标 URL。

  • options ApiRequestContextGetOptions?(可选)

    • Data|DataByte|DataObject string? | byte? | [object]?(可选) 新增于:v1.26#

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

    • FailOnStatusCode bool?(可选)#

      对于非 2xx 和 3xx 的响应代码是否抛出异常。默认情况下,所有状态码都会返回响应对象。

    • Form FormData?(可选) 新增于:v1.26#

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

      可以通过 ApiRequestContext.CreateFormData 创建 FormData 的实例。

    • Headers IDictionary?<string, string>(可选)#

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

    • IgnoreHTTPSErrors bool?(可选)#

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

    • MaxRedirects int?(可选) 新增于:v1.26#

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

    • MaxRetries int?(可选) 新增于:v1.46#

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

    • Multipart FormData?(可选) 新增于:v1.26#

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

      可以通过 ApiRequestContext.CreateFormData 创建 FormData 的实例。

    • Params IDictionary?<string, [object]>(可选)#

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

    • ParamsString string?(可选) 新增于:v1.47#

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

    • Timeout [float]?(可选)#

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

返回值


HeadAsync

新增于:v1.16 apiRequestContext.HeadAsync

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

用法

await ApiRequestContext.HeadAsync(url, options);

参数

  • url string#

    目标 URL。

  • options ApiRequestContextHeadOptions?(可选)

    • Data|DataByte|DataObject string? | byte? | [object]?(可选) 新增于:v1.26#

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

    • FailOnStatusCode bool?(可选)#

      对于非 2xx 和 3xx 的响应代码是否抛出异常。默认情况下,所有状态码都会返回响应对象。

    • Form FormData?(可选) 新增于:v1.26#

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

      可以通过 ApiRequestContext.CreateFormData 创建 FormData 的实例。

    • Headers IDictionary?<string, string>(可选)#

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

    • IgnoreHTTPSErrors bool?(可选)#

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

    • MaxRedirects int?(可选) 新增于:v1.26#

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

    • MaxRetries int?(可选) 新增于:v1.46#

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

    • Multipart FormData?(可选) 新增于:v1.26#

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

      可以通过 ApiRequestContext.CreateFormData 创建 FormData 的实例。

    • Params IDictionary?<string, [object]>(可选)#

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

    • ParamsString string?(可选) 新增于:v1.47#

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

    • Timeout [float]?(可选)#

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

返回值


PatchAsync

新增于:v1.16 apiRequestContext.PatchAsync

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

用法

await ApiRequestContext.PatchAsync(url, options);

参数

  • url string#

    目标 URL。

  • options ApiRequestContextPatchOptions?(可选)

    • Data|DataByte|DataObject string? | byte? | [object]?(可选)#

      允许设置请求的 POST 数据。如果 data 参数是一个对象,它将被序列化为 JSON 字符串,并且如果未显式设置,content-type 标头将被设置为 application/json。否则,如果未显式设置,content-type 标头将被设置为 application/octet-stream

    • FailOnStatusCode bool?(可选)#

      对于 2xx 和 3xx 以外的响应代码是否抛出异常。默认情况下,所有状态码都会返回响应对象。

    • Form FormData?(可选)#

      提供一个对象,该对象将使用 application/x-www-form-urlencoded 编码序列化为 HTML 表单,并作为此请求体发送。如果指定了此参数,除非显式提供,否则 content-type 标头将设置为 application/x-www-form-urlencoded

      可以通过 ApiRequestContext.CreateFormData 创建 FormData 的实例。

    • Headers IDictionary?<string, string>(可选)#

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

    • IgnoreHTTPSErrors bool?(可选)#

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

    • MaxRedirects int?(可选) 新增于:v1.26#

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

    • MaxRetries int?(可选) 新增于:v1.46#

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

    • Multipart FormData?(可选)#

      提供一个对象,该对象将使用 multipart/form-data 编码序列化为 HTML 表单,并作为此请求体发送。如果指定了此参数,除非显式提供,否则 content-type 标头将设置为 multipart/form-data。文件值可以作为包含文件名、MIME 类型及其内容的类似文件的对象传递。

      可以通过 ApiRequestContext.CreateFormData 创建 FormData 的实例。

    • Params IDictionary?<string, [object]>(可选)#

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

    • ParamsString string?(可选) 新增于:v1.47#

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

    • Timeout [float]?(可选)#

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

返回值


PostAsync

新增于:v1.16 apiRequestContext.PostAsync

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

用法

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

var data = new Dictionary<string, object>() {
{ "firstName", "John" },
{ "lastName", "Doe" }
};
await request.PostAsync("https://example.com/api/createBook", new() { DataObject = data });

要将表单数据发送到服务器,请使用 form 选项。其值将使用 application/x-www-form-urlencoded 编码方式编码到请求正文中(有关如何使用 multipart/form-data 表单编码方式发送文件,请参见下文):

var formData = Context.APIRequest.CreateFormData();
formData.Set("title", "Book Title");
formData.Set("body", "John Doe");
await request.PostAsync("https://example.com/api/findBook", new() { Form = formData });

在请求正文中发送文件的常见方法是使用 multipart/form-data 编码方式将其作为表单字段上传。使用 FormData 构造请求正文,并将其作为 multipart 参数传递给请求:

var file = new FilePayload()
{
Name = "f.js",
MimeType = "text/javascript",
Buffer = System.Text.Encoding.UTF8.GetBytes("console.log(2022);")
};
var multipart = Context.APIRequest.CreateFormData();
multipart.Set("fileField", file);
await request.PostAsync("https://example.com/api/uploadScript", new() { Multipart = multipart });

参数

  • url string#

    目标 URL。

  • options ApiRequestContextPostOptions?(可选)

    • Data|DataByte|DataObject string? | byte? | [object]?(可选)#

      允许设置请求的 POST 数据。如果 data 参数是一个对象,它将被序列化为 JSON 字符串,并且如果未显式设置,content-type 标头将被设置为 application/json。否则,如果未显式设置,content-type 标头将被设置为 application/octet-stream

    • FailOnStatusCode bool?(可选)#

      对于非 2xx 和 3xx 的响应代码是否抛出异常。默认情况下,所有状态码都会返回响应对象。

    • Form FormData?(可选)#

      提供一个对象,该对象将使用 application/x-www-form-urlencoded 编码序列化为 HTML 表单,并作为此请求体发送。如果指定了此参数,除非显式提供,否则 content-type 标头将设置为 application/x-www-form-urlencoded

      可以通过 ApiRequestContext.CreateFormData 创建 FormData 的实例。

    • Headers IDictionary?<string, string>(可选)#

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

    • IgnoreHTTPSErrors bool?(可选)#

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

    • MaxRedirects int?(可选) 新增于:v1.26#

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

    • MaxRetries int?(可选) 新增于:v1.46#

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

    • Multipart FormData?(可选)#

      提供一个对象,该对象将使用 multipart/form-data 编码序列化为 HTML 表单,并作为此请求体发送。如果指定了此参数,除非显式提供,否则 content-type 标头将设置为 multipart/form-data。文件值可以作为包含文件名、MIME 类型及其内容的类似文件的对象传递。

      可以通过 ApiRequestContext.CreateFormData 创建 FormData 的实例。

    • Params IDictionary?<string, [object]>(可选)#

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

    • ParamsString string?(可选) 新增于:v1.47#

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

    • Timeout [float]?(可选)#

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

返回值


PutAsync

新增于:v1.16 apiRequestContext.PutAsync

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

用法

await ApiRequestContext.PutAsync(url, options);

参数

  • url string#

    目标 URL。

  • options ApiRequestContextPutOptions?可选

    • Data|DataByte|DataObject string? | byte? | [object]?(可选#

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

    • FailOnStatusCode bool?(可选#

      对于非 2xx 和 3xx 的响应代码是否抛出异常。默认情况下,所有状态码都会返回响应对象。

    • Form FormData?(可选#

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

      可以通过 ApiRequestContext.CreateFormData 创建 FormData 的实例。

    • Headers IDictionary?<string, string>(可选#

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

    • IgnoreHTTPSErrors bool?(可选#

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

    • MaxRedirects int?(可选新增于:v1.26#

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

    • MaxRetries int?(可选新增于:v1.46#

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

    • Multipart FormData?(可选#

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

      可以通过 ApiRequestContext.CreateFormData 创建 FormData 的实例。

    • Params IDictionary?<string, [object]>(可选#

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

    • ParamsString string?(可选新增于:v1.47#

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

    • Timeout [float]?(可选#

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

返回值


StorageStateAsync

新增于:v1.16 apiRequestContext.StorageStateAsync

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

用法

await ApiRequestContext.StorageStateAsync(options);

参数

  • options ApiRequestContextStorageStateOptions? (可选)
    • IndexedDB bool? (可选) 新增于:v1.51#

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

    • Path string? (可选)#

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

返回值