我正在编写许多单元测试,但我担心有一天回来阅读测试代码时无法理解正在测试的内容。
问题是:如何使用PHPDoc记录PHPUnit测试?
@covers
注释(它是PHPUnit特有的,而不是phpDocumentor使用的文档标签),突出测试用例应该练习的代码。通过将其放在docblock中,您告诉代码阅读器测试所针对的代码。如果您还让phpDocumentor为您的测试用例生成文档,则它应将注释视为“自定义标记”,并将其显示为通用信息。请注意,@covers
的目的是限制PHPUnit执行的代码覆盖率测量范围。它作为文档信息的使用是附带的,但很有用。@uses
标记。这应该会导致@used-by
标记自动出现在受测试的方法/函数的文档中。有一种建议是使用测试函数名称,但这可能会变得过于简略和神秘。在这种情况下,可以在可选的 $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文档中的样子: