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 --logs

Common 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.

Related guides