test(examples): controller-level component golden tests

Extract Build*Component() methods from the reconcile loops in the
component-prerequisites, extraction-and-guards, and grace-inconsistency
examples so tests can build components through the same assembly path
the controller uses. Add controller_test.go + testdata/ golden snapshots
for each example using golden.AssertComponentYAML.

Update resource tests in all three examples (and custom-resource) to
call the actual factory functions rather than duplicating builder
construction, so the golden files reflect real factory output.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: sourcehawk

examples/component-prerequisites/app/controller.go

@@ -48,40 +48,55 @@ func (r *Controller) Reconcile(ctx context.Context, owner *ExampleApp) (err erro
 	}()
 
 	// --- Infra component: no prerequisites ---
-	cmResource, err := r.NewConfigMapResource(owner)
+	infra, err := r.BuildInfraComponent(owner)
 	if err != nil {
 		return err
 	}
 
-	infra, err := component.NewComponentBuilder().
-		WithName("infra").
-		WithConditionType("InfraReady").
-		WithResource(cmResource).
-		Build()
-	if err != nil {
+	if err := infra.Reconcile(ctx, recCtx); err != nil {
 		return err
 	}
 
-	if err := infra.Reconcile(ctx, recCtx); err != nil {
+	// --- App component: depends on InfraReady ---
+	app, err := r.BuildAppComponent(owner)
+	if err != nil {
 		return err
 	}
 
-	// --- App component: depends on InfraReady ---
+	return app.Reconcile(ctx, recCtx)
+}
+
+// BuildInfraComponent assembles the infra component: a single ConfigMap reporting
+// the InfraReady condition, with no prerequisites. The controller and tests share
+// this so the reconciled component and the golden snapshot stay in lockstep.
+func (r *Controller) BuildInfraComponent(owner *ExampleApp) (*component.Component, error) {
+	cmResource, err := r.NewConfigMapResource(owner)
+	if err != nil {
+		return nil, err
+	}
+
+	return component.NewComponentBuilder().
+		WithName("infra").
+		WithConditionType("InfraReady").
+		WithResource(cmResource).
+		Build()
+}
+
+// BuildAppComponent assembles the app component: a Deployment reporting the
+// AppReady condition, gated behind the InfraReady prerequisite. The DependsOn
+// prerequisite is the point of this example, so the controller and tests build
+// the component the same way.
+func (r *Controller) BuildAppComponent(owner *ExampleApp) (*component.Component, error) {
 	deployResource, err := r.NewDeploymentResource(owner)
 	if err != nil {
-		return err
+		return nil, err
 	}
 
-	app, err := component.NewComponentBuilder().
+	return component.NewComponentBuilder().
 		WithName("app").
 		WithConditionType("AppReady").
 		WithResource(deployResource).
 		WithPrerequisite(component.DependsOn("InfraReady")).
 		Suspend(owner.Spec.Suspended).
 		Build()
-	if err != nil {
-		return err
-	}
-
-	return app.Reconcile(ctx, recCtx)
 }

examples/component-prerequisites/app/controller_test.go

@@ -0,0 +1,63 @@
+package app_test
+
+import (
+	"flag"
+	"testing"
+
+	"github.com/sourcehawk/operator-component-framework/examples/component-prerequisites/app"
+	"github.com/sourcehawk/operator-component-framework/examples/component-prerequisites/resources"
+	"github.com/sourcehawk/operator-component-framework/pkg/testing/golden"
+	"github.com/stretchr/testify/require"
+	appsv1 "k8s.io/api/apps/v1"
+	corev1 "k8s.io/api/core/v1"
+	"k8s.io/apimachinery/pkg/runtime"
+)
+
+var update = flag.Bool("update", false, "update golden files")
+
+func testOwner() *app.ExampleApp {
+	owner := &app.ExampleApp{
+		Spec: app.ExampleAppSpec{Version: "1.0.0"},
+	}
+	owner.Name = "my-app"
+	owner.Namespace = "default"
+	return owner
+}
+
+func testController() *app.Controller {
+	return &app.Controller{
+		NewConfigMapResource:  resources.NewConfigMapResource,
+		NewDeploymentResource: resources.NewDeploymentResource,
+	}
+}
+
+func testScheme(t *testing.T) *runtime.Scheme {
+	t.Helper()
+	scheme := runtime.NewScheme()
+	require.NoError(t, appsv1.AddToScheme(scheme))
+	require.NoError(t, corev1.AddToScheme(scheme))
+	return scheme
+}
+
+// TestInfraComponentShape goldens the infra component the controller reconciles.
+// It builds through BuildInfraComponent, the same assembly the controller uses,
+// so the snapshot reflects the real desired state.
+func TestInfraComponentShape(t *testing.T) {
+	comp, err := testController().BuildInfraComponent(testOwner())
+	require.NoError(t, err)
+
+	golden.AssertComponentYAML(t, "testdata/infra-component.yaml", comp,
+		golden.WithScheme(testScheme(t)), golden.Update(*update))
+}
+
+// TestAppComponentShape goldens the app component the controller reconciles.
+// The DependsOn("InfraReady") prerequisite is the point of this example; the
+// component is built through BuildAppComponent so the controller and the
+// snapshot stay in lockstep.
+func TestAppComponentShape(t *testing.T) {
+	comp, err := testController().BuildAppComponent(testOwner())
+	require.NoError(t, err)
+
+	golden.AssertComponentYAML(t, "testdata/app-component.yaml", comp,
+		golden.WithScheme(testScheme(t)), golden.Update(*update))
+}

examples/component-prerequisites/app/testdata/app-component.yaml

@@ -0,0 +1,21 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  labels:
+    app: my-app
+  name: my-app-app
+  namespace: default
+spec:
+  selector:
+    matchLabels:
+      app: my-app
+  strategy: {}
+  template:
+    metadata:
+      labels:
+        app: my-app
+    spec:
+      containers:
+      - image: my-app:1.0.0
+        name: app
+        resources: {}

examples/component-prerequisites/app/testdata/infra-component.yaml

@@ -0,0 +1,9 @@
+apiVersion: v1
+data:
+  cluster-dns: 10.96.0.10
+kind: ConfigMap
+metadata:
+  labels:
+    app: my-app
+  name: my-app-infra-config
+  namespace: default

examples/component-prerequisites/resources/configmap_test.go

@@ -6,7 +6,6 @@ import (
 
 	"github.com/sourcehawk/operator-component-framework/examples/component-prerequisites/resources"
 	sharedapp "github.com/sourcehawk/operator-component-framework/examples/shared/app"
-	"github.com/sourcehawk/operator-component-framework/pkg/primitives/configmap"
 	"github.com/sourcehawk/operator-component-framework/pkg/testing/golden"
 	"github.com/stretchr/testify/require"
 	corev1 "k8s.io/api/core/v1"
@@ -24,16 +23,17 @@ func testOwner(version string) *sharedapp.ExampleApp {
 	return owner
 }
 
-// TestConfigMapShape pins the infra component's ConfigMap baseline. Changes
-// to the base object surface as a diff against the golden file.
+// TestConfigMapShape pins the infra component's ConfigMap as built by its
+// factory. The factory registers no mutations, so the golden file captures the
+// full desired state. Changes to the base object surface as a diff.
 func TestConfigMapShape(t *testing.T) {
 	scheme := runtime.NewScheme()
 	require.NoError(t, corev1.AddToScheme(scheme))
 
 	owner := testOwner("1.0.0")
-	res, err := configmap.NewBuilder(resources.BaseConfigMap(owner)).Build()
+	res, err := resources.NewConfigMapResource(owner)
 	require.NoError(t, err)
 
-	golden.AssertYAML(t, "testdata/configmap.yaml", res,
+	golden.AssertYAML(t, "testdata/configmap.yaml", res.(golden.Previewer),
 		golden.WithScheme(scheme), golden.Update(*update))
 }

examples/component-prerequisites/resources/deployment_test.go

@@ -1,24 +1,39 @@
 package resources_test
 
 import (
-	"fmt"
 	"testing"
 
 	"github.com/sourcehawk/operator-component-framework/examples/component-prerequisites/resources"
-	"github.com/sourcehawk/operator-component-framework/pkg/feature"
-	"github.com/sourcehawk/operator-component-framework/pkg/mutation/editors"
-	"github.com/sourcehawk/operator-component-framework/pkg/mutation/selectors"
-	"github.com/sourcehawk/operator-component-framework/pkg/primitives/deployment"
+	"github.com/sourcehawk/operator-component-framework/pkg/component/concepts"
 	"github.com/sourcehawk/operator-component-framework/pkg/testing/golden"
+	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 	appsv1 "k8s.io/api/apps/v1"
 	"k8s.io/apimachinery/pkg/runtime"
 )
 
-// TestDeploymentShape verifies the app component's Deployment for each version.
-// The baseline carries the latest container layout; the version mutation sets
-// the image tag. Golden files for each version catch regressions when the
-// baseline or mutation logic changes.
+// TestDeploymentMutations verifies the factory registers the Version mutation
+// and that it fires at every version. The version gate has no constraint, so
+// the mutation always applies and rewrites the image tag.
+func TestDeploymentMutations(t *testing.T) {
+	owner := testOwner("1.0.0")
+	res, err := resources.NewDeploymentResource(owner)
+	require.NoError(t, err)
+
+	inspector, ok := res.(concepts.MutationInspector)
+	require.True(t, ok)
+
+	assert.ElementsMatch(t, []string{"Version"}, inspector.RegisteredMutations())
+
+	firing, err := inspector.FiringSet()
+	require.NoError(t, err)
+	assert.ElementsMatch(t, []string{"Version"}, firing)
+}
+
+// TestDeploymentShape verifies the app component's Deployment as built by its
+// factory for each version. The baseline carries the latest container layout;
+// the Version mutation sets the image tag. Golden files for each version catch
+// regressions when the baseline or mutation logic changes.
 func TestDeploymentShape(t *testing.T) {
 	scheme := runtime.NewScheme()
 	require.NoError(t, appsv1.AddToScheme(scheme))
@@ -44,22 +59,11 @@ func TestDeploymentShape(t *testing.T) {
 		t.Run(tt.name, func(t *testing.T) {
 			owner := testOwner(tt.version)
 
-			res, err := deployment.NewBuilder(resources.BaseDeployment(owner)).
-				WithMutation(deployment.Mutation{
-					Name:    "Version",
-					Feature: feature.NewVersionGate(tt.version, nil),
-					Mutate: func(m *deployment.Mutator) error {
-						m.EditContainers(selectors.ContainerNamed("app"), func(ce *editors.ContainerEditor) error {
-							ce.Raw().Image = fmt.Sprintf("my-app:%s", tt.version)
-							return nil
-						})
-						return nil
-					},
-				}).
-				Build()
+			res, err := resources.NewDeploymentResource(owner)
 			require.NoError(t, err)
 
-			golden.AssertYAML(t, tt.golden, res, golden.WithScheme(scheme), golden.Update(*update))
+			golden.AssertYAML(t, tt.golden, res.(golden.Previewer),
+				golden.WithScheme(scheme), golden.Update(*update))
 		})
 	}
 }

examples/custom-resource/resources/certificate_test.go

@@ -6,10 +6,10 @@ import (
 
 	"github.com/sourcehawk/operator-component-framework/examples/custom-resource/resources"
 	sharedapp "github.com/sourcehawk/operator-component-framework/examples/shared/app"
-	"github.com/sourcehawk/operator-component-framework/pkg/mutation/editors"
-	unstruct "github.com/sourcehawk/operator-component-framework/pkg/primitives/unstructured"
+	"github.com/sourcehawk/operator-component-framework/pkg/component/concepts"
 	"github.com/sourcehawk/operator-component-framework/pkg/primitives/unstructured/static"
 	"github.com/sourcehawk/operator-component-framework/pkg/testing/golden"
+	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 	uns "k8s.io/apimachinery/pkg/apis/meta/v1/unstructured"
 )
@@ -25,41 +25,31 @@ func testOwner() *sharedapp.ExampleApp {
 	return owner
 }
 
-// TestCertificateShape verifies the CertificateRequest's shape after mutations
-// set spec fields (issuerRef, dnsNames) and metadata labels. The golden file
-// catches regressions when the mutation logic or base object changes.
-func TestCertificateShape(t *testing.T) {
-	owner := testOwner()
+// TestCertificateMutations verifies the factory registers the certificate-spec
+// mutation and that it fires. The mutation has no gate, so it always applies.
+func TestCertificateMutations(t *testing.T) {
+	res, err := resources.NewCertificateResource(testOwner())
+	require.NoError(t, err)
+
+	inspector, ok := res.(concepts.MutationInspector)
+	require.True(t, ok)
+
+	assert.ElementsMatch(t, []string{"certificate-spec"}, inspector.RegisteredMutations())
 
-	res, err := static.NewBuilder(resources.BaseCertificateRequest(owner)).
-		WithMutation(unstruct.Mutation{
-			Name: "certificate-spec",
-			Mutate: func(m *unstruct.Mutator) error {
-				m.EditContent(func(e *editors.UnstructuredContentEditor) error {
-					if err := e.SetNestedString("letsencrypt-prod", "spec", "issuerRef", "name"); err != nil {
-						return err
-					}
-					if err := e.SetNestedString("ClusterIssuer", "spec", "issuerRef", "kind"); err != nil {
-						return err
-					}
-					return e.SetNestedSlice(
-						[]interface{}{owner.Name + ".example.com"},
-						"spec", "dnsNames",
-					)
-				})
-
-				m.EditObjectMetadata(func(meta *editors.ObjectMetaEditor) error {
-					meta.EnsureLabel("app", owner.Name)
-					return nil
-				})
-
-				return nil
-			},
-		}).
-		Build()
+	firing, err := inspector.FiringSet()
+	require.NoError(t, err)
+	assert.ElementsMatch(t, []string{"certificate-spec"}, firing)
+}
+
+// TestCertificateShape verifies the CertificateRequest as built by its factory,
+// after the certificate-spec mutation sets spec fields (issuerRef, dnsNames)
+// and metadata labels. The golden file catches regressions when the mutation
+// logic or base object changes.
+func TestCertificateShape(t *testing.T) {
+	res, err := resources.NewCertificateResource(testOwner())
 	require.NoError(t, err)
 
-	golden.AssertYAML(t, "testdata/certificate.yaml", res, golden.Update(*update))
+	golden.AssertYAML(t, "testdata/certificate.yaml", res.(golden.Previewer), golden.Update(*update))
 }
 
 // TestCertificateBaseShape pins the bare base object before any mutations.

examples/extraction-and-guards/app/controller.go

@@ -44,28 +44,37 @@ func (r *Controller) Reconcile(ctx context.Context, owner *ExampleApp) (err erro
 		}
 	}()
 
+	comp, err := r.BuildComponent(owner)
+	if err != nil {
+		return err
+	}
+
+	return comp.Reconcile(ctx, recCtx)
+}
+
+// BuildComponent assembles the database component: a ConfigMap registered before
+// a Secret, both wired to a shared dbHost pointer. The ConfigMap extractor writes
+// the pointer and the Secret guard reads it, so registration order matters. The
+// controller and tests share this assembly so the reconciled component and the
+// golden snapshot stay in lockstep.
+func (r *Controller) BuildComponent(owner *ExampleApp) (*component.Component, error) {
 	// Shared state: the ConfigMap extractor writes here, the Secret guard reads it.
 	var dbHost string
 
 	cmResource, err := r.NewConfigMapResource(owner, &dbHost)
 	if err != nil {
-		return err
+		return nil, err
 	}
 
 	secretResource, err := r.NewSecretResource(owner, &dbHost)
 	if err != nil {
-		return err
+		return nil, err
 	}
 
-	comp, err := component.NewComponentBuilder().
+	return component.NewComponentBuilder().
 		WithName("database").
 		WithConditionType("DatabaseReady").
 		WithResource(cmResource).
 		WithResource(secretResource).
 		Build()
-	if err != nil {
-		return err
-	}
-
-	return comp.Reconcile(ctx, recCtx)
 }