APIRequestContext
此 API 用于 Web API 测试。你可以使用它来触发 API 端点、配置微服务、为端到端测试准备环境或服务。
每个 Playwright 浏览器上下文都关联有一个 APIRequestContext 实例,该实例与浏览器上下文共享 cookie 存储,并且可以通过 BrowserContext.APIRequest 或 Page.APIRequest 进行访问。也可以通过调用 ApiRequest.NewContextAsync() 手动创建一个新的 APIRequestContext 实例。
Cookie 管理
由 BrowserContext.APIRequest 和 Page.APIRequest 返回的 APIRequestContext 与相应的 BrowserContext 共享 cookie 存储。每个 API 请求的 Cookie
标头都将填充来自浏览器上下文的值。如果 API 响应包含 Set-Cookie
标头,它将自动更新 BrowserContext 的 cookie,并且从页面发出的请求将获取这些 cookie。这意味着,如果你使用此 API 登录,你的端到端测试也将处于登录状态,反之亦然。
如果你希望 API 请求不干扰浏览器的 cookie,你应该通过调用 ApiRequest.NewContextAsync() 创建一个新的 APIRequestContext。这样的 APIRequestContext
对象将拥有自己独立的 cookie 存储。
方法
CreateFormData
添加于:v1.23创建一个新的 FormData 实例,该实例用于在发出 HTTP 请求时提供表单和多部分数据。
用法
ApiRequestContext.CreateFormData
返回值
DeleteAsync
新增于:v1.16发送 HTTP(S) DELETE 请求并返回其响应。此方法将从上下文中填充请求 cookie,并根据响应更新上下文 cookie。该方法将自动跟随重定向。
用法
await ApiRequestContext.DeleteAsync(url, options);
参数
-
目标 URL。
-
options
ApiRequestContextDeleteOptions?
(可选)-
Data|DataByte|DataObject
string? | byte? | [object]?(可选) 新增于:v1.17#允许设置请求的 POST 数据。如果
data
参数是一个对象,它将被序列化为 JSON 字符串,并且如果未显式设置,content-type
标头将被设置为application/json
。否则,如果未显式设置,content-type
标头将被设置为application/octet-stream
。 -
对于非 2xx 和 3xx 的响应代码是否抛出异常。默认情况下,所有状态码都会返回响应对象。
-
提供一个对象,该对象将使用
application/x-www-form-urlencoded
编码序列化为 HTML 表单,并作为此请求体发送。如果指定了此参数,除非显式提供,否则content-type
标头将设置为application/x-www-form-urlencoded
。可以通过 ApiRequestContext.CreateFormData 创建 FormData 的实例。
-
Headers
IDictionary?<string, string>(可选)#允许设置 HTTP 标头。这些标头将应用于获取的请求以及由其发起的任何重定向。
-
发送网络请求时是否忽略 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.16ApiRequestContext.GetAsync() 及类似方法返回的所有响应都会存储在内存中,以便后续调用 ApiResponse.BodyAsync()。此方法会释放其所有资源,对已释放的 APIRequestContext 调用任何方法都会抛出异常。
用法
await ApiRequestContext.DisposeAsync(options);
参数
返回值
FetchAsync
新增于:v1.16发送 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
。 -
对于非 2xx 和 3xx 的响应代码是否抛出异常。默认情况下,所有状态码都会返回响应对象。
-
提供一个对象,该对象将使用
application/x-www-form-urlencoded
编码序列化为 HTML 表单,并作为此请求体发送。如果指定了此参数,除非明确提供,否则content-type
标头将设置为application/x-www-form-urlencoded
。可以通过 ApiRequestContext.CreateFormData 创建 FormData 的实例。
-
Headers
IDictionary?<string, string>(可选)#允许设置 HTTP 标头。这些标头将应用于所获取的请求以及由其发起的任何重定向。
-
发送网络请求时是否忽略 HTTPS 错误。默认为
false
。 -
MaxRedirects
int?(可选) 新增于:v1.26#将自动跟随的请求重定向的最大数量。如果超过此数量,将抛出错误。默认为
20
。传递0
表示不跟随重定向。 -
MaxRetries
int?(可选) 新增于:v1.46#网络错误应重试的最大次数。目前仅重试
ECONNRESET
错误。不会根据 HTTP 响应代码进行重试。如果超过限制,将抛出错误。默认为0
- 不重试。 -
提供一个对象,该对象将使用
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发送 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。
-
options
ApiRequestContextGetOptions?
(可选)-
Data|DataByte|DataObject
string? | byte? | [object]?(可选) 新增于:v1.26#允许设置请求的 POST 数据。如果
data
参数是一个对象,它将被序列化为 JSON 字符串,并且如果未明确设置,content-type
标头将被设置为application/json
。否则,如果未明确设置,content-type
标头将被设置为application/octet-stream
。 -
对于非 2xx 和 3xx 的响应代码是否抛出异常。默认情况下,所有状态码都会返回响应对象。
-
提供一个对象,该对象将使用
application/x-www-form-urlencoded
编码序列化为 HTML 表单,并作为此请求体发送。如果指定了此参数,除非明确提供,否则content-type
标头将设置为application/x-www-form-urlencoded
。可以通过 ApiRequestContext.CreateFormData 创建 FormData 的实例。
-
Headers
IDictionary?<string, string>(可选)#允许设置 HTTP 标头。这些标头将应用于获取的请求以及由其发起的任何重定向。
-
发送网络请求时是否忽略 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发送 HTTP(S) HEAD 请求并返回其响应。该方法将从上下文中填充请求 cookie,并根据响应更新上下文 cookie。该方法将自动跟随重定向。
用法
await ApiRequestContext.HeadAsync(url, options);
参数
-
目标 URL。
-
options
ApiRequestContextHeadOptions?
(可选)-
Data|DataByte|DataObject
string? | byte? | [object]?(可选) 新增于:v1.26#允许设置请求的 POST 数据。如果
data
参数是一个对象,它将被序列化为 JSON 字符串,并且如果未明确设置,content-type
标头将被设置为application/json
。否则,如果未明确设置,content-type
标头将被设置为application/octet-stream
。 -
对于非 2xx 和 3xx 的响应代码是否抛出异常。默认情况下,所有状态码都会返回响应对象。
-
提供一个对象,该对象将使用
application/x-www-form-urlencoded
编码序列化为 HTML 表单,并作为此请求体发送。如果指定了此参数,除非明确提供,否则content-type
标头将设置为application/x-www-form-urlencoded
。可以通过 ApiRequestContext.CreateFormData 创建 FormData 的实例。
-
Headers
IDictionary?<string, string>(可选)#允许设置 HTTP 标头。这些标头将应用于获取的请求以及由其发起的任何重定向。
-
发送网络请求时是否忽略 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发送 HTTP(S) PATCH 请求并返回其响应。此方法将从上下文中填充请求 cookie,并根据响应更新上下文 cookie。该方法将自动跟随重定向。
用法
await ApiRequestContext.PatchAsync(url, options);
参数
-
目标 URL。
-
options
ApiRequestContextPatchOptions?
(可选)-
Data|DataByte|DataObject
string? | byte? | [object]?(可选)#允许设置请求的 POST 数据。如果
data
参数是一个对象,它将被序列化为 JSON 字符串,并且如果未显式设置,content-type
标头将被设置为application/json
。否则,如果未显式设置,content-type
标头将被设置为application/octet-stream
。 -
对于 2xx 和 3xx 以外的响应代码是否抛出异常。默认情况下,所有状态码都会返回响应对象。
-
提供一个对象,该对象将使用
application/x-www-form-urlencoded
编码序列化为 HTML 表单,并作为此请求体发送。如果指定了此参数,除非显式提供,否则content-type
标头将设置为application/x-www-form-urlencoded
。可以通过 ApiRequestContext.CreateFormData 创建 FormData 的实例。
-
Headers
IDictionary?<string, string>(可选)#允许设置 HTTP 标头。这些标头将应用于获取的请求以及由其发起的任何重定向。
-
发送网络请求时是否忽略 HTTPS 错误。默认为
false
。 -
MaxRedirects
int?(可选) 新增于:v1.26#将自动跟随的请求重定向的最大数量。如果超过此数量,将抛出错误。默认为
20
。传递0
以不跟随重定向。 -
MaxRetries
int?(可选) 新增于:v1.46#网络错误应重试的最大次数。目前仅重试
ECONNRESET
错误。不会根据 HTTP 响应代码进行重试。如果超过限制,将抛出错误。默认为0
- 不重试。 -
提供一个对象,该对象将使用
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发送 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。
-
options
ApiRequestContextPostOptions?
(可选)-
Data|DataByte|DataObject
string? | byte? | [object]?(可选)#允许设置请求的 POST 数据。如果
data
参数是一个对象,它将被序列化为 JSON 字符串,并且如果未显式设置,content-type
标头将被设置为application/json
。否则,如果未显式设置,content-type
标头将被设置为application/octet-stream
。 -
对于非 2xx 和 3xx 的响应代码是否抛出异常。默认情况下,所有状态码都会返回响应对象。
-
提供一个对象,该对象将使用
application/x-www-form-urlencoded
编码序列化为 HTML 表单,并作为此请求体发送。如果指定了此参数,除非显式提供,否则content-type
标头将设置为application/x-www-form-urlencoded
。可以通过 ApiRequestContext.CreateFormData 创建 FormData 的实例。
-
Headers
IDictionary?<string, string>(可选)#允许设置 HTTP 标头。这些标头将应用于获取的请求以及由其发起的任何重定向。
-
发送网络请求时是否忽略 HTTPS 错误。默认为
false
。 -
MaxRedirects
int?(可选) 新增于:v1.26#将自动跟随的请求重定向的最大数量。如果超过此数量,将抛出错误。默认为
20
。传递0
以不跟随重定向。 -
MaxRetries
int?(可选) 新增于:v1.46#网络错误应重试的最大次数。目前仅重试
ECONNRESET
错误。不会根据 HTTP 响应代码进行重试。如果超过限制,将抛出错误。默认为0
- 不重试。 -
提供一个对象,该对象将使用
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发送 HTTP(S) PUT 请求并返回其响应。此方法将从上下文中填充请求 cookie,并根据响应更新上下文 cookie。该方法将自动跟随重定向。
用法
await ApiRequestContext.PutAsync(url, options);
参数
-
目标 URL。
-
options
ApiRequestContextPutOptions?
(可选)-
Data|DataByte|DataObject
string? | byte? | [object]?(可选)#允许设置请求的 POST 数据。如果
data
参数是一个对象,它将被序列化为 JSON 字符串,并且如果未明确设置,content-type
标头将被设置为application/json
。否则,如果未明确设置,content-type
标头将被设置为application/octet-stream
。 -
对于非 2xx 和 3xx 的响应代码是否抛出异常。默认情况下,所有状态码都会返回响应对象。
-
提供一个对象,该对象将使用
application/x-www-form-urlencoded
编码序列化为 HTML 表单,并作为此请求体发送。如果指定了此参数,除非明确提供,否则content-type
标头将设置为application/x-www-form-urlencoded
。可以通过 ApiRequestContext.CreateFormData 创建 FormData 的实例。
-
Headers
IDictionary?<string, string>(可选)#允许设置 HTTP 标头。这些标头将应用于获取的请求以及由其发起的任何重定向。
-
发送网络请求时是否忽略 HTTPS 错误。默认为
false
。 -
MaxRedirects
int?(可选) 新增于:v1.26#将自动跟随的请求重定向的最大数量。如果超过此数量,将抛出错误。默认为
20
。传递0
以不跟随重定向。 -
MaxRetries
int?(可选) 新增于:v1.46#网络错误应重试的最大次数。目前仅重试
ECONNRESET
错误。不会基于 HTTP 响应代码进行重试。如果超过限制,将抛出错误。默认为0
- 不重试。 -
提供一个对象,该对象将使用
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返回此请求上下文的存储状态,包含当前的 cookies 和传递给构造函数的本地存储快照。
用法
await ApiRequestContext.StorageStateAsync(options);
参数
options
ApiRequestContextStorageStateOptions?
(可选)
返回值