2024年02月02日玄貓（BlackCat）

Karate API 測試入門

本文介紹如何使用 Karate 框架進行 API 測試，涵蓋設定 Maven 專案、編寫基礎測試案例、驗證 JSON 回應等內容。文章以 JSONPlaceholder API 為例，示範如何使用 Karate 的關鍵字，例如 url、path、param、method、status 和

Web 開發測試

API 測試 Karate JSON Maven REST API Postman

Karate 是一個根據 Cucumber 的 API 測試框架，它結合了 BDD 的易讀性和 API 測試的靈活性。透過簡單的 Gherkin 語法，開發者和測試人員都能輕鬆撰寫和理解測試案例。本文將引導讀者從設定 Karate 專案開始，逐步學習如何編寫基礎的 API 測試，包含設定 URL、路徑、引數，傳送不同 HTTP 方法的請求，以及驗證回應的狀態碼和 JSON 內容。此外，還會介紹如何使用 Postman 探索 API，以及在 VS Code 中設定 Karate 外掛，簡化測試流程並提升效率。這些技巧能協助團隊更有效率地進行 API 測試，確保軟體品質。

設定您的 Karate 專案

使用 Maven 設定 Karate 專案

在建立 Karate 專案時，Maven 是一個非常有用的工具。Maven 是一個專案管理工具，可以幫助您管理專案的依賴關係、建置和測試。

建立 Karate 專案

要建立一個新的 Karate 專案，您可以使用 Maven 的 archetype 功能。archetype 是一個範本，可以幫助您快速建立一個新的專案。

首先，您需要在 VS Code 中開啟 Maven 助理。然後，您需要選擇 karate-archetype 作為 archetype。接下來，您需要輸入一些基本資訊，例如 groupId、artifactId 和 version。


### 指定專案的 group ID
groupId 通常代表組織或公司的名稱。在本例中，我們使用 `blog.softwaretester` 作為 groupId。


### 指定 artifact ID
artifactId 通常代表專案的名稱。在本例中，我們使用 `karate-maven` 作為 artifactId。

選擇好輸出資料夾後，Maven 助理會在終端機視窗中繼續執行。它會詢問您要給專案什麼版本。如果您接受預設值 1.0-SNAPSHOT，只需按下 Enter 鍵。

[INFO] Using property: groupId = blog.softwaretester
[INFO] Using property: artifactId = karate-maven
Define value for property 'version' 1.0-SNAPSHOT: :
[INFO] Using property: package = blog.softwaretester
Confirm properties configuration:
groupId: blog.softwaretester
artifactId: karate-maven
version: 1.0-SNAPSHOT
package: blog.softwaretester
Y: :

如果您看到 BUILD SUCCESS，表示專案已成功建立。

檢查專案結構

建立好專案後，您可以在 VS Code 的 explorer 面板中看到專案的結構。專案中包含了幾個重要的檔案，例如 users.feature、UsersRunner.java、ExampleTest.java、karate-config.js 和 logback-test.xml。


### 專案檔案說明
* `users.feature`：這是一個範例測試案例，用於示範如何撰寫 Karate 測試。
* `UsersRunner.java` 和 `ExampleTest.java`：這些是測試執行器類別，用於執行 Karate 測試。
* `karate-config.js`：這是 Karate 的中央設定檔，用於設定全域變數和函式。
* `logback-test.xml`：這是 Karate 的日誌設定檔，用於設定日誌輸出。

不使用 Archetype 建立專案

雖然 Karate archetype 是一個很好的起點，但您也可以從頭開始建立一個新的 Maven 專案，並手動新增所需的依賴關係和設定。

編寫基本的 Karate 測試

在上一章完成系統準備和IDE設定後，我們現在可以進入主要主題：編寫 Karate API 測試。除了基本的 Karate 命令和結構外，我們還將仔細研究如何使測試場景更容易閱讀和更直接。當您有數十或數百個場景時，使它們盡可能可讀和易於理解尤其有益，這樣您就不必太多地思考場景的作用和資料的外觀。

本章涵蓋的主要主題

探索被測 API
呼叫端點和設定引數
匹配狀態程式碼和回應
使用有效載荷傳送請求
使用變數和資料表

技術需求

您需要以下內容：

在第2章中完成的系統和IDE設定。
Postman（可透過 https://www.postman.com/downloads 取得）用於探索我們稍後要測試的 API。

探索被測 API

編寫有效的 API 測試的第一步是探索被測 API。這可以透過閱讀 API 檔案和實際操作來完成。這樣，您就可以瞭解介面的結構以及可能存在哪些錯誤源需要自動測試。

JSONPlaceholder API

我們將在本章中使用 JSONPlaceholder API。這是一個公開可用的模擬 API，模擬了一個真實的 API。與真實的 REST 應用程式不同，這裡的資料不是動態生成的，而是傳回固定的靜態資料。這使得它非常適合用於說明一些 Karate 的概念。

使用 Postman

Postman 是與 API 互動以深入瞭解它的理想工具。如果您不想安裝或使用 Postman，也可以直接使用網頁瀏覽器進行基本的 API 探索。只需將 API URL 貼上到瀏覽器中，它就會執行 GET 呼叫並顯示您收到的資料。

建立新的 Karate 專案

讓我們按照第2章中的步驟建立一個新的 Karate 專案。我將其命名為 karate-jsonplaceholder，因為這是一個很好的描述它將要測試的內容。完成後，您應該在 VS Code 中看到一個類別似這樣的專案。

新增新的功能檔案

讓我們在 src/test/java 下新增一個新的 scenarios 資料夾，用於存放功能檔案。下一步是在該資料夾中新增一個新的功能檔案，該檔案將包含屬於相同業務案例的場景。

編寫第一個測試案例

現在，我們可以開始編寫第一個測試案例。首先，我們需要在 scenarios 資料夾中建立一個新的功能檔案，例如 get_posts.feature。

Feature: 取得帖子

  Scenario: 取得所有帖子
    Given url 'https://jsonplaceholder.typicode.com/posts'
    When method get
    Then status 200
    And match response == '#[]'

內容解密：

Feature：定義了功能名稱，即取得帖子。
Scenario：定義了一個場景，即取得所有帖子。
Given url：指定了請求的 URL。
When method get：傳送 GET 請求。
Then status 200：檢查回應狀態碼是否為 200。
And match response == '#[]'：檢查回應是否為一個 JSON 陣列。

這個測試案例檢查了取得所有帖子的 API 端點是否傳回了正確的回應。

使用 Karate 編寫基礎測試

建立新的測試檔案

首先，我們要測試 posts 端點，因此需要建立一個新的檔案。將其命名為 posts.feature，因為它涉及測試 posts 端點。由於 Karate 外掛能夠識別 .feature 檔案副檔名，因此該檔案左側會顯示 Karate 圖示。

組態測試執行

開啟 posts.feature 檔案後，首先新增必備的 Feature: 關鍵字，並在之後新增對 Posts 端點測試的描述，以增加清晰度。

Feature: Posts 端點測試

接下來，為了方便稍後檢查一切是否正常運作，讓我們快速組態 IDE 中的測試執行。

組態 Karate 外掛

當開啟 feature 檔案時，您會看到所謂的 CodeLens。這是一種顯示在檔案中某些可執行行上方的功能，包含兩個動作：Karate: Run 和 Karate: Debug。現在，我們只使用執行功能（除錯將在第 4 章討論）。

點選 Karate: Run 後，會彈出一個對話方塊，提示需要一個 Karate Runner 檔案。目前，我們不需要這個，相關內容將在第 4 章討論。相反，我們將組態 Karate 外掛使用另一種方式來執行測試。

點選 VS Code 右上角的 Karate 圖示並選擇 Open Settings，將進入 Karate Runner 外掛設定頁面（或者，您可以透過 File | Preferences | Settings 選單進入）。

啟用 Karate 命令列

這將使用 Karate 命令列透過 Maven 啟動測試，而不需要專門的 runner 檔案。傳回 feature 檔案並點選 Karate: Run 後，您應該會在終端機中看到大量輸出：

======================================================
elapsed: 0.34 | threads: 1 | thread time: 0.00
features: 0 | skipped: 1 | efficiency: 0.00
scenarios: 0 | passed: 0 | failed: 0
======================================================

由於我們的 feature 尚未包含任何場景，因此報告指出沒有執行任何 feature 和場景。這就是為什麼我們也沒有透過的場景數量。

新增場景

讓我們在建立的 feature 下新增一個場景，以測試 posts 端點是否可用：

Feature: Posts 端點測試
Scenario: 檢查特定使用者的 posts

您會注意到，Karate 外掛也在場景上方增加了 CodeLens，這使得不僅可以執行 feature 檔案中的所有內容，還可以選擇要執行的場景。

嘗試點選此場景上方的 Karate: Run，應該會給出與之前不同的結果，因為現在我們有了一個屬於該 feature 的場景：

======================================================
elapsed: 3.70 | threads: 1 | thread time: 0.00
features: 1 | skipped: 0 | efficiency: 0.00
scenarios: 1 | passed: 1 | failed: 0
======================================================

然而，我們尚未實作任何步驟。因此，我們的場景被標記為透過——因為尚未有任何內容可能失敗。我們將在下一節中實作一些步驟。

呼叫端點和設定引數

在本文中，我們將瞭解更多關於呼叫常見端點和設定引數的資訊。

設定 URL

讓我們討論每個 Karate API 測試開始時的基本操作——呼叫特定的 URL。這是透過 url 關鍵字實作的。由於這是我們的初始條件，因此我們可以在此處使用 Given 關鍵字：

Scenario: 檢查特定使用者的 posts
Given url 'https://jsonplaceholder.typicode.com/posts?userId=1'

將 URL 置於引號中非常重要，否則會出現錯誤。這是由於 Karate 使用正規表示式解析步驟的方式，如第 1 章所述。此外，它必須與 Given url 在同一行；只是由於行長限制才未顯示在同一行。

指定 HTTP 方法

接下來，我們需要指定要使用的 HTTP 方法（GET、POST、PUT、DELETE、PATCH 等）。在我們的例子中，由於這是一個簡單的呼叫以檢索所有 posts，因此我們希望使用 GET。幸運的是，Karate 的慣例使用與這些方法（也稱為動詞）相同的名稱作為關鍵字，只是以小寫形式，並以 method 為字首：

Scenario: 檢查特定使用者的 posts
Given url 'https://jsonplaceholder.typicode.com/posts?userId=1'
When method get

我們在此步驟中使用 When，因為這可以被視為對當前設定的 URL 執行的操作。

程式碼解析

Given url 'https://jsonplaceholder.typicode.com/posts?userId=1'
When method get

內容解密：

Given url 'https://jsonplaceholder.typicode.com/posts?userId=1'：此步驟設定了要測試的 URL。這裡使用 Given 是因為它定義了測試的初始條件。URL 被置於引號中，以避免解析錯誤。
When method get：此步驟指定了要使用的 HTTP 方法。在此例中，使用 GET 方法來檢索資料。When 表示這是一個對目前設定 URL 的操作。
整體邏輯：這段程式碼設定了一個測試場景，首先定義了要呼叫的 URL，然後指定了要使用的 HTTP 方法。這是一個基本的 API 呼叫測試結構。

再次使用場景的 CodeLens 中的 Karate: Run 執行測試，應該會給出與之前類別似的輸出，因為我們尚未指定關於呼叫此 URL 時預期結果的任何斷言。到目前為止，它還不是一個真正的測試，而只是一系列呼叫 URL 的命令鏈。

編寫基本的 Karate 測試

在之前的範例中，我們看到了完整的請求和回應日誌，包括方法、URL 和一些標頭。讓我們來看看如何使這個測試更具可讀性。

將基礎 URL 與路徑分離

你可能已經注意到，我們目前在第一步中指定了完整的端點 URL。將基礎 URL 和具體的資源路徑分開，可以提高程式碼的可維護性和重用性。

Scenario: 檢查特定使用者的帖子
Given url 'https://jsonplaceholder.typicode.com'
And path 'posts'
When method get

使用 path 關鍵字將指定的路徑新增到基礎 URL。注意，你不需要新增斜線，Karate 會自動為我們做這件事。

程式碼解析：

Given url 'https://jsonplaceholder.typicode.com'
And path 'posts'
When method get

內容解密：

Given url 設定基礎 URL。
And path 新增具體的資源路徑到基礎 URL。
When method get 傳送 GET 請求。

設定查詢引數

最後，讓我們來設定查詢引數。

Scenario: 檢查特定使用者的帖子
Given url 'https://jsonplaceholder.typicode.com'
And path 'posts'
And param userId = 1
When method get

注意等號前後的空格，這對於 Karate 認別是重要的。與 path 步驟一樣，我們使用 And 關鍵字，因為它與第一個 Given 步驟相關聯。

程式碼解析：

And param userId = 1

內容解密：

And param 設定查詢引數。
userId = 1 指定查詢引數的鍵值對。

比對狀態碼和回應

在最後的輸出中，我們看到我們獲得了一個 200 的狀態碼（也稱為 OK）。這意味著請求是成功的。讓我們新增一個步驟來驗證這一點。

比對狀態碼和型別

如果你想比對一個簡單的狀態碼，可以使用 status 關鍵字，如下所示：

Scenario: 檢查特定使用者的帖子
Given url 'https://jsonplaceholder.typicode.com'
And path 'posts'
And param userId = 1
When method get
Then status 200

我們在這裡使用 Then 關鍵字來表示這是一個斷言。在此時，我們可以執行測試（應該透過）。

狀態碼列表

有關 HTTP 狀態碼的完整列表，請參閱 https://developer.mozilla.org/en-US/docs/Web/HTTP/Status。

讓我們故意使它失敗一次，以驗證這個測試不會在錯誤情況下給出假陽性結果。

使測試失敗

讓我們更改狀態碼為錯誤的值，然後再次執行測試：

Then status 404

正如預期的，測試失敗了，甚至在日誌中給出了錯誤原因：

status code was: 200, expected: 404, response time in milliseconds: 478

此外，在 VS Code 中，我們可以看到透過和失敗的測試數量，以及 IDE 頁尾中的整體失敗狀態。

圖示：測試失敗

此圖示顯示在 VS Code 中測試失敗的狀態。

圖示：測試透過

此圖示顯示在 VS Code 中測試透過的狀態。

我們可以看到，在 VS Code 頁尾中，由於勾選圖示旁邊的數字是 1。此外，背景顏色不再是紅色。

使用 Karate 進行基礎測試：驗證 JSON 回應

在進行 REST API 測試時，驗證回應的正確性是非常重要的。除了檢查 HTTP 狀態碼之外，我們還需要驗證回應的內容。在本章中，我們將探討如何使用 Karate 來驗證 JSON 回應。

探索 response 變數

當我們發出請求後，Karate 會將回應內容儲存在 response 變數中。我們可以使用 print 陳述式來印出整個 JSON 回應。

Scenario: 檢查使用者特定的文章
Given url 'https://jsonplaceholder.typicode.com/posts'
When method get
Then status 200
And match responseType == 'json'
* print "RESPONSE:", response

這裡的 * 符號表示這是一個除錯步驟，不屬於一般的場景流程。

存取 JSON 元素

我們可以直接存取 JSON 元素，就像存取 JavaScript 物件一樣。例如，要取得第一個元素的 userId，我們可以使用 response[0].userId。

* print "First user id:", response[0].userId

縮寫

Karate 提供了許多縮寫，可以簡化程式碼。例如，response 可以縮寫為 $。

處理巢狀 JSON 元素

我們可以使用點符號（.）來存取巢狀 JSON 元素。例如，response.book.title 可以取得書的標題。

斷言元素數量

我們可以使用 length 屬性來取得陣列的元素數量。例如，response.length 可以取得回應陣列的元素數量。

* print "Length", response.length
And assert response.length > 1

程式碼解析：

* print "Length", response.length
And assert response.length > 1

* print "Length", response.length：印出回應陣列的元素數量。
And assert response.length > 1：斷言回應陣列的元素數量大於 1。

使用匹配器

匹配器可以用來比較預期的屬性和值，並提供有關實際狀態的資訊。例如，我們可以使用 match 陳述式來驗證回應的內容。

And match response[0].userId == 1

程式碼解析：

And match response[0].userId == 1

And match response[0].userId == 1：驗證第一個元素的 userId 是否等於 1。

此圖示

@startuml
skinparam backgroundColor #FEFEFE
skinparam sequenceArrowThickness 2

title Karate API 測試入門

actor "客戶端" as client
participant "API Gateway" as gateway
participant "認證服務" as auth
participant "業務服務" as service
database "資料庫" as db
queue "訊息佇列" as mq

client -> gateway : HTTP 請求
gateway -> auth : 驗證 Token
auth --> gateway : 認證結果

alt 認證成功
    gateway -> service : 轉發請求
    service -> db : 查詢/更新資料
    db --> service : 回傳結果
    service -> mq : 發送事件
    service --> gateway : 回應資料
    gateway --> client : HTTP 200 OK
else 認證失敗
    gateway --> client : HTTP 401 Unauthorized
end

@enduml

圖示解析：

此圖示展示了使用 Karate 進行測試的主要步驟，包括發出請求、儲存回應內容、存取 JSON 元素、處理巢狀 JSON 元素、斷言元素數量和使用匹配器。這些步驟可以幫助我們更有效地驗證 API 的正確性。