Установка

1

$ composer require --dev "symfony/phpunit-bridge:*"

Если вы планируете и использовать обычный скрипт PHPUnit (а не изменённый скрипт PHPUnit, предоставленный Symfony), то вам нужно зарегистрировать новый слушатель теста под названием SymfonyTestsListener:

1
2
3
4
5
6
7
8
9
10
11

<!-- https://phpunit.de/manual/6.0/en/appendixes.configuration.html -->
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/6.0/phpunit.xsd"
>

    <!-- ... -->

    <listeners>
        <listener class="Symfony\Bridge\PhpUnit\SymfonyTestsListener"/>
    </listeners>
</phpunit>

Использование

Когда компонент установлен, создаётся скрипт simple-phpunit в каталоге vendor/ для запуска тестов. Этот скрипт создаёт оболочку для исходного бинарного PHPUnit, чтобы предоставить больше функций:

1
2

$ cd my-project/
$ ./vendor/bin/simple-phpunit

После выполнения ваших тестов PHPUnit, вы получите отчёт, похожий на этот:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

$ ./vendor/bin/simple-phpunit
  PHPUnit by Sebastian Bergmann.

  Конфигурация, считанная из <your-project>/phpunit.xml.dist
  .................

  Time: 1.77 seconds, Memory: 5.75Mb

  OK (17 тестов, 21 утверждений)

  Оставшиеся уведомления об устареваниях (2)

  getEntityManager устарел в Symfony 2.1. Вместо этого используйте getManager: 2x
    1x в DefaultControllerTest::testPublicUrls из App\Tests\Controller
    1x в BlogControllerTest::testIndex из App\Tests\Controller

Этот отчёт включает в себя:

Незаглушённые

Сообщает об уведомлениях об устаревании, которые были запущены без рекомендованного оператора @-silencing.

Унаследованные

Уведомления об устаревании помечают тесты, которые ясно тестируют какие-то функци наследования.

Оставшиеся/Другие

Все другие (не наследственные) уведомления об устаревании, сгруппированные по собщению, классу теста и методу.

1
2
3
4
5

<!-- phpunit.xml.dist -->
<!-- ... -->
<listeners>
    <listener class="Symfony\Bridge\PhpUnit\SymfonyTestsListener"/>
</listeners>

Параллельный запуск тестов

Измененный скрипт PHPUnit позволяет запускать тесты параллельно, предоставляя каталог, содержащий множество наборов тестов с собственным phpunit.xml.dist.

1
2
3
4
5
6
7

├── tests/
│   ├── Functional/
│   │   ├── ...
│   │   └── phpunit.xml.dist
│   ├── Unit/
│   │   ├── ...
│   │   └── phpunit.xml.dist

1

$ ./vendor/bin/simple-phpunit tests/

Изменённый скрипт PHPUnit будет рекурсивно продвигаться по предоставленному каталогу, на глубину до 3 суб-каталогов или значения, указанного переменной окружения SYMFONY_PHPUNIT_MAX_DEPTH, в поисках файлов phpunit.xml.dist, а затем запускать каждый найденный набор параллельно, собирая их вывод и отображая результаты каждого набора тестов в собственном разделе.

Вызов уведомлений об устаревании

Уведомления об устаревании могут быть вызваны используяtrigger_deprecation из пакета symfony/deprecation-contracts:

1
2
3
4
5

// обозначает, что что-то устарело с версии 1.3 vendor-name/packagename
trigger_deprecation('vendor-name/package-name', '1.3', 'Your deprecation message');

// вы также можете использовать формат printf (все аргументы после сообщения будут использованы)
trigger_deprecation('...', '1.3', 'Value "%s" is deprecated, use ...  instead.', $value);

Обозначение тестов как наследуемых

Существует три способа отметить тест, как наследуемый:

• (Рекомендованный) Добавьте аннотацию @group legacy к его классу или методу;
• Сделайте так, чтобы имя его класса начиналось с префикса Legacy;
• Сделайте так, чтобы имя его метода начиналось с testLegacy*() вместо test*().

Конфигурация

В случае, если вам нужно ислледовать отслеживание стека определённого устаревания, вызванного нашими модульными тестами, вы можете установить переменную окружения SYMFONY_DEPRECATIONS_HELPER в регулярном выражении, которое соответствует сообщению этого устаревания, заканчивающийся на /. Например:

1
2
3
4
5
6
7
8
9
10
11
12

<!-- https://phpunit.de/manual/6.0/en/appendixes.configuration.html -->
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/6.0/phpunit.xsd"
>

    <!-- ... -->

    <php>
        <server name="KERNEL_CLASS" value="App\Kernel"/>
        <env name="SYMFONY_DEPRECATIONS_HELPER" value="/foobar/"/>
    </php>
</phpunit>

PHPUnit остановит ваш пакет тестов, как только будет вызвано уведомление об устаревании, сообщение которого содержит строку "foobar".

1
2
3
4
5

# Этот файл содержит паттерны, которые нужно игнорировать во время тестирования использования
# устаревшего кода.

%The "Symfony\\Component\\Validator\\Context\\ExecutionContextInterface::.*\(\)" method is considered internal Used by the validator engine\. (Should not be called by user\W+code\. )?It may change without further notice\. You should not extend it from "[^"]+"\.%
%The "PHPUnit\\Framework\\TestCase::addWarning\(\)" method is considered internal%

1

$ SYMFONY_DEPRECATIONS_HELPER='ignoreFile=./tests/baseline-ignore' ./vendor/bin/simple-phpunit

1

$ SYMFONY_DEPRECATIONS_HELPER='generateBaseline=true&baselineFile=./tests/allowed.json' ./vendor/bin/simple-phpunit

1

$ SYMFONY_DEPRECATIONS_HELPER='baselineFile=./tests/allowed.json' ./vendor/bin/simple-phpunit

1
2
3
4
5
6
7
8
9
10
11
12

<!-- phpunit.xml.dist -->
<!-- ... -->
<listeners>
    <listener class="Symfony\Bridge\PhpUnit\SymfonyTestsListener">
        <arguments>
            <array>
                <!-- установите эту опцию как 0, чтобы отключить интеграцию DebugClassLoader -->
                <element key="debug-class-loader"><integer>0</integer></element>
            </array>
        </arguments>
    </listener>
</listeners>

1

$ php bin/console debug:container --deprecations

1
2

# .env.test
SYMFONY_PHPUNIT_LOCALE="fr_FR"

1
2
3
4
5
6
7
8
9
10
11
12

<!-- https://phpunit.de/manual/6.0/en/appendixes.configuration.html -->
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/6.0/phpunit.xsd"
>

    <!-- ... -->

    <php>
        <!-- ... -->
        <env name="SYMFONY_PHPUNIT_LOCALE" value="fr_FR"/>
    </php>
</phpunit>

Напишите утверждения об устареваниях

При добавлении устареваний в ваш код, вам может захотеться писать тесты, проверяющие, чтобы они вызывались, как требуется. Чтобы сделать это, мост предоставляет аннотацию expectDeprecation(), которую вы можете использовать в ваших методах тестов. Она требует, чтобы вы передали ожидаемое сообщение, данное в том же формате, что и для метода PHPUnit assertStringMatchesFormat(). Если вы ожидаете более одного сообщения об устаревании для заданного метода теста, вы можете использовать аннотацию несколько раз (порядок имеет значение):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

use PHPUnit\Framework\TestCase;
use Symfony\Bridge\PhpUnit\ExpectDeprecationTrait;

class MyTest extends TestCase
{
    use ExpectDeprecationTrait;

    /**
     * @group legacy
     */
    public function testDeprecatedCode(): void
    {
        // протестировать код, вызывающий следующее устаревание:
        // trigger_deprecation('vendor-name/package-name', '5.1', 'This "Foo" method is deprecated.');
        $this->expectDeprecation('Since vendor-name/package-name 5.1: This "%s" method is deprecated');

        // ...

        // протестировать код, вызывающий следующее устаревание:
        // trigger_deprecation('vendor-name/package-name', '4.4', 'The second argument of the "Bar" method is deprecated.');
        $this->expectDeprecation('Since vendor-name/package-name 4.4: The second argument of the "%s" method is deprecated.');
    }
}

Отображение полной трассировки стека

По умолчанию, PHPUnit Bridge отображает только сообщения об устаревании. Чтобы отобразить полную трассировку стека, связанную с устареванием, установите значение SYMFONY_DEPRECATIONS_HELPER как регулярное выражение, совпадающее с сообщением об устаревании.

Например, если вызывается следующее уведомление об устаревании:

1
2

1x: Doctrine\Common\ClassLoader is deprecated.
  1x in EntityTypeTest::setUp from Symfony\Bridge\Doctrine\Tests\Form\Type

Запуск следующей команды отобразить полную трассировку стегка:

1

$ SYMFONY_DEPRECATIONS_HELPER='/Doctrine\\Common\\ClassLoader is deprecated\./' ./vendor/bin/simple-phpunit

Тестирование с несколькими версиями PHPUnit

При тестировании библиотеки, которая должна быть совместимой с несколькими версиями PHP, пакет тестов не может использовать самые новые версии PHPUnit, потому что:

• В PHPUnit 8 устарели несколько методов, уступив место другим методам, которые не доступны в более старых версиях (например, PHPUnit 4);
• В PHPUnit 8 был добавлен возвратный тип void к методу setUp(), что не совместимо с PHP 5.5;
• PHPUnit перешел на классы пространств имен, начиная с PHPUnit 6, поэтому тесты должны работать и с, и без пространств имен.

Тесты, чувствительные ко времени

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

use PHPUnit\Framework\TestCase;
use Symfony\Component\Stopwatch\Stopwatch;

class MyTest extends TestCase
{
    public function testSomething(): void
    {
        $stopwatch = new Stopwatch();

        $stopwatch->start('event_name');
        sleep(10);
        $duration = $stopwatch->stop('event_name')->getDuration();

        $this->assertEquals(10000, $duration);
    }
}

1
2
3
4
5

<!-- phpunit.xml.dist -->
<!-- ... -->
<listeners>
    <listener class="\Symfony\Bridge\PhpUnit\SymfonyTestsListener" />
</listeners>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

use PHPUnit\Framework\TestCase;
use Symfony\Component\Stopwatch\Stopwatch;

/**
 * @group time-sensitive
 */
class MyTest extends TestCase
{
    public function testSomething(): void
    {
        $stopwatch = new Stopwatch();

        $stopwatch->start('event_name');
        sleep(10);
        $duration = $stopwatch->stop('event_name')->getDuration();

        $this->assertEquals(10000, $duration);
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

// класс, использующий функцию time(), будет сымитирован
namespace App;

class MyClass
{
    public function getTimeInHours(): void
    {
        return time() / 3600;
    }
}

// тест, ясно имитирующий внешнюю функцию time()
namespace App\Tests;

use App\MyClass;
use PHPUnit\Framework\TestCase;
use Symfony\Bridge\PhpUnit\ClockMock;

/**
 * @group time-sensitive
 */
class MyTest extends TestCase
{
    public function getTimeInHours(): void
    {
        ClockMock::register(MyClass::class);

        $my = new MyClass();
        $result = $my->getTimeInHours();

        $this->assertEquals(time() / 3600, $result);
    }
}

Тесты, чувствительные к СДИ

Тесты, создающие соединения сети, например, проверка валидности записи СДИ (Системы доменных имён) может быть долгой в выполнении и ненадёжной вследствие условий сети. По этой причине, данный компонент также предоставляет имитации этих PHP функций:

• checkdnsrr
• dns_check_record
• getmxrr
• dns_get_mx
• gethostbyaddr
• gethostbyname
• gethostbynamel
• dns_get_record

1
2
3
4
5
6
7
8
9
10
11
12
13

use App\Validator\DomainValidator;
use PHPUnit\Framework\TestCase;

class MyTest extends TestCase
{
    public function testEmail(): void
    {
        $validator = new DomainValidator(['checkDnsRecord' => true]);
        $isValid = $validator->validate('example.com');

        // ...
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

use App\Validator\DomainValidator;
use PHPUnit\Framework\TestCase;
use Symfony\Bridge\PhpUnit\DnsMock;

/**
 * @group dns-sensitive
 */
class DomainValidatorTest extends TestCase
{
    public function testEmails(): void
    {
        DnsMock::withMockedHosts([
            'example.com' => [['type' => 'A', 'ip' => '1.2.3.4']],
        ]);

        $validator = new DomainValidator(['checkDnsRecord' => true]);
        $isValid = $validator->validate('example.com');

        // ...
    }
}

1
2
3
4
5
6
7
8
9
10
11
12

DnsMock::withMockedHosts([
    'example.com' => [
        [
            'type' => 'A',
            'ip' => '1.2.3.4',
        ],
        [
            'type' => 'AAAA',
            'ipv6' => '::12',
        ],
    ],
]);

Тесты, основанные на существовании классов

Тесты, которые ведут себя по-разному, в зависимости от существования классов, к примеру, зависимостей разработки Composer, часто сложно тестировать для другого случая. По этой причине, данный компонент также предоставляет имитацию таких PHP-функций:

• class_exists
• interface_exists
• trait_exists
• enum_exists

1
2
3
4
5
6
7
8
9
10
11
12
13

use Vendor\DependencyClass;

class MyClass
{
    public function hello(): string
    {
        if (class_exists(DependencyClass::class)) {
            return 'The dependency behavior.';
        }

        return 'The default behavior.';
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13

use MyClass;
use PHPUnit\Framework\TestCase;

class MyClassTest extends TestCase
{
    public function testHello(): void
    {
        $class = new MyClass();
        $result = $class->hello(); // "The dependency behavior."

        // ...
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

use MyClass;
use PHPUnit\Framework\TestCase;
use Vendor\DependencyClass;

class MyClassTest extends TestCase
{
    // ...

    public function testHelloDefault()
    {
        ClassExistsMock::register(MyClass::class);
        ClassExistsMock::withMockedClasses([DependencyClass::class => false]);

        $class = new MyClass();
        $result = $class->hello(); // "The default behavior."

        // ...
    }
}

Диагностика и устранение неполадок

Аннотации @group time-sensitive и @group dns-sensitive работают "по соглашению" и предполагают, что пространства имён тестируемого класса могут быть получены просто путём удаления части Tests\ из пространств имён тестов. Т.е., если полное имя класса вашего случая тестирования (FQCN) - App\Tests\Watch\DummyWatchTest, он предполагает, что пространство имён тестируемого класса - App\Watch.

Если это соглашение не работает для вашего приложение, сконфигурируйте имитацию пространств имён в файле phpunit.xml, как это делается, например, в компоненте HttpKernel:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

<!-- https://phpunit.de/manual/4.1/en/appendixes.configuration.html -->
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/4.1/phpunit.xsd"
>

    <!-- ... -->

    <listeners>
        <listener class="Symfony\Bridge\PhpUnit\SymfonyTestsListener">
            <arguments>
                <array>
                    <element key="time-sensitive"><string>Symfony\Component\HttpFoundation</string></element>
                </array>
            </arguments>
        </listener>
    </listeners>
</phpunit>

За кулисами, слушатель PHPUnit внедряет сымитированные функции в пространство имен тестируемых классов. Для того, чтобы все работало, как ожидается, слушатель должен выполняться до того, как начнет работу тестируемый класс.

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

Вы можете:

• Объявить пространства имён тестируемых классов в вашем phpunit.xml.dist;

или * Зарегистрировать пространства имен в конце файла config/bootstrap.php.

1
2
3
4
5
6
7
8
9
10
11

<!-- phpunit.xml.dist -->
<!-- ... -->
<listeners>
    <listener class="Symfony\Bridge\PhpUnit\SymfonyTestsListener">
            <arguments>
                <array>
                    <element key="time-sensitive"><string>Acme\MyClassTest</string></element>
                </array>
            </arguments>
        </listener>
</listeners>

1
2
3
4
5
6
7

// config/bootstrap.php
use Symfony\Bridge\PhpUnit\ClockMock;

// ...
if ('test' === $_SERVER['APP_ENV']) {
    ClockMock::register('Acme\\MyClassTest\\');
}

Изменённый скрипт PHPUnit

Этот мост предоставляет изменённую версию PHPUnit, которую вы можете вызвать, используя его команду bin/simple-phpunit. Она имеет следующие функции:

• Работает с отдельным каталогом поставщиков, который не конфликтует с вашими;
• Не встраивает prophecy, чтобы избежать конфликтов с этими зависимостями;
• Собирает и повторяет пропущенные тесты, когда определена переменная окружения SYMFONY_PHPUNIT_SKIPPED_TESTS: она должна указывать имя файла, который будет использован для хранения пропущенных тестов при первом запуске, и повторять их при повторном запуске;
• Параллелит выполнение пакета тестов, когда каталог задан в качестве аргумента, сканируя этот каталог на предмет файлов phpunit.xml.dist до уровня SYMFONY_PHPUNIT_MAX_DEPTH (указан как переменная окружения, по умолчанию - 3);

Скрипт пишет изменённый PHPUnit, который он строит, в каталоге, который можно сконфигурировать с помощью SYMFONY_PHPUNIT_DIR, или в том же каталоге, что и simple-phpunit, если он не предоставлен. Также можно установить эту переменную окружения в файле phpunit.xml.dist.

Если вы установили мост через Composer, то вы можете запустить его, вызвав, к примеру:

1

$ vendor/bin/simple-phpunit

1
2
3
4
5

<!-- phpunit.xml.dist -->
<!-- ... -->
<php>
    <env name="SYMFONY_PHPUNIT_REQUIRE" value="vendor/name:^1.2 vendor/name2:^3"/>
</php>

Слушатель покрытия кода

По умолчанию, покрытие кода рассчитывается с использованием следующего правила: если строчка кода выполняется, то она отмечается, как охваченная. А тест, который выполняет строчку кода, следовательно, отмечается, как "покрывающий строчку кода". Это может вводить в заблуждение.

Рассмотрите следующий пример:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

class Bar
{
    public function barMethod(): string
    {
        return 'bar';
    }
}

class Foo
{
    public function __construct(
        private Bar $bar,
    ) {
    }

    public function fooMethod(): string
    {
        $this->bar->barMethod();

        return 'bar';
    }
}

class FooTest extends PHPUnit\Framework\TestCase
{
    public function test(): void
    {
        $bar = new Bar();
        $foo = new Foo($bar);

        $this->assertSame('bar', $foo->fooMethod());
    }
}

Метод FooTest::test выполняет каждую строчку кода классов Foo и Bar, но Bar на самом деле не тестируется. CoverageListener направлен на исправление этого поведения, путём добавления соответствующей аннотации @covers в каждом тесте класса.

Если класс теста уже определяет аннотацию @covers, то этот слушатель ничего не делает. В обратном случае, он пытается найти код, связанный с тестом, удалив часть имени класса Test: My\Namespace\Tests\FooTest -> My\Namespace\Foo.

1
2
3
4
5
6
7
8
9
10
11

<!-- https://phpunit.de/manual/6.0/en/appendixes.configuration.html -->
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/6.0/phpunit.xsd"
>

    <!-- ... -->

    <listeners>
        <listener class="Symfony\Bridge\PhpUnit\CoverageListener"/>
    </listeners>
</phpunit>

1
2
3
4
5
6
7

<listeners>
    <listener class="Symfony\Bridge\PhpUnit\CoverageListener">
        <arguments>
            <string>My\Namespace\SutSolver::solve</string>
        </arguments>
    </listener>
</listeners>

1
2
3
4
5
6
7
8

<listeners>
    <listener class="Symfony\Bridge\PhpUnit\CoverageListener">
        <arguments>
            <null/>
            <boolean>true</boolean>
        </arguments>
    </listener>
</listeners>