1. O que é e para que serve

Codeception é um framework completo para testes de aplicações PHP que combina as melhores práticas de testes unitários, funcionais, de aceitação (acceptance) e de integração. Diferente do PHPUnit padrão, o Codeception oferece uma API única e intuitiva para todos os tipos de teste, além de ferramentas poderosas para trabalhar com navegadores (via WebDriver ou PhpBrowser), bancos de dados, REST API e até JavaScript.

O principal objetivo do Codeception é tornar o processo de escrita de testes o mais simples e legível possível. O framework utiliza uma sintaxe inspirada em BDD (Behavior-Driven Development), onde os testes são descritos em linguagem natural através de métodos de ação: $I->amOnPage('/login'), $I->fillField('email', 'user@example.com'), $I->click('Login'). Isso permite que não apenas desenvolvedores, mas também testadores, analistas e gerentes entendam facilmente o que está sendo verificado.

Codeception é indispensável em projetos que exigem testes abrangentes: desde a verificação de classes individuais (testes unitários) até a simulação de ações de um usuário real no navegador (testes de aceitação). Ele suporta frameworks populares (Laravel, Symfony, Yii2, Zend), gerencia automaticamente transações de banco de dados, tira screenshots em caso de erros e gera relatórios detalhados. Se você quer aumentar a qualidade do código e reduzir o tempo de testes de regressão, o Codeception será seu aliado confiável.

2. Instalação

O Codeception é distribuído via Composer, o gerenciador de pacotes padrão do PHP. Certifique-se de ter o PHP versão 7.4 ou superior e o Composer instalados.

Execute no terminal, na raiz do seu projeto:

composer require --dev codeception/codeception

Após a instalação, você pode inicializar o Codeception no projeto:

vendor/bin/codecept init

Este comando criará a estrutura básica de diretórios: tests/ com as subpastas unit, functional, acceptance, além do arquivo de configuração codeception.yml.

Para trabalhar com testes de navegador, instale também o módulo WebDriver (se você planeja usar Selenium ou ChromeDriver):

composer require --dev codeception/module-webdriver

Para testar REST API, instale o módulo REST:

composer require --dev codeception/module-rest

3. Primeiros passos — exemplo mínimo funcional

Vamos criar um teste unitário simples para verificar uma função matemática. Após a inicialização (codecept init), você já tem o arquivo tests/unit.suite.yml. Vamos editá-lo para habilitar o módulo Asserts:

# tests/unit.suite.yml
actor: UnitTester
modules:
    enabled:
        - Asserts

Agora, crie o arquivo de teste tests/unit/MathTest.php:

<?php
use Codeception\Test\Unit;

class MathTest extends Unit
{
    protected UnitTester $tester;

    public function testAddition()
    {
        $result = 2 + 3;
        $this->tester->assertEquals(5, $result, '2 + 3 deve ser igual a 5');
    }

    public function testSubtraction()
    {
        $result = 10 - 4;
        $this->tester->assertGreaterThan(5, $result, '10 - 4 deve ser maior que 5');
    }
}

Execute o teste:

vendor/bin/codecept run unit

Você deve ver uma saída verde indicando que os testes passaram com sucesso.