APIRequestContext
此 API 用於 Web API 測試。您可以使用它來觸發 API 端點、設定微服務、準備環境或服務以進行端對端測試。
每個 Playwright 瀏覽器內容都與一個 APIRequestContext 實例相關聯,該實例與瀏覽器內容共用 Cookie 儲存空間,並且可以透過 browser_context.request 或 page.request 存取。也可以透過呼叫 api_request.new_context() 手動建立新的 APIRequestContext 實例。
Cookie 管理
由 browser_context.request 和 page.request 傳回的 APIRequestContext 與對應的 BrowserContext 共用 Cookie 儲存空間。每個 API 請求都會具有 Cookie
標頭,其中填入來自瀏覽器內容的值。如果 API 回應包含 Set-Cookie
標頭,它將自動更新 BrowserContext Cookie,並且從頁面發出的請求將會提取它們。這表示如果您使用此 API 登入,您的端對端測試將會處於登入狀態,反之亦然。
如果您希望 API 請求不干擾瀏覽器 Cookie,您應該透過呼叫 api_request.new_context() 建立新的 APIRequestContext。此類 APIRequestContext
物件將具有其自己的隔離 Cookie 儲存空間。
- 同步
- 非同步
import os
from playwright.sync_api import sync_playwright
REPO = "test-repo-1"
USER = "github-username"
API_TOKEN = os.getenv("GITHUB_API_TOKEN")
with sync_playwright() as p:
# This will launch a new browser, create a context and page. When making HTTP
# requests with the internal APIRequestContext (e.g. `context.request` or `page.request`)
# it will automatically set the cookies to the browser page and vice versa.
browser = p.chromium.launch()
context = browser.new_context(base_url="https://api.github.com")
api_request_context = context.request
page = context.new_page()
# Alternatively you can create a APIRequestContext manually without having a browser context attached:
# api_request_context = p.request.new_context(base_url="https://api.github.com")
# Create a repository.
response = api_request_context.post(
"/user/repos",
headers={
"Accept": "application/vnd.github.v3+json",
# Add GitHub personal access token.
"Authorization": f"token {API_TOKEN}",
},
data={"name": REPO},
)
assert response.ok
assert response.json()["name"] == REPO
# Delete a repository.
response = api_request_context.delete(
f"/repos/{USER}/{REPO}",
headers={
"Accept": "application/vnd.github.v3+json",
# Add GitHub personal access token.
"Authorization": f"token {API_TOKEN}",
},
)
assert response.ok
assert await response.body() == '{"status": "ok"}'
import os
import asyncio
from playwright.async_api import async_playwright, Playwright
REPO = "test-repo-1"
USER = "github-username"
API_TOKEN = os.getenv("GITHUB_API_TOKEN")
async def run(playwright: Playwright):
# This will launch a new browser, create a context and page. When making HTTP
# requests with the internal APIRequestContext (e.g. `context.request` or `page.request`)
# it will automatically set the cookies to the browser page and vice versa.
browser = await playwright.chromium.launch()
context = await browser.new_context(base_url="https://api.github.com")
api_request_context = context.request
page = await context.new_page()
# Alternatively you can create a APIRequestContext manually without having a browser context attached:
# api_request_context = await playwright.request.new_context(base_url="https://api.github.com")
# Create a repository.
response = await api_request_context.post(
"/user/repos",
headers={
"Accept": "application/vnd.github.v3+json",
# Add GitHub personal access token.
"Authorization": f"token {API_TOKEN}",
},
data={"name": REPO},
)
assert response.ok
assert response.json()["name"] == REPO
# Delete a repository.
response = await api_request_context.delete(
f"/repos/{USER}/{REPO}",
headers={
"Accept": "application/vnd.github.v3+json",
# Add GitHub personal access token.
"Authorization": f"token {API_TOKEN}",
},
)
assert response.ok
assert await response.body() == '{"status": "ok"}'
async def main():
async with async_playwright() as playwright:
await run(playwright)
asyncio.run(main())
方法
delete
新增於:v1.16傳送 HTTP(S) DELETE 請求並傳回其回應。此方法將會從內容填入請求 Cookie,並從回應更新內容 Cookie。此方法將會自動追蹤重新導向。
用法
api_request_context.delete(url)
api_request_context.delete(url, **kwargs)
引數
-
目標 URL。
-
data
str | bytes | Serializable (選用)新增於:v1.17#允許設定請求的 post 資料。如果 data 參數是物件,它將會序列化為 json 字串,並且如果未明確設定,
content-type
標頭將會設定為application/json
。否則,如果未明確設定,content-type
標頭將會設定為application/octet-stream
。 -
fail_on_status_code
bool (選用)#是否在 2xx 和 3xx 以外的回應代碼上擲回例外。預設會針對所有狀態代碼傳回回應物件。
-
form
Dict[str, str | float | bool] (選用)新增於:v1.17#提供一個物件,該物件將使用
application/x-www-form-urlencoded
編碼序列化為 html 表單,並作為此請求的主體傳送。如果指定此參數,除非明確提供,否則content-type
標頭將會設定為application/x-www-form-urlencoded
。 -
允許設定 HTTP 標頭。這些標頭將適用於擷取的請求以及由此請求啟動的任何重新導向。
-
ignore_https_errors
bool (選用)#是否在傳送網路請求時忽略 HTTPS 錯誤。預設為
false
。 -
max_redirects
int (選用)新增於:v1.26#將自動追蹤的最大請求重新導向次數。如果超過次數,將會擲回錯誤。預設為
20
。傳遞0
以不追蹤重新導向。 -
max_retries
int (選用)新增於:v1.46#應重試網路錯誤的最大次數。目前僅重試
ECONNRESET
錯誤。不會根據 HTTP 回應代碼重試。如果超過限制,將會擲回錯誤。預設為0
- 不重試。 -
multipart
Dict[str, str | float | bool | [ReadStream] | Dict] (選用)新增於:v1.17#提供一個物件,該物件將使用
multipart/form-data
編碼序列化為 html 表單,並作為此請求的主體傳送。如果指定此參數,除非明確提供,否則content-type
標頭將會設定為multipart/form-data
。檔案值可以作為包含檔案名稱、mime 類型及其內容的類檔案物件傳遞。 -
params
Dict[str, str | float | bool] | str (選用)#要與 URL 一起傳送的查詢參數。
-
請求逾時時間,以毫秒為單位。預設為
30000
(30 秒)。傳遞0
以停用逾時。
傳回
dispose
新增於:v1.16由 api_request_context.get() 和類似方法傳回的所有回應都儲存在記憶體中,以便您稍後可以呼叫 api_response.body()。此方法會捨棄其所有資源,在已處置的 APIRequestContext 上呼叫任何方法都會擲回例外。
用法
api_request_context.dispose()
api_request_context.dispose(**kwargs)
引數
傳回
fetch
新增於:v1.16傳送 HTTP(S) 請求並傳回其回應。此方法將會從內容填入請求 Cookie,並從回應更新內容 Cookie。此方法將會自動追蹤重新導向。
用法
JSON 物件可以直接傳遞到請求
data = {
"title": "Book Title",
"body": "John Doe",
}
api_request_context.fetch("https://example.com/api/createBook", method="post", data=data)
在請求主體中傳送檔案的常用方法是以 multipart/form-data
編碼將其作為表單欄位上傳,方法是指定 multipart
參數
api_request_context.fetch(
"https://example.com/api/uploadScript", method="post",
multipart={
"fileField": {
"name": "f.js",
"mimeType": "text/javascript",
"buffer": b"console.log(2022);",
},
})
引數
-
目標 URL 或 Request,用於從中取得所有參數。
-
data
str | bytes | Serializable (選用)#允許設定請求的 post 資料。如果 data 參數是物件,它將會序列化為 json 字串,並且如果未明確設定,
content-type
標頭將會設定為application/json
。否則,如果未明確設定,content-type
標頭將會設定為application/octet-stream
。 -
fail_on_status_code
bool (選用)#是否在 2xx 和 3xx 以外的回應代碼上擲回例外。預設會針對所有狀態代碼傳回回應物件。
-
form
Dict[str, str | float | bool] (選用)#提供一個物件,該物件將使用
application/x-www-form-urlencoded
編碼序列化為 html 表單,並作為此請求的主體傳送。如果指定此參數,除非明確提供,否則content-type
標頭將會設定為application/x-www-form-urlencoded
。 -
允許設定 HTTP 標頭。這些標頭將適用於擷取的請求以及由此請求啟動的任何重新導向。
-
ignore_https_errors
bool (選用)#是否在傳送網路請求時忽略 HTTPS 錯誤。預設為
false
。 -
max_redirects
int (選用)新增於:v1.26#將自動追蹤的最大請求重新導向次數。如果超過次數,將會擲回錯誤。預設為
20
。傳遞0
以不追蹤重新導向。 -
max_retries
int (選用)新增於:v1.46#應重試網路錯誤的最大次數。目前僅重試
ECONNRESET
錯誤。不會根據 HTTP 回應代碼重試。如果超過限制,將會擲回錯誤。預設為0
- 不重試。 -
multipart
Dict[str, str | float | bool | [ReadStream] | Dict] (選用)#提供一個物件,該物件將使用
multipart/form-data
編碼序列化為 html 表單,並作為此請求的主體傳送。如果指定此參數,除非明確提供,否則content-type
標頭將會設定為multipart/form-data
。檔案值可以作為包含檔案名稱、mime 類型及其內容的類檔案物件傳遞。 -
params
Dict[str, str | float | bool] | str (選用)#要與 URL 一起傳送的查詢參數。
-
請求逾時時間,以毫秒為單位。預設為
30000
(30 秒)。傳遞0
以停用逾時。
傳回
get
新增於:v1.16傳送 HTTP(S) GET 請求並傳回其回應。此方法將會從內容填入請求 Cookie,並從回應更新內容 Cookie。此方法將會自動追蹤重新導向。
用法
可以使用 params
選項設定請求參數,它們將會序列化為 URL 搜尋參數
query_params = {
"isbn": "1234",
"page": "23"
}
api_request_context.get("https://example.com/api/getText", params=query_params)
引數
-
目標 URL。
-
data
str | bytes | Serializable (選用)新增於:v1.26#允許設定請求的 post 資料。如果 data 參數是物件,它將會序列化為 json 字串,並且如果未明確設定,
content-type
標頭將會設定為application/json
。否則,如果未明確設定,content-type
標頭將會設定為application/octet-stream
。 -
fail_on_status_code
bool (選用)#是否在 2xx 和 3xx 以外的回應代碼上擲回例外。預設會針對所有狀態代碼傳回回應物件。
-
form
Dict[str, str | float | bool] (選用)新增於:v1.26#提供一個物件,該物件將使用
application/x-www-form-urlencoded
編碼序列化為 html 表單,並作為此請求的主體傳送。如果指定此參數,除非明確提供,否則content-type
標頭將會設定為application/x-www-form-urlencoded
。 -
允許設定 HTTP 標頭。這些標頭將適用於擷取的請求以及由此請求啟動的任何重新導向。
-
ignore_https_errors
bool (選用)#是否在傳送網路請求時忽略 HTTPS 錯誤。預設為
false
。 -
max_redirects
int (選用)新增於:v1.26#將自動追蹤的最大請求重新導向次數。如果超過次數,將會擲回錯誤。預設為
20
。傳遞0
以不追蹤重新導向。 -
max_retries
int (選用)新增於:v1.46#應重試網路錯誤的最大次數。目前僅重試
ECONNRESET
錯誤。不會根據 HTTP 回應代碼重試。如果超過限制,將會擲回錯誤。預設為0
- 不重試。 -
multipart
Dict[str, str | float | bool | [ReadStream] | Dict] (選用)新增於:v1.26#提供一個物件,該物件將使用
multipart/form-data
編碼序列化為 html 表單,並作為此請求的主體傳送。如果指定此參數,除非明確提供,否則content-type
標頭將會設定為multipart/form-data
。檔案值可以作為包含檔案名稱、mime 類型及其內容的類檔案物件傳遞。 -
params
Dict[str, str | float | bool] | str (選用)#要與 URL 一起傳送的查詢參數。
-
請求逾時時間,以毫秒為單位。預設為
30000
(30 秒)。傳遞0
以停用逾時。
傳回
head
新增於:v1.16傳送 HTTP(S) HEAD 請求並傳回其回應。此方法將會從內容填入請求 Cookie,並從回應更新內容 Cookie。此方法將會自動追蹤重新導向。
用法
api_request_context.head(url)
api_request_context.head(url, **kwargs)
引數
-
目標 URL。
-
data
str | bytes | Serializable (選用)新增於:v1.26#允許設定請求的 post 資料。如果 data 參數是物件,它將會序列化為 json 字串,並且如果未明確設定,
content-type
標頭將會設定為application/json
。否則,如果未明確設定,content-type
標頭將會設定為application/octet-stream
。 -
fail_on_status_code
bool (選用)#是否在 2xx 和 3xx 以外的回應代碼上擲回例外。預設會針對所有狀態代碼傳回回應物件。
-
form
Dict[str, str | float | bool] (選用)新增於:v1.26#提供一個物件,該物件將使用
application/x-www-form-urlencoded
編碼序列化為 html 表單,並作為此請求的主體傳送。如果指定此參數,除非明確提供,否則content-type
標頭將會設定為application/x-www-form-urlencoded
。 -
允許設定 HTTP 標頭。這些標頭將適用於擷取的請求以及由此請求啟動的任何重新導向。
-
ignore_https_errors
bool (選用)#是否在傳送網路請求時忽略 HTTPS 錯誤。預設為
false
。 -
max_redirects
int (選用)新增於:v1.26#將自動追蹤的最大請求重新導向次數。如果超過次數,將會擲回錯誤。預設為
20
。傳遞0
以不追蹤重新導向。 -
max_retries
int (選用)新增於:v1.46#應重試網路錯誤的最大次數。目前僅重試
ECONNRESET
錯誤。不會根據 HTTP 回應代碼重試。如果超過限制,將會擲回錯誤。預設為0
- 不重試。 -
multipart
Dict[str, str | float | bool | [ReadStream] | Dict] (選用)新增於:v1.26#提供一個物件,該物件將使用
multipart/form-data
編碼序列化為 html 表單,並作為此請求的主體傳送。如果指定此參數,除非明確提供,否則content-type
標頭將會設定為multipart/form-data
。檔案值可以作為包含檔案名稱、mime 類型及其內容的類檔案物件傳遞。 -
params
Dict[str, str | float | bool] | str (選用)#要與 URL 一起傳送的查詢參數。
-
請求逾時時間,以毫秒為單位。預設為
30000
(30 秒)。傳遞0
以停用逾時。
傳回
patch
新增於:v1.16傳送 HTTP(S) PATCH 請求並傳回其回應。此方法將會從內容填入請求 Cookie,並從回應更新內容 Cookie。此方法將會自動追蹤重新導向。
用法
api_request_context.patch(url)
api_request_context.patch(url, **kwargs)
引數
-
目標 URL。
-
data
str | bytes | Serializable (選用)#允許設定請求的 post 資料。如果 data 參數是物件,它將會序列化為 json 字串,並且如果未明確設定,
content-type
標頭將會設定為application/json
。否則,如果未明確設定,content-type
標頭將會設定為application/octet-stream
。 -
fail_on_status_code
bool (選用)#是否在 2xx 和 3xx 以外的回應代碼上擲回例外。預設會針對所有狀態代碼傳回回應物件。
-
form
Dict[str, str | float | bool] (選用)#提供一個物件,該物件將使用
application/x-www-form-urlencoded
編碼序列化為 html 表單,並作為此請求的主體傳送。如果指定此參數,除非明確提供,否則content-type
標頭將會設定為application/x-www-form-urlencoded
。 -
允許設定 HTTP 標頭。這些標頭將適用於擷取的請求以及由此請求啟動的任何重新導向。
-
ignore_https_errors
bool (選用)#是否在傳送網路請求時忽略 HTTPS 錯誤。預設為
false
。 -
max_redirects
int (選用)新增於:v1.26#將自動追蹤的最大請求重新導向次數。如果超過次數,將會擲回錯誤。預設為
20
。傳遞0
以不追蹤重新導向。 -
max_retries
int (選用)新增於:v1.46#應重試網路錯誤的最大次數。目前僅重試
ECONNRESET
錯誤。不會根據 HTTP 回應代碼重試。如果超過限制,將會擲回錯誤。預設為0
- 不重試。 -
multipart
Dict[str, str | float | bool | [ReadStream] | Dict] (選用)#提供一個物件,該物件將使用
multipart/form-data
編碼序列化為 html 表單,並作為此請求的主體傳送。如果指定此參數,除非明確提供,否則content-type
標頭將會設定為multipart/form-data
。檔案值可以作為包含檔案名稱、mime 類型及其內容的類檔案物件傳遞。 -
params
Dict[str, str | float | bool] | str (選用)#要與 URL 一起傳送的查詢參數。
-
請求逾時時間,以毫秒為單位。預設為
30000
(30 秒)。傳遞0
以停用逾時。
傳回
post
新增於:v1.16傳送 HTTP(S) POST 請求並傳回其回應。此方法將會從內容填入請求 Cookie,並從回應更新內容 Cookie。此方法將會自動追蹤重新導向。
用法
JSON 物件可以直接傳遞到請求
data = {
"title": "Book Title",
"body": "John Doe",
}
api_request_context.post("https://example.com/api/createBook", data=data)
若要將表單資料傳送至伺服器,請使用 form
選項。其值將會使用 application/x-www-form-urlencoded
編碼編碼到請求主體中 (請參閱下方如何使用 multipart/form-data
表單編碼來傳送檔案)
formData = {
"title": "Book Title",
"body": "John Doe",
}
api_request_context.post("https://example.com/api/findBook", form=formData)
在請求主體中傳送檔案的常用方法是以 multipart/form-data
編碼將其作為表單欄位上傳。使用 [FormData] 建構請求主體,並將其作為 multipart
參數傳遞至請求
api_request_context.post(
"https://example.com/api/uploadScript'",
multipart={
"fileField": {
"name": "f.js",
"mimeType": "text/javascript",
"buffer": b"console.log(2022);",
},
})
引數
-
目標 URL。
-
data
str | bytes | Serializable (選用)#允許設定請求的 post 資料。如果 data 參數是物件,它將會序列化為 json 字串,並且如果未明確設定,
content-type
標頭將會設定為application/json
。否則,如果未明確設定,content-type
標頭將會設定為application/octet-stream
。 -
fail_on_status_code
bool (選用)#是否在 2xx 和 3xx 以外的回應代碼上擲回例外。預設會針對所有狀態代碼傳回回應物件。
-
form
Dict[str, str | float | bool] (選用)#提供一個物件,該物件將使用
application/x-www-form-urlencoded
編碼序列化為 html 表單,並作為此請求的主體傳送。如果指定此參數,除非明確提供,否則content-type
標頭將會設定為application/x-www-form-urlencoded
。 -
允許設定 HTTP 標頭。這些標頭將適用於擷取的請求以及由此請求啟動的任何重新導向。
-
ignore_https_errors
bool (選用)#是否在傳送網路請求時忽略 HTTPS 錯誤。預設為
false
。 -
max_redirects
int (選用)新增於:v1.26#將自動追蹤的最大請求重新導向次數。如果超過次數,將會擲回錯誤。預設為
20
。傳遞0
以不追蹤重新導向。 -
max_retries
int (選用)新增於:v1.46#應重試網路錯誤的最大次數。目前僅重試
ECONNRESET
錯誤。不會根據 HTTP 回應代碼重試。如果超過限制,將會擲回錯誤。預設為0
- 不重試。 -
multipart
Dict[str, str | float | bool | [ReadStream] | Dict] (選用)#提供一個物件,該物件將使用
multipart/form-data
編碼序列化為 html 表單,並作為此請求的主體傳送。如果指定此參數,除非明確提供,否則content-type
標頭將會設定為multipart/form-data
。檔案值可以作為包含檔案名稱、mime 類型及其內容的類檔案物件傳遞。 -
params
Dict[str, str | float | bool] | str (選用)#要與 URL 一起傳送的查詢參數。
-
請求逾時時間,以毫秒為單位。預設為
30000
(30 秒)。傳遞0
以停用逾時。
傳回
put
新增於:v1.16傳送 HTTP(S) PUT 請求並傳回其回應。此方法將會從內容填入請求 Cookie,並從回應更新內容 Cookie。此方法將會自動追蹤重新導向。
用法
api_request_context.put(url)
api_request_context.put(url, **kwargs)
引數
-
目標 URL。
-
data
str | bytes | Serializable (選用)#允許設定請求的 post 資料。如果 data 參數是物件,它將會序列化為 json 字串,並且如果未明確設定,
content-type
標頭將會設定為application/json
。否則,如果未明確設定,content-type
標頭將會設定為application/octet-stream
。 -
fail_on_status_code
bool (選用)#是否在 2xx 和 3xx 以外的回應代碼上擲回例外。預設會針對所有狀態代碼傳回回應物件。
-
form
Dict[str, str | float | bool] (選用)提供一個物件,該物件將使用
application/x-www-form-urlencoded
編碼序列化為 html 表單,並作為此請求的主體傳送。如果指定此參數,除非明確提供,否則content-type
標頭將會設定為application/x-www-form-urlencoded
。 -
允許設定 HTTP 標頭。這些標頭將適用於擷取的請求以及由此請求啟動的任何重新導向。
-
ignore_https_errors
bool (選填)#是否在傳送網路請求時忽略 HTTPS 錯誤。預設為
false
。 -
max_redirects
int (選用)新增於:v1.26#將自動追蹤的最大請求重新導向次數。如果超過次數,將會擲回錯誤。預設為
20
。傳遞0
以不追蹤重新導向。 -
max_retries
int (選用)新增於:v1.46#應重試網路錯誤的最大次數。目前僅重試
ECONNRESET
錯誤。不會根據 HTTP 回應代碼重試。如果超過限制,將會擲回錯誤。預設為0
- 不重試。 -
multipart
Dict[str, str | float | bool | [ReadStream] | Dict] (選填)#提供一個物件,該物件將使用
multipart/form-data
編碼序列化為 html 表單,並作為此請求的主體傳送。如果指定此參數,除非明確提供,否則content-type
標頭將會設定為multipart/form-data
。檔案值可以作為包含檔案名稱、mime 類型及其內容的類檔案物件傳遞。 -
params
Dict[str, str | float | bool] | str (選填)#要與 URL 一起傳送的查詢參數。
-
請求逾時時間,以毫秒為單位。預設為
30000
(30 秒)。傳遞0
以停用逾時。
傳回
storage_state
新增於:v1.16傳回此請求上下文的儲存狀態,如果已傳遞至建構函式,則包含目前的 Cookie 和本機儲存體快照。
用法
api_request_context.storage_state()
api_request_context.storage_state(**kwargs)
引數
-
path
Union[str, pathlib.Path] (選填)#儲存儲存狀態的檔案路徑。如果 path 是相對路徑,則會相對於目前的工作目錄解析。如果未提供路徑,儲存狀態仍會傳回,但不會儲存到磁碟。
傳回