Cómo ejecutar tests en paralelo con pytest: guía práctica

Cuando tu suite de tests crece, el tiempo de ejecución empieza a ser un problema. Lo que tardaba 2 minutos pasa a tardar 10, luego 20, luego media hora. En ese momento la paralelización es la solución más efectiva — ejecutar varios tests al mismo tiempo en lugar de uno detrás de otro.

En este artículo te explico cómo hacerlo con pytest y pytest-xdist paso a paso.

---

Por qué la paralelización importa

En un pipeline de CI/CD, cada minuto que tarda la suite de tests es un minuto que el equipo espera para saber si su código es correcto. Si los tests tardan 30 minutos, nadie va a ejecutarlos frecuentemente y los bugs llegarán más tarde.

La paralelización puede reducir ese tiempo de forma drástica. Una suite que tarda 30 minutos en secuencial puede tardar 8-10 minutos ejecutando 4 workers en paralelo.

---

pytest-xdist — el plugin de paralelización para pytest

El plugin más usado para paralelizar tests en pytest es pytest-xdist. Distribuye los tests entre múltiples workers que se ejecutan simultáneamente.

Para instalarlo:

bash

pip install pytest-xdist

Para ejecutar los tests en paralelo con 4 workers:

bash

pytest tests/ -n 4

Para usar automáticamente todos los cores disponibles del sistema:

bash

pytest tests/ -n auto

Con -n auto pytest-xdist detecta cuántos cores tiene tu máquina y usa todos para maximizar la velocidad.

---

Cuántos workers usar

La regla general es usar tantos workers como cores tenga tu máquina. Si tienes 4 cores, -n 4 es el punto de partida óptimo.

En CI/CD la mayoría de runners de GitHub Actions tienen 2 cores disponibles, así que -n 2 suele ser el máximo útil en ese entorno. Usar más workers de los que hay cores disponibles puede ralentizar la ejecución en lugar de acelerarla.

---

El requisito fundamental — tests independientes

La paralelización solo funciona bien si tus tests son completamente independientes entre sí. Si un test depende del estado que dejó el test anterior, en ejecución paralela ese estado puede no existir todavía — o puede haber sido modificado por otro test que se ejecutó en paralelo.

Antes de paralelizar, verifica que cada test prepara su propio estado y lo limpia después. Los fixtures de pytest con scope correcto son la herramienta principal para garantizar esto.

Si tienes tests que comparten datos de prueba, cada uno debe trabajar con sus propios datos únicos para evitar conflictos en ejecución paralela.

---

Configurar pytest-xdist en pytest.ini

Para no tener que escribir -n auto en cada ejecución, puedes configurarlo en pytest.ini:

ini

[pytest]
addopts = -n auto

Con esto, cada vez que ejecutes pytest a secas los tests se ejecutarán en paralelo automáticamente.

---

Integrar la paralelización en GitHub Actions

Para aprovechar la paralelización en CI/CD añade esto a tu workflow:

yaml

- name: Instalar dependencias
  run: |
    pip install -r requirements.txt
    pip install pytest-xdist
    playwright install --with-deps

- name: Ejecutar tests en paralelo
  run: pytest tests/ -n 2 -v

Con -n 2 aprovechas los dos cores disponibles en los runners gratuitos de GitHub Actions.

---

Paralelización con Playwright — consideraciones especiales

Cuando usas pytest-xdist con Playwright hay que tener en cuenta que cada worker necesita su propio contexto de navegador. Si compartes el mismo objeto de página entre workers, los tests interferirán entre sí.

La forma correcta es definir los fixtures de Playwright con scope="function" para que cada test reciba su propia instancia de página:

python

@pytest.fixture(scope="function")
def page(browser):
    context = browser.new_context()
    page = context.new_page()
    yield page
    context.close()

Con este fixture cada test tiene su propia página aislada y pueden ejecutarse en paralelo sin interferencias.

---

Cuándo no paralelizar

La paralelización no siempre es la solución correcta. No tiene sentido paralelizar si los tests no son independientes — primero hay que arreglar las dependencias. Tampoco tiene sentido si la suite es pequeña y rápida — el overhead de arrancar workers puede ser mayor que el tiempo ahorrado. Y si los tests dependen de un recurso externo con limitaciones de concurrencia — como una API con rate limiting — la paralelización puede causar fallos.

Si quieres saber más sobre cómo optimizar tu suite de tests puedes leer cómo eliminar tests flaky o cómo generar reportes HTML con pytest.

Y si necesitas ayuda para optimizar la estrategia de testing de tu proyecto puedes ver mis servicios en fatimaqa.com.