如何記錄 PHPUnit 測試

Question

我正在編寫很多單元測試，我擔心有一天我會回來閱讀測試代碼並且無法理解正在測試的內容。

問題是：如何使用PHPDoc記錄PHPUnit測試？

Answer 1

使用@covers注釋（它特定於 PHPUnit，而不是 phpDocumentor 使用的文檔標簽）來突出測試用例應該執行的內容。 通過將它放在 docblock 中，您可以告訴代碼閱讀器測試的目標代碼是什么。 如果您有 phpDocumentor 也為您的測試用例生成文檔，那么它應該將注釋視為“自定義標簽”，並將其顯示為通用信息。 但請注意， @covers是限制 PHPUnit 完成的代碼覆蓋率測量。 它用作文檔信息是偶然的，但很有用。

如果您希望在測試用例和測試代碼之間建立某種文檔鏈接，還可以將@uses標記放在測試用例的@uses中。 這應該會導致@used-by標簽自動出現在測試方法/函數的文檔中。

Answer 2

建議的一種方法是使用測試函數名稱，但這最終可能過於簡短和晦澀。 在這種情況下，在可選的 $message 參數中放入一些文本來解釋測試正在做什么。

assertSame(mixed $expected, mixed $actual[, string $message = ''])

我發現這很有幫助，特別是如果您習慣於使用 Jasmine 之類的東西編寫 JavaScript 測試，您可以在其中放置一個人類可讀的句子來解釋每個測試要測試的內容。

這是一個簡單的例子。 如果您將測試描述作為函數參數的默認值，它將被記錄下來。 如果你對每個功能只進行一個測試（即單一職責原則），那么當你幾年后回顧時，這些測試可能比每個功能有多個測試更有意義。

<?php
use PHPUnit\Framework\TestCase;

final class ArrayPushTest extends TestCase
{
    public function testPushStringToEmptyArray(string $description = 
        'A string is pushed into an empty array at array index 0.'
        ) : void
    {
        $a = [];
        array_push($a, 'zero');
        $this->assertSame('zero', $a[0], $description);
    }
}

這就是 phpDocumentor 文檔中的樣子：

phpDocumentor 輸出