Helm Chart Testing: helm unittest, chart-testing, and Local Kubernetes Validation
Helm charts generate Kubernetes manifests from templates and values. The same testing problem applies here as with CloudFormation: templates can render syntactically valid YAML that deploys incorrectly, and by the time you discover the problem, you've disrupted a running cluster.
The Helm testing ecosystem provides tools for different testing depths: helm-unittest for template unit tests, helm lint and helm template for basic validation, chart-testing (ct) for CI integration, and kind/minikube for actual Kubernetes deployment testing.
The Helm Testing Toolkit
| Tool | What it validates | Speed |
|---|---|---|
helm lint |
Basic chart structure, YAML syntax | Seconds |
helm template |
Template rendering, values substitution | Seconds |
helm-unittest |
Template output assertions | Seconds |
chart-testing (ct) |
Chart installation in real cluster | Minutes |
| kind/minikube | Full cluster integration | Minutes |
Use all of them at appropriate stages of your CI pipeline.
Basic Validation with helm lint and helm template
Before any other testing, run basic validation:
# Lint the chart (validates structure and syntax)
helm lint ./my-chart
# Render templates without deploying (validate Kubernetes resource structure)
helm template my-release ./my-chart --values values-staging.yaml | kubectl apply --dry-run=client -f -
# Validate with specific values sets
helm template my-release ./my-chart \
--values values-production.yaml \
--set image.tag=latest \
| kubectl apply --dry-run=client -f -kubectl apply --dry-run=client validates the rendered manifests against the Kubernetes API schema without sending them to a cluster — all locally.
Unit Testing with helm-unittest
helm-unittest is a Helm plugin that lets you write assertion-based unit tests for your chart templates.
Installation:
helm plugin install https://github.com/helm-unittest/helm-unittestTest structure:
my-chart/
├── Chart.yaml
├── values.yaml
├── templates/
│ ├── deployment.yaml
│ ├── service.yaml
│ └── ingress.yaml
└── tests/
├── deployment_test.yaml
├── service_test.yaml
└── ingress_test.yamlDeployment test example:
# tests/deployment_test.yaml
suite: Deployment tests
templates:
- deployment.yaml
tests:
- it: should create a deployment
asserts:
- isKind:
of: Deployment
- isAPIVersion:
of: apps/v1
- it: should have correct replica count from values
set:
replicaCount: 3
asserts:
- equal:
path: spec.replicas
value: 3
- it: should use image from values
set:
image.repository: nginx
image.tag: "1.24"
asserts:
- equal:
path: spec.template.spec.containers[0].image
value: "nginx:1.24"
- it: should not include resource limits when not set
set:
resources: {}
asserts:
- notExists:
path: spec.template.spec.containers[0].resources.limits
- it: should set resource limits when provided
set:
resources:
limits:
cpu: "500m"
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"
- it: should set correct environment variables
set:
env:
- name: DATABASE_URL
value: postgresql://db:5432/app
asserts:
- contains:
path: spec.template.spec.containers[0].env
content:
name: DATABASE_URL
value: postgresql://db:5432/app
- it: should not mount volumes by default
asserts:
- notExists:
path: spec.template.spec.volumes
- it: should have readiness probe configured
asserts:
- exists:
path: spec.template.spec.containers[0].readinessProbe
- equal:
path: spec.template.spec.containers[0].readinessProbe.httpGet.path
value: /healthzService test example:
# tests/service_test.yaml
suite: Service tests
templates:
- service.yaml
tests:
- it: should create ClusterIP service by default
asserts:
- isKind:
of: Service
- equal:
path: spec.type
value: ClusterIP
- it: should create LoadBalancer service when type is set
set:
service.type: LoadBalancer
asserts:
- equal:
path: spec.type
value: LoadBalancer
- it: should expose correct port
set:
service.port: 8080
asserts:
- equal:
path: spec.ports[0].port
value: 8080Ingress test example:
# tests/ingress_test.yaml
suite: Ingress tests
templates:
- ingress.yaml
tests:
- it: should not create ingress when disabled
set:
ingress.enabled: false
asserts:
- hasDocuments:
count: 0
- it: should create ingress with correct host when enabled
set:
ingress.enabled: true
ingress.hosts:
- host: app.example.com
paths:
- path: /
pathType: Prefix
asserts:
- isKind:
of: Ingress
- equal:
path: spec.rules[0].host
value: app.example.com
- it: should set TLS configuration when provided
set:
ingress.enabled: true
ingress.tls:
- secretName: app-tls
hosts:
- app.example.com
asserts:
- exists:
path: spec.tls
- equal:
path: spec.tls[0].secretName
value: app-tlsRunning tests:
# Run all tests
helm unittest ./my-chart
# Run with verbose output
helm unittest -v ./my-chart
# Run specific test file
helm unittest -f 'tests/deployment_test.yaml' ./my-chart
# Output in JUnit format for CI
helm unittest ./my-chart -o xml -t test-results.xmlchart-testing (ct)
chart-testing is a tool from the Helm project for CI testing of Helm charts. It automates:
- Detecting which charts changed (to avoid testing unmodified charts)
- Linting changed charts
- Installing changed charts into a real Kubernetes cluster
- Running Helm test hooks
- Upgrading charts from previous versions
Installation:
brew install chart-testing # macOS
# Or using Docker
docker run --rm -it quay.io/helmpack/chart-testing:latestConfiguration (ct.yaml):
# ct.yaml
remote: origin
target-branch: main
chart-dirs:
- charts
helm-extra-args: --timeout 600s
validate-maintainers: false
lint-conf: .yamllint.yamlUsage:
# Lint changed charts
ct lint --config ct.yaml
# Install changed charts (requires cluster access)
ct install --config ct.yaml
# Lint and install (full test)
ct lint-and-install --config ct.yamlGitHub Actions workflow:
lint-and-test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0 # Required for detecting changes
- name: Set up Helm
uses: azure/setup-helm@v3
- name: Set up chart-testing
uses: helm/chart-testing-action@v2.6.1
- name: Run chart-testing lint
run: ct lint --config ct.yaml
- name: Create kind cluster
uses: helm/kind-action@v1.9.0
if: steps.list-changed.outputs.changed == 'true'
- name: Run chart-testing install
run: ct install --config ct.yaml
if: steps.list-changed.outputs.changed == 'true'Helm Test Hooks
Helm supports test hooks — Kubernetes Jobs that run after helm install to verify the deployment. These run when you execute helm test <release>:
# templates/tests/test-connection.yaml
apiVersion: v1
kind: Pod
metadata:
name: "{{ include "my-chart.fullname" . }}-test-connection"
labels:
{{- include "my-chart.labels" . | nindent 4 }}
annotations:
"helm.sh/hook": test
"helm.sh/hook-delete-policy": hook-succeeded
spec:
restartPolicy: Never
containers:
- name: wget
image: busybox:1.36
command:
- wget
- "--spider"
- "http://{{ include "my-chart.fullname" . }}:{{ .Values.service.port }}"# templates/tests/test-database-connection.yaml
apiVersion: v1
kind: Pod
metadata:
name: "{{ include "my-chart.fullname" . }}-test-db"
annotations:
"helm.sh/hook": test
"helm.sh/hook-delete-policy": hook-succeeded
spec:
restartPolicy: Never
containers:
- name: postgres-test
image: postgres:14
env:
- name: DATABASE_URL
valueFrom:
secretKeyRef:
name: "{{ include "my-chart.fullname" . }}-secret"
key: database-url
command:
- sh
- -c
- |
psql $DATABASE_URL -c "SELECT 1" && echo "Database connection: OK"Run tests after deployment:
helm install my-release ./my-chart
helm test my-releaseIf any test pod exits with a non-zero code, helm test fails.
Integration Testing with kind
kind (Kubernetes in Docker) runs a real Kubernetes cluster in Docker containers, suitable for local development and CI:
# Install kind
go install sigs.k8s.io/kind@latest
# or: brew install kind
# Create a cluster
kind create cluster --name test-cluster --config kind-config.yaml# kind-config.yaml
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
- role: control-plane
- role: worker
- role: workerTesting a chart against a kind cluster:
#!/bin/bash
# scripts/test-chart.sh
# Create cluster
kind create cluster --name test-chart
# Load local images into kind (avoids DockerHub rate limits)
kind load docker-image myapp:latest --name test-chart
# Install the chart
helm install my-release ./my-chart \
--set image.tag=latest \
--wait \
--timeout 5m
# Run Helm tests
helm test my-release
# Additional smoke tests
kubectl get pods -l app.kubernetes.io/name=my-chart
kubectl wait --for=condition=ready pod -l app.kubernetes.io/name=my-chart --timeout=120s
# Clean up
kind delete cluster --name test-chartGitLab CI with kind:
helm-integration-test:
stage: test
image: docker:24
services:
- docker:24-dind
variables:
DOCKER_HOST: tcp://docker:2376
DOCKER_TLS_CERTDIR: "/certs"
script:
- apk add --no-cache curl bash
- curl -Lo /usr/local/bin/kind "https://kind.sigs.k8s.io/dl/v0.22.0/kind-linux-amd64"
- chmod +x /usr/local/bin/kind
- curl -LO "https://dl.k8s.io/release/$(curl -sL https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
- chmod +x kubectl && mv kubectl /usr/local/bin/
- kind create cluster
- helm install test-release ./my-chart --wait --timeout 5m
- helm test test-release
- kind delete clusterValidating values.yaml Schema
Add a JSON schema (values.schema.json) to your chart for validation:
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"replicaCount": {
"type": "integer",
"minimum": 1,
"description": "Number of replicas"
},
"image": {
"type": "object",
"required": ["repository", "tag"],
"properties": {
"repository": { "type": "string" },
"tag": { "type": "string" },
"pullPolicy": {
"type": "string",
"enum": ["Always", "IfNotPresent", "Never"]
}
}
},
"resources": {
"type": "object",
"properties": {
"limits": {
"type": "object",
"properties": {
"cpu": { "type": "string" },
"memory": { "type": "string" }
}
}
}
}
},
"required": ["replicaCount", "image"]
}Helm validates values against this schema during helm install, helm upgrade, and helm template. Invalid values fail immediately with a clear error message.
Testing Multiple Values Combinations
For charts with complex configuration options, testing multiple values combinations catches edge cases:
# tests/comprehensive_test.yaml
suite: Comprehensive values tests
templates:
- deployment.yaml
- service.yaml
tests:
- it: default values should produce valid resources
# No set directives - uses values.yaml defaults
asserts:
- isKind:
of: Deployment
- isNotEmpty:
path: spec.template.spec.containers
- it: production values override
values:
- ../values-production.yaml
asserts:
- equal:
path: spec.replicas
value: 3
- it: minimal configuration
set:
replicaCount: 1
image.repository: nginx
image.tag: "1.24"
ingress.enabled: false
resources: {}
asserts:
- isKind:
of: DeploymentThe combination of helm-unittest for template assertions, chart-testing for CI integration, and kind for actual deployment testing gives you confidence in your Helm charts before they reach production clusters.