Helm Chart Unit Testing with helm-unittest
helm-unittest renders your Helm templates with given values and lets you assert the resulting YAML with a simple test DSL. It catches configuration bugs before any cluster is involved — and runs in seconds. Add it to CI and never ship a broken chart again.
Helm is the de facto package manager for Kubernetes. Most teams use it to manage their application deployments, and most teams test their charts by deploying them to a cluster and hoping nothing breaks. That works until it doesn't — until a values override silently produces wrong resource limits, until a conditional block renders the wrong secret, until a required annotation is missing in production but not staging.
Helm chart unit testing with helm-unittest solves this. It renders templates locally, without a cluster, and lets you assert the resulting Kubernetes manifests. The feedback loop is seconds, not minutes. This post walks through everything you need to adopt it.
What helm-unittest Does
helm-unittest is a Helm plugin. You give it test files written in YAML, and it:
- Renders your chart templates using specified values
- Runs assertions against the rendered YAML output
- Reports pass/fail with context on what was expected vs. what was produced
It supports the same templating engine Helm uses internally, so what you test is exactly what Helm would produce. No surprises from rendering differences.
Installation
Install as a Helm plugin:
helm plugin install https://github.com/helm-unittest/helm-unittestVerify:
helm unittest --helpFor CI, use the Docker image instead of installing the plugin:
docker run --rm -v $(pwd):/apps helmunittest/helm-unittest:latest /apps/mychartChart Structure
Assume a chart with this layout:
mychart/
Chart.yaml
values.yaml
templates/
deployment.yaml
service.yaml
ingress.yaml
_helpers.tpl
tests/
deployment_test.yaml
service_test.yaml
ingress_test.yamlBy convention, tests live in a tests/ directory inside the chart. helm-unittest discovers them automatically when you run:
helm unittest mychart/Writing Your First Test Suite
A test suite is a YAML file with one or more test cases. Each test case specifies values to use and a set of assertions.
tests/deployment_test.yaml:
suite: Deployment tests
templates:
- templates/deployment.yaml
tests:
- it: should render with default values
asserts:
- isKind:
of: Deployment
- equal:
path: metadata.name
value: mychart
- equal:
path: spec.replicas
value: 1
- equal:
path: spec.template.spec.containers[0].image
value: nginx:1.25
- it: should use custom replica count
set:
replicaCount: 3
asserts:
- equal:
path: spec.replicas
value: 3
- it: should set resource limits when provided
set:
resources.limits.cpu: "500m"
resources.limits.memory: "256Mi"
asserts:
- equal:
path: spec.template.spec.containers[0].resources.limits.cpu
value: "500m"
- equal:
path: spec.template.spec.containers[0].resources.limits.memory
value: "256Mi"Run it:
helm unittest mychart/Output:
### Chart [ mychart ] mychart/
PASS Deployment tests mychart/tests/deployment_test.yaml
Charts: 1 passed, 1 total
Test Suites: 1 passed, 1 total
Tests: 3 passed, 3 totalAssertion Types
helm-unittest provides a rich assertion vocabulary. Here are the most useful ones:
Equality and matching:
- equal:
path: metadata.labels.app
value: mychart
- matchRegex:
path: spec.template.spec.containers[0].image
pattern: "^nginx:"
- contains:
path: spec.template.spec.containers[0].env
content:
name: MY_ENV_VAR
value: helloExistence checks:
- isNotNull:
path: spec.template.spec.containers[0].resources
- isNull:
path: spec.template.spec.hostNetwork
- isNotEmpty:
path: metadata.annotationsDocument structure:
- isKind:
of: Deployment
- isAPIVersion:
of: apps/v1
- hasDocuments:
count: 1Negation:
- notEqual:
path: spec.template.spec.containers[0].securityContext.runAsRoot
value: trueTesting Values Overrides and Conditionals
The most valuable tests cover conditional blocks — the {{- if .Values.ingress.enabled }} sections that are easy to get wrong.
templates/ingress.yaml:
{{- if .Values.ingress.enabled }}
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: {{ include "mychart.fullname" . }}
{{- if .Values.ingress.annotations }}
annotations:
{{- toYaml .Values.ingress.annotations | nindent 4 }}
{{- end }}
spec:
rules:
{{- range .Values.ingress.hosts }}
- host: {{ .host }}
http:
paths:
{{- range .paths }}
- path: {{ .path }}
pathType: {{ .pathType }}
backend:
service:
name: {{ include "mychart.fullname" $ }}
port:
number: {{ $.Values.service.port }}
{{- end }}
{{- end }}
{{- end }}tests/ingress_test.yaml:
suite: Ingress tests
templates:
- templates/ingress.yaml
tests:
- it: should not render when ingress is disabled
set:
ingress.enabled: false
asserts:
- hasDocuments:
count: 0
- it: should render when ingress is enabled
set:
ingress.enabled: true
ingress.hosts[0].host: myapp.example.com
ingress.hosts[0].paths[0].path: /
ingress.hosts[0].paths[0].pathType: Prefix
asserts:
- hasDocuments:
count: 1
- isKind:
of: Ingress
- equal:
path: spec.rules[0].host
value: myapp.example.com
- it: should include annotations when provided
set:
ingress.enabled: true
ingress.annotations.kubernetes\.io/ingress\.class: nginx
ingress.hosts[0].host: myapp.example.com
ingress.hosts[0].paths[0].path: /
ingress.hosts[0].paths[0].pathType: Prefix
asserts:
- equal:
path: metadata.annotations["kubernetes.io/ingress.class"]
value: nginxTesting with Multiple Value Files
For charts with complex environments (dev, staging, prod), test with actual values files:
suite: Production deployment tests
templates:
- templates/deployment.yaml
tests:
- it: should have correct replica count in production
values:
- values.yaml
- values-production.yaml
asserts:
- equal:
path: spec.replicas
value: 5
- equal:
path: spec.template.spec.containers[0].resources.requests.memory
value: "512Mi"This is more realistic than set: for production validation — it uses the same values files your deployment pipeline uses.
Security and Policy Tests
helm-unittest is excellent for enforcing security policies across all workloads:
suite: Security policy tests
templates:
- templates/deployment.yaml
tests:
- it: should not run as root
asserts:
- equal:
path: spec.template.spec.securityContext.runAsNonRoot
value: true
- it: should drop all capabilities
asserts:
- contains:
path: spec.template.spec.containers[0].securityContext.capabilities.drop
content: ALL
- it: should have read-only root filesystem
asserts:
- equal:
path: spec.template.spec.containers[0].securityContext.readOnlyRootFilesystem
value: true
- it: should not allow privilege escalation
asserts:
- equal:
path: spec.template.spec.containers[0].securityContext.allowPrivilegeEscalation
value: falseThese tests document your security requirements and catch regressions when someone modifies the chart.
CI Integration
GitHub Actions:
name: Helm Chart Tests
on:
push:
paths:
- 'charts/**'
pull_request:
paths:
- 'charts/**'
jobs:
helm-unittest:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install Helm
uses: azure/setup-helm@v3
with:
version: v3.14.0
- name: Install helm-unittest plugin
run: helm plugin install https://github.com/helm-unittest/helm-unittest
- name: Run chart tests
run: |
for chart in charts/*/; do
echo "Testing $chart..."
helm unittest "$chart"
done
- name: Lint charts
run: |
for chart in charts/*/; do
helm lint "$chart"
doneUsing Docker for faster CI (no plugin install):
- name: Run helm-unittest
run: |
docker run --rm \
-v ${{ github.workspace }}:/apps \
helmunittest/helm-unittest:latest \
/apps/charts/mychartThe Docker approach is faster in CI because it skips plugin installation and uses a pinned image version.
Combining with helm lint and helm template
helm-unittest sits in a quality chain alongside other tools:
# 1. Lint: check chart syntax and best practices
helm lint mychart/ -f mychart/values-prod.yaml
# 2. Unit test: assert rendered output
helm unittest mychart/
# 3. Dry-run against a real cluster (catches CRD issues helm-unittest can't)
helm install mychart ./mychart/ --dry-run --generate-name
# 4. Deploy to staging
helm upgrade --install mychart ./mychart/ -n stagingDon't skip steps 1 and 2 just because you have step 3. Dry-run requires cluster access and is slow. helm-unittest catches 80% of issues in milliseconds.
Common Pitfalls
Pitfall 1: Testing the wrong template. The templates: key in your test suite must match the actual file path. A mismatch silently produces zero documents and your hasDocuments: count: 1 test fails with a confusing error.
Pitfall 2: Path syntax for keys with dots. Annotation keys like kubernetes.io/ingress.class must be quoted: metadata.annotations["kubernetes.io/ingress.class"].
Pitfall 3: Not testing the disabled case. Conditional templates need a test for enabled: false that asserts hasDocuments: count: 0. Without it, a broken conditional that always renders is never caught.
Pitfall 4: Ignoring _helpers.tpl coverage. Helper templates affect many resources. Test the outputs that depend on helpers rather than trying to test helpers directly.
What to Test
A minimal but effective test suite for any chart covers:
- Default values produce valid, runnable manifests
- Each optional feature (ingress, HPA, PDB, ServiceAccount) renders correctly when enabled and does not render when disabled
- Values overrides (replica count, image tag, resource limits) are reflected in the output
- Security context settings are enforced
- Labels and annotations are consistently applied
That is typically 15–30 tests per chart, and they run in under two seconds. There is no good reason not to have them.