Testing

Kubernetes has four test layers. Each has a different harness and a different cost-vs-coverage trade-off.

Unit tests

Plain go test. Lives next to the production code (foo.go ↔ foo_test.go). Run via:

make test                            # all packages
make test WHAT=./pkg/scheduler/...    # narrow scope
make test KUBE_RACE=-race             # with the race detector
make test WHAT=./pkg/kubelet GOFLAGS="-run TestSyncPod"

The driver script is hack/test-go.sh. The make test target sets sensible defaults including -count=1 and parallelism.

The largest single test files in the repo are unit tests. pkg/kubelet/kubelet_pods_test.go is 293,556 lines on its own. Subpackages like pkg/apis/core/validation/ have multi-thousand-line tables of input/output cases.

Conventions

• Use t.Run(name, func(t *testing.T) { ... }) for table-driven cases. Keep the name human-readable; it shows up in test output.
• Prefer cmp.Diff over hand-written comparison loops for struct equality.
• Use k8s.io/apimachinery/pkg/util/diff and k8s.io/utils/ktesting to share setup boilerplate.
• Avoid time.Sleep. Use k8s.io/client-go/util/wait (wait.PollUntilContextTimeout) for time-based assertions.
• Test files declare package foo_test only when external testing is required (cross-package calls). Otherwise they share the production package.

Integration tests

Lives under test/integration/<topic>/. Spins up a real kube-apiserver against an in-process etcd. Doesn't run kubelets — controllers and scheduler are wired directly to the apiserver fixture.

make test-integration WHAT=./test/integration/scheduler
make test-integration WHAT=./test/integration/auth

hack/install-etcd.sh downloads etcd if it isn't on PATH. The test framework lives in test/integration/framework/.

Integration tests are stricter than unit tests:

• They exercise admission, validation, defaulting, and conversion through the real API surface.
• They are the only place to test "this cross-controller interaction" without spinning up a full cluster.
• They are still in-process, so they're cheap enough to run on every PR.

End-to-end tests

test/e2e/ (cluster-scope) and test/e2e_node/ (per-node, no apiserver) are Ginkgo suites. They run against a real cluster.

hack/ginkgo-e2e.sh --ginkgo.focus="Conformance"
hack/e2e-node-test.sh

The e2e framework is in test/e2e/framework/. Tests are organized by SIG (test/e2e/apps, test/e2e/storage, test/e2e/network, test/e2e/scheduling, ...).

E2E tests must:

• Be hermetic — clean up every resource they create.
• Be parallel-safe by default, or annotate with [Serial] if not.
• Have an explicit [Conformance] annotation to opt into the conformance suite.

Conformance

test/conformance/ defines the certification baseline every certified Kubernetes distribution must pass. The tests themselves are tagged subsets of test/e2e. Adding a new conformance test requires a SIG-Architecture review.

Fuzz tests

test/fuzz/ exercises serialization, conversion, validation, and admission paths with randomized inputs. Most fuzzers run the standard go-fuzz harness. New API types require a fuzzer registration in pkg/api/testing/.

Performance tests

test/integration/scheduler/perf/ and the e2e scalability suite (test/e2e/scalability historically; now mostly out-of-tree in kubernetes/perf-tests) measure scheduling throughput, watch latency, and cluster bring-up time. These are not part of the default PR pipeline; they run on dedicated cloud capacity.

Test data

Most subsystems store fixture data in nearby testdata/ directories. The convention is:

• testdata/ — input data
• testdata/golden/ — expected outputs (generated and committed)

Use -update flags (where supported) to regenerate golden files after intentional changes.

Running everything before a PR

The "did I break anything?" runner is:

hack/verify-all.sh

It executes: vet, golangci-lint, gofmt, codegen freshness, vendor freshness, OWNERS validity, boilerplate, generated docs, and the staging-module module-graph integrity. Most CI failures are catchable by this script.