Testing

Traefik is heavily tested. The make targets are organized so that day-to-day work runs only the tests you need.

Test layout

Layer	Location	Runner
Go unit tests	pkg/**/*_test.go, cmd/**/*_test.go	make test-unit
Go integration tests	integration/*_test.go	make test-integration (Docker required, 20m timeout)
Gateway API conformance	integration/gateway_api_conformance_test.go (+ tag gatewayAPIConformance)	make test-gateway-api-conformance
Knative conformance	integration/knative_conformance_test.go (+ tag knativeConformance)	make test-knative-conformance
Dashboard unit tests	webui/src/**/*.spec.ts	make test-ui-unit (runs vitest in Docker)

Unit tests

make test-unit runs:

GOOS=$(GOOS) GOARCH=$(GOARCH) go test -cover -coverprofile=cover.out -v ./pkg/... ./cmd/...

Most subsystems follow a foo.go / foo_test.go convention:

• pkg/server/configurationwatcher_test.go exercises the configuration debouncing and listener dispatch.
• pkg/server/router/router_test.go builds full handler trees from synthetic dynamic configurations and asserts on routing decisions.
• pkg/middlewares/<name>/<name>_test.go tests the middleware in isolation against httptest.
• pkg/provider/<name>/<name>_test.go typically uses recorded fixtures or in-memory fakes (e.g. pkg/provider/kubernetes/crd/fixtures.yml).

Test helpers live in pkg/testhelpers/ (e.g. context with logger, asserters). Use them rather than rolling your own.

Integration tests

integration/ is its own Go package that compiles to a single test binary. Each _test.go file covers a behavior end-to-end:

• simple_test.go (~92k bytes) is the catch-all suite for small scenarios.
• https_test.go, acme_test.go exercise TLS and ACME flows.
• docker_test.go, k8s_test.go, consul_test.go, etcd_test.go, etc. exercise per-provider behavior.
• tracing_test.go is one of the largest files and validates OpenTelemetry traces end-to-end.

Integration tests build a real Traefik binary, write a configuration file under integration/fixtures/, start the binary against fake or containerized backends (integration/resources/), and run HTTP/TCP/UDP assertions via integration/try/.

Run the whole suite:

make pull-images   # one-time: pull Docker images used by tests
make test-integration

Run a single test:

go test ./integration -test.timeout=10m -test.run TestSimpleSuite/TestRouting -v

-failfast is on by default in the Makefile target — drop it locally if you want to see all failures.

Conformance suites

Both Gateway API and Knative ship upstream conformance tests. Traefik runs them against a freshly built image.

make test-gateway-api-conformance
make test-knative-conformance

These targets call build-image-dirty so they use the binary in your working tree. Update the traefikVersion flag in the Makefile if you bump the major.minor.

Dashboard unit tests

make test-ui-unit

Internally this builds the traefik-webui Docker image (webui/buildx.Dockerfile), installs Yarn dependencies, and runs yarn test:unit:ci (vitest). The tests are colocated with components in webui/src/.

To run them outside Docker:

cd webui
yarn install
yarn test

Coverage

make test-unit writes cover.out at the repo root. To inspect:

go tool cover -html=cover.out

Integration tests do not produce coverage output by default — they focus on behavior, not coverage.

Writing a new test

A new middleware test mirrors an existing one. For example, to test a hypothetical pkg/middlewares/foo:

package foo

import (
    "net/http"
    "net/http/httptest"
    "testing"

    "github.com/stretchr/testify/assert"
    "github.com/traefik/traefik/v3/pkg/config/dynamic"
    "github.com/traefik/traefik/v3/pkg/testhelpers"
)

func TestNew(t *testing.T) {
    next := http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
        w.WriteHeader(http.StatusOK)
    })
    h, err := New(t.Context(), next, dynamic.Foo{Enabled: true}, "test")
    assert.NoError(t, err)

    rec := httptest.NewRecorder()
    h.ServeHTTP(rec, testhelpers.MustNewRequest(http.MethodGet, "http://x/", nil))
    assert.Equal(t, http.StatusOK, rec.Code)
}

For a new integration scenario, copy a small file like integration/timeout_test.go and adapt the fixture under integration/fixtures/.

Race detection

Go race tests are not on by default in the Makefile. Run them locally on suspicion:

go test -race ./pkg/server/...

The configuration watcher and entry-point lifecycle are the most race-sensitive areas.