controller-tests

When invoked:

Context

You are writing integration tests for Kubernetes controllers using:

• envtest: Provides a real API server for testing without a full cluster
• Ginkgo v2: BDD testing framework
• Gomega: Assertion library with Eventually/Consistently for async checks

Workflow

1. Analyze the controller: Read the controller file specified in $ARGUMENTS (default: look for *_controller.go files in internal/controller/)

2. Check existing tests: Read the corresponding *_controller_test.go file and suite_test.go to understand:

   • How the test suite is set up (manager, clients, field indexes)
   • Existing test patterns and helpers
   • Build tags used (e.g., //go:build integration)

3. Identify test gaps: Based on the controller's Reconcile logic, identify untested scenarios:

   • Happy path reconciliation
   • Finalizer add/remove
   • Status condition updates
   • Cross-namespace references (ReferenceGrant)
   • Conflict detection
   • Error handling paths

4. Write tests following these patterns:

Timeout Constants

Define timeout constants at the package or file level:

const (
    TestTimeout       = 10 * time.Second
    TestRetryInterval = 100 * time.Millisecond
)

Test Structure

Context("When <scenario>", func() {
    // Constants for this context
    const resourceName = "test-<scenario>-resource"

    // Typed names
    typeNamespacedName := types.NamespacedName{
        Name:      resourceName,
        Namespace: "default",
    }

    // Helper functions
    BeforeEach(func() {
		createTestGateway(ctx, gatewayName, "default")
		createTestMCPGatewayExtension(ctx, resourceName, "default", gatewayName, "default")
	})

	AfterEach(func() {
		deleteTestMCPGatewayExtension(ctx, resourceName, "default")
		deleteTestGateway(ctx, gatewayName, "default")
	})

    It("should <expected behavior>", func() {
        // Test body
    })
})

Cache Synchronization Pattern

When using a manager's cached client, always wait for cache sync before reconciling:

// Wait for cache to see the resource before reconciling
Eventually(func(g Gomega) {
    cached := &v1alpha1.MyResource{}
    g.Expect(testIndexedClient.Get(ctx, namespacedName, cached)).To(Succeed())
}, TestTimeout, TestRetryInterval).Should(Succeed())

_, err := reconciler.Reconcile(ctx, reconcile.Request{
    NamespacedName: namespacedName,
})
Expect(err).NotTo(HaveOccurred())