Day 6: Tests with envtest
Goal: A test suite that checks the real reconciler against a real API server – with
Eventually,Consistently, tables, unit tests without a cluster and coverage, ready for CI · Duration: approx. 120 min · Prerequisite: Day 5
Briefing
- envtest starts etcd + kube-apiserver per suite; the manager with your reconciler runs next to it as a goroutine.
- Tests check results, not calls:
Eventuallywaits until the cluster reaches the expected state. Notime.Sleep. - Each spec gets its own namespace – no dependencies between tests, order does not matter (Ginkgo shuffles it).
- Whatever works without an API server (mutate functions, error paths) you test faster with Go tables and the fake client.
go test ./internal/controller/
|- TestControllers (Ginkgo) -> envtest: etcd + kube-apiserver + CRDs
| |- Manager + StaticSiteReconciler (goroutine)
| +- Specs: k8sClient (no cache) + Eventually/Consistently
|- TestMutateDeployment -> pure Go table, no cluster
+- TestReconcileContentMissing -> fake client + FakeRecorder
Drill 1: Starting point
For tests you do not need envtest-up –
the suite starts its own control plane. Terminal 1 is enough:
source ~/op-lab/env.sh
cp -r ~/op-lab/tag05-site-operator ~/op-lab/tag06-site-operator
cd ~/op-lab/tag06-site-operator
rm -f lab/columns.txt lab/recorder.txt lab/check.sh
go test ./internal/... -count=1 -v -ginkgo.v -ginkgo.no-color 2>&1 \
| grep -E '^(StaticSite|Ran [0-9]|SUCCESS)'Expected (shortened):
StaticSite Controller When reconciling a resource should successfully reconcile ...
StaticSite API setzt Defaults im API-Server
StaticSite API lehnt replicas > 10 ab
StaticSite API – contentFrom verlangt configMapRef.name
Ran 4 of 4 Specs in 5.541 seconds
SUCCESS! -- 4 Passed | 0 Failed | 0 Pending | 0 Skipped
The Kubebuilder test calls Reconcile directly and only
checks “no error”. Today you replace it with specs that check the
behavior.
Save your progress? Sign up for free
Drill 2: The suite starts the manager
k8sClient reads directly from the API server (no cache)
– so the test always sees the current state. The reconciler gets the
manager’s cached client, as in production.
cat > internal/controller/suite_test.go <<'EOF'
package controller
import (
"context"
"path/filepath"
"testing"
"time"
. "github.com/onsi/ginkgo/v2"
. "github.com/onsi/gomega"
"k8s.io/client-go/kubernetes/scheme"
ctrl "sigs.k8s.io/controller-runtime"
"sigs.k8s.io/controller-runtime/pkg/client"
"sigs.k8s.io/controller-runtime/pkg/envtest"
logf "sigs.k8s.io/controller-runtime/pkg/log"
"sigs.k8s.io/controller-runtime/pkg/log/zap"
metricsserver "sigs.k8s.io/controller-runtime/pkg/metrics/server"
webv1alpha1 "example.com/site-operator/api/v1alpha1"
)
var (
ctx context.Context
cancel context.CancelFunc
testEnv *envtest.Environment
k8sClient client.Client // direkt, ohne Cache: sieht immer den aktuellen Stand
)
func TestControllers(t *testing.T) {
RegisterFailHandler(Fail)
RunSpecs(t, "Controller Suite")
}
var _ = BeforeSuite(func() {
logf.SetLogger(zap.New(zap.WriteTo(GinkgoWriter), zap.UseDevMode(true)))
SetDefaultEventuallyTimeout(10 * time.Second)
SetDefaultEventuallyPollingInterval(100 * time.Millisecond)
// Otherwise the default timeout does not apply with WithContext(ctx) – the test would hang forever.
EnforceDefaultTimeoutsWhenUsingContexts()
ctx, cancel = context.WithCancel(context.Background())
Expect(webv1alpha1.AddToScheme(scheme.Scheme)).To(Succeed())
By("envtest starten (Binaries aus KUBEBUILDER_ASSETS)")
testEnv = &envtest.Environment{
CRDDirectoryPaths: []string{
filepath.Join("..", "..", "config", "crd", "bases"),
},
ErrorIfCRDPathMissing: true,
}
cfg, err := testEnv.Start()
Expect(err).NotTo(HaveOccurred())
k8sClient, err = client.New(cfg, client.Options{Scheme: scheme.Scheme})
Expect(err).NotTo(HaveOccurred())
By("Manager mit dem echten Reconciler starten")
mgr, err := ctrl.NewManager(cfg, ctrl.Options{
Scheme: scheme.Scheme,
Metrics: metricsserver.Options{BindAddress: "0"}, // kein Port im Test
})
Expect(err).NotTo(HaveOccurred())
Expect((&StaticSiteReconciler{
Client: mgr.GetClient(),
Scheme: mgr.GetScheme(),
Recorder: mgr.GetEventRecorder("site-operator"),
}).SetupWithManager(mgr)).To(Succeed())
go func() {
defer GinkgoRecover()
Expect(mgr.Start(ctx)).To(Succeed())
}()
})
var _ = AfterSuite(func() {
By("Manager und envtest stoppen")
cancel()
Expect(testEnv.Stop()).To(Succeed())
})
EOFWarning: Without
EnforceDefaultTimeoutsWhenUsingContexts(), Gomega ignores the default timeout as soon as you useWithContext(ctx)– a failingEventuallythen hangs until thego testtimeout (10 min). That is exactly what happens in Drill 5 if you leave it out.
Save your progress? Sign up for free
Drill 3: Test helpers
Small helpers keep the specs readable. GinkgoHelper()
makes failures point to the calling line, not into the helper.
cat > internal/controller/helpers_test.go <<'EOF'
package controller
import (
"context"
"fmt"
. "github.com/onsi/ginkgo/v2"
. "github.com/onsi/gomega"
appsv1 "k8s.io/api/apps/v1"
corev1 "k8s.io/api/core/v1"
"k8s.io/apimachinery/pkg/api/meta"
metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
"sigs.k8s.io/controller-runtime/pkg/client"
webv1alpha1 "example.com/site-operator/api/v1alpha1"
)
// newNamespace isolates each spec in its own namespace.
// envtest never fully deletes namespaces (no namespace controller) – irrelevant in tests.
func newNamespace(ctx context.Context) string {
ns := &corev1.Namespace{ObjectMeta: metav1.ObjectMeta{GenerateName: "site-test-"}}
Expect(k8sClient.Create(ctx, ns)).To(Succeed())
return ns.Name
}
// newStaticSite builds a valid StaticSite; mutate adjusts it per test.
func newStaticSite(ns, name string,
mutate ...func(*webv1alpha1.StaticSite)) *webv1alpha1.StaticSite {
site := &webv1alpha1.StaticSite{
ObjectMeta: metav1.ObjectMeta{Name: name, Namespace: ns},
Spec: webv1alpha1.StaticSiteSpec{Content: "<h1>Test</h1>"},
}
for _, m := range mutate {
m(site)
}
return site
}
// markDeploymentReady plays the Deployment controller that envtest does not have.
func markDeploymentReady(ctx context.Context, key client.ObjectKey, n int32) {
GinkgoHelper()
dep := &appsv1.Deployment{}
Expect(k8sClient.Get(ctx, key, dep)).To(Succeed())
patch := client.MergeFrom(dep.DeepCopy())
dep.Status = appsv1.DeploymentStatus{
ObservedGeneration: dep.Generation, Replicas: n,
UpdatedReplicas: n, ReadyReplicas: n, AvailableReplicas: n,
}
Expect(k8sClient.Status().Patch(ctx, dep, patch)).To(Succeed())
}
// condition returns a function for Eventually/Consistently.
func condition(ctx context.Context, key client.ObjectKey,
typ string) func() (metav1.Condition, error) {
return func() (metav1.Condition, error) {
site := &webv1alpha1.StaticSite{}
if err := k8sClient.Get(ctx, key, site); err != nil {
return metav1.Condition{}, err
}
c := meta.FindStatusCondition(site.Status.Conditions, typ)
if c == nil {
return metav1.Condition{}, fmt.Errorf("condition %s fehlt", typ)
}
return *c, nil
}
}
// haveCondition checks status and reason in a single matcher.
func haveCondition(status metav1.ConditionStatus, reason string) OmegaMatcher {
return SatisfyAll(HaveField("Status", status), HaveField("Reason", reason))
}
EOF
go vet ./internal/controller/ && echo vet-okExpected:
vet-ok
Why markDeploymentReady? envtest has no Deployment
controller (Day 4) – you play it, like with fake_ready on
Day 5, only in Go.
Save your progress? Sign up for free
Drill 4: Specs for the reconciler
The file replaces the Kubebuilder test. Each spec creates a StaticSite and waits for the result – exactly what you checked by hand with kubectl on Days 4 and 5.
cat > internal/controller/staticsite_controller_test.go <<'EOF'
package controller
import (
"time"
. "github.com/onsi/ginkgo/v2"
. "github.com/onsi/gomega"
appsv1 "k8s.io/api/apps/v1"
corev1 "k8s.io/api/core/v1"
metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
"k8s.io/utils/ptr"
"sigs.k8s.io/controller-runtime/pkg/client"
webv1alpha1 "example.com/site-operator/api/v1alpha1"
)
var _ = Describe("StaticSite Controller", func() {
var (
ns string
key client.ObjectKey
site *webv1alpha1.StaticSite
)
BeforeEach(func(ctx SpecContext) {
ns = newNamespace(ctx)
key = client.ObjectKey{Namespace: ns, Name: "demo"}
site = newStaticSite(ns, "demo")
})
// getDeployment waits until the operator has created the Deployment.
getDeployment := func(ctx SpecContext) *appsv1.Deployment {
GinkgoHelper()
dep := &appsv1.Deployment{}
Eventually(func() error { return k8sClient.Get(ctx, key, dep) }).
WithContext(ctx).Should(Succeed())
return dep
}
It("erzeugt ConfigMap, Deployment und Service mit Owner", func(ctx SpecContext) {
Expect(k8sClient.Create(ctx, site)).To(Succeed())
dep := getDeployment(ctx)
Expect(metav1.IsControlledBy(dep, site)).To(BeTrue())
Expect(dep.Spec.Template.Annotations).
To(HaveKey("web.lab.example/content-hash"))
Expect(dep.Spec.Template.Spec.Containers[0].Ports[0].ContainerPort).
To(Equal(int32(8080)))
svc := &corev1.Service{}
Expect(k8sClient.Get(ctx, key, svc)).To(Succeed())
Expect(svc.Spec.Ports[0].Port).To(Equal(int32(80)))
cm := &corev1.ConfigMap{}
cmKey := client.ObjectKey{Namespace: ns, Name: "demo-content"}
Expect(k8sClient.Get(ctx, cmKey, cm)).To(Succeed())
Expect(cm.Data).To(HaveKeyWithValue("index.html", "<h1>Test</h1>"))
})
It("dreht manuelle Änderungen zurück", func(ctx SpecContext) {
Expect(k8sClient.Create(ctx, site)).To(Succeed())
dep := getDeployment(ctx)
dep.Spec.Replicas = ptr.To[int32](5)
Expect(k8sClient.Update(ctx, dep)).To(Succeed())
Eventually(func(g Gomega) {
g.Expect(k8sClient.Get(ctx, key, dep)).To(Succeed())
g.Expect(*dep.Spec.Replicas).To(Equal(int32(1)))
}).WithContext(ctx).Should(Succeed())
})
It("rollt bei neuem Inhalt mit neuem Hash aus", func(ctx SpecContext) {
Expect(k8sClient.Create(ctx, site)).To(Succeed())
hash := getDeployment(ctx).Spec.Template.Annotations[contentHashAnnotation]
Expect(k8sClient.Get(ctx, key, site)).To(Succeed())
site.Spec.Content = "<h1>Version 2</h1>"
Expect(k8sClient.Update(ctx, site)).To(Succeed())
Eventually(func() string {
return getDeployment(ctx).Spec.Template.Annotations[contentHashAnnotation]
}).WithContext(ctx).ShouldNot(Equal(hash))
})
It("meldet Available erst mit bereiten Pods", func(ctx SpecContext) {
Expect(k8sClient.Create(ctx, site)).To(Succeed())
available := condition(ctx, key, webv1alpha1.ConditionAvailable)
Eventually(available).WithContext(ctx).Should(haveCondition(
metav1.ConditionFalse, webv1alpha1.ReasonReplicasNotReady))
Consistently(available).WithContext(ctx).WithTimeout(time.Second).
Should(HaveField("Status", metav1.ConditionFalse))
markDeploymentReady(ctx, key, 1)
Eventually(available).WithContext(ctx).Should(haveCondition(
metav1.ConditionTrue, webv1alpha1.ReasonAllReplicasReady))
Expect(k8sClient.Get(ctx, key, site)).To(Succeed())
Expect(site.Status.ObservedGeneration).To(Equal(site.Generation))
Expect(site.Status.URL).To(Equal("http://demo." + ns + ".svc"))
})
It("schreibt im Ruhezustand nichts mehr (kein Hotloop)", func(ctx SpecContext) {
Expect(k8sClient.Create(ctx, site)).To(Succeed())
getDeployment(ctx)
markDeploymentReady(ctx, key, 1)
Eventually(condition(ctx, key, webv1alpha1.ConditionAvailable)).
WithContext(ctx).Should(HaveField("Status", metav1.ConditionTrue))
resourceVersions := func() []string {
s, d := &webv1alpha1.StaticSite{}, &appsv1.Deployment{}
Expect(k8sClient.Get(ctx, key, s)).To(Succeed())
Expect(k8sClient.Get(ctx, key, d)).To(Succeed())
return []string{s.ResourceVersion, d.ResourceVersion}
}
before := resourceVersions()
Consistently(resourceVersions).WithContext(ctx).
WithTimeout(2 * time.Second).Should(Equal(before))
})
It("meldet ContentMissing und erholt sich", func(ctx SpecContext) {
site.Spec.Content = ""
site.Spec.ContentFrom = &webv1alpha1.ContentSource{
ConfigMapRef: &webv1alpha1.ConfigMapReference{Name: "html"},
}
Expect(k8sClient.Create(ctx, site)).To(Succeed())
degraded := condition(ctx, key, webv1alpha1.ConditionDegraded)
Eventually(degraded).WithContext(ctx).Should(haveCondition(
metav1.ConditionTrue, webv1alpha1.ReasonContentMissing))
Expect(k8sClient.Create(ctx, &corev1.ConfigMap{
ObjectMeta: metav1.ObjectMeta{Name: "html", Namespace: ns},
Data: map[string]string{"index.html": "<h1>CM</h1>"},
})).To(Succeed())
// Until Day 10 the operator does not watch foreign ConfigMaps:
// an annotation wakes it up instead of waiting 30 s for RequeueAfter.
Expect(k8sClient.Get(ctx, key, site)).To(Succeed())
site.Annotations = map[string]string{"test/poke": "1"}
Expect(k8sClient.Update(ctx, site)).To(Succeed())
Eventually(degraded).WithContext(ctx).Should(haveCondition(
metav1.ConditionFalse, webv1alpha1.ReasonAsExpected))
})
})
EOF
go test ./internal/controller/ -count=1 -v -ginkgo.v -ginkgo.no-color 2>&1 \
| grep -E '^(StaticSite Controller|Ran [0-9]|SUCCESS)'Expected (order varies):
StaticSite Controller erzeugt ConfigMap, Deployment und Service mit Owner
StaticSite Controller dreht manuelle Änderungen zurück
StaticSite Controller rollt bei neuem Inhalt mit neuem Hash aus
StaticSite Controller meldet Available erst mit bereiten Pods
StaticSite Controller schreibt im Ruhezustand nichts mehr (kein Hotloop)
StaticSite Controller meldet ContentMissing und erholt sich
Ran 9 of 9 Specs in 9.144 seconds
SUCCESS! -- 9 Passed | 0 Failed | 0 Pending | 0 Skipped
Three patterns:
| Tool | Question | Example |
|---|---|---|
Eventually |
Will it become true at some point? | Deployment exists |
Consistently |
Does it stay true for a while? | no hot loop, not Available yet |
func(g Gomega) |
several checks per attempt | Get + compare replicas |
Save your progress? Sign up for free
Drill 5: A test must be able to fail
A test that never fails proves nothing. Remove
Owns(&appsv1.Deployment{}) – then the operator no
longer notices manual changes to the Deployment:
F=internal/controller/staticsite_controller.go
cp $F lab/controller.keep
sed -i.bak '/Owns(&appsv1.Deployment{})/d' $F && rm $F.bak
go test ./internal/controller/ -count=1 -ginkgo.no-color -ginkgo.focus="zurück" 2>&1 \
| grep -E 'Timed out|<int32>|^\s+to equal|Ran [0-9]|FAIL!'
cp lab/controller.keep $F && rm lab/controller.keepExpected:
[FAILED] Timed out after 10.000s.
<int32>: 5
to equal
<int32>: 1
Ran 1 of 9 Specs in 15.947 seconds
FAIL! -- 0 Passed | 1 Failed | 0 Pending | 8 Skipped
-ginkgo.focus selects specs by a regex on their names.
After copying the file back, everything is green again.
Save your progress? Sign up for free
Drill 6: Tables – with and without an API server
DescribeTable is Ginkgo’s table test. Here the real API
server checks the CRD validation from Day 3:
cat > internal/controller/validation_test.go <<'EOF'
package controller
import (
"strings"
. "github.com/onsi/ginkgo/v2"
. "github.com/onsi/gomega"
apierrors "k8s.io/apimachinery/pkg/api/errors"
webv1alpha1 "example.com/site-operator/api/v1alpha1"
)
type siteMutator = func(*webv1alpha1.StaticSite)
func replicas(n int32) siteMutator {
return func(s *webv1alpha1.StaticSite) { s.Spec.Replicas = n }
}
var _ = DescribeTable("CRD-Validierung",
func(ctx SpecContext, mutate siteMutator, valid bool) {
site := newStaticSite(newNamespace(ctx), "v", mutate)
err := k8sClient.Create(ctx, site)
if valid {
Expect(err).NotTo(HaveOccurred())
return
}
Expect(apierrors.IsInvalid(err)).To(BeTrue(), "err = %v", err)
},
Entry("minimal", func(*webv1alpha1.StaticSite) {}, true),
Entry("10 Replikas", replicas(10), true),
Entry("11 Replikas", replicas(11), false),
// omitempty: 0 is never sent at all, the server sets the default 1.
Entry("0 Replikas = Default", replicas(0), true),
Entry("Inhalt über 64 KiB", func(s *webv1alpha1.StaticSite) {
s.Spec.Content = strings.Repeat("x", 64*1024+1)
}, false),
)
EOFThe mutate functions from Day 4 do not need a cluster at all – a classic Go table is enough and checks idempotency along the way:
cat > internal/controller/resources_test.go <<'EOF'
package controller
import (
"testing"
appsv1 "k8s.io/api/apps/v1"
"k8s.io/apimachinery/pkg/api/equality"
metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
webv1alpha1 "example.com/site-operator/api/v1alpha1"
)
// Pure unit test: no API server, runs in milliseconds.
func TestMutateDeployment(t *testing.T) {
tests := []struct {
name, path, wantMount string
}{
{"Wurzel", "/", "/usr/share/nginx/html"},
{"Unterpfad", "/docs", "/usr/share/nginx/html/docs"},
{"ohne führenden Slash", "blog/", "/usr/share/nginx/html/blog"},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
site := &webv1alpha1.StaticSite{
ObjectMeta: metav1.ObjectMeta{Name: "demo"},
Spec: webv1alpha1.StaticSiteSpec{
Path: tt.path, Replicas: 2, Image: "nginx:lab",
},
}
dep := &appsv1.Deployment{}
mutateDeployment(dep, site, "abc")
mount := dep.Spec.Template.Spec.Containers[0].VolumeMounts[0]
if mount.MountPath != tt.wantMount {
t.Errorf("MountPath = %q, want %q", mount.MountPath, tt.wantMount)
}
before := dep.DeepCopy()
mutateDeployment(dep, site, "abc") // zweiter Lauf darf nichts ändern
if !equality.Semantic.DeepEqual(before, dep) {
t.Error("mutateDeployment ist nicht idempotent")
}
})
}
}
EOF
go test ./internal/controller/ -count=1 -run TestMutateDeployment -v 2>&1 \
| grep -E '^\s*--- |^ok'
go test ./internal/controller/ -count=1 -v -ginkgo.v -ginkgo.no-color 2>&1 \
| grep -E '^(CRD|Ran [0-9]|SUCCESS)'Expected (run times vary):
--- PASS: TestMutateDeployment (0.00s)
--- PASS: TestMutateDeployment/Wurzel (0.00s)
--- PASS: TestMutateDeployment/Unterpfad (0.00s)
--- PASS: TestMutateDeployment/ohne_führenden_Slash (0.00s)
ok example.com/site-operator/internal/controller 0.372s
CRD-Validierung minimal
CRD-Validierung 10 Replikas
CRD-Validierung 11 Replikas
CRD-Validierung 0 Replikas = Default
CRD-Validierung Inhalt über 64 KiB
Ran 14 of 14 Specs in 9.258 seconds
SUCCESS! -- 14 Passed | 0 Failed | 0 Pending | 0 Skipped
-run TestMutateDeployment does not start envtest –
TestControllers is not executed at all. The entry “0
Replikas” shows a trap from Day 3: because of omitempty, Go
never sends the 0, and the server sets the default 1. If you want to
allow or reject 0, the field needs a pointer.
Save your progress? Sign up for free
Drill 7: Error paths with the fake client
The fake client from controller-runtime is an in-memory store without
defaults, validation and watches. That is ideal for error paths: fast,
deterministic, no manager. events.NewFakeRecorder collects
events in a channel.
cat > internal/controller/reconcile_fake_test.go <<'EOF'
package controller
import (
"context"
"strings"
"testing"
"time"
"k8s.io/apimachinery/pkg/api/meta"
metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
"k8s.io/apimachinery/pkg/runtime"
clientgoscheme "k8s.io/client-go/kubernetes/scheme"
"k8s.io/client-go/tools/events"
ctrl "sigs.k8s.io/controller-runtime"
"sigs.k8s.io/controller-runtime/pkg/client"
"sigs.k8s.io/controller-runtime/pkg/client/fake"
webv1alpha1 "example.com/site-operator/api/v1alpha1"
)
// The fake client knows neither defaults nor validation – ideal for error paths.
func TestReconcileContentMissing(t *testing.T) {
scheme := runtime.NewScheme()
_ = clientgoscheme.AddToScheme(scheme)
_ = webv1alpha1.AddToScheme(scheme)
site := &webv1alpha1.StaticSite{
ObjectMeta: metav1.ObjectMeta{Name: "demo", Namespace: "default"},
Spec: webv1alpha1.StaticSiteSpec{Replicas: 1,
ContentFrom: &webv1alpha1.ContentSource{
ConfigMapRef: &webv1alpha1.ConfigMapReference{Name: "fehlt"},
}},
}
c := fake.NewClientBuilder().WithScheme(scheme).
WithObjects(site).WithStatusSubresource(site).Build()
rec := events.NewFakeRecorder(10)
r := &StaticSiteReconciler{Client: c, Scheme: scheme, Recorder: rec}
key := client.ObjectKeyFromObject(site)
res, err := r.Reconcile(context.Background(), ctrl.Request{NamespacedName: key})
if err != nil || res.RequeueAfter != 30*time.Second {
t.Fatalf("Reconcile = %+v, %v; want RequeueAfter 30s, nil", res, err)
}
got := &webv1alpha1.StaticSite{}
if err := c.Get(context.Background(), key, got); err != nil {
t.Fatal(err)
}
cond := meta.FindStatusCondition(got.Status.Conditions,
webv1alpha1.ConditionDegraded)
if cond == nil || cond.Reason != webv1alpha1.ReasonContentMissing {
t.Fatalf("Degraded = %+v, want Reason ContentMissing", cond)
}
close(rec.Events)
var warnings []string
for e := range rec.Events {
if strings.HasPrefix(e, "Warning ContentMissing") {
warnings = append(warnings, e)
}
}
if len(warnings) != 1 {
t.Errorf("Warning-Events = %q, want genau eins", warnings)
}
}
EOF
go test ./internal/controller/ -count=1 -run TestReconcileContentMissing -v 2>&1 \
| grep -E '^(--- |ok)'Expected:
--- PASS: TestReconcileContentMissing (0.04s)
ok example.com/site-operator/internal/controller 0.419s
WithStatusSubresource(site) is mandatory, otherwise the
fake client does not write Status().Patch like a real API
server. Rule of thumb: fake client for logic and error paths, envtest
for everything that needs watches, defaults or validation.
Save your progress? Sign up for free
Drill 8: Coverage, race detector and CI
Now everything together – exactly as the pipeline runs it:
go test ./internal/controller/ -count=1 -race -coverprofile=cover.out \
-ginkgo.no-color -ginkgo.junit-report=junit.xml
go tool cover -func=cover.out | grep -E 'Reconcile|updateStatus|total'
grep -o '<testsuites [^>]*>' internal/controller/junit.xmlExpected (shortened):
ok example.com/site-operator/internal/controller 11.839s coverage: 93.8% ...
.../internal/controller/staticsite_controller.go:44: Reconcile 90.0%
.../internal/controller/status.go:20: updateStatus 100.0%
total: (statements) 93.8%
<testsuites tests="16" disabled="0" errors="0" failures="0" time="9.902920667">
-race finds data races between manager goroutines and
test code; GitLab, Jenkins and GitHub read junit.xml (it
sits in the package directory, 14 specs + BeforeSuite/AfterSuite) as a
test report. go tool cover -html=cover.out shows which
lines no test reaches.
Kubebuilder has already set up CI:
.github/workflows/test.yml calls make test.
The target downloads the envtest binaries via setup-envtest
into bin/k8s/ and tests all packages except
test/e2e:
grep -A1 '^test:' Makefile
make test 2>&1 | tail -4Expected (shortened):
test: manifests generate fmt vet setup-envtest ## Run tests.
KUBEBUILDER_ASSETS="$(shell "$(ENVTEST)" use $(ENVTEST_K8S_VERSION) ...
example.com/site-operator/api/v1alpha1 coverage: 0.0% of statements
example.com/site-operator/cmd coverage: 0.0% of statements
ok example.com/site-operator/internal/controller 10.452s coverage: 93.0% ...
example.com/site-operator/test/utils coverage: 0.0% of statements
Tip: The first time,
make testdownloads about 100 MB intobin/k8s/. Locally,go test ./internal/...withKUBEBUILDER_ASSETSfromenv.shis enough; in CI you cachebin/between runs.
Save your progress? Sign up for free
Checkpoint
cat > lab/check.sh <<'EOF'
ok() { echo "✔ $1"; }
nok() { echo "✘ $1"; }
P=./internal/controller/
env -u KUBEBUILDER_ASSETS go test $P -count=1 \
-run 'TestMutateDeployment|TestReconcileContentMissing' >/dev/null 2>&1 \
&& ok "Unit-Tests ohne envtest" || nok "Unit-Tests"
out=$(go test $P -count=1 -v -ginkgo.no-color -coverprofile=cover.out 2>&1)
echo "$out" | grep -q '^SUCCESS!' && ok "envtest-Suite grün" || nok "Suite rot"
n=$(echo "$out" | sed -nE 's/^Ran ([0-9]+) of.*/\1/p')
[ "${n:-0}" -ge 14 ] && ok "$n Specs" || nok "zu wenige Specs (${n:-0})"
cov=$(go tool cover -func=cover.out | awk '/^total:/ {print int($3)}')
[ "${cov:-0}" -ge 80 ] && ok "Coverage ${cov}%" || nok "Coverage ${cov:-0}%"
grep -l 'time.Sleep' internal/controller/*_test.go >/dev/null \
&& nok "time.Sleep in Tests" || ok "kein time.Sleep – nur Eventually"
EOF
bash lab/check.shExpected:
✔ Unit-Tests ohne envtest
✔ envtest-Suite grün
✔ 14 Specs
✔ Coverage 92%
✔ kein time.Sleep – nur Eventually
Challenge
Write an envtest spec that proves that a missing ConfigMap puts a
Warning event with reason ContentMissing
into the namespace.
Hint: The recorder writes
events.k8s.io/v1 events; k8sClient.List with
eventsv1.EventList and client.InNamespace(ns)
finds them, ContainElement + HaveField checks
them.
Solution
cat > internal/controller/events_test.go <<'EOF'
package controller
import (
. "github.com/onsi/ginkgo/v2"
. "github.com/onsi/gomega"
eventsv1 "k8s.io/api/events/v1"
"sigs.k8s.io/controller-runtime/pkg/client"
webv1alpha1 "example.com/site-operator/api/v1alpha1"
)
var _ = It("erzeugt ein Warning-Event bei fehlendem Inhalt", func(ctx SpecContext) {
ns := newNamespace(ctx)
site := newStaticSite(ns, "ohne-cm", func(s *webv1alpha1.StaticSite) {
s.Spec.Content = ""
s.Spec.ContentFrom = &webv1alpha1.ContentSource{
ConfigMapRef: &webv1alpha1.ConfigMapReference{Name: "fehlt"},
}
})
Expect(k8sClient.Create(ctx, site)).To(Succeed())
Eventually(func(g Gomega) []eventsv1.Event {
var list eventsv1.EventList
g.Expect(k8sClient.List(ctx, &list, client.InNamespace(ns))).To(Succeed())
return list.Items
}).WithContext(ctx).Should(ContainElement(SatisfyAll(
HaveField("Type", "Warning"),
HaveField("Reason", webv1alpha1.ReasonContentMissing),
HaveField("Regarding.Name", "ohne-cm"),
)))
})
EOF
go test ./internal/controller/ -count=1 -v -ginkgo.v -ginkgo.no-color \
-ginkgo.focus="Warning-Event" 2>&1 | grep -E '^(erzeugt|Ran [0-9]|SUCCESS)'Expected:
erzeugt ein Warning-Event bei fehlendem Inhalt
Ran 1 of 15 Specs in 5.341 seconds
SUCCESS! -- 1 Passed | 0 Failed | 0 Pending | 14 Skipped
HaveField("Regarding.Name", …) reaches into nested
fields. The code state in code/tag06-site-operator does not
include the challenge.
Save your progress? Sign up for free
Enterprise Note
- Parallelize envtest suites:
ginkgo -pstarts a separate control plane per process – namespaces per spec (as here) are the prerequisite. - Pipelines pin the envtest version (
ENVTEST_K8S_VERSION) to the customer’s oldest supported Kubernetes version and additionally test against the newest one. - envtest does not replace an E2E test: images, RBAC in the cluster, webhooks with real certificates and pod behavior are only checked by a kind run (Day 12).
- Fix flaky tests immediately, never cover them up with
FlakeAttemptsor longer timeouts – usually there is a real race or a hot loop behind them. - Store test reports (
junit.xml) and coverage as pipeline artifacts; set coverage thresholds per package instead of globally, otherwisecmd/andtest/utilsdilute them.