ApiTestCase

API測試用例

ApiTestCase是一個 PHPUnit 測試案例，它將讓您作為 Symfony API 開發人員的生活變得更加輕鬆。它使用一些很酷的功能擴展了基本的 Symfony WebTestCase。

多虧了 PHP-Matcher，根據其自述文件，您可以「像黑幫一樣編寫預期的 json 回應」。我們絕對同意。

它還使用 Alice 來輕鬆載入 Doctrine 裝置。

特徵：

• 使用 Symfony 進行 API 開發的清晰 TDD 工作流程；
• JSON/XML 匹配，並具有清晰的錯誤訊息；
• 與 Alice 一起載入裝置（選購） ；

安裝

假設您已經全域安裝了 Composer：

composer require --dev lchrusciel/api-test-case

完成了！ ApiTestCase 使用預設配置。

用法

我們為您的測試案例提供兩個基類：JsonApiTestCase 和 XmlApiTestCase。根據您要建立的 API 的格式選擇一種。

Json 範例

基本的 TDD 工作流程如下：

1. 編寫發送請求的測試案例，並使用assertResponse斷言方法檢查回應內容是否符合您的期望。您需要響應文件的名稱；
2. 使用您在步驟 1 中選擇的名稱建立文件，並將預期的回應內容放入其中。例如，它應該放在src/AppBundle/Tests/Responses/Expected/hello_world.json中。
3. 把它變成紅色。
4. 讓它變綠。
5. 重構。

讓我們來看一個簡單的例子！編寫以下測試：

 namespace AppBundle  Tests  Controller  HelloWorldTest ;

use ApiTestCase  JsonApiTestCase ;

class HelloWorldTest extends JsonApiTestCase
{
    public function testGetHelloWorldResponse ()
    {
        $ this -> client -> request ( ' GET ' , ' / ' );

        $ response = $ this -> client -> getResponse ();

        $ this -> assertResponse ( $ response , ' hello_world ' );
    }
}

現在定義預期的回應檔：

{
    "message" : " Hello ApiTestCase World! "
}

運行您的測試：

vendor/bin/phpunit

您的測試應該會因一些錯誤而失敗，您可能缺少控制器和路由，因此請繼續定義它們！一旦您實現了控制器並配置了適當的路由，您就可以再次執行測試：

如果回應內容符合我們的預期，控制台將顯示一個簡單的訊息：

OK (1 tests, 2 assertions)

否則它將顯示收到訊息的差異：

 " Hello ApiTestCase World " does not match " Hello ApiTestCase World! " .
@@ -1,4 +1,3 @@
 {
-    " message " : " Hello ApiTestCase World! "
+    " message " : " Hello ApiTestCase World "
 }
-

首先，函數assertResponse將檢查回應碼（200是預設回應碼），然後它將檢查回應頭是否包含application/json內容類型。最後它會檢查回應內容是否符合預期。有時您無法預測回應中的某些值，例如資料庫中自動產生的日期或 ID。這裡不需要魔法，因為 PHP-Matcher 會提供協助。這些只是可用模式的幾個範例：

• @string@
• @integer@
• @boolean@
• @array@

查看 PHP-Matcher 文件的更多資訊。

透過這些模式，您的預期回應將如下所示：

{
    "message" : " @string@ "
}

完成此操作後，關鍵message下的任何字串都將與該模式相符。更複雜的預期反應可能如下所示：

[
    {
        "id" : " @integer@ " ,
        "name" : " Star-Wars T-shirt " ,
        "sku" : " SWTS " ,
        "price" : 5500 ,
        "sizes" : " @array@ " ,
        "created_at" : " @[email protected]() "
    },
    {
        "id" : " @integer@ " ,
        "name" : " Han Solo Mug " ,
        "sku" : " HSM " ,
        "price" : 500 ,
        "sizes" : " @array@ " ,
        "created_at" : " @[email protected]() "
    }
]

並將匹配以下產品清單：

 array (
    array (
        ' id ' => 1 ,
        ' name ' => ' Star-Wars T-shirt ' ,
        ' sku ' => ' SWTS ' ,
        ' price ' => 5500 ,
        ' sizes ' => array ( ' S ' , ' M ' , ' L ' ),
        ' created_at ' => new  DateTime (),
    ),
    array (
        ' id ' => 2 ,
        ' name ' => ' Han Solo Mug ' ,
        ' sku ' => ' HSM ' ,
        ' price ' => 500 ,
        ' sizes ' => array ( ' S ' , ' L ' ),
        ' created_at ' => new  DateTime (),
    ),
)

使用資料庫裝置進行測試

ApiTestCase 與nelmio/alice整合。感謝這個漂亮的庫，您可以在需要時輕鬆加載您的燈具。您必須定義您的裝置並將它們放置在適當的目錄中。以下是如何定義固定裝置和用例的一些範例。有關如何定義裝置的更多信息，請查看 Alice 的文檔。

為了將 Alice 與 Doctrine 結合使用，您應該啟用兩個額外的捆綁包：

交響樂 4.0+

 // config/bundles.php
return [
    // ...
    
    Nelmio  Alice  Bridge  Symfony NelmioAliceBundle::class => [ ' test ' => true ],
    Fidry  AliceDataFixtures  Bridge  Symfony FidryAliceDataFixturesBundle::class => [ ' test ' => true ],
];

現在，假設您的應用程式中有一個名為 Book 的對應 Doctrine 實體：

    class Book 
    {
        private $ id ;
        private $ title ;
        private $ author ;
    
        // ... 
    }

要載入測試的固定裝置，您需要在src/AppBundle/Tests/DataFixtures/ORM/books.yml中定義一個簡單的YAML檔案：

    ApiTestCaseTestEntityBook :
        book1 :
            title : " Lord of The Rings "
            author : " J. R. R. Tolkien "
        book2 :
            title : " Game of Thrones "
            price : " George R. R. Martin "

最後，要在測試中使用這些裝置，只需呼叫適當的方法：

    public function testBooksIndexAction ()
    {
        // This method require subpath to locate specific fixture file in your DataFixtures/ORM directory.
        $ this -> loadFixturesFromFile ( ' books.yml ' );  
      
        // There is another method that allows you to load fixtures from directory.
        $ this -> loadFixturesFromDirectory ( ' big_library ' );
    }

配置參考

若要自訂測試套件配置，您可以為 phpunit.xml 添加更多選項：

< php >
    < server name = " KERNEL_CLASS " value = " AcmeKernel " />
    < server name = " EXPECTED_RESPONSE_DIR " value = " /path/to/expected/responses/ " />
    < server name = " FIXTURES_DIR " value = " /path/to/DataFixtures/ORM/ " />
    < server name = " OPEN_ERROR_IN_BROWSER " value = " true/false " />
    < server name = " OPEN_BROWSER_COMMAND " value = " open %s " />
    < server name = " IS_DOCTRINE_ORM_SUPPORTED " value = " true/false " />
    < server name = " TMP_DIR " value = " /tmp/path/to/temporary/folder/ " />
    < server name = " ESCAPE_JSON " value = " true/false " />
</ php >

• KERNEL_CLASS可讓您準確指定應使用哪個類別來設定核心。
• ERESPONSE_DIR變數包含具有預期回應的資料夾的路徑。當 API 結果與現有 json 檔案進行比較時使用。如果未設定此值，ApiTestCase 將嘗試猜測回應的位置，在相對於控制器測試類別位於的資料夾「../Responses」中尋找回應。
• FIXTURES_DIR變數包含包含資料裝置的資料夾的路徑。預設情況下，如果未設定此變量，它將搜尋相對位於您的測試類別的../DataFixtures/ORM/ 。如果資料夾不存在或沒有任何檔案要加載，ApiTestCase 會拋出 RunTimeException。
• OPEN_ERROR_IN_BROWSER是一個開啟瀏覽器視窗中顯示錯誤的標誌。預設值為 false。
• OPEN_BROWSER_COMMAND是一個用來開啟瀏覽器但出現異常的指令。
• IS_DOCTRINE_ORM_SUPPORTED是一個打開學說支援的標誌，包括方便的資料固定載入器和資料庫清除器。
• TMP_DIR變數包含臨時資料夾的路徑，其中將儲存日誌檔案。
• ESCAPE_JSON是一個標誌，在將 JSON 輸出與預期資料進行比較之前，它會開啟 JSON 輸出的轉義（unicode 字元和斜線）。預設值為 false。該標誌的存在只是為了向後相容於先前版本的 ApiTestCase（開啟時），並將在未來版本中刪除。

範例專案

在test/目錄中，您可以找到使用該程式庫所需的最少配置的範例 Symfony 專案。

測試

為了執行我們的 PHPUnit 測試套件，請執行下列命令：

composer install
test/app/console doctrine:database:create
test/app/console doctrine:schema:create
vendor/bin/phpunit

錯誤追蹤和建議

如果您發現錯誤或有改進的好主意，請在此存儲庫上提出問題。

版本控制

版本將以major.minor.patch格式進行編號。

並按照以下準則建構。

• 破壞向後相容性會導致重大問題。
• 在不破壞向後相容性的情況下增加的新內容會帶來輕微的影響。
• 錯誤修復和其他變更會影響補丁。

有關 SemVer 的更多信息，請訪問 semver.org 網站。

麻省理工學院許可證

許可證可以在這裡找到。

作者

該庫最初由以下人員創建：

• 武卡斯·赫魯希希爾
• 米哈烏·馬爾辛科夫斯基
• 帕韋烏·延德爾熱耶夫斯基
• 阿卡迪烏斯·克拉科維亞克

在 Lakion 公司的 https://github.com/Lakion/ApiTestCase 儲存庫下。

請參閱貢獻者清單。