Using Helm Test Hooks to Validate Charts After Install

Problem: Ensuring a chart works after installation

When you push a new version of a Helm chart, you want confidence that the deployed resources behave as expected before promoting the release to production. Manual checks are tedious and error‑prone, especially in automated pipelines.

Thesis: Helm’s built‑in test hook lets you run validation jobs inside the cluster, giving you automated pass/fail feedback without extra tooling.

How Helm test works

Helm looks for any Kubernetes Job manifest whose file name matches templates/test*.yaml in the chart. When you run helm test <release>, Helm creates those jobs in the same namespace as the release, waits for them to complete, and returns a non‑zero exit code if any job fails.

Key behaviors

• Test pods have access to ConfigMaps, Secrets, Services, and other resources created by the chart, enabling end‑to‑end checks.
• By default Helm deletes the test pods after they finish (--cleanup=true). Use --cleanup=false to keep them for log inspection.
• The command streams logs when you add --logs; otherwise you must inspect pods manually.

Writing a test template

Below is a minimal test that runs a busybox container, prints a success message, and sleeps a few seconds so you can see the pod in Running state.

# templates/test-connection.yaml\napiVersion: batch/v1\nkind: Job\nmetadata:\n  name: {{ include 'chart.fullname' . }}-test-connection\n  labels:\n    {{- include 'chart.labels' . | nindent 4 }}\n  annotations:\n    helm.sh/hook: test\n    helm.sh/hook-delete-policy: hook-succeeded,hook-failed\nspec:\n  template:\n    spec:\n      restartPolicy: Never\n      containers:\n        - name: test\n          image: busybox:1.38\n          command: ['sh', '-c', 'echo ''test passed'' && sleep 5']\n

The helm.sh/hook annotation tells Helm to treat this Job as a test hook. The delete policy ensures the job is cleaned up after it finishes (unless you override with --cleanup=false).

Running and interpreting the test

Assuming you have a chart directory ./mychart and a Kubernetes cluster where you can create jobs:

1. Install the chart: helm install myrelease ./mychart
2. Run the test and view logs: helm test myrelease --logs
3. If the job succeeds, you will see output similar to:

NAME: myrelease\nLAST DEPLOYED: ...\nTEST SUITE:     myrelease-test-connection\nStarted at:     2026-10-12T15:30:00Z\nCompleted at:   2026-10-12T15:30:05Z\nPassed:         1\nFailed:         0\n

The command exits with code 0. To simulate a failure, change the container command to ['sh', '-c', 'exit 1'] and re‑run helm test myrelease --logs. The pod will go into CrashLoopBackOff, the logs will show the exit code, and helm test will return a non‑zero exit code.

Trade‑offs and limitations

• Test jobs run in the release namespace, so they may clash with existing workloads or consume unexpected resources. Consider using a dedicated test namespace or limiting resource requests in the test container.
• If the test image cannot be pulled (e.g., due to registry authentication or network policies), the job fails with ImagePullBackOff, which Helm treats as a test failure. Ensure the image is accessible from the cluster.
• Helm test only validates namespaced objects. Cluster‑scoped resources such as CRDs, namespace‑level RBAC, or PodSecurityPolicies are not exercised; you need additional tooling (e.g., kubectl checks, Conftest, or OPA) for those.
• The test hook does not trigger an automatic rollback of the release. Your CI pipeline must interpret the exit code and decide whether to run helm uninstall or promote the release.

Actionable closing

Add a simple test job to every chart that verifies the most critical behavior—such as a service responding on its port or a ConfigMap containing expected keys. Run helm test as a step in your CI pipeline after helm install or helm upgrade. Keep the test image lightweight, set modest resource requests, and always check the exit code; treat any non‑zero result as a blocker for promotion. This gives you fast, automated feedback without leaving the Helm workflow.