Docker E2E Testing

Developer Documentation

For the complete technical reference, see test/e2e/README.md in the repository.

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.

Frequently asked questions

How do I run the E2E suite against an ephemeral GitLab?

Run make test-e2e-docker. That target orchestrates the Docker stack, waits for GitLab, configures the test user and CI runner, runs the Go E2E suite with the e2e build tag, and writes JUnit plus JSON reports. The default path uses GitLab CE and creates temporary GitLab data that is removed when the stack is torn down, so you get high-confidence validation without relying on a real .env GitLab instance.

How do I run Enterprise/Premium Docker E2E coverage?

Set ENTERPRISE_LICENSE in .env or your shell and run make test-e2e-docker-enterprise. That target uses the GitLab EE image plus the e2e enterprise build tags, so the common harness files and the test/e2e/suite/*_ee_test.go Enterprise/Premium tests are compiled and executed. When ENTERPRISE_LICENSE holds a 24-character activation code, the first successful run exports a reusable license key to test/e2e/.enterprise-license, so later runs install it through the License API instead of spending the activation code again.

When should I use Docker E2E mode instead of unit tests?

Use Docker E2E when changing tool registration, catalog projection, or schemas; when changing pipeline, job, webhook, custom emoji, or mirror behavior; and when verifying release candidates before publishing binaries. It is usually unnecessary for editing a narrow Markdown page or debugging a failing unit test with mocked GitLab responses. Docker E2E is slower than unit tests but is the preferred validation path for architecture migrations because it exercises the real GitLab API together with the MCP transport.

How do I clean up Docker E2E test data?

Run docker compose -f test/e2e/docker-compose.yml down -v to remove all containers and volumes, including the temporary GitLab data. If a run fails, keep the stack up while inspecting GitLab data, runner logs, and the generated E2E report files, then tear it down once you finish triage. A rerun that sees stale data usually means the previous stack was not removed with down -v.