Testes Automatizados com PHPUnit

✓ Resposta: Nomear as chaves do Data Provider é o detalhe que economiza tempo: a saída do PHPUnit mostra calcularTotal com "preços com centavos quebrados" em vez de #4. E use assertEqualsWithDelta para float — assertSame em soma de decimais falha por arredondamento binário.

<?php

declare(strict_types=1);

namespace Tests\Unit;

use App\Domain\Carrinho;
use App\Domain\Produto;
use PHPUnit\Framework\Attributes\DataProvider;
use PHPUnit\Framework\Attributes\Test;
use PHPUnit\Framework\TestCase;

final class CarrinhoTest extends TestCase
{
    private Carrinho $carrinho;

    protected function setUp(): void
    {
        $this->carrinho = new Carrinho();
    }

    #[Test]
    public function carrinhoNasceVazio(): void
    {
        self::assertTrue($this->carrinho->estaVazio());
        self::assertSame(0.0, $this->carrinho->calcularTotal());
    }

    #[Test]
    public function adicionarProdutoTiraOCarrinhoDoEstadoVazio(): void
    {
        $this->carrinho->adicionar(new Produto(1, 'Teclado', 349.90), 1);

        self::assertFalse($this->carrinho->estaVazio());
        self::assertSame(349.90, $this->carrinho->calcularTotal());
    }

    #[Test]
    public function adicionarOMesmoProdutoSomaAsQuantidades(): void
    {
        $teclado = new Produto(1, 'Teclado', 100.00);

        $this->carrinho->adicionar($teclado, 2);
        $this->carrinho->adicionar($teclado, 3);

        self::assertSame(1, $this->carrinho->quantidadeDeItens());
        self::assertSame(500.00, $this->carrinho->calcularTotal());
    }

    #[Test]
    public function removerTiraOProdutoDoCarrinho(): void
    {
        $this->carrinho->adicionar(new Produto(1, 'Teclado', 100.00), 1);
        $this->carrinho->adicionar(new Produto(2, 'Mouse', 50.00), 1);

        $this->carrinho->remover(1);

        self::assertSame(50.00, $this->carrinho->calcularTotal());
    }

    #[Test]
    public function removerProdutoInexistenteNaoQuebra(): void
    {
        $this->carrinho->remover(999);

        self::assertTrue($this->carrinho->estaVazio());
    }

    #[Test]
    public function quantidadeZeroOuNegativaEhRejeitada(): void
    {
        $this->expectException(\InvalidArgumentException::class);

        $this->carrinho->adicionar(new Produto(1, 'Teclado', 100.00), 0);
    }

    /**
     * Data Provider: o mesmo teste roda uma vez por conjunto. Cada caso
     * aparece nomeado na saída, então a falha diz QUAL cenário quebrou.
     */
    #[Test]
    #[DataProvider('cenariosDeTotal')]
    public function calcularTotalSomaCorretamente(array $itens, float $esperado): void
    {
        foreach ($itens as [$id, $nome, $preco, $quantidade]) {
            $this->carrinho->adicionar(new Produto($id, $nome, $preco), $quantidade);
        }

        // Comparação de float pede delta: 0.1 + 0.2 !== 0.3 em binário.
        self::assertEqualsWithDelta($esperado, $this->carrinho->calcularTotal(), 0.001);
    }

    public static function cenariosDeTotal(): array
    {
        return [
            'carrinho vazio' => [
                [], 0.0,
            ],
            'um produto, uma unidade' => [
                [[1, 'Teclado', 349.90, 1]], 349.90,
            ],
            'um produto, várias unidades' => [
                [[1, 'Teclado', 349.90, 3]], 1049.70,
            ],
            'produtos diferentes' => [
                [[1, 'Teclado', 349.90, 1], [2, 'Mouse', 129.50, 2]], 608.90,
            ],
            'preços com centavos quebrados' => [
                [[1, 'Cabo', 19.99, 3], [2, 'Adesivo', 4.95, 7]], 94.62,
            ],
            'produto gratuito não altera o total' => [
                [[1, 'Teclado', 100.00, 1], [2, 'Brinde', 0.0, 5]], 100.00,
            ],
        ];
    }
}

✓ Resposta: O mock isola o controller: o teste não depende de segredo, relógio ou biblioteca de JWT — e roda em milissegundos. Repare no expects(self::never()): garantir que uma chamada não acontece é uma asserção legítima, e pega trabalho desperdiçado.

<?php

declare(strict_types=1);

namespace Tests\Unit;

use App\Auth\AuthController;
use App\Auth\ServicoJWT;
use App\Auth\TokenExpiradoException;
use App\Auth\TokenInvalidoException;
use PHPUnit\Framework\Attributes\Test;
use PHPUnit\Framework\TestCase;

final class AuthControllerTest extends TestCase
{
    #[Test]
    public function tokenValidoDevolve200ComOsDadosDoUsuario(): void
    {
        // createMock devolve um dublê com todos os métodos neutros; só o que
        // for configurado tem comportamento. Nenhum token real é emitido.
        $jwt = $this->createMock(ServicoJWT::class);

        $jwt->expects(self::once())          // exatamente uma chamada
            ->method('validar')
            ->with('token-valido')           // e com este argumento
            ->willReturn(['sub' => 7, 'jti' => 'abc', 'exp' => time() + 900]);

        $resposta = (new AuthController($jwt))->perfil('token-valido');

        self::assertSame(200, $resposta['status']);
        self::assertSame(7, $resposta['corpo']['usuario_id']);
    }

    #[Test]
    public function tokenExpiradoDevolve401(): void
    {
        $jwt = $this->createMock(ServicoJWT::class);

        $jwt->method('validar')
            ->willThrowException(new TokenExpiradoException('Token expirado.'));

        $resposta = (new AuthController($jwt))->perfil('token-velho');

        self::assertSame(401, $resposta['status']);
        self::assertSame('token_expirado', $resposta['corpo']['erro']);
    }

    #[Test]
    public function tokenInvalidoDevolve401ComCodigoProprio(): void
    {
        $jwt = $this->createMock(ServicoJWT::class);

        $jwt->method('validar')
            ->willThrowException(new TokenInvalidoException('Assinatura inválida.'));

        $resposta = (new AuthController($jwt))->perfil('token-forjado');

        self::assertSame(401, $resposta['status']);
        self::assertSame('token_invalido', $resposta['corpo']['erro']);

        // A mensagem técnica não pode vazar para o cliente.
        self::assertStringNotContainsString('Assinatura', json_encode($resposta['corpo']));
    }

    #[Test]
    public function tokenAusenteNemChegaAConsultarOServico(): void
    {
        $jwt = $this->createMock(ServicoJWT::class);

        // never(): provar que o método NÃO é chamado é tão útil quanto
        // provar que é — aqui, que não se gasta validação com token vazio.
        $jwt->expects(self::never())->method('validar');

        $resposta = (new AuthController($jwt))->perfil('');

        self::assertSame(401, $resposta['status']);
    }

    #[Test]
    public function respostasSucessivasSimulamRenovacaoDeToken(): void
    {
        $jwt = $this->createMock(ServicoJWT::class);

        // willReturnOnConsecutiveCalls: 1ª chamada falha, 2ª passa.
        $jwt->method('validar')
            ->willReturnOnConsecutiveCalls(
                self::throwException(new TokenExpiradoException('expirado')),
                ['sub' => 7, 'jti' => 'novo', 'exp' => time() + 900],
            );

        $controller = new AuthController($jwt);

        self::assertSame(401, $controller->perfil('t1')['status']);
        self::assertSame(200, $controller->perfil('t2')['status']);
    }
}

✓ Resposta: O último teste é o mais valioso da suíte: ele documenta que identificador passa por lista branca. Um refactor que "simplifique" a validação some com a proteção contra injeção — e é justamente esse teste que impede o merge.

<?php

declare(strict_types=1);

namespace Tests\Unit;

use App\Database\QueryBuilder;
use PHPUnit\Framework\Attributes\DataProvider;
use PHPUnit\Framework\Attributes\Test;
use PHPUnit\Framework\TestCase;

final class QueryBuilderTest extends TestCase
{
    // O builder é a peça perfeita para teste unitário: entra chamada de
    // método, sai string. Nenhum banco envolvido.
    #[Test]
    public function selectSimples(): void
    {
        [$sql, $params] = (new QueryBuilder())->from('produtos')->build();

        self::assertSame('SELECT * FROM produtos', $sql);
        self::assertSame([], $params);
    }

    #[Test]
    public function selectComColunas(): void
    {
        [$sql] = (new QueryBuilder())
            ->select('id', 'nome')
            ->from('produtos')
            ->build();

        self::assertSame('SELECT id, nome FROM produtos', $sql);
    }

    #[Test]
    public function whereGeraPlaceholderEParametro(): void
    {
        [$sql, $params] = (new QueryBuilder())
            ->from('produtos')
            ->where('ativo', '=', 1)
            ->build();

        self::assertStringContainsString('WHERE ativo = :', $sql);
        self::assertContains(1, $params);
        self::assertCount(1, $params);
    }

    #[Test]
    public function doisWheresSaoUnidosPorAnd(): void
    {
        [$sql, $params] = (new QueryBuilder())
            ->from('produtos')
            ->where('ativo', '=', 1)
            ->where('preco', '>', 100)
            ->build();

        self::assertMatchesRegularExpression('/WHERE ativo = :\w+ AND preco > :\w+/', $sql);
        self::assertCount(2, $params);

        // Placeholders distintos: se colidissem, um valor sobrescreveria o outro.
        self::assertCount(2, array_unique(array_keys($params)));
    }

    #[Test]
    public function whereInAceitaLista(): void
    {
        [$sql, $params] = (new QueryBuilder())
            ->from('produtos')
            ->whereIn('categoria_id', [1, 2, 3])
            ->build();

        self::assertStringContainsString('categoria_id IN (', $sql);
        self::assertCount(3, $params);
    }

    #[Test]
    public function orderByAceitaAscEDesc(): void
    {
        [$sqlAsc] = (new QueryBuilder())->from('p')->orderBy('nome')->build();
        [$sqlDesc] = (new QueryBuilder())->from('p')->orderBy('preco', 'desc')->build();

        self::assertStringEndsWith('ORDER BY nome ASC', $sqlAsc);
        self::assertStringEndsWith('ORDER BY preco DESC', $sqlDesc);
    }

    #[Test]
    public function limitEOffsetSaemNaOrdemCerta(): void
    {
        [$sql] = (new QueryBuilder())
            ->from('produtos')
            ->limit(10)
            ->offset(20)
            ->build();

        self::assertStringEndsWith('LIMIT 10 OFFSET 20', $sql);
    }

    #[Test]
    public function clausulasSaemNaOrdemDoSqlIndependenteDaOrdemDasChamadas(): void
    {
        // Chamadas fora de ordem, SQL na ordem correta: é o que o builder
        // garante e o motivo de ele existir.
        [$sql] = (new QueryBuilder())
            ->limit(5)
            ->orderBy('nome')
            ->from('produtos')
            ->where('ativo', '=', 1)
            ->select('id')
            ->build();

        self::assertMatchesRegularExpression(
            '/^SELECT id FROM produtos WHERE .+ ORDER BY nome ASC LIMIT 5$/',
            $sql,
        );
    }

    #[Test]
    public function buildSemFromLancaExcecao(): void
    {
        $this->expectException(\LogicException::class);
        $this->expectExceptionMessage('from()');

        (new QueryBuilder())->select('id')->build();
    }

    #[Test]
    #[DataProvider('identificadoresPerigosos')]
    public function identificadorInvalidoEhRejeitado(string $coluna): void
    {
        $this->expectException(\InvalidArgumentException::class);

        (new QueryBuilder())->from('produtos')->orderBy($coluna)->build();
    }

    public static function identificadoresPerigosos(): array
    {
        return [
            'injeção com drop'  => ['nome; DROP TABLE produtos'],
            'comentário sql'    => ['nome --'],
            'espaço e union'    => ['id UNION SELECT senha FROM usuarios'],
            'aspas'             => ["nome'"],
            'parêntese'         => ['count(*)'],
        ];
    }
}

✓ Resposta: Cuidado com o que o SQLite não reproduz do MySQL: sem PRAGMA foreign_keys = ON ele ignora FK, os tipos são flexíveis, e ENUM/UNSIGNED não existem. Serve muito bem para testar a mecânica do runner; o SQL específico do MySQL merece um teste contra MySQL de verdade.

<?php

declare(strict_types=1);

namespace Tests\Integration;

use App\Database\MigrationRunner;
use PDO;
use PHPUnit\Framework\Attributes\Test;
use PHPUnit\Framework\TestCase;

final class MigrationRunnerTest extends TestCase
{
    private PDO $pdo;
    private MigrationRunner $runner;

    protected function setUp(): void
    {
        // :memory: nasce e morre com a conexão: cada teste começa do zero,
        // sem arquivo para limpar e sem interferência entre testes.
        $this->pdo = new PDO('sqlite::memory:', null, null, [
            PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
        ]);

        // SQLite ignora foreign keys por padrão — sem isto, o teste passaria
        // mesmo com FK apontando para tabela inexistente.
        $this->pdo->exec('PRAGMA foreign_keys = ON');

        $this->runner = new MigrationRunner($this->pdo, [
            'Migration001Usuarios'   => new Migration001Usuarios(),
            'Migration002Categorias' => new Migration002Categorias(),
            'Migration003Produtos'   => new Migration003Produtos(),
        ]);
    }

    #[Test]
    public function migrateCriaTodasAsTabelas(): void
    {
        $this->runner->migrate();

        foreach (['usuarios', 'categorias', 'produtos'] as $tabela) {
            self::assertTrue($this->tabelaExiste($tabela), "Faltou a tabela {$tabela}");
        }
    }

    #[Test]
    public function migrateRegistraAsMigrationsExecutadas(): void
    {
        $this->runner->migrate();

        $executadas = $this->pdo->query('SELECT migration FROM migrations ORDER BY id')
                                ->fetchAll(PDO::FETCH_COLUMN);

        self::assertSame(
            ['Migration001Usuarios', 'Migration002Categorias', 'Migration003Produtos'],
            $executadas,
        );
    }

    #[Test]
    public function migrateEhIdempotente(): void
    {
        $aplicadas = $this->runner->migrate();
        self::assertSame(3, $aplicadas);

        // A segunda chamada não pode explodir nem reaplicar nada.
        $segunda = $this->runner->migrate();

        self::assertSame(0, $segunda, 'A 2ª execução não deveria aplicar nada.');
        self::assertSame(3, $this->contarMigrationsRegistradas());
    }

    #[Test]
    public function rollbackRemoveAsTabelasDoUltimoLote(): void
    {
        $this->runner->migrate();
        self::assertTrue($this->tabelaExiste('produtos'));

        $this->runner->rollback();

        foreach (['usuarios', 'categorias', 'produtos'] as $tabela) {
            self::assertFalse($this->tabelaExiste($tabela), "Sobrou a tabela {$tabela}");
        }

        self::assertSame(0, $this->contarMigrationsRegistradas());
    }

    #[Test]
    public function migrateAposRollbackFuncionaDeNovo(): void
    {
        $this->runner->migrate();
        $this->runner->rollback();

        $reaplicadas = $this->runner->migrate();

        self::assertSame(3, $reaplicadas);
        self::assertTrue($this->tabelaExiste('produtos'));
    }

    #[Test]
    public function foreignKeyImpedeProdutoSemCategoria(): void
    {
        $this->runner->migrate();

        $this->expectException(\PDOException::class);

        $this->pdo->exec(
            "INSERT INTO produtos (categoria_id, nome, preco) VALUES (999, 'Órfão', 10)"
        );
    }

    private function tabelaExiste(string $nome): bool
    {
        $stmt = $this->pdo->prepare(
            "SELECT COUNT(*) FROM sqlite_master WHERE type = 'table' AND name = :nome"
        );
        $stmt->execute([':nome' => $nome]);

        return (int) $stmt->fetchColumn() > 0;
    }

    private function contarMigrationsRegistradas(): int
    {
        return (int) $this->pdo->query('SELECT COUNT(*) FROM migrations')->fetchColumn();
    }
}

✓ Resposta: Cobertura mede o que executou, não o que foi verificado: um teste sem nenhum assert pode dar 100%. Por isso 90% é meta de orientação, não de qualidade — os 10% que faltam quase sempre são os caminhos de erro, e são justamente os que mais quebram em produção.

<?php
// ============ Instalando o driver de cobertura ============
//
// PCOV — leve e rápido, só mede cobertura de linha:
//   pecl install pcov
//   php.ini:  extension=pcov
//             pcov.enabled=1
//             pcov.directory=/caminho/do/projeto/src
//
// Xdebug — mais lento, mas mede branch e path coverage:
//   pecl install xdebug
//   php.ini:  zend_extension=xdebug
//             xdebug.mode=coverage
//
// Conferir:  php -m | grep -E 'pcov|xdebug'

// ============ phpunit.xml ============
// <?xml version="1.0" encoding="UTF-8"?>
// <phpunit bootstrap="vendor/autoload.php" colors="true"
//          failOnWarning="true" failOnRisky="true">
//     <testsuites>
//         <testsuite name="unit">        <directory>tests/Unit</directory></testsuite>
//         <testsuite name="integration"> <directory>tests/Integration</directory></testsuite>
//     </testsuites>
//
//     <source>
//         <include>
//             <directory>src/Domain</directory>
//             <directory>src/Service</directory>
//         </include>
//         <exclude>
//             <!-- Config e migrations não são lógica: incluí-las só
//                  distorce o número para baixo. -->
//             <directory>src/Config</directory>
//             <file>src/Database/Migration001Usuarios.php</file>
//         </exclude>
//     </source>
//
//     <coverage>
//         <report>
//             <html outputDirectory="coverage"/>
//             <text outputFile="php://stdout" showOnlySummary="true"/>
//             <clover outputFile="coverage/clover.xml"/>
//         </report>
//     </coverage>
// </phpunit>

// ============ Rodando ============
//   vendor/bin/phpunit --coverage-html coverage/
//   vendor/bin/phpunit --coverage-text
//   vendor/bin/phpunit --coverage-text --path-coverage      (só Xdebug)
//
// Abrir coverage/index.html: as linhas vermelhas são o que nenhum teste
// executou. É por elas que se começa.

declare(strict_types=1);

namespace Tests\Unit;

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

// #[CoversClass] restringe a medição ao alvo real do teste: sem isso, um
// teste de Carrinho "cobre" Produto de tabela, e o número engana.
#[CoversClass(\App\Domain\Carrinho::class)]
final class CarrinhoCoberturaTest extends TestCase
{
    // Os caminhos que costumam ficar vermelhos são os de erro — ninguém
    // lembra de testar o `throw`.
    #[Test]
    public function quantidadeNegativaLancaExcecao(): void
    {
        $this->expectException(\InvalidArgumentException::class);

        (new \App\Domain\Carrinho())->adicionar(new \App\Domain\Produto(1, 'X', 10.0), -1);
    }

    #[Test]
    public function aplicarCupomExpiradoNaoAlteraOTotal(): void
    {
        $carrinho = new \App\Domain\Carrinho();
        $carrinho->adicionar(new \App\Domain\Produto(1, 'Teclado', 100.0), 1);

        $carrinho->aplicarCupom('EXPIRADO10', new \DateTimeImmutable('2020-01-01'));

        self::assertSame(100.0, $carrinho->calcularTotal());
    }

    #[Test]
    public function carrinhoAcimaDoLimiteDeItensRecusaNovoProduto(): void
    {
        $carrinho = new \App\Domain\Carrinho(limiteDeItens: 2);

        $carrinho->adicionar(new \App\Domain\Produto(1, 'A', 10.0), 1);
        $carrinho->adicionar(new \App\Domain\Produto(2, 'B', 10.0), 1);

        $this->expectException(\DomainException::class);
        $carrinho->adicionar(new \App\Domain\Produto(3, 'C', 10.0), 1);
    }
}

// ============ Exigindo o mínimo no CI ============
// vendor/bin/phpunit --coverage-text \
//   --coverage-clover coverage/clover.xml \
//   --fail-on-incomplete --fail-on-skipped
//
// O PHPUnit 11 aceita limite mínimo direto no XML:
// <coverage><report>...</report></coverage>
// com requireCoverageMetadata="true" no elemento <phpunit>.