Pruebas de integración PHP con Docker: guía completa

Introducción: por qué las pruebas de integración de PHP en Docker son imprescindibles

El desarrollo de aplicaciones PHP modernas rara vez se limita a un solo servidor. Bases de datos, cachés (Redis, Memcached), colas (RabbitMQ), APIs externas — todo esto requiere verificar la interacción de los componentes. Las pruebas unitarias aíslan el código, pero no garantizan que la clase A funcione correctamente con la clase B a través de una base de datos real. Aquí es donde las pruebas de integración vienen al rescate.

El problema del enfoque clásico es la configuración del entorno. El desarrollador pasa horas configurando MySQL, ajustando permisos e instalando extensiones de PHP. Docker resuelve este problema de una vez por todas. En este artículo, analizaremos cómo organizar las pruebas de integración de una aplicación PHP utilizando Docker y Docker Compose. Obtendrá configuraciones listas, ejemplos de código y recomendaciones de optimización.

1. Configuración del entorno Docker para pruebas PHP

1.1. Estructura básica del proyecto

Supongamos que tenemos una aplicación PHP simple en Symfony o Laravel (cualquier framework sirve). Crearemos un archivo docker-compose.yml en la raíz del proyecto:

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"  # Redirección a un puerto no estándar para no interferir con la BD 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

Puntos clave:

• El servicio test_runner utiliza un contenedor separado con PHP CLI — esto aísla la ejecución de las pruebas de la aplicación principal.
• La base de datos se levanta con un esquema limpio. Para cada ejecución de pruebas, podemos recrearla.
• El puerto de MySQL se redirige al 3307 para no interferir con la BD local del desarrollador.

1.2. Dockerfile para la aplicación PHP

Crearemos un Dockerfile para el servicio 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 imagen se utilizará tanto para el desarrollo como para las pruebas. Es importante instalar la extensión pdo_mysql — sin ella, las pruebas que trabajan con la BD fallarán.

2. Escritura de pruebas de integración con PHPUnit

2.1. Configuración básica de PHPUnit

Asegúrese de tener PHPUnit instalado (a través de Composer). El archivo phpunit.xml debe apuntar a la base de datos de prueba:

<?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. Ejemplo de prueba de integración: trabajo con BD

Supongamos que tenemos un repositorio de usuarios. Escribamos una prueba que verifique el guardado y la búsqueda:

<?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