wilhelm

wilhelm

Partial-matching assertions for Kubernetes resources in Go tests. Designed for testing Helm charts, controllers, and any code that produces K8s manifests.

[!WARNING] Pre-release. The API may shift before v1.0.0.

The idea

import (
	"os"
	"testing"

	"k8s.io/client-go/tools/clientcmd"

	"github.com/mridang/wilhelm/assert"
	"github.com/mridang/wilhelm/env"
)

func TestMyDeployment(t *testing.T) {
	cfg, _ := clientcmd.BuildConfigFromFlags("", os.Getenv("KUBECONFIG"))
	e, _ := env.NewEnv(cfg, "my-namespace")

	e.AssertPartial(t, "my-release", assert.DeploymentAssertion{
		Spec: assert.DeploymentSpecAssertion{
			Replicas: assert.SomePtr(int32(3)),
			Template: assert.PodTemplateSpecAssertion{
				Spec: assert.PodSpecAssertion{
					Containers: assert.Some([]assert.ContainerAssertion{
						{Name: assert.Some("app"), Image: assert.Some("nginx:1.27")},
					}),
				},
			},
		},
	})
}

You describe only the fields you care about. Wilhelm fetches the resource, walks the assertion via reflection, and ignores any field left at its zero value. Maps (labels, annotations) are subset-matched so Helm's own metadata doesn't break the assertion.

Repo layout

The repo is a Go multi-module monorepo. The CRD subpackages each declare their own go.mod, so a downstream consumer only pulls the operator types they actually import. A workspace file (go.work) keeps everything buildable from one checkout during development.

CRD coverage in v0.1

Deferred to a future release

Quick start

Importing the core packages:

go get github.com/mridang/wilhelm/assert
go get github.com/mridang/wilhelm/env

Importing one CRD subpackage pair (Flux Helm releases, for example):

go get github.com/mridang/wilhelm/assert/flux/helm
go get github.com/mridang/wilhelm/env/flux/helm

Bring your own cluster — wilhelm takes a *rest.Config from k8s.io/client-go/rest. Wilhelm does not start clusters, install charts, or wrap kubectl.

Field semantics at a glance

Development

devbox shell                                # or: devbox run -- <command>
make build                                  # build the root module
make test                                   # run unit tests
make lint                                   # golangci-lint
make format                                 # dprint + go fmt
make generate                               # regenerate root zz_generated.go files
make generate-all                           # regenerate every wilhelm module
make crd-list                               # list every wilhelm submodule

bash hack/scaffold-crd.sh <family> <ver> <upstream> <api-group>
                                            # scaffold a new CRD subpackage
bash hack/verify-all.sh                     # build + lint every wilhelm module

devbox.json pins Go 1.26, golangci-lint, dprint, gotestsum, helm, and kubectl. CI mirrors the same toolchain.

dprint.json deliberately formats only Markdown, JSON, YAML and TOML — Go formatting is handled by the standard gofmt/goimports chain (invoked via make format and golangci-lint --fix). Keeping the two tools disjoint avoids fight-loops on zz_generated.go.

License

Apache-2.0.