| name | running-unit-tests |
| description | Use when running, writing, or troubleshooting unit tests for integration-service. Covers make test, envtest setup, suite patterns, mock loader, CRD discovery, coverage, and common test failures. |
Running Unit Tests
Overview
Unit tests use Ginkgo v2 + Gomega with envtest (a local K8s API server). Every package has a *_suite_test.go that bootstraps envtest with CRDs, registers schemes, and starts a controller manager.
When to Use
- Running or debugging unit tests
- Adding tests to a new or existing package
- Troubleshooting envtest or CRD-related test failures
- Understanding the mock loader pattern
Quick Reference
| Command | What it does |
|---|
make test | Full pipeline: manifests, generate, fmt, vet, envtest, download-crds, then go test ./... -coverprofile cover.out |
make download-crds | Downloads CRD YAMLs from dependency modules (vendoring prunes non-Go files) |
make envtest | Downloads setup-envtest tool |
go test ./internal/controller/snapshot/... | Run tests for a single package |
go test ./... -run TestName | Run a specific test by name |
Suite Setup Pattern
Every suite follows this structure (see any *_suite_test.go):
- CRD paths via
CRDDirectoryPaths — local CRDs from config/crd/bases plus dependency CRDs found via toolkit.GetRelativeDependencyPath()
- Scheme registration — add all API types (
applicationapiv1alpha1, tektonv1, releasev1alpha1, v1beta2)
- Manager creation —
ctrl.NewManager() with Metrics.BindAddress: "0" (disables metrics to avoid port conflicts) and LeaderElection: false
- Cache setup — call
cache.Setup*Cache(k8sManager) functions before starting manager
- Start manager in goroutine —
go func() { defer GinkgoRecover(); k8sManager.Start(ctx) }()
- Cleanup —
cancel() context and testEnv.Stop() in AfterSuite
CRD directory paths are relative to the suite file location. Adjust depth (.., ../..) based on package nesting.
Mock Loader Pattern
loader/loader_mock.go intercepts resource loading via context keys:
mockContext := toolkit.GetMockedContext(ctx, []toolkit.MockData{
{ContextKey: loader.SnapshotContextKey, Resource: mySnapshot},
})
result, err := adapter.loader.GetSnapshot(mockContext, client, name, namespace)
Each resource type has a corresponding *ContextKey constant (34 keys available).
Test Conventions
- BDD structure:
Describe > Context("When...") > It("should...")
- Use
Eventually for async assertions, never time.Sleep
- Always
Get() after Create()/Update() to ensure server-side state
- Test idempotency: calling Reconcile twice must produce the same result
ginkgolinter is enabled — follow its conventions
Common Mistakes
| Problem | Fix |
|---|
no matches for kind "X" | Missing CRD in CRDDirectoryPaths — add the dependency path |
| Port conflict on metrics | Ensure Metrics.BindAddress: "0" in manager options |
make test fails on missing CRDs | Run make download-crds — vendoring prunes YAML files |
| Stale generated code | Run make generate manifests before testing |
| Tests pass locally, fail in CI | Check go mod tidy and make fmt — CI fails on uncommitted changes |
Coverage
- Tool: codecov with flag
unit-tests
- Threshold: 3% drop allowed from base commit
- Ignores:
**/zz_generated*, e2e-tests/**, vendor
