Установка

1

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

Якщо ви плануєте писати ствердження про старіння та використовувати звичайний скрипт PHPUnit (а не змінений скрипт PHPUnit, наданий Symfony), то вам потрібно зареєструвати новий слухач тесту під назвою SymfonyTestsListener:

1
2
3
4
5
6
7
8
9
10
11

<!-- http://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 tests, 21 assertions)

  Сповіщення про старіння, що залишилися (2)

  getEntityManager застарів з Symfony 2.1. Використайте getManager натомість: 2x
    1x in DefaultControllerTest::testPublicUrls from App\Tests\Controller
    1x in BlogControllerTest::testIndex from 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 у регулярному виразі, яка відповідає повідомленню цього старіння, і закінчується на /. Наприклад:

<!-- http://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="AppKernel"/> <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

Напишіть твердження про старіння

При додаванні старінь до вашого коду, вам може захотітися писати тести, що перевіряють, щоб вони викликалися так, як вимагається. Щоб зробити це, міст надає анотацію
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()
    {
        // протестувати код, що викликає наступне старіння:
        // trigger_deprecation('vendor-name/package-name', '5.1', 'Цей метод "Foo" застарів.');
        $this->expectDeprecation('Since vendor-name/package-name 5.1: This "%s" method is deprecated');

        // ...

        // протестувати код, що викликає наступне старіння:
        // trigger_deprecation('vendor-name/package-name', '4.4', 'Другий аргумент методу "Bar" застарів.');
        $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()
    {
        $stopwatch = new Stopwatch();

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

        $this->assertEquals(10, $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()
    {
        $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()
    {
        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 testGetTimeInHours()
    {
        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()
    {
        $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()
    {
        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

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()
    {
        $class = new MyClass();
        $result = $class->hello(); // "Поведінка залежності."

        // ...
    }
}

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 Component:

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

<!-- http://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
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
34
35

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

class Foo
{
    private $bar;

    public function __construct(Bar $bar)
    {
        $this->bar = $bar;
    }

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

        return 'bar';
    }
}

class FooTest extends PHPUnit\Framework\TestCase
{
    public function test()
    {
        $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

<!-- http://phpunit.de/manual/6.0/en/appendixes.configuration.html -->
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:noNamespaceSchemaLocation="http://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>