Testing

Cilium ships several distinct test surfaces. Choose based on what you changed.

Go unit tests

make unit-tests                                # run everything
go test ./pkg/policy/...                       # one subtree
go test -run TestSelectorCache ./pkg/policy/   # one test
go test -race ./pkg/...                        # with race detector

• Test files live alongside source files (*_test.go).
• Most pkg/ packages have table-driven tests.
• Where tests need a fake k8s API server, helpers live in pkg/k8s/testutils/ and pkg/testutils/.
• Hive-based tests use hivetest.Lifecycle, hivetest.Logger, and hive.New to spin up only the cells under test.

Privileged unit tests

Some tests require root and a Linux kernel with BPF support (loading maps, mounting bpffs, attaching programs):

make tests-privileged                          # run all
sudo go test -tags=privileged ./pkg/maps/...   # subset

These run in CI under privileged-unit-tests.yaml on a Ubuntu runner with kernel headers. They are gated by the privileged build tag.

BPF unit tests

The bpf/ tree has its own test harness using bpf_prog_test_run (the kernel's eBPF self-test interface) plus the bpftest Go runner:

make -C bpf unit-test            # compile + run
make -C bpf complexity-tests     # verifier complexity stress tests

Tests are written in C under bpf/tests/ and parameterised in YAML configs.

Connectivity test

The flagship end-to-end suite is cilium connectivity test, implemented under cilium-cli/connectivity/:

# Install Cilium into a kind cluster and run the suite
cilium install --version $(cat VERSION)
cilium connectivity test

It deploys a battery of pods (echo-same-node, echo-other-node, client, ...) and exercises every policy/encryption/LB feature. CI runs subsets of this suite on every PR across multiple kernel and Kubernetes versions.

Legacy Ginkgo suite (test/)

The older Ginkgo end-to-end tests under test/ still cover several features but are gradually being migrated. They run in dedicated VM-based CI workflows. New tests should prefer the connectivity-test suite or package-level Go tests.

Hubble Relay and Hubble UI integration

pkg/hubble/relay/ and the Relay binary have their own gRPC-level tests using a fake hubble-observer server. Run via go test ./pkg/hubble/....

How to run a single workflow locally

For matrix workflows that hit a kind cluster, use the helpers under contrib/:

# Build local images and load them into kind
make kind-image kind-install

# Or for a specific image
DOCKER_IMAGE=cilium-dev make kind-image

CI also exposes act-compatible workflows where possible; for the privileged BPF tests you need a real Linux host.

Coverage

Coverage is tracked per workflow but not gated. To check coverage locally:

go test -coverprofile=cover.out ./pkg/policy/...
go tool cover -html=cover.out

Mocks and fakes

• K8s clientset: k8s.io/client-go/kubernetes/fake, wrapped by pkg/k8s/testutils/.
• BPF maps: pkg/bpf/fake_map.go and per-map fakes (pkg/maps/fake/, pkg/maps/lbmap/...).
• Datapath: pkg/datapath/fake/ provides a no-op datapath for control-plane tests.
• Identity allocator: pkg/testidentity/ and pkg/identity/cache/cache_mock.go.

Linters

golangci-lint run                     # config in .golangci.yaml
make checkpatch                       # commit message + import ordering + license headers
make -C Documentation check           # docs and CRD/Helm sync checks

The license-header check enforces an SPDX-License-Identifier line on every Go and C source file.