APIRequestContext

此 API 用於 Web API 測試。您可以使用它來觸發 API 端點、設定微服務、準備環境或您的 e2e 測試服務。

每個 Playwright 瀏覽器 context 都與一個 APIRequestContext 實例相關聯，該實例與瀏覽器 context 共用 Cookie 儲存空間，並且可以透過 BrowserContext.request() 或 Page.request() 存取。也可以透過呼叫 APIRequest.newContext() 手動建立新的 APIRequestContext 實例。

Cookie 管理

由 BrowserContext.request() 和 Page.request() 傳回的 APIRequestContext 與對應的 BrowserContext 共用 Cookie 儲存空間。每個 API 請求都會將 Cookie 標頭填入瀏覽器 context 的值。如果 API 回應包含 Set-Cookie 標頭，它將自動更新 BrowserContext Cookie，並且從頁面發出的請求將會取得它們。這表示如果您使用此 API 登入，您的 e2e 測試將會處於登入狀態，反之亦然。

如果您希望 API 請求不干擾瀏覽器 Cookie，您應該透過呼叫 APIRequest.newContext() 建立新的 APIRequestContext。此 APIRequestContext 物件將擁有其自己隔離的 Cookie 儲存空間。

---

方法

delete

新增於：v1.16 apiRequestContext.delete

發送 HTTP(S) DELETE 請求並傳回其回應。此方法將從 context 填入請求 Cookie，並從回應更新 context Cookie。此方法將自動追蹤重新導向。

用法

APIRequestContext.delete(url);
APIRequestContext.delete(url, options);

引數

• url String#

  目標 URL。

• options RequestOptions (選用)新增於：v1.18#

  選用請求參數。

傳回

• APIResponse#

---

dispose

新增於：v1.16 apiRequestContext.dispose

由 APIRequestContext.get() 和類似方法傳回的所有回應都儲存在記憶體中，以便您稍後可以呼叫 APIResponse.body()。此方法會捨棄其所有資源，在已捨棄的 APIRequestContext 上呼叫任何方法都會擲回例外。

用法

APIRequestContext.dispose();
APIRequestContext.dispose(options);

引數

• options ApiRequestContext.DisposeOptions (選用)

  • setReason String (選用)新增於：v1.45#

    要報告給 context 捨棄中斷之操作的原因。

傳回

• void#

---

fetch

新增於：v1.16 apiRequestContext.fetch

發送 HTTP(S) 請求並傳回其回應。此方法將從 context 填入請求 Cookie，並從回應更新 context Cookie。此方法將自動追蹤重新導向。

用法

JSON 物件可以直接傳遞到請求

Map<String, Object> data = new HashMap();
data.put("title", "Book Title");
data.put("body", "John Doe");
request.fetch("https://example.com/api/createBook", RequestOptions.create().setMethod("post").setData(data));

在請求主體中發送檔案的常見方法是以 multipart/form-data 編碼將其作為表單欄位上傳，方法是指定 multipart 參數

// Pass file path to the form data constructor:
Path file = Paths.get("team.csv");
APIResponse response = request.fetch("https://example.com/api/uploadTeamList",
  RequestOptions.create().setMethod("post").setMultipart(
    FormData.create().set("fileField", file)));

// Or you can pass the file content directly as FilePayload object:
FilePayload filePayload = new FilePayload("f.js", "text/javascript",
      "console.log(2022);".getBytes(StandardCharsets.UTF_8));
APIResponse response = request.fetch("https://example.com/api/uploadScript",
  RequestOptions.create().setMethod("post").setMultipart(
    FormData.create().set("fileField", filePayload)));

引數

• urlOrRequest String | Request#

  目標 URL 或 Request 以從中取得所有參數。

• options RequestOptions (選用)新增於：v1.18#

  選用請求參數。

傳回

• APIResponse#

---

get

新增於：v1.16 apiRequestContext.get

發送 HTTP(S) GET 請求並傳回其回應。此方法將從 context 填入請求 Cookie，並從回應更新 context Cookie。此方法將自動追蹤重新導向。

用法

請求參數可以使用 params 選項進行設定，它們將序列化為 URL 搜尋參數

request.get("https://example.com/api/getText", RequestOptions.create()
  .setQueryParam("isbn", "1234")
  .setQueryParam("page", 23));

引數

• url String#

  目標 URL。

• options RequestOptions (選用)新增於：v1.18#

  選用請求參數。

傳回

• APIResponse#

---

head

新增於：v1.16 apiRequestContext.head

發送 HTTP(S) HEAD 請求並傳回其回應。此方法將從 context 填入請求 Cookie，並從回應更新 context Cookie。此方法將自動追蹤重新導向。

用法

APIRequestContext.head(url);
APIRequestContext.head(url, options);

引數

• url String#

  目標 URL。

• options RequestOptions (選用)新增於：v1.18#

  選用請求參數。

傳回

• APIResponse#

---

patch

新增於：v1.16 apiRequestContext.patch

發送 HTTP(S) PATCH 請求並傳回其回應。此方法將從 context 填入請求 Cookie，並從回應更新 context Cookie。此方法將自動追蹤重新導向。

用法

APIRequestContext.patch(url);
APIRequestContext.patch(url, options);

引數

• url String#

  目標 URL。

• options RequestOptions (選用)新增於：v1.18#

  選用請求參數。

傳回

• APIResponse#

---

post

新增於：v1.16 apiRequestContext.post

發送 HTTP(S) POST 請求並傳回其回應。此方法將從 context 填入請求 Cookie，並從回應更新 context Cookie。此方法將自動追蹤重新導向。

用法

JSON 物件可以直接傳遞到請求

Map<String, Object> data = new HashMap();
data.put("title", "Book Title");
data.put("body", "John Doe");
request.post("https://example.com/api/createBook", RequestOptions.create().setData(data));

若要將表單資料傳送到伺服器，請使用 form 選項。其值將使用 application/x-www-form-urlencoded 編碼編碼到請求主體中 (請參閱下文如何使用 multipart/form-data 表單編碼來傳送檔案)

request.post("https://example.com/api/findBook", RequestOptions.create().setForm(
    FormData.create().set("title", "Book Title").set("body", "John Doe")
));

在請求主體中傳送檔案的常見方法是以 multipart/form-data 編碼將其作為表單欄位上傳。使用 FormData 建構請求主體，並將其作為 multipart 參數傳遞給請求

// Pass file path to the form data constructor:
Path file = Paths.get("team.csv");
APIResponse response = request.post("https://example.com/api/uploadTeamList",
  RequestOptions.create().setMultipart(
    FormData.create().set("fileField", file)));

// Or you can pass the file content directly as FilePayload object:
FilePayload filePayload1 = new FilePayload("f1.js", "text/javascript",
      "console.log(2022);".getBytes(StandardCharsets.UTF_8));
APIResponse response = request.post("https://example.com/api/uploadScript",
  RequestOptions.create().setMultipart(
    FormData.create().set("fileField", filePayload)));

引數

• url String#

  目標 URL。

• options RequestOptions (選用)新增於：v1.18#

  選用請求參數。

傳回

• APIResponse#

---

put

新增於：v1.16 apiRequestContext.put

發送 HTTP(S) PUT 請求並傳回其回應。此方法將從 context 填入請求 Cookie，並從回應更新 context Cookie。此方法將自動追蹤重新導向。

用法

APIRequestContext.put(url);
APIRequestContext.put(url, options);

引數

• url String#

  目標 URL。

• options RequestOptions (選用)新增於：v1.18#

  選用請求參數。

傳回

• APIResponse#

---

storageState

新增於：v1.16 apiRequestContext.storageState

傳回此請求 context 的儲存狀態，包含目前的 Cookie 和本機儲存空間快照 (如果已傳遞至建構函式)。

用法

APIRequestContext.storageState();
APIRequestContext.storageState(options);

引數

• options ApiRequestContext.StorageStateOptions (選用)

  • setPath Path (選用)#

    儲存儲存狀態的檔案路徑。如果 setPath 是相對路徑，則會相對於目前的工作目錄解析。如果未提供路徑，仍然會傳回儲存狀態，但不會儲存到磁碟。

傳回

• String#