Pruebas E2E con Docker

Documentación para desarrolladores

Para la referencia técnica completa, consulta test/e2e/README.md en el repositorio.

El modo E2E con Docker arranca un entorno desechable de GitLab, provisiona fixtures, registra un runner de CI y ejecuta la suite end-to-end de MCP contra esa instancia local. La ruta por defecto usa GitLab CE; el modo Enterprise usa la imagen EE más una licencia Ultimate local. Úsalo cuando necesites validación de alta confianza sin depender de una instancia real configurada en .env.

Qué incluye

Componente	Propósito
GitLab CE o EE	Instancia efímera de GitLab para llamadas reales a REST y GraphQL
GitLab Runner	Habilita flujos de pipelines y jobs que los tests unitarios no pueden ejercitar
Servicio de fixtures	Proporciona endpoints deterministas para webhooks, emoji personalizados y mirrors
Suite E2E	Ejecuta flujos de herramientas individuales, meta-herramientas y herramientas dinámicas mediante transporte MCP en memoria

El modo Docker cubre los mismos flujos de ciclo de vida que los E2E autoalojados, además de escenarios de pipelines y jobs que solo están disponibles en Docker. Crea datos temporales en GitLab y los elimina al desmontar el stack.

Ejecución rápida

make test-e2e-docker

Ese objetivo orquesta el stack Docker, espera a GitLab, configura el usuario y el runner de pruebas, ejecuta la suite E2E de Go con el build tag e2e, y escribe reportes JUnit y JSON.

Para ejecutar la cobertura Enterprise/Premium contra GitLab EE, define ENTERPRISE_LICENSE en .env o en la shell y usa:

make test-e2e-docker-enterprise

Ese objetivo se ejecuta con los build tags e2e enterprise, asi compila los archivos comunes de harness y los tests Enterprise/Premium de test/e2e/suite/*_ee_test.go. Los tests solo CE viven en test/e2e/suite/*_ce_test.go y quedan en make test-e2e-docker, mientras las fixtures Enterprise pueden ajustarse de forma independiente.

Cuando ENTERPRISE_LICENSE contiene un activation code de 24 caracteres, la primera ejecucion correcta exporta la licencia reutilizable generada a test/e2e/.enterprise-license. Las siguientes ejecuciones Enterprise prefieren ese cache local ignorado por Git y lo instalan mediante la License API, asi no consumen otra vez el activation code.

Flujo manual

Usa la secuencia manual cuando necesites inspeccionar la UI de GitLab o relanzar un test concreto sin recrear el stack cada vez.

docker compose -f test/e2e/docker-compose.yml up -d
./test/e2e/scripts/wait-for-gitlab.sh
./test/e2e/scripts/setup-gitlab.sh
./test/e2e/scripts/register-runner.sh

set -a && source test/e2e/.env.docker && set +a
go test -v -tags e2e -timeout 600s ./test/e2e/suite/

docker compose -f test/e2e/docker-compose.yml down -v

Para preparar Enterprise manualmente, usa la imagen EE en los comandos de compose y activa el flag durante el provisionamiento:

env GITLAB_IMAGE=gitlab/gitlab-ee:latest docker compose -f test/e2e/docker-compose.yml up -d
GITLAB_ENTERPRISE=true ./test/e2e/scripts/setup-gitlab.sh
env GITLAB_IMAGE=gitlab/gitlab-ee:latest docker compose -f test/e2e/docker-compose.yml down -v

Para ejecutar solo el flujo de herramientas dinámicas después de preparar el entorno:

E2E_MODE=docker \
  go test -v -tags e2e -timeout 600s \
  -run '^TestDynamicToolSurface' \
  ./test/e2e/suite/

Cuándo usarlo

Situación	¿Usar E2E Docker?
Cambios en registro de herramientas, proyección del catálogo o schemas	Sí
Cambios en pipelines, jobs, webhooks, emoji personalizados o mirrors	Sí
Verificar release candidates antes de publicar binarios	Sí
Editar una página Markdown estrecha	Normalmente no
Depurar un unit test fallando con respuestas mock de GitLab	Normalmente no

Reportes y limpieza

La suite escribe reportes legibles por máquinas para CI y diagnóstico local. Si una ejecución falla, mantén el stack Docker levantado mientras inspeccionas los datos de GitLab, los logs del runner y los reportes E2E generados. Cuando termines, elimina todos los datos de prueba con:

docker compose -f test/e2e/docker-compose.yml down -v

Solución de problemas

Síntoma	Qué comprobar
GitLab nunca queda listo	Límites de memoria y CPU de Docker; GitLab necesita varios GB de RAM
Los escenarios Enterprise no se habilitan	GITLAB_ENTERPRISE=true, la imagen EE y ENTERPRISE_LICENSE en .env
Tests de pipelines o jobs saltados/fallando	Salida de registro del runner y valores de test/e2e/.env.docker
Fallos en webhooks o mirrors	Salud del contenedor de fixtures y URLs internas de la red Docker
Una repetición ve datos antiguos	Ejecuta docker compose -f test/e2e/docker-compose.yml down -v y empieza de nuevo

Docker E2E es más lento que los tests unitarios, pero es la ruta de validación preferida para migraciones de arquitectura porque ejercita la API real de GitLab, el transporte MCP y todas las superficies públicas de herramientas a la vez.

Preguntas frecuentes

¿Cómo ejecuto la suite E2E contra una instancia efímera de GitLab?

Ejecuta make test-e2e-docker. Ese objetivo orquesta el stack Docker, espera a GitLab, configura el usuario y el runner de CI de pruebas, ejecuta la suite E2E de Go con el build tag e2e y escribe reportes JUnit y JSON. La ruta por defecto usa GitLab CE y crea datos temporales que se eliminan al desmontar el stack, de modo que obtienes validación de alta confianza sin depender de una instancia real configurada en .env.

¿Cómo ejecuto la cobertura Enterprise/Premium de E2E con Docker?

Define ENTERPRISE_LICENSE en .env o en la shell y ejecuta make test-e2e-docker-enterprise. Ese objetivo usa la imagen GitLab EE más los build tags e2e enterprise, así que se compilan y ejecutan los archivos comunes de harness y los tests Enterprise/Premium de test/e2e/suite/*_ee_test.go. Cuando ENTERPRISE_LICENSE contiene un activation code de 24 caracteres, la primera ejecución correcta exporta una licencia reutilizable a test/e2e/.enterprise-license, de modo que las siguientes ejecuciones la instalan mediante la License API en lugar de consumir otra vez el activation code.

¿Cuándo debería usar el modo E2E con Docker en lugar de tests unitarios?

Usa E2E con Docker al cambiar el registro de herramientas, la proyección del catálogo o los schemas; al cambiar el comportamiento de pipelines, jobs, webhooks, emoji personalizados o mirrors; y al verificar release candidates antes de publicar binarios. Normalmente no hace falta para editar una página Markdown estrecha o depurar un test unitario fallando con respuestas mock de GitLab. E2E con Docker es más lento que los tests unitarios pero es la ruta de validación preferida para migraciones de arquitectura porque ejercita la API real de GitLab junto con el transporte MCP.

¿Cómo limpio los datos de prueba de E2E con Docker?

Ejecuta docker compose -f test/e2e/docker-compose.yml down -v para eliminar todos los contenedores y volúmenes, incluidos los datos temporales de GitLab. Si una ejecución falla, mantén el stack levantado mientras inspeccionas los datos de GitLab, los logs del runner y los reportes E2E generados, y desmóntalo al terminar el diagnóstico. Una repetición que ve datos antiguos suele indicar que el stack anterior no se eliminó con down -v.