Тестовые дублёры

createStub()

Создаёт тестовую заглушку для указанного интерфейса (или расширяемого класса).

$stub = $this->createStub(InterfaceName::class);

Все методы исходного типа заменяются реализацией, возвращающей автоматически сгенерированное значение, которое соответствует объявленному типу возвращаемого значения метода; исходный метод при этом не вызывается. Такие методы называются «дублированными методами» или «методами-заглушками».

Дублированные методы можно настроить с помощью описанных ниже методов.

createStubForIntersectionOfInterfaces()

Создаёт тестовую заглушку для пересечения интерфейсов.

$stub = $this->createStubForIntersectionOfInterfaces(
    [InterfaceA::class, InterfaceB::class]
);

Это полезно, когда нужно заменить объект, реализующий несколько интерфейсов.

createConfiguredStub()

Создаёт тестовую заглушку с уже настроенными методами, возвращающими определённые значения.

$stub = $this->createConfiguredStub(
    InterfaceName::class,
    [
        'methodOne' => 'return value one',
        'methodTwo' => 'return value two',
    ]
);

// $stub->methodOne() will return "return value one"
// $stub->methodTwo() will return "return value two"

Это вспомогательный метод для простых случаев.

getStubBuilder()

Метод getStubBuilder() предоставляет гибкий API для создания тестовых заглушек. Его следует использовать только в особых случаях, которые не поддерживаются более простыми методами createStub() или createStubForIntersectionOfInterfaces().

Используйте getStubBuilder() только при необходимости расширенной настройки, например:

• Указать собственное имя класса тестовой заглушки

• Включить исходный конструктор с пользовательскими аргументами

• Создать частичные тестовые заглушки (дублировать только определённые методы)

• Управлять поведением клонирования

• Отключить автоматическую генерацию возвращаемых значений

Метод getStubBuilder(string $type) возвращает объект, который можно использовать для настройки, а затем создания тестовой заглушки для указанного интерфейса (или расширяемого класса).

У объекта, возвращаемого методом getStubBuilder(), есть, помимо прочих, метод с именем getStub(). Он создаёт и возвращает настроенную тестовую заглушку. Этот метод должен вызываться последним в цепочке вызовов методов гибкого API.

Для настройки создания тестовой заглушки можно использовать следующие методы объекта, возвращаемого методом getStubBuilder():

setStubClassName(string $name)

Задаёт пользовательское имя для сгенерированного класса тестовой заглушки.

onlyMethods(array $methods)

Указывает, какие методы следует дублировать (заменить заглушками). Методы, не включённые в этот список, сохранят исходную реализацию, в результате чего будет создан частичный дублёр.

setConstructorArgs(array $arguments)

Задаёт аргументы, передаваемые конструктору при использовании enableOriginalConstructor() (см. ниже).

disableOriginalConstructor()

Отключает вызов исходного конструктора. Это полезно, когда нужно создать частичный дублёр, а конструктор имеет побочные эффекты или требует зависимостей, которые вы не хотите предоставлять.

enableOriginalConstructor()

Включает вызов исходного конструктора. Используйте этот метод вместе с setConstructorArgs() (см. выше), чтобы передать обязательные аргументы.

disableOriginalClone()

Отключает вызов исходного метода __clone() при клонировании тестовой заглушки.

enableOriginalClone()

Включает вызов исходного метода __clone() при клонировании тестовой заглушки.

enableAutoReturnValueGeneration()

Включает автоматическую генерацию возвращаемых значений для дублированных методов, для которых не настроены явные возвращаемые значения.

disableAutoReturnValueGeneration()

Отключает автоматическую генерацию возвращаемых значений. Если она отключена, методы-заглушки без явной настройки возвращают null или выбрасывают исключение — в зависимости от объявленного типа возвращаемого значения.

willReturn()

Настраивает метод на возврат определённого значения.

$stub = $this->createStub(InterfaceName::class);

$stub
    ->method('doSomething')
    ->willReturn('result');

// $stub->doSomething() always returns "result"

Возвращаемое значение должно соответствовать объявленному типу возвращаемого значения метода.

С помощью willReturn() можно настроить метод так, чтобы при последовательных вызовах он возвращал разные значения:

$stub = $this->createStub(InterfaceName::class);

$stub
    ->method('doSomething')
    ->willReturn('first result', 'second result');

// $stub->doSomething() returns "first result" when it is invoked for the first time
// $stub->doSomething() returns "second result" when it is invoked for the second time
// $stub->doSomething() will trigger an error when it is invoked more than twice

Если метод настроен на возврат разных значений при последовательных вызовах, его можно вызвать только столько раз, сколько задано возвращаемых значений.

willReturnSelf()

Настраивает метод на возврат самого объекта тестовой заглушки.

$stub = $this->createStub(InterfaceName::class);

$stub
    ->method('doSomething')
    ->willReturnSelf();

Это полезно для тестирования цепочечных интерфейсов.

willReturnArgument()

Настраивает метод на возврат одного из своих аргументов.

$stub = $this->createStub(InterfaceName::class);

$stub
    ->method('doSomething')
    ->willReturnArgument(0);

// $stub->doSomething('some value') returns 'some value'

Индексация аргументов начинается с нуля.

willReturnMap()

Настраивает метод на возврат разных значений в зависимости от полученных аргументов.

$stub = $this->createStub(InterfaceName::class);

$stub
    ->method('doSomething')
    ->willReturnMap([
        ['foo', 'bar', 'baz'],
        ['one', 'two', 'three'],
    ]);

// $stub->doSomething('foo', 'bar') returns 'baz'
// $stub->doSomething('one', 'two') returns 'three'

Каждый вложенный массив содержит аргументы метода, за которыми следует возвращаемое значение.

Каждая позиция параметра в карте значений может содержать буквальное значение (сравниваемое с помощью ===) или ограничение PHPUnit:

$stub = $this->createStub(InterfaceName::class);

$stub
    ->method('doSomething')
    ->willReturnMap([
        [$this->greaterThan(5), 'large'],
        [$this->lessThanOrEqual(5), 'small'],
    ]);

// $stub->doSomething(10) returns 'large'
// $stub->doSomething(3) returns 'small'

Если в карте значений не найдено совпадение, возвращается null.

willReturnStrictMap()

Работает так же, как willReturnMap(), но выбрасывает ExpectationFailedException, если вызову метода не соответствует ни одна запись в карте значений, вместо того чтобы без предупреждения возвращать null:

$stub = $this->createStub(InterfaceName::class);

$stub
    ->method('doSomething')
    ->willReturnStrictMap([
        [1, 'one'],
        [2, 'two'],
    ]);

// $stub->doSomething(1) returns 'one'
// $stub->doSomething(99) throws ExpectationFailedException

Как и в willReturnMap(), для сопоставления параметров можно использовать объекты-ограничения.

willReturnCallback()

Настраивает метод на возврат результата функции обратного вызова.

$stub = $this->createStub(InterfaceName::class);

$stub
    ->method('doSomething')
    ->willReturnCallback(
        static fn(string $input) => strtoupper($input)
    );

// $stub->doSomething('string') returns 'STRING'

Функция обратного вызова получает аргументы метода и может реализовывать сложную логику.

Свойства с перехватчиками чтения

В PHP 8.4 появилась языковая возможность свойств с перехватчиками чтения.

В приведённом ниже примере показан интерфейс, объявляющий свойство с перехватчиком чтения:

<?php declare(strict_types=1);
interface InterfaceWithGetHookedProperty
{
    public string $property { get; }
}

Поведение свойства с перехватчиком чтения property можно настроить следующим образом:

<?php declare(strict_types=1);
use PHPUnit\Framework\MockObject\Runtime\PropertyHook;
use PHPUnit\Framework\TestCase;

final class ExampleTest extends TestCase
{
    public function testExample(): void
    {
        $stub = $this->createStub(
            InterfaceWithHookedProperty::class,
        );

        $stub
            ->method(PropertyHook::get('property'))
            ->willReturn('value');

        $this->assertSame('value', $stub->property);
    }
}

В приведённом выше примере PropertyHook::get('property') используется для указания, что мы хотим настроить поведение метода, вызываемого при чтении свойства с именем property.

willThrowException()

Настраивает метод на выбрасывание исключения вместо возврата значения.

$stub = $this->createStub(InterfaceName::class);

$stub
    ->method('doSomething')
    ->willThrowException(new Exception);

// $stub->doSomething() throws the configured exception

createMock()

Создаёт мок-объект для указанного интерфейса (или расширяемого класса).

$mock = $this->createMock(InterfaceName::class);

Для всех методов можно настроить возвращаемые значения и ожидания.

createMockForIntersectionOfInterfaces()

Создаёт мок-объект для пересечения интерфейсов.

$mock = $this->createMockForIntersectionOfInterfaces(
    [InterfaceA::class, InterfaceB::class]
);

Это полезно, когда нужно заменить объект, реализующий несколько интерфейсов.

createConfiguredMock()

Создаёт мок-объект с методами, уже настроенными на возврат определённых значений.

$mock = $this->createConfiguredMock(
    InterfaceName::class,
    [
        'methodOne' => 'return value one',
        'methodTwo' => 'return value two',
    ]
);

// $mock->methodOne() will return "return value one"
// $mock->methodTwo() will return "return value two"

Это вспомогательный метод для простых случаев.

createPartialMock()

Создаёт мок-объект для расширяемого класса, в котором подменяются тестовыми двойниками только указанные методы. Все остальные методы сохраняют исходную реализацию.

$mock = $this->createPartialMock(
    ClassName::class,
    ['methodToDouble']
);

$mock
    ->expects($this->once())
    ->method('methodToDouble')
    ->willReturn('mocked value');

// $mock->methodToDouble() is expected to be called once
// $mock->methodToDouble() returns "mocked value"
// All other methods of ClassName execute their real code

Это может быть полезно, если нужно протестировать класс, но заменить только определённые методы (например, методы, взаимодействующие с внешними системами), сохранив при этом остальное поведение класса. Исходный конструктор отключается.

getMockBuilder()

Метод getMockBuilder() предоставляет гибкий API для создания мок-объектов. Его следует использовать только в нестандартных случаях, которые не поддерживаются более простыми методами createMock() или createMockForIntersectionOfInterfaces().

Документация и рекомендации для getStubBuilder() (см. выше) также применимы к getMockBuilder(), за двумя исключениями:

• Для задания пользовательского имени класса созданного класса мок-объекта используется метод setMockClassName()

• Последним в цепочке вызовов методов гибкого API необходимо вызывать метод getMock()

once()

Метод должен быть вызван ровно один раз.

$mock = $this->createMock(InterfaceName::class);

$mock
    ->expects($this->once())
    ->method('doSomething');

once() — это удобная обёртка для exactly(1).

exactly(int $count)

Метод должен быть вызван ровно $count раз.

$mock = $this->createMock(InterfaceName::class);

$mock
    ->expects($this->exactly(2))
    ->method('doSomething');

atLeastOnce()

Метод должен быть вызван как минимум один раз.

$mock = $this->createMock(InterfaceName::class);

$mock
    ->expects($this->atLeastOnce())
    ->method('doSomething');

atLeastOnce() — это удобная обёртка для atLeast(1).

atLeast(int $requiredInvocations)

Метод должен быть вызван как минимум $requiredInvocations раз.

$mock = $this->createMock(InterfaceName::class);

$mock
    ->expects($this->atLeast(2))
    ->method('doSomething');

atMost(int $allowedInvocations)

Метод не должен вызываться более $allowedInvocations раз.

$mock = $this->createMock(InterfaceName::class);

$mock
    ->expects($this->atMost(2))
    ->method('doSomething');

never()

Метод не должен вызываться.

$mock = $this->createMock(InterfaceName::class);

$mock
    ->expects($this->never())
    ->method('doSomething');

never() — это удобная обёртка для exactly(0).

any()

Метод может быть вызван ноль или более раз. Число вызовов не ограничивается ожиданиями, поэтому тест не завершится с ошибкой независимо от количества вызовов метода (в том числе если он не будет вызван ни разу).

$mock = $this->createMock(InterfaceName::class);

$mock
    ->expects($this->any())
    ->method('doSomething')
    ->willReturn('value');

Показанная выше конфигурация объекта-мока эквивалентна конфигурации тестовой заглушки, приведённой ниже:

$stub = $this->createStub(InterfaceName::class);

$stub
    ->method('doSomething')
    ->willReturn('value');

with()

Метод with() проверяет аргументы, переданные вызываемому методу мока.

$mock = $this->createMock(InterfaceName::class);

$mock
    ->expects($this->once())
    ->method('doSomething')
    ->with('argument 1', 'argument 2');

В приведённом выше примере мы настраиваем объект-мок так, чтобы ожидался ровно один вызов метода doSomething(). При этом единственном вызове должны быть переданы аргументы "argument 1" и argument 2".

Приведённый выше пример эквивалентен следующему:

$mock = $this->createMock(InterfaceName::class);

$mock
    ->expects($this->once())
    ->method('doSomething')
    ->with($this->equalTo('argument 1'), $this->equalTo('argument 2'));

Метод with() проверяет аргументы, переданные вызываемому методу мока, с помощью объектов Constraint. Если значение, переданное в with(), не является объектом Constraint, оно автоматически оборачивается в объект Constraint, проверяющий равенство. Объект Constraint, проверяющий равенство, можно создать вручную с помощью $this->equalTo().

PHPUnit предоставляет множество методов ограничений для проверки аргументов:

Идентичность и равенство

• identicalTo()

• equalTo()

• equalToCanonicalizing()

• equalToIgnoringCase()

• equalToWithDelta()

• objectEquals()

Количество

• isEmpty()

• countOf()

• greaterThan()

• greaterThanOrEqual()

• lessThan()

• lessThanOrEqual()

Математика

• isFinite()

• isInfinite()

• isNan()

Логические значения

• isFalse()

• isTrue()

Операторы

• logicalAnd()

• logicalNot()

• logicalOr()

• logicalXor()

Строки

• isJson()

• matches()

• matchesRegularExpression()

• stringContains()

• stringEndsWith()

• stringEqualsStringIgnoringLineEndings()

• stringStartsWith()

Перебираемые значения

• arrayHasKey()

• containsEqual()

• containsIdentical()

• containsOnlyArray()

• containsOnlyBool()

• containsOnlyCallable()

• containsOnlyClosedResource()

• containsOnlyFloat()

• containsOnlyInstancesOf()

• containsOnlyInt()

• containsOnlyIterable()

• containsOnlyNull()

• containsOnlyNumeric()

• containsOnlyObject()

• containsOnlyResource()

• containsOnlyScalar()

• containsOnlyString()

• isList()

Типы

• isArray()

• isBool()

• isCallable()

• isClosedResource()

• isFloat()

• isInstanceOf()

• isInt()

• isIterable()

• isNull()

• isNumeric()

• isObject()

• isResource()

• isScalar()

• isString()

Файловая система

• directoryExists()

• fileExists()

• isReadable()

• isWritable()

Ожидание вызовов одного метода с разными аргументами в определённом порядке

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

1. Метод вызывается ожидаемое число раз

2. При каждом вызове передаются правильные аргументы

3. Вызовы происходят в определённом порядке

Рассмотрим службу, зависящую от Dispatcher и использующую его метод dispatch() для отправки событий. В этих сценариях важен порядок отправки событий. Мы не можем обработать этот случай с помощью with() (см. выше), поскольку настройка двух отдельных ожиданий с помощью expects() для одного и того же метода не работает (второе ожидание перезаписывает первое).

Метод withParameterSetsInOrder() решает эту задачу, позволяя указать несколько наборов параметров, которые должны сопоставляться последовательно:

$dispatcher = $this->createMock(Dispatcher::class);

$dispatcher
    ->expects($this->exactly(2))
    ->method('dispatch')
    ->withParameterSetsInOrder(
        [new AnEvent],
        [new AnotherEvent],
    );

$service = new Service($dispatcher);

$service->doSomething();

Упорядоченные наборы параметров позволяют проверить, что метод вызывается несколько раз с разными аргументами в определённом порядке. Это необходимо, если порядок операций влияет на корректность или требуется проверить определённый рабочий процесс либо протокол.

Тест завершится с ошибкой, если:

• Метод вызван с неправильными аргументами

• Вызовы происходят в неправильном порядке

• Метод вызван меньше или больше раз, чем ожидалось

Ожидание вызовов одного метода с разными аргументами в произвольном порядке

Иногда требуется проверить, что метод вызывается несколько раз с определёнными аргументами, но порядок вызовов не имеет значения. Например:

• Регистрация нескольких событий, для которых последовательность не важна

• Отправка уведомлений нескольким получателям

• Запись независимых друг от друга элементов аудита

Метод withParameterSetsInAnyOrder() позволяет указать несколько наборов параметров, которые должны быть использованы все, но могут сопоставляться в любом порядке:

$dispatcher = $this->createMock(Dispatcher::class);

$dispatcher
    ->expects($this->exactly(2))
    ->method('dispatch')
    ->withParameterSetsInAnyOrder(
        [new AnotherEvent],
        [new AnEvent],
    );

$service = new Service($dispatcher);

$service->doSomething();

Неупорядоченные наборы параметров позволяют проверить, что метод вызывается несколько раз с определёнными аргументами, не задавая определённую последовательность. Это полезно, когда:

1. Порядок операций не влияет на корректность

2. Нужно оставить реализации свободу действий

3. Тестируется код, в котором вызовы могут менять порядок ради оптимизации

Тест завершится с ошибкой, если:

• Метод вызван с аргументами, которые не соответствуют ни одному ожидаемому набору параметров

• Использованы не все наборы параметров (некоторые ожидаемые вызовы отсутствуют)

• Метод вызван меньше или больше раз, чем ожидалось

Ожидание вызовов одного метода с разными аргументами в частично заданном порядке

Иногда порядок одних вызовов важен, а других — нет. Например, вызов инициализации должен произойти на определённой позиции в последовательности, тогда как окружающие его вызовы могут выполняться в любом порядке.

Метод withParameterSetsInPartialOrder() позволяет указать несколько наборов параметров, отдельные из которых можно «закрепить» за определённой позицией, а остальные сопоставлять в любом порядке. Набор параметров закрепляется, если обернуть его в массив с ключом pinned; его положение в списке аргументов withParameterSetsInPartialOrder() определяет индекс вызова (начиная с нуля), с которым он должен быть сопоставлен:

$dispatcher = $this->createMock(Dispatcher::class);

$dispatcher
    ->expects($this->exactly(3))
    ->method('dispatch')
    ->withParameterSetsInPartialOrder(
        [new AnEvent],
        [new AnotherEvent],
        ['pinned' => new FinalEvent],
    );

$service = new Service($dispatcher);

$service->doSomething();

В приведённом выше примере AnEvent и AnotherEvent могут отправляться в любом порядке при первых двух вызовах, но аргументом третьего (и последнего) вызова должен быть FinalEvent.

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

• Значимый порядок имеют только некоторые вызовы (например, вызов настройки или завершения), а остальные можно переставлять

• Нужно закрепить определённый вызов за конкретной позицией, не задавая излишне строгий порядок для всех остальных вызовов

Тест завершится с ошибкой, если:

• Закреплённый набор параметров не сопоставлен на заданной для него позиции

• Метод вызван с аргументами, которые не соответствуют ни одному из оставшихся (незакреплённых) наборов параметров

• Использованы не все наборы параметров (некоторые ожидаемые вызовы отсутствуют)

• Метод вызван меньше или больше раз, чем ожидалось

Проверка относительного порядка вызовов между ожиданиями объекта-мока

Методы id() и after() позволяют задавать зависимости между ожиданиями объекта-мока и гарантировать, что один метод будет вызван только после вызова другого.

• id(string $id): присваивает ожиданию уникальный идентификатор

• after(string $id): указывает, что это ожидание следует проверять, только если совпало ожидание с заданным идентификатором

Ниже приведён полный пример использования id() и after() для проверки того, что two() вызывается после one():

public function testTwoIsCalledAfterOne(): void
{
    $mock = $this->createMock(ServiceInterface::class);

    $mock
        ->expects($this->once())
        ->method('one')
        ->id('first-call');

    $mock
        ->expects($this->once())
        ->method('two')
        ->after('first-call');

    $mock->one();
    $mock->two();
}

1. Настройка первого ожидания

$mock
    ->expects($this->once())
    ->method('one')
    ->id('first-call');

• expects($this->once()) задаёт ожидание, что следующий метод будет вызван ровно один раз

• method('one') указывает, что это ожидание относится к методу one()

• id('first-call') присваивает этому ожиданию уникальный идентификатор "first-call". На этот идентификатор могут ссылаться другие ожидания с помощью after().

2. Настройка второго ожидания

$mock
    ->expects($this->once())
    ->method('two')
    ->after('first-call');

• expects($this->once()) задаёт ожидание, что two() будет вызван ровно один раз

• method('two') указывает, что это ожидание относится к методу two()

• after('first-call') создаёт зависимость от ожидания с идентификатором "first-call"'"

Это означает, что:

• Ожидание для two() будет проверяться, только после вызова one()

• Если two() вызывается до one(), этот вызов не будет засчитан при выполнении данного ожидания

• Тест завершится с ошибкой, если two() не будет вызван после вызова one()

3. Выполнение тестируемой системы

$mock->one();
$mock->two();

• Вызов one() для объекта-мока выполняет первое ожидание и «разблокирует» второе

• Вызов two() для объекта-мока выполняет второе ожидание, поскольку one() уже был вызван

Если two() вызван до one(), этот вызов не будет засчитан при выполнении ожидания after().

Повторная регистрация того же идентификатора приведёт к ошибке теста. Использование after() с идентификатором, который не был зарегистрирован с помощью id(), приведёт к сбою теста.

Методы, которые никогда не возвращают управление

Тип возвращаемого значения never указывает, что функция или метод никогда не завершится обычным образом. Такие методы могут:

• Выбросить исключение

• Вызвать exit() или die()

• Войти в бесконечный цикл

При написании модульных тестов для имитации методов с типом возвращаемого значения never требуется особая обработка, поскольку мок не может действительно «не возвращать управление»: при вызове он должен что-то сделать.

Если вы создаёте объект-мок интерфейса или расширяемого класса с методом, имеющим тип возвращаемого значения never, при вызове этого метода объект-мок выбросит NeverReturningMethodException. Это исключение имитирует поведение метода, который не завершается обычным образом.

Рассмотрим сценарий, в котором у нас есть интерфейс ErrorHandler с методом handle(), имеющим тип возвращаемого значения never:

<?php declare(strict_types=1);
interface ErrorHandler
{
    public function handle(Exception $e): never;
}

<?php declare(strict_types=1);
final readonly class ErrorHandlerImplementation implements ErrorHandler
{
    public function handle(Exception $e): never
    {
        print $e->getMessage();

        exit;
    }
}

<?php declare(strict_types=1);
final readonly class ServiceImplementation implements Service
{
    private ErrorHandler $errorHandler;

    public function __construct(ErrorHandler $errorHandler)
    {
        $this->errorHandler = $errorHandler;
    }

    public function doSomething(): void
    {
        try {
            // ...

            throw new Exception('message');
        } catch (Exception $e) {
            $this->errorHandler->handle($e);
        }
    }
}

Мы хотим проверить, что при выбрасывании исключения во время выполнения ServiceImplementation::doSomething() метод ErrorHandler::handle() вызывается с объектом исключения ожидаемого типа. Вот как это сделать:

1. Создание объекта-мока

$errorHandler = $this->createMock(ErrorHandler::class);

Эта строка создаёт объект-мок, реализующий интерфейс ErrorHandler. В объекте-моке будут все методы, определённые в интерфейсе, включая метод handle() с типом возвращаемого значения never.

2. Настройка объекта-мока

$errorHandler
    ->expects($this->once())
    ->method('handle')
    ->with($this->isInstanceOf(Exception::class))
    ->seal();

Эта цепочка вызовов настраивает поведение и ожидания объекта-мока:

• ->expects($this->once()): задаёт ожидание, что метод handle() будет вызван во время теста ровно один раз. Если метод не будет вызван или будет вызван более одного раза, тест завершится с ошибкой.

• ->method('handle'): указывает, что мы настраиваем метод handle() объекта-мока.

• ->with($this->isInstanceOf(Exception::class)): указывает, что метод handle() должен быть вызван с аргументом, являющимся экземпляром класса Exception. Это ограничение проверяет аргумент, переданный методу.

• ->seal(): завершает настройку мока и запрещает дальнейшие изменения конфигурации.

3. Создание тестируемой системы

$service = new ServiceImplementation($errorHandler);

Эта строка создаёт экземпляр класса ServiceImplementation, передавая ему созданный нами объект-мок, который заменяет зависимость ErrorHandler. Это стандартная процедура внедрения зависимостей, позволяющая тестировать ServiceImplementation изолированно от зависимости ErrorHandler.

4. Настройка ожидания, что вызываемый метод мока не вернёт управление

$this->expectException(NeverReturningMethodException::class);

Эта строка указывает PHPUnit, что во время теста ожидается исключение NeverReturningMethodException. Это ключевой момент при тестировании методов с типом возвращаемого значения never:

• При вызове $service->doSomething() внутри будет вызван $this->errorHandler->handle($e)

• Поскольку у handle() тип возвращаемого значения never, PHPUnit выбрасывает NeverReturningMethodException

• Ожидая это исключение, мы документируем предположение о том, что метод handle() не возвращает управление

5. Выполнение тестируемой системы

$service->doSomething();

Эта строка вызывает тестируемый метод. Последовательность выполнения такова:

1. Для службы вызывается doSomething()

2. Внутри doSomething() выбрасывается исключение, которое перехватывается

3. Перехваченное исключение передаётся в $this->errorHandler->handle($e)

4. Вызывается метод handle() объекта-мока

5. PHPUnit проверяет ожидание (метод вызван один раз с экземпляром Exception)

6. PHPUnit выбрасывает NeverReturningMethodException, поскольку у метода тип возвращаемого значения never

7. Тест проходит, поскольку мы ожидали это исключение

Всегда используйте $this->expectException(NeverReturningMethodException::class) при тестировании кода, вызывающего метод мока с типом возвращаемого значения never.

Исключение заменяет поведение «не возвращать управление»: в реальном коде метод с типом возвращаемого значения never вызвал бы exit(), выбросил исключение или вошёл бы в бесконечный цикл. В тестах NeverReturningMethodException имитирует это поведение, обеспечивая контролируемый способ завершить метод.

Проверка всё равно выполняется: даже если выбрасывается исключение, PHPUnit по-прежнему проверяет, выполнены ли заданные ожидания (например, expects($this->once()) и with()).

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

Свойства с перехватчиком установки значения

В примере ниже показан интерфейс, объявляющий свойство с перехватчиком установки значения:

<?php declare(strict_types=1);
interface InterfaceWithSetHookedProperty
{
    public string $property { set; }
}

Ожидания для свойства property с перехватчиком установки значения можно настроить следующим образом:

<?php declare(strict_types=1);
use PHPUnit\Framework\MockObject\Runtime\PropertyHook;
use PHPUnit\Framework\TestCase;

final class SetHookedPropertyMockExampleTest extends TestCase
{
    public function testExample(): void
    {
        $mock = $this->createMock(
            InterfaceWithSetHookedProperty::class,
        );

        $mock
            ->expects($this->once())
            ->method(PropertyHook::set('property'))
            ->with('value');

        $mock->property = 'value';
    }
}

В приведённом выше примере PropertyHook::set('property') используется, чтобы указать, что мы хотим настроить ожидание для метода, вызываемого при обращении на запись к свойству с именем property.

Обязательное запечатывание mock-объектов

Описанный выше метод seal() предоставляет разработчикам возможность по желанию завершить настройку mock-объектов и предотвратить неожиданные вызовы методов. Однако разработчикам необходимо самостоятельно помнить о вызове этого метода для своих mock-объектов, чтобы воспользоваться этой мерой безопасности.

По мере развития проектов и установления стандартов тестирования в командах становится полезным закреплять определённые практики тестирования на уровне проекта, а не полагаться на то, что отдельные разработчики будут применять их последовательно. Именно поэтому requireSealedMockObjects="true" можно использовать в файле конфигурации XML PHPUnit, чтобы установить политику на уровне проекта, закрепляющую лучшую практику запечатывания mock-объектов.