🎭 Test Doubles and Dependency Injection

What Are Test Doubles?

A test double is an object that stands in for a real dependency during a test. The name comes from a "stunt double" in film: it looks enough like the real actor to play a specific scene, without the real one having to take the risk.

💡 Why bother? Suppose UserService depends on a UserRepository that hits a database. If you test UserService with the real repository, a failing test could mean a bug in the service or a bad database connection, slow I/O, or missing data. Swap in a double and any failure can only be the service — that's isolation.

Doubles buy you four things: isolation (test one unit at a time), control (force any scenario, even rare ones like "the payment gateway timed out"), verification (assert a collaborator was called correctly), and speed (no network or disk).

The Five Types

Gerard Meszaros gave us a shared vocabulary. All five are "test doubles"; the differences are about how much they do and what you assert on them:

Dependency Injection

Doubles are only possible if a class lets you supply its dependencies from outside. That is dependency injection (DI). Contrast the two designs:

❌ Hard-wired dependency (untestable)

class UserService
{
    private UserRepository $users;

    public function __construct()
    {
        // Created internally — a test can never replace it
        $this->users = new UserRepository();
    }
}

✅ Injected dependency (testable)

class UserService
{
    // Depend on an interface, not a concrete class
    public function __construct(
        private readonly UserRepositoryInterface $users
    ) {}

    public function name(int $id): string
    {
        return $this->users->findById($id)?->name() ?? 'Unknown';
    }
}

There are three ways to inject, from most to least common:

• Constructor injection — required dependencies passed to __construct(). The default choice; the object is always valid once built.
• Setter injection — optional dependencies set via setLogger(...) after construction.
• Method injection — a dependency passed to the single method that needs it.

Doubles with PHPUnit

PHPUnit can generate doubles for any class or interface. createStub() makes a state double; createMock() makes one you can also set expectations on.

Creating a stub

#[Test]
public function it_returns_the_users_name(): void
{
    // A stub configured to return a fixed user
    $repo = $this->createStub(UserRepositoryInterface::class);
    $repo->method('findById')->willReturn(new User(1, 'John Doe'));

    $service = new UserService($repo);

    $this->assertSame('John Doe', $service->name(1));
}

Shaping stub responses

// A fixed value
$repo->method('findById')->willReturn($user);

// Different values on consecutive calls
$repo->method('findById')
     ->willReturnOnConsecutiveCalls($user1, $user2, null);

// Compute from arguments
$repo->method('findById')
     ->willReturnCallback(fn (int $id) =>
         $id === 1 ? new User(1, 'John') : null);

// Return an argument, or throw
$repo->method('save')->willReturnArgument(0);
$repo->method('findById')->willThrowException(new NotFoundException());

Creating a mock with expectations

#[Test]
public function deleting_a_user_sends_a_notification(): void
{
    $repo = $this->createStub(UserRepositoryInterface::class);
    $repo->method('findById')->willReturn(new User(1, 'John'));
    $repo->method('delete')->willReturn(true);

    $notifier = $this->createMock(NotifierInterface::class);
    $notifier->expects($this->once())         // must be called exactly once
             ->method('userDeleted')
             ->with($this->equalTo(1));        // with this argument

    $service = new UserService($repo, $notifier);
    $this->assertTrue($service->delete(1));
    // PHPUnit verifies the expectation automatically at test end
}

// Modern replacement: match responses to arguments, not call order
$repo->method('findById')->willReturnMap([
    [101, $product1],
    [102, $product2],
]);

Mockery for Expressive Mocks

Mockery is a standalone library with a fluent syntax that many find more readable than PHPUnit's, plus first-class spies and partial mocks. It's what Laravel uses under the hood.

composer require --dev mockery/mockery

use Mockery;
use PHPUnit\Framework\TestCase;

class UserServiceTest extends TestCase
{
    protected function tearDown(): void
    {
        Mockery::close();   // verifies expectations & cleans up
        parent::tearDown();
    }

    public function test_it_fetches_a_user(): void
    {
        $repo = Mockery::mock(UserRepositoryInterface::class);
        $repo->shouldReceive('findById')
             ->once()
             ->with(1)
             ->andReturn(new User(1, 'John Doe'));

        $service = new UserService($repo);

        $this->assertSame('John Doe', $service->name(1));
    }
}

Spies verify after the fact

// A spy: act first, assert afterwards — reads more naturally for some tests
$repo = Mockery::spy(UserRepositoryInterface::class);

$service = new UserService($repo);
$service->register('John', 'john@example.com');

$repo->shouldHaveReceived('save')->once();

Partial mocks and argument matchers

// Mock only one method; the rest run for real
$user = Mockery::mock(User::class)->makePartial();
$user->shouldReceive('isAdmin')->andReturn(true);

// Flexible argument matching
$mailer->shouldReceive('send')->with(
    'john@example.com',
    Mockery::type('string'),
    Mockery::pattern('/welcome/i')
);

Worked Example: OrderService

Let's tie it together. OrderService depends on three collaborators — a product repository, a payment gateway, and a mailer — all injected. We'll test the happy path and a failure path using stubs (for state) and mocks (for interactions).

<?php
class OrderService
{
    public function __construct(
        private readonly ProductRepositoryInterface $products,
        private readonly PaymentGatewayInterface $gateway,
        private readonly MailerInterface $mailer,
    ) {}

    public function placeOrder(int $userId, string $sku, int $qty): Order
    {
        $product = $this->products->findBySku($sku)
            ?? throw new \InvalidArgumentException("Unknown product: $sku");

        if ($product->stock() < $qty) {
            throw new \RuntimeException('Insufficient stock');
        }

        $total  = $product->price() * $qty;
        $result = $this->gateway->charge($userId, $total);

        if (! $result->succeeded()) {
            throw new \RuntimeException('Payment failed: ' . $result->message());
        }

        $order = new Order($userId, $sku, $qty, $total, $result->transactionId());
        $this->mailer->sendConfirmation($userId, $order);

        return $order;
    }
}

Happy path

#[Test]
public function it_charges_and_confirms_a_valid_order(): void
{
    // Stub: state the service reads
    $products = $this->createStub(ProductRepositoryInterface::class);
    $products->method('findBySku')->willReturn(new Product('BOOK', 20.0, stock: 5));

    // Stub the gateway to succeed
    $gateway = $this->createStub(PaymentGatewayInterface::class);
    $gateway->method('charge')
            ->willReturn(new PaymentResult(true, 'txn_123'));

    // Mock: verify the confirmation email is sent once
    $mailer = $this->createMock(MailerInterface::class);
    $mailer->expects($this->once())
           ->method('sendConfirmation')
           ->with(1, $this->isInstanceOf(Order::class));

    $service = new OrderService($products, $gateway, $mailer);
    $order   = $service->placeOrder(1, 'BOOK', 2);

    $this->assertSame(40.0, $order->total());
    $this->assertSame('txn_123', $order->transactionId());
}

Failure path: payment declined

#[Test]
public function it_does_not_email_when_payment_is_declined(): void
{
    $products = $this->createStub(ProductRepositoryInterface::class);
    $products->method('findBySku')->willReturn(new Product('BOOK', 20.0, stock: 5));

    $gateway = $this->createStub(PaymentGatewayInterface::class);
    $gateway->method('charge')
            ->willReturn(new PaymentResult(false, 'Card declined'));

    // The mailer must NEVER be called on a failed payment
    $mailer = $this->createMock(MailerInterface::class);
    $mailer->expects($this->never())->method('sendConfirmation');

    $service = new OrderService($products, $gateway, $mailer);

    $this->expectException(\RuntimeException::class);
    $this->expectExceptionMessage('Payment failed: Card declined');

    $service->placeOrder(1, 'BOOK', 2);
}

DI Containers

Injecting dependencies by hand is fine for a handful of classes, but a real app has hundreds. A dependency injection container knows how to build objects and their dependency graph for you. PHP-DI is a popular standalone choice:

use DI\ContainerBuilder;
use function DI\autowire;

$container = (new ContainerBuilder())
    ->addDefinitions([
        // Bind an interface to a concrete implementation
        UserRepositoryInterface::class => autowire(DbUserRepository::class),
        MailerInterface::class         => autowire(SmtpMailer::class),
    ])
    ->build();

// The container resolves the whole graph via constructor type-hints
$service = $container->get(UserService::class);

Hands-on Exercise

public function cancelOrder(int $orderId): bool
{
    $order = $this->orders->findById($orderId);
    if ($order === null || $order->status() !== 'paid') {
        return false;   // nothing to cancel
    }

    $refund = $this->gateway->refund($order->transactionId());
    if (! $refund->succeeded()) {
        throw new \RuntimeException('Refund failed');
    }

    $order->markCancelled();
    $this->orders->save($order);
    $this->mailer->sendCancellation($order->userId(), $order);

    return true;
}

<?php
namespace Tests\Unit;

use PHPUnit\Framework\TestCase;
use PHPUnit\Framework\Attributes\Test;

class OrderCancellationTest extends TestCase
{
    #[Test]
    public function a_paid_order_is_refunded_and_emailed(): void
    {
        $order = new Order(userId: 7, status: 'paid', transactionId: 'txn_9');

        $orders = $this->createMock(OrderRepositoryInterface::class);
        $orders->method('findById')->willReturn($order);
        $orders->expects($this->once())->method('save')->with($order);

        $gateway = $this->createStub(PaymentGatewayInterface::class);
        $gateway->method('refund')->willReturn(new RefundResult(true));

        $mailer = $this->createMock(MailerInterface::class);
        $mailer->expects($this->once())
               ->method('sendCancellation')
               ->with(7, $order);

        $service = new OrderService($orders, $gateway, $mailer);

        $this->assertTrue($service->cancelOrder(1));
    }

    #[Test]
    public function an_unpaid_order_cannot_be_cancelled(): void
    {
        $orders = $this->createStub(OrderRepositoryInterface::class);
        $orders->method('findById')
               ->willReturn(new Order(userId: 7, status: 'pending', transactionId: ''));

        $gateway = $this->createMock(PaymentGatewayInterface::class);
        $gateway->expects($this->never())->method('refund');

        $mailer = $this->createMock(MailerInterface::class);
        $mailer->expects($this->never())->method('sendCancellation');

        $service = new OrderService($orders, $gateway, $mailer);

        $this->assertFalse($service->cancelOrder(1));
    }

    #[Test]
    public function a_failed_refund_throws_and_sends_no_email(): void
    {
        $order = new Order(userId: 7, status: 'paid', transactionId: 'txn_9');

        $orders = $this->createStub(OrderRepositoryInterface::class);
        $orders->method('findById')->willReturn($order);

        $gateway = $this->createStub(PaymentGatewayInterface::class);
        $gateway->method('refund')->willReturn(new RefundResult(false));

        $mailer = $this->createMock(MailerInterface::class);
        $mailer->expects($this->never())->method('sendCancellation');

        $service = new OrderService($orders, $gateway, $mailer);

        $this->expectException(\RuntimeException::class);
        $service->cancelOrder(1);
    }
}

Best Practices & Anti-Patterns

Summary & Quiz

📚 Further Reading

• Martin Fowler — Mocks Aren't Stubs
• PHPUnit 11 — Test Doubles
• Mockery documentation
• PHP-DI — dependency injection container

🚀 What's Next?

You can now isolate any unit under test. Next we zoom all the way out to the opposite end of the pyramid: end-to-end testing principles, where nothing is mocked and you verify the whole system as a user would.