如何记录PHPUnit测试

Question

我正在编写许多单元测试，但我担心有一天回来阅读测试代码时无法理解正在测试的内容。

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

- Eleandro Duzentos

---

为什么这个问题被点赞了两次？ - Bhavin

为什么这个问题不应该是@Bhavin提出的？ - Eleandro Duzentos

你会像记录其他任何东西一样来记录它吗？ - iainn

如果测试名称不是自说明的，那就是个不好的开端。 - Mark Baker

Answer 1

使用@covers注释（它是PHPUnit特有的，而不是phpDocumentor使用的文档标签），突出测试用例应该练习的代码。通过将其放在docblock中，您告诉代码阅读器测试所针对的代码。如果您还让phpDocumentor为您的测试用例生成文档，则它应将注释视为“自定义标记”，并将其显示为通用信息。请注意，@covers的目的是限制PHPUnit执行的代码覆盖率测量范围。它作为文档信息的使用是附带的，但很有用。

如果您想要一些测试用例和被测试代码之间的文档链接，请在测试用例的docblock中放置@uses标记。这应该会导致@used-by标记自动出现在受测试的方法/函数的文档中。

- ashnazg

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输出

- mls