Helm Chart Testing Strategies: Unit Tests, Integration Tests, and CI Validation
Helm charts package Kubernetes applications into reusable, configurable units. They also concentrate complexity: a chart with 20 configurable values can produce hundreds of different Kubernetes manifests depending on those values. Testing every significant combination is the only way to ship a chart confidently.
This guide covers the full Helm chart testing stack: template unit tests, values schema validation, lint checks, and integration testing in a real cluster.
The Four Layers of Helm Chart Testing
Layer 1 — Schema validation: Verify that values conform to the expected types and constraints.
Layer 2 — Template unit tests: Verify that the rendered templates match expectations for given values.
Layer 3 — Lint and policy checks: Verify that rendered manifests follow Kubernetes best practices.
Layer 4 — Integration tests: Deploy the chart into a real cluster and verify it works.
Each layer catches different issues. Skip any one of them and you'll find its problems in production.
Layer 1: Values Schema Validation
Add a values.schema.json to your chart to enforce types and required fields:
// charts/myapp/values.schema.json
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"required": ["image", "replicaCount"],
"properties": {
"replicaCount": {
"type": "integer",
"minimum": 1,
"maximum": 20
},
"image": {
"type": "object",
"required": ["repository", "tag"],
"properties": {
"repository": { "type": "string", "minLength": 1 },
"tag": { "type": "string", "minLength": 1 },
"pullPolicy": {
"type": "string",
"enum": ["Always", "IfNotPresent", "Never"]
}
}
},
"resources": {
"type": "object",
"properties": {
"limits": {
"type": "object",
"properties": {
"cpu": { "type": "string" },
"memory": { "type": "string" }
}
}
}
},
"ingress": {
"type": "object",
"properties": {
"enabled": { "type": "boolean" },
"host": {
"type": "string",
"format": "hostname"
}
}
}
}
}Test schema validation:
# Valid values — should succeed
helm install test-release ./charts/myapp \
--set image.repository=myapp \
--set image.tag=latest \
--dry-run
# Invalid values — should fail with schema error
helm install test-release ./charts/myapp \
--set replicaCount=0 \ # Below minimum
--dry-runLayer 2: Template Unit Tests With helm-unittest
helm-unittest tests rendered chart templates without deploying to a cluster:
# Install the plugin
helm plugin install https://github.com/helm-unittest/helm-unittest
# Run tests
helm unittest charts/myappWrite test files in charts/myapp/tests/:
# charts/myapp/tests/deployment_test.yaml
suite: deployment tests
tests:
- it: should render deployment with correct replicas
set:
replicaCount: 3
image.repository: myapp
image.tag: "1.0.0"
asserts:
- isKind:
of: Deployment
- equal:
path: spec.replicas
value: 3
- it: should use correct image
set:
image.repository: registry.example.com/myapp
image.tag: "2.0.0"
image.pullPolicy: Always
asserts:
- equal:
path: spec.template.spec.containers[0].image
value: "registry.example.com/myapp:2.0.0"
- equal:
path: spec.template.spec.containers[0].imagePullPolicy
value: Always
- it: should set resource limits when provided
set:
resources.limits.cpu: "500m"
resources.limits.memory: "128Mi"
asserts:
- equal:
path: spec.template.spec.containers[0].resources.limits.cpu
value: "500m"
- equal:
path: spec.template.spec.containers[0].resources.limits.memory
value: "128Mi"
- it: should not set resource limits when not provided
set:
resources: {}
asserts:
- notExists:
path: spec.template.spec.containers[0].resources.limits# charts/myapp/tests/ingress_test.yaml
suite: ingress tests
tests:
- it: should not render ingress when disabled
set:
ingress.enabled: false
asserts:
- hasDocuments:
count: 0
template: templates/ingress.yaml
- it: should render ingress when enabled
set:
ingress.enabled: true
ingress.host: myapp.example.com
asserts:
- isKind:
of: Ingress
- equal:
path: spec.rules[0].host
value: myapp.example.com
template: templates/ingress.yaml
- it: ingress host is required when ingress is enabled
set:
ingress.enabled: true
# ingress.host not set
asserts:
- failedTemplate:
errorMessage: "ingress.host is required when ingress.enabled is true"
template: templates/ingress.yaml# charts/myapp/tests/security_test.yaml
suite: security tests
tests:
- it: should run as non-root by default
asserts:
- equal:
path: spec.template.spec.securityContext.runAsNonRoot
value: true
- it: should not use host network
asserts:
- equal:
path: spec.template.spec.hostNetwork
value: false
- it: should have readOnlyRootFilesystem when enabled
set:
securityContext.readOnlyRootFilesystem: true
asserts:
- equal:
path: spec.template.spec.containers[0].securityContext.readOnlyRootFilesystem
value: trueRun with verbose output to see all test results:
helm unittest charts/myapp -vLayer 3: Linting With chart-testing
chart-testing (ct) runs Helm lint plus additional checks:
# Install chart-testing
brew install chart-testing
# Run lint
ct lint --charts charts/myapp
# With custom configuration
ct lint --config ct.yaml# ct.yaml
chart-dirs:
- charts
target-branch: main
check-version-increment: true
validate-maintainers: false
helm-lint-extra-args:
- "--strict"chart-testing also validates:
- Chart version incremented on change
Chart.yamlhas required fieldsvalues.yamlhas documentation- All templates render without error for all
ci/values files
Layer 4: Integration Testing With chart-testing and kind
chart-testing can deploy charts into kind and run Helm tests:
# Install the chart and run tests
ct install --charts charts/myapp --cluster-name kind-chart-testFor this to work, add a test pod to your chart:
# charts/myapp/templates/tests/test-connection.yaml
apiVersion: v1
kind: Pod
metadata:
name: "{{ include "myapp.fullname" . }}-test-connection"
annotations:
"helm.sh/hook": test
"helm.sh/hook-delete-policy": before-hook-creation,hook-succeeded
spec:
containers:
- name: wget
image: busybox
command: ['wget']
args: ['--spider', '--timeout=10', 'http://{{ include "myapp.fullname" . }}:{{ .Values.service.port }}/health']
restartPolicy: NeverRun with:
helm test myapp-releaseTesting Multiple Values Combinations
Create ci/ values files to test different configurations:
charts/myapp/ci/
├── minimal-values.yaml # Minimum required values
├── production-values.yaml # Production-like configuration
├── ha-values.yaml # High availability configuration
└── ingress-values.yaml # With ingress enabled# charts/myapp/ci/minimal-values.yaml
image:
repository: myapp
tag: test
# charts/myapp/ci/ha-values.yaml
replicaCount: 3
image:
repository: myapp
tag: test
resources:
limits:
cpu: "1"
memory: "256Mi"
requests:
cpu: "100m"
memory: "64Mi"
podDisruptionBudget:
enabled: true
minAvailable: 2
affinity:
podAntiAffinity:
requiredDuringSchedulingIgnoredDuringExecution:
- topologyKey: kubernetes.io/hostnamechart-testing will test each ci/*.yaml file:
ct install --charts charts/myapp
# Runs: helm install with each ci/*.yaml file, then helm testAdvanced Template Testing
For complex conditional logic in templates, test edge cases explicitly:
# charts/myapp/tests/hpa_test.yaml
suite: HorizontalPodAutoscaler tests
tests:
- it: HPA is not created when autoscaling is disabled
set:
autoscaling.enabled: false
asserts:
- hasDocuments:
count: 0
template: templates/hpa.yaml
- it: HPA uses correct min/max replicas
set:
autoscaling.enabled: true
autoscaling.minReplicas: 2
autoscaling.maxReplicas: 10
asserts:
- equal:
path: spec.minReplicas
value: 2
- equal:
path: spec.maxReplicas
value: 10
template: templates/hpa.yaml
- it: HPA targets CPU utilization
set:
autoscaling.enabled: true
autoscaling.targetCPUUtilizationPercentage: 75
asserts:
- contains:
path: spec.metrics
content:
type: Resource
resource:
name: cpu
target:
type: Utilization
averageUtilization: 75
template: templates/hpa.yaml
- it: replicaCount is ignored when HPA is enabled
set:
autoscaling.enabled: true
replicaCount: 5
asserts:
- notExists:
path: spec.replicas
template: templates/deployment.yamlCI Pipeline Configuration
# .github/workflows/helm-charts.yml
name: Helm Chart CI
on:
push:
paths:
- 'charts/**'
jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0 # Needed for chart-testing to compare against target branch
- uses: azure/setup-helm@v3
- name: Install chart-testing
uses: helm/chart-testing-action@v2.6.1
- name: Lint charts
run: ct lint --config ct.yaml
- name: Install helm-unittest
run: helm plugin install https://github.com/helm-unittest/helm-unittest
- name: Run unit tests
run: helm unittest charts/myapp -v
integration:
runs-on: ubuntu-latest
needs: lint
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: azure/setup-helm@v3
- uses: helm/chart-testing-action@v2.6.1
- name: Create kind cluster
uses: helm/kind-action@v1.9.0
with:
cluster_name: chart-test
- name: Install chart (all ci/ values)
run: ct install --config ct.yaml --cluster-name chart-testThe combination of helm-unittest (fast, no cluster) and chart-testing with kind (real deployment) gives you comprehensive coverage. Unit tests run on every commit. Integration tests run on PR merge.
HelpMeTest runs behavioral verification against applications deployed via Helm, confirming that chart updates produce the expected user-visible behavior. Start free →