Docker E2E Testing

Docker E2E mode starts a disposable GitLab environment, provisions fixtures, registers a CI runner, and runs the MCP end-to-end suite against that local instance. The default path uses GitLab CE; Enterprise mode uses the EE image plus a local Ultimate license. Use it when you need high-confidence validation without relying on a real .env GitLab instance.

What it includes

Component	Purpose
GitLab CE or EE	Ephemeral GitLab instance for real REST and GraphQL API calls
GitLab Runner	Enables pipeline and job workflows that unit tests cannot exercise
Fixture service	Provides deterministic webhook, custom emoji, and mirror endpoints
E2E suite	Runs individual, meta-tool, and dynamic tool workflows through in-memory MCP transport

Docker mode covers the same lifecycle workflows as self-hosted E2E plus Docker-only pipeline and job scenarios. It creates temporary GitLab data and removes it when the stack is torn down.

Quick run

make test-e2e-docker

That target orchestrates the Docker stack, waits for GitLab, configures the test user and runner, runs the Go E2E suite with the e2e build tag, and writes JUnit plus JSON reports.

To run the Enterprise/Premium coverage against GitLab EE, set ENTERPRISE_LICENSE in .env or your shell and use:

make test-e2e-docker-enterprise

That target runs with the e2e enterprise build tags, so common harness files plus test/e2e/suite/*_ee_test.go Enterprise/Premium tests are compiled and executed. CE-only tests live in test/e2e/suite/*_ce_test.go and stay in make test-e2e-docker, while Enterprise fixtures can be tuned independently.

When ENTERPRISE_LICENSE contains a 24-character activation code, the first successful run exports the generated reusable license key to test/e2e/.enterprise-license. Later Enterprise runs prefer that ignored local cache and install it through the License API, so they do not need to spend the activation code again.

Manual workflow

Use the manual sequence when you need to inspect the GitLab UI or rerun a focused test without recreating the stack every time.

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

For manual Enterprise setup, replace the compose commands with the EE image and set the edition flag during provisioning:

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

To run only the dynamic tool surface workflow after setup:

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

When to use it

Situation	Use Docker E2E?
Changing tool registration, catalog projection, or schemas	Yes
Changing pipeline, job, webhook, custom emoji, or mirror behavior	Yes
Verifying release candidates before publishing binaries	Yes
Editing a narrow Markdown page only	Usually no
Debugging a failing unit test with mocked GitLab responses	Usually no

Reports and cleanup

The suite writes machine-readable reports for CI and local triage. If a run fails, keep the Docker stack up while inspecting GitLab data, runner logs, and the generated E2E report files. When finished, remove all test data with:

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

Troubleshooting

Symptom	What to check
GitLab never becomes ready	Docker memory and CPU limits; GitLab needs several GB of RAM
Enterprise scenarios are not enabled	`GITLAB_ENTERPRISE=true`, the EE image, and `ENTERPRISE_LICENSE` in `.env`
Pipeline or job tests are skipped/failing	Runner registration output and `test/e2e/.env.docker` values
Webhook or mirror tests fail	Fixture service container health and internal Docker network URLs
A rerun sees stale data	Run `docker compose -f test/e2e/docker-compose.yml down -v` and start again

Docker E2E is slower than unit tests, but it is the preferred validation path for architecture migrations because it exercises the real GitLab API, the MCP transport, and every public tool surface together.