Question

I'm writing a lot of unit tests and I'm afraid one day I'll come back to read the test codes and not be able to understand what's being tested.

The question is: How do i document PHPUnit tests using PHPDoc?

Answer 1

使用@covers注释（它特定于PHPUnit，而不是phpDocumentor使用的文档标记）来突出显示测试用例应该执行的操作。通过将其放在docblock中，您可以告诉代码阅读器测试的目标代码是什么。如果你有phpDocumentor也为你的测试用例生成文档，那么它应该将注释视为“自定义标记”，并将其显示为通用信息。但请注意，@covers的要点是限制PHPUnit完成的代码覆盖率测量。它作为doc信息使用是偶然的，但很有用。

如果您希望在测试用例和测试代码之间链接某种文档，请将@uses标记放在测试用例的docblock中。这应该会导致@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 output

How to document PHPUnit tests

2 个答案: