如何记录 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 输出