framework

testing/framework — deckhouse-style hook test harness

Functional, end-to-end testing for module hooks without a real Kubernetes cluster, addon-operator, or shell-operator.

The framework spins up a fake dynamic Kubernetes client, generates snapshots from your hook's KubernetesConfig bindings, runs the handler with a real *pkg.HookInput, and replays every recorded patch operation against the fake cluster — so you can assert on cluster state directly.

It mirrors the flow of deckhouse/testing/hooks, but has no dependency on addon-operator or shell-operator.

When to use it

Use the framework for functional tests of a hook:

• the hook reads multiple kinds of resources via KubernetesConfig bindings;
• the hook produces a sequence of Create / Delete / Patch operations and you want to assert on the resulting cluster state;
• the hook uses input.DC.GetK8sClient() to interact with the API server directly;
• you want a single test to walk through several state transitions (KubeStateSet → RunHook → assert → KubeStateSet → RunHook → assert).

For small unit tests where you only care about a single path, prefer testing/helpers.

Quick start

package myhook_test

import (
    "context"
    "testing"

    "github.com/stretchr/testify/require"

    "github.com/deckhouse/module-sdk/pkg"
    "github.com/deckhouse/module-sdk/testing/framework"
)

func TestMyHook(t *testing.T) {
    cfg := &pkg.HookConfig{
        Kubernetes: []pkg.KubernetesConfig{{
            Name:       "nodes",
            APIVersion: "v1",
            Kind:       "Node",
            JqFilter:   `{name: .metadata.name}`,
        }},
    }

    handler := func(_ context.Context, in *pkg.HookInput) error {
        in.Values.Set("count", len(in.Snapshots.Get("nodes")))
        return nil
    }

    f := framework.HookExecutionConfigInit(t, cfg, handler, `{}`, `{}`)

    f.KubeStateSet(`
---
apiVersion: v1
kind: Node
metadata:
  name: kube-worker-1
---
apiVersion: v1
kind: Node
metadata:
  name: kube-worker-2
`)

    f.RunHook()

    require.NoError(t, f.HookError())
    require.Equal(t, int64(2), f.ValuesGet("count").Int())
}

API reference

Construction

t is a testing.TB, so *testing.T, sub-tests, and GinkgoT() all work.

Cluster state

Custom resources

f := framework.NewHookExecutionConfig(t, cfg, handler,
    framework.WithSchemeBuilder(myapis.SchemeBuilder), // for typed CRDs
    framework.WithCRD("acme.io", "v1", "Widget", true), // for ad-hoc CRs
)

// or, after construction:
f.RegisterCRD("acme.io", "v1", "Widget", true)

WithSchemeBuilder is preferred when the CRD has Go types you can import; WithCRD / RegisterCRD is used to teach the GVR resolver about a kind that lives only in YAML.

OpenAPI defaults

In production, addon-operator applies defaults from the module's OpenAPI schemas (openapi/values.yaml and openapi/config-values.yaml) before invoking a hook. The framework can do the same so tests don't drift from real-world behaviour:

f := framework.NewHookExecutionConfig(t, cfg, handler,
    framework.WithOpenAPIDir("../openapi"),
    framework.WithInitialValues(`{"https": {"mode": "CertManager"}}`),
)

Behaviour:

• WithOpenAPIDir(dir) looks for <dir>/values.yaml and <dir>/config-values.yaml. Whichever ones are present are loaded.
• For each schema, the framework extracts every default: declared in it and uses the result as a baseline values document.
• Anything passed via WithInitialValues / WithInitialConfigValues is then deep-merged on top — your test's values always override schema defaults.
• The x-extend extension is honoured. If values.yaml declares x-extend.schema: config-values.yaml, the values store inherits all defaults from config-values.yaml plus its own.

For more granular control use WithValuesSchema(path) / WithConfigValuesSchema(path) instead — they fail the test if the file is missing.

The lower-level helpers LoadOpenAPISchema, SchemaDefaults, and MergeValues are also exported, which is handy when you want to assemble a full values document outside NewHookExecutionConfig:

schema, err := framework.LoadOpenAPISchema("../openapi/values.yaml")
require.NoError(t, err)
defaults := framework.SchemaDefaults(schema)
merged := framework.MergeValues(defaults, map[string]any{
    "replicas": 5,
})

Values

Running and inspecting

How it works

RunHook runs the same five-step pipeline every time:

1. Generate snapshots. For each KubernetesConfig binding, the framework lists matching resources from the fake cluster (honouring NameSelector, NamespaceSelector, LabelSelector, FieldSelector), then runs JqFilter on each match.
2. Build a real HookInput. Values and config values are wrapped in pkg/patchable-values.PatchableValues, the patch collector is a recordingPatchCollector, and the metrics collector is a real internal/metric.Collector.
3. Invoke the handler. Errors are captured in HookError().
4. Apply values patches. The framework merges the patches the hook produced via input.Values.Set/Remove back into its values store (and same for config values).
5. Replay cluster patches. Each recorded Create / Delete / MergePatch / JSONPatch / JQFilter is applied to the fake dynamic client, so KubernetesResource(...) returns the post-hook state.

If the handler returned an error, step 5 is skipped — error-path tests can still assert on values patches and the recorded operations the hook intended to issue.

Pitfalls and tips

• The fake client uses meta.UnsafeGuessKindToResource for GVR mapping. Standard Kubernetes kinds (Pod, Node, StatefulSet, …) work out of the box; custom kinds need WithCRD or WithSchemeBuilder.
• KubeStateSet rebuilds the fake client; if you keep references to objects fetched before, refresh them with KubernetesResource.
• The DependencyContainer's HTTP and registry clients return errors by default. If your hook calls input.DC.GetHTTPClient() you must override them via f.DependencyContainer().SetHTTPClient(...) before RunHook.
• LoggerOutput() captures everything the hook logs, including the framework's own diagnostic messages — use strings.Contains rather than line-by-line equality.

Real-world examples in this repo

• testing/framework/example_test.go — verbose, deliberately documentation-style end-to-end test.
• common-hooks/storage-class-change/hook_framework_test.go — selectors, config-values overrides, BeforeHookCheck gating.
• examples/example-module/hooks/subfolder/snapshot_framework_test.go — snapshot binding driven by cluster YAML.
• examples/example-module/hooks/subfolder/patch_framework_test.go — replay of Create+Delete+Patch operations.
• examples/single-file-example/hooks/main_framework_test.go — labels and namespace scoping.
• examples/dependency-example-module/hooks/subfolder/http_client_framework_test.go — overriding the HTTP client on the framework's DependencyContainer.