如何记录 PHPUnit 测试

Question

我正在写很多单元测试，我担心有一天我会回来阅读测试代码而无法理解正在测试的内容.

问题是：如何使用 PHPDoc 记录 PHPUnit 测试？

Answer 1

使用 @covers 注释（它特定于 PHPUnit，而不是 phpDocumentor 使用的文档标记）来突出显示测试用例应该执行的内容。通过将它放在文档块中，您可以告诉代码 reader 测试的目标代码。如果您有 phpDocumentor 还为您的测试用例生成文档，那么它应该将注释视为 "custom tag"，并将其显示为通用信息。但是请注意，@covers 的目的是限制 PHPUnit 完成的代码覆盖率测量。它用作文档信息是偶然的，但很有用。

如果您想要在测试用例和被测代码之间建立某种文档链接，还可以将 @uses 标记放在测试用例的文档块中。这应该会导致 @used-by 标记自动出现在测试的 method/function.

的文档中

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 output

如何记录 PHPUnit 测试

How to document PHPUnit tests

php

phpunit

phpdoc