Teste de Integração PHP com Docker: Guia Completo

Introdução: por que o teste de integração PHP no Docker é indispensável

O desenvolvimento de aplicações PHP modernas raramente se limita a um único servidor. Bancos de dados, caches (Redis, Memcached), filas (RabbitMQ), APIs externas — tudo isso requer verificação da interação entre componentes. Testes unitários isolam o código, mas não garantem que a classe A funcione corretamente com a classe B através de um banco de dados real. É aqui que o teste de integração entra em ação.

O problema da abordagem clássica é a configuração do ambiente. O desenvolvedor gasta horas configurando MySQL, ajustando permissões e instalando extensões PHP. O Docker resolve esse problema de uma vez por todas. Neste artigo, vamos abordar como organizar testes de integração para uma aplicação PHP usando Docker e Docker Compose. Você receberá configurações prontas, exemplos de código e recomendações de otimização.

1. Configuração do ambiente Docker para testes PHP

1.1. Estrutura básica do projeto

Suponha que temos uma aplicação PHP simples em Symfony ou Laravel (qualquer framework serve). Vamos criar o arquivo docker-compose.yml na raiz do projeto:

version: '3.8'

services:  php:    build: .    volumes:      - .:/var/www/html    environment:      - DATABASE_URL=mysql://test_user:test_pass@db:3306/test_db    depends_on:      - db

  db:    image: mysql:8.0    environment:      MYSQL_ROOT_PASSWORD: root_pass      MYSQL_DATABASE: test_db      MYSQL_USER: test_user      MYSQL_PASSWORD: test_pass    ports:      - "3307:3306"  # Redirecionamento para porta não padrão para evitar conflito com banco local

  test_runner:    image: php:8.2-cli    volumes:      - .:/var/www/html    working_dir: /var/www/html    entrypoint: ["vendor/bin/phpunit"]    depends_on:      - db      - php

Pontos-chave:

• O serviço test_runner usa um contêiner separado com PHP CLI — isso isola a execução dos testes da aplicação principal.
• O banco de dados é iniciado com um esquema limpo. Para cada execução de testes, podemos recriá-lo.
• A porta do MySQL é redirecionada para 3307 para não interferir com o banco de dados local do desenvolvedor.

1.2. Dockerfile para a aplicação PHP

Vamos criar o Dockerfile para o serviço principal php:

FROM php:8.2-fpm

RUN docker-php-ext-install pdo_mysql mysqli

COPY --from=composer:latest /usr/bin/composer /usr/bin/composer

WORKDIR /var/www/html

COPY . .

RUN composer install --no-interaction --prefer-dist

Esta imagem será usada tanto para desenvolvimento quanto para testes. É importante instalar a extensão pdo_mysql — sem ela, os testes que interagem com o banco de dados falharão.

2. Escrevendo testes de integração com PHPUnit

2.1. Configuração básica do PHPUnit

Certifique-se de ter o PHPUnit instalado (via Composer). O arquivo phpunit.xml deve apontar para o banco de dados de teste:

<?xml version="1.0" encoding="UTF-8"?><phpunit bootstrap="vendor/autoload.php">    <php>        <env name="DATABASE_URL" value="mysql://test_user:test_pass@db:3306/test_db" />        <env name="APP_ENV" value="test" />    </php>    <testsuites>        <testsuite name="Integration">            <directory>tests/Integration</directory>        </testsuite>    </testsuites></phpunit>

2.2. Exemplo de teste de integração: trabalhando com banco de dados

Suponha que temos um repositório de usuários. Vamos escrever um teste que verifica a persistência e a busca:

<?php

namespace App\\Tests\\Integration;

use App\\Entity\\User;use App\\Repository\\UserRepository;use Doctrine\\ORM\\EntityManagerInterface;use Symfony\\Bundle\\FrameworkBundle\\Test\\KernelTestCase;

class UserRepos