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?
2 Answers
One way as suggested is to use the test function name but this can end up too abbreviated and cryptic. In this case put some text in the optional $message parameter to explain what the test is doing.
assertSame(mixed $expected, mixed $actual[, string $message = ''])
I finds this helps, particularly if you are used to writing JavaScript tests with something like Jasmine where you put a human readable sentence to explain what is being tested for each test.
Here is a simple example. If you put the test description as the default value for a function argument it will be documented. If you put just one test per function (i.e. single responsibility principle) then when you look back in a few years time maybe the tests will make more sense than having multiple tests per function.
<?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);
}
}
And this is what it looks like in the docs with phpDocumentor:
Related