helm test: Usage, Options & Common CI Errors
Run a chart's built-in tests against the live release.
helm test executes the test hooks defined in a chart against a deployed release - typically a pod that probes the service and exits 0 on success. It is the post-deploy smoke check in a Helm-based CI pipeline.
What it does
helm test NAME runs the pods annotated helm.sh/hook: test in the release. Each test pod runs to completion; a non-zero exit fails the test. --logs streams the test pods' output (essential for seeing why a test failed in CI); --timeout bounds the run. Tests live in the chart under templates/tests/.
Common usage
helm test web -n prod
helm test web --logs # show test pod output
helm test web --timeout 5m
helm upgrade --install web ./charts/web --wait && helm test web --logsCommon errors in CI
"Error: ... pod web-test-connection failed" means a test pod exited non-zero. Pass --logs to see its output and diagnose (often the service is not actually reachable yet, so gate test behind --wait on the upgrade). A chart with no test hooks gives "no tests found", which a script may misread as success. Assert the chart actually defines tests if you rely on them. Test pods are not auto-deleted by default and can collide on re-run ("already exists"); add the helm.sh/hook-delete-policy annotation (e.g. before-hook-creation) in the chart so re-runs are clean.
Using this in CI
A runner has no kubeconfig, no cached context, and no interactive auth. Every kubectl invocation in CI needs the context supplied explicitly, and most confusing CI failures here are the command running against the wrong cluster or no cluster at all.
# never rely on the ambient context on a runner
kubectl --context "$KUBE_CONTEXT" -n "$NAMESPACE" get pods
# confirm what you are actually connected to before mutating anything
kubectl config current-context
kubectl cluster-info
# fail fast instead of hanging on an unreachable API server
kubectl --request-timeout=30s get nodes