Testing Strategy

Choose the smallest test that proves the change you actually made.

The testing stack is layered on purpose. Start with the cheapest signal that can fail for the right reason, then move outward only when the change touches controller wiring, real API semantics, full cluster lifecycle, or environment-specific behavior.

Diagram

Testing layers

Move outward only when the cheaper layer can no longer prove the behavior you changed.

Decision matrix

Choose test depth by change scope

Choose test depth by change scope.

If your change affects	Run this first	What it proves
Pure Go logic, parsers, renderers, helpers, or small decision functions	make test or targeted go test ./...	Deterministic in-process behavior with no Kubernetes API dependency.
Object builders, manifests, patches, or fake-client contract behavior	make test plus targeted package tests	Resource shape and emitted contracts when API-server semantics do not matter.
Reconciliation, finalizers, status writes, admission behavior, or server-side validation/defaulting	make test-integration	Real API-server semantics through EnvTest.
Lifecycle flows, networking, storage, upgrades, backup and restore, or workload startup	make test-e2e or a label-filtered make test-e2e-ci ... run	Real cluster behavior with real images and controller wiring.
Disaster recovery, performance thresholds, or compatibility against an existing platform cluster	Focused manual or scheduled workflow validation	Evidence from the environment that production-like assumptions actually hold.

Fake client boundary

Use the controller-runtime fake client as a fast contract tool, not as a substitute for the API server. If the test depends on validation, defaulting, Generation or ResourceVersion behavior, subresources, watches, cache wiring, or controller-manager setup, move to EnvTest.

Verify

PR-equivalent local gate

bash

make bootstrap
make doctor
make ci-core

This is the default maintainer expectation before you open a PR or ask someone else to chase a failing branch.

Inspect

Focused fuzz and existing-cluster checks

bash

make fuzz
FUZZTIME=30s make fuzz
FUZZ_TARGET_FILTER='FuzzRenderHCL|internal/adapter/auth' make fuzz

export KUBECONFIG=/path/to/your/kubeconfig
export E2E_OPERATOR_IMAGE=quay.io/your-org/openbao-operator:dev
export E2E_API_SERVER_CIDR=0.0.0.0/0
make test-e2e-existing E2E_LABEL_FILTER='openshift'

Use fuzzing when parsers, normalizers, auth helpers, or config rendering changed. Use test-e2e-existing when you need focused OpenShift or non-Kind validation against an existing cluster.

Decision matrix

Special validation lanes

Special validation lanes.

Lane	When to use it	Primary entry point
Fuzzing	Parser, renderer, auth, or normalization changes that benefit from mutated input coverage.	make fuzz locally, make fuzz-long in longer sweeps.
Performance	Controller or lifecycle changes that may affect reconcile cost, startup time, or upgrade behavior.	make verify-perf and the Performance Baseline Capture workflow.
Existing-cluster compatibility	OpenShift or platform-specific validation that a local Kind cluster cannot faithfully represent.	make test-e2e-existing ... with a preconfigured cluster context.

After test selection

Continuous integrationSee how CI maps these layers to workflow gates, routing, and label-driven E2E expansion.Coding standardsGo back to project conventions when the implementation itself still needs cleanup before more test depth helps.Release managementMove into release and publish flow once the branch is stable and ready for maintainer handling.