1. O que é e para que serve

Mockery é uma biblioteca poderosa e flexível para criar objetos mock (mock objects) em PHP. Ela é projetada para uso em testes unitários (unit testing) e permite que desenvolvedores isolem o código testado de suas dependências. Em vez de usar objetos reais (como conexão com banco de dados, clientes de API ou sistema de arquivos), você cria "simuladores" (mocks) que imitam o comportamento dos originais. Isso torna os testes rápidos, confiáveis e independentes de fatores externos.

Para que serve? Imagine que você está testando uma classe OrderProcessor que envia um e-mail após a finalização do pedido. Se você usar um Mailer real, seu teste ficará lento, dependerá da disponibilidade do servidor SMTP e poderá enviar e-mails para usuários reais acidentalmente. Com o Mockery, você cria um Mailer "falso" que apenas verifica se o método send() foi chamado com os argumentos corretos. Isso permite focar na lógica do OrderProcessor, e não na infraestrutura.

Mockery não é apenas uma substituição de objetos. Ela oferece uma API rica para descrever expectativas (expectations): você pode especificar quantas vezes um método deve ser chamado, com quais argumentos, em qual ordem e o que ele deve retornar. Isso torna os testes não apenas isolados, mas também autodocumentados, pois as expectativas descrevem claramente a interação entre os objetos.

2. Instalação

O Mockery é instalado via Composer — o gerenciador de pacotes padrão do PHP. Recomenda-se instalá-lo como dependência de desenvolvimento (require-dev), já que não é necessário no ambiente de produção.

composer require --dev mockery/mockery

Após a instalação, verifique se seu arquivo composer.json contém a seguinte entrada na seção require-dev:

{
    "require-dev": {
        "mockery/mockery": "^1.6"
    }
}

Se você usa PHPUnit, o Mockery se integra a ele "de fábrica" através do trait \Mockery\Adapter\Phpunit\MockeryPHPUnitIntegration.

3. Primeiros passos

Vamos criar um teste simples que demonstra a funcionalidade básica do Mockery. Suponha que temos uma classe Calculator que depende de um serviço Logger.

<?php
// Classes de exemplo
interface Logger {
    public function log(string $message): void;
}

class Calculator {
    private Logger $logger;

    public function __construct(Logger $logger) {
        $this->logger = $logger;
    }

    public function add(int $a, int $b): int {
        $result = $a + $b;
        $this->logger->log("Adding $a and $b, result: $result");
        return $result;
    }
}

// Teste usando Mockery
use PHPUnit\Framework\TestCase;
use Mockery\Adapter\Phpunit\MockeryPHPUnitIntegration;

class CalculatorTest extends TestCase {
    use MockeryPHPUnitIntegration;

    public function testAddLogsCorrectly(): void {
        // 1. Criamos um mock para Logger
        $loggerMock = Mockery::mock(Logger::class);

        // 2. Descrevemos a expectativa: método log() deve ser chamado 1 vez
        //    com a mensagem específica
        $loggerMock->shouldReceive('log')
            ->once()
            ->with('Adding 2 and 3, result: 5');

        // 3. Criamos o objeto testado com o mock
        $calculator = new Calculator($loggerMock);

        // 4.