Как документировать тесты PHPUnit

Используйте аннотацию @covers (она специфична для PHPUnit, а не тег документации, используемый phpDocumentor), чтобы выделить то, что должен выполнять тестовый пример. Имея его в докблоке, вы сообщаете читателю кода, какой код предназначен для теста. Если у вас есть phpDocumentor, который также генерирует документы для ваших тестовых случаев, тогда он должен рассматривать аннотацию как «настраиваемый тег» и отображать ее как общую информацию. Обратите внимание, однако, что пункт @covers состоит в том, чтобы ограничить измерения покрытия кода, выполняемые PHPUnit. Его использование в качестве информации о документе является случайным, но полезным.

Если вам нужен какой-то документ, связывающий тестовый пример и тестируемый код, также поместите тег @uses в докблок тестового примера. Это должно привести к тому, что тег @used-by автоматически появится в документации для тестируемого метода/функции.

Один из предложенных способов — использовать имя тестовой функции, но это может оказаться слишком сокращенным и загадочным. В этом случае поместите текст в необязательный параметр $message, чтобы объяснить, что делает тест.

assertSame(mixed $expected, mixed $actual[, string $message = ''])

Я считаю, что это помогает, особенно если вы привыкли писать тесты JavaScript с чем-то вроде Jasmine, где вы вставляете удобочитаемое предложение, чтобы объяснить, что тестируется для каждого теста.

Вот простой пример. Если вы поместите описание теста в качестве значения по умолчанию для аргумента функции, оно будет задокументировано. Если вы поместите только один тест на функцию (то есть принцип единой ответственности), то, оглядываясь назад через несколько лет, возможно, тесты будут иметь больше смысла, чем несколько тестов для каждой функции.

<?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