Helm Chart Testing with helm-unittest and ct
Helm charts are infrastructure code and deserve the same test discipline as application code. helm-unittest lets you write declarative YAML tests against rendered templates, while chart-testing (ct) handles lint, schema validation, and install tests in CI. Together they catch broken templates before they reach a cluster.
Key Takeaways
Test rendered output, not intent. helm-unittest renders your templates with given values and asserts the exact YAML output—no guessing whether a conditional block fires correctly.
Separate unit tests from install tests. Unit tests (helm-unittest) are fast and run everywhere; install tests (ct) deploy to a real cluster and are reserved for CI on PRs.
Test all value combinations that matter. If a value toggles a feature, write a test for both true and false. Untested code paths break in production.
Validate default values. Most breakage comes from missing or wrong defaults. Write a test that uses zero overrides and asserts the defaults produce valid output.
Use ct's version detection. chart-testing automatically detects which charts changed and only tests those—this keeps CI fast even in large monorepos with many charts.
The Case for Chart Tests
A Helm chart is a template program. It takes values as input and produces Kubernetes manifests as output. Every {{ if }}, {{ range }}, and {{ default }} is a code path that can produce wrong output if your values change or your template logic has a bug.
Without tests, you discover these bugs when helm upgrade fails in staging—or worse, when a pod won't start in production because a container image tag was wrong or a ConfigMap reference was missing.
helm-unittest and chart-testing (ct) give you two complementary layers: fast unit tests that run in seconds, and real install tests that verify your chart works against an actual Kubernetes API.
Installing the Tools
helm-unittest is a Helm plugin:
helm plugin install https://github.com/helm-unittest/helm-unittest.gitchart-testing is a standalone binary:
# macOS
brew install chart-testing
# Or download from GitHub releases
curl -Lo /tmp/ct.tar.gz https://github.com/helm/chart-testing/releases/latest/download/chart-testing_Linux_amd64.tar.gz
tar -xzf /tmp/ct.tar.gz -C /usr/local/bin cthelm-unittest: Writing Your First Test Suite
Tests live alongside your chart in a tests/ directory. Each test file targets one template file:
charts/
my-app/
Chart.yaml
values.yaml
templates/
deployment.yaml
service.yaml
ingress.yaml
_helpers.tpl
tests/
deployment_test.yaml
service_test.yaml
ingress_test.yamlA test file for deployment.yaml might look like:
# charts/my-app/tests/deployment_test.yaml
suite: deployment
templates:
- deployment.yaml
tests:
- it: should render with default values
asserts:
- isKind:
of: Deployment
- equal:
path: metadata.name
value: RELEASE-NAME-my-app
- equal:
path: spec.replicas
value: 1
- equal:
path: spec.template.spec.containers[0].image
value: nginx:latest
- isNotEmpty:
path: spec.selector.matchLabels
- it: should set replica count from values
set:
replicaCount: 3
asserts:
- equal:
path: spec.replicas
value: 3
- it: should apply resource limits when set
set:
resources:
limits:
cpu: "500m"
memory: "256Mi"
requests:
cpu: "250m"
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: "256Mi"
- it: should not set resource limits by default
asserts:
- isNull:
path: spec.template.spec.containers[0].resources.limits
- it: should add environment variables
set:
env:
- name: DATABASE_URL
value: postgres://localhost:5432/app
- name: REDIS_URL
value: redis://localhost:6379
asserts:
- contains:
path: spec.template.spec.containers[0].env
content:
name: DATABASE_URL
value: postgres://localhost:5432/app
- lengthEqual:
path: spec.template.spec.containers[0].env
count: 2Run the suite:
helm unittest charts/my-appOutput shows pass/fail per test case, with diffs when assertions fail.
Testing Conditional Blocks
Conditional logic is where charts most often break. Test every branch:
# charts/my-app/tests/ingress_test.yaml
suite: ingress
templates:
- ingress.yaml
tests:
- it: should not render ingress when disabled
set:
ingress.enabled: false
asserts:
- hasDocuments:
count: 0
- it: should render ingress when enabled
set:
ingress.enabled: true
ingress.hostname: app.example.com
asserts:
- hasDocuments:
count: 1
- isKind:
of: Ingress
- equal:
path: spec.rules[0].host
value: app.example.com
- it: should use nginx ingress class by default
set:
ingress.enabled: true
ingress.hostname: app.example.com
asserts:
- equal:
path: metadata.annotations["kubernetes.io/ingress.class"]
value: nginx
- it: should support TLS configuration
set:
ingress.enabled: true
ingress.hostname: app.example.com
ingress.tls: true
ingress.tlsSecret: my-tls-secret
asserts:
- isNotEmpty:
path: spec.tls
- equal:
path: spec.tls[0].secretName
value: my-tls-secret
- contains:
path: spec.tls[0].hosts
content: app.example.com
- it: should fail when ingress enabled but hostname missing
set:
ingress.enabled: true
asserts:
- failedTemplate:
errorMessage: "ingress.hostname is required when ingress.enabled is true"The failedTemplate assertion is particularly useful—it tests that your chart fails fast with a clear error rather than silently rendering broken YAML.
Testing with Values Files
For complex configurations, use values files instead of individual set directives:
# charts/my-app/tests/production_values_test.yaml
suite: production values
templates:
- deployment.yaml
- service.yaml
tests:
- it: should render correctly with production values
values:
- ../ci/production-values.yaml
asserts:
- equal:
path: spec.replicas
value: 3
- equal:
path: spec.template.spec.containers[0].resources.limits.memory
value: "1Gi"Keep a ci/ directory with value files for each environment you support. This ensures your chart works for real-world configurations, not just defaults.
Testing Helper Templates
_helpers.tpl functions are often untested but frequently wrong. Test them by asserting on objects that use them:
suite: helpers
templates:
- deployment.yaml
tests:
- it: should generate correct chart labels
release:
name: my-release
namespace: production
chart:
version: "1.2.3"
asserts:
- equal:
path: metadata.labels["helm.sh/chart"]
value: my-app-1.2.3
- equal:
path: metadata.labels["app.kubernetes.io/instance"]
value: my-release
- equal:
path: metadata.labels["app.kubernetes.io/version"]
value: "1.2.3"chart-testing (ct): Lint and Install Tests
helm-unittest tests rendered YAML. chart-testing does two more things:
- Lint: validates Chart.yaml, checks for required fields, and runs
helm lint - Install: deploys your chart to a real cluster and checks pods become healthy
Create a ct.yaml configuration at the repo root:
# ct.yaml
remote: origin
target-branch: main
chart-dirs:
- charts
chart-repos:
- bitnami=https://charts.bitnami.com/bitnami
helm-extra-args: "--timeout 300s"
validate-maintainers: false
check-version-increment: trueWith check-version-increment: true, ct will fail if you change a chart without bumping its version—good discipline for shared charts.
Run lint locally:
ct lint --config ct.yamlRun install tests (requires a cluster):
ct install --config ct.yaml --allThe --all flag tests all charts. Without it, ct detects which charts changed since the target branch and only tests those.
GitHub Actions: Full CI Pipeline
# .github/workflows/helm-tests.yml
name: Helm Chart Tests
on:
pull_request:
paths:
- 'charts/**'
push:
branches: [main]
jobs:
unit-tests:
name: helm-unittest
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install Helm
uses: azure/setup-helm@v3
with:
version: "3.14.0"
- name: Install helm-unittest plugin
run: helm plugin install https://github.com/helm-unittest/helm-unittest.git
- name: Run unit tests
run: |
for chart in charts/*/; do
if [ -d "${chart}tests" ]; then
echo "Testing ${chart}"
helm unittest "${chart}"
fi
done
lint:
name: ct lint
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0 # ct needs full history to detect changes
- name: Install Helm
uses: azure/setup-helm@v3
with:
version: "3.14.0"
- name: Install chart-testing
uses: helm/chart-testing-action@v2.6.1
- name: Run chart lint
run: ct lint --config ct.yaml
install-tests:
name: ct install
runs-on: ubuntu-latest
needs: [unit-tests, lint]
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Install Helm
uses: azure/setup-helm@v3
with:
version: "3.14.0"
- name: Install chart-testing
uses: helm/chart-testing-action@v2.6.1
- name: Create kind cluster
uses: helm/kind-action@v1.9.0
with:
cluster_name: chart-testing
- name: Run chart install tests
run: ct install --config ct.yamlThe kind cluster is ephemeral—created fresh for each CI run, destroyed after. No shared cluster state, no flaky tests from leftover resources.
Structuring CI Values for Install Tests
Chart-testing looks for values files in charts/<chart-name>/ci/ automatically. Create one file per scenario:
charts/my-app/ci/
default-values.yaml # minimal config, tests defaults
full-values.yaml # all features enabled
minimal-values.yaml # only required values setct will run a separate install test for each values file in ci/. This gives you multi-scenario install testing without writing any test code.
Example full-values.yaml:
replicaCount: 2
image:
repository: nginx
tag: "1.25"
ingress:
enabled: true
hostname: test.example.com
autoscaling:
enabled: true
minReplicas: 2
maxReplicas: 5
resources:
limits:
cpu: "500m"
memory: "256Mi"
requests:
cpu: "250m"
memory: "128Mi"Testing Chart Dependencies
If your chart has dependencies (subcharts), test that they're configured correctly:
suite: redis dependency
templates:
- charts/redis/templates/deployment.yaml
tests:
- it: should configure redis with correct password
set:
redis.auth.password: supersecret
asserts:
- contains:
path: spec.template.spec.containers[0].env
content:
name: REDIS_PASSWORD
value: supersecretYou need to run helm dependency update before running unittest with subchart tests.
Schema Validation
Add a values.schema.json to your chart to validate inputs at helm install time:
{
"$schema": "https://json-schema.org/draft-07/schema#",
"properties": {
"replicaCount": {
"type": "integer",
"minimum": 1,
"maximum": 100
},
"image": {
"type": "object",
"required": ["repository", "tag"],
"properties": {
"repository": { "type": "string" },
"tag": { "type": "string" }
}
},
"ingress": {
"type": "object",
"properties": {
"enabled": { "type": "boolean" },
"hostname": { "type": "string" }
},
"if": {
"properties": { "enabled": { "const": true } }
},
"then": {
"required": ["hostname"]
}
}
},
"required": ["image"]
}This schema is enforced by Helm itself—before your templates even render. Combined with failedTemplate assertions in helm-unittest, you get defense at two layers.
Measuring Coverage
There's no built-in coverage tool for Helm charts, but you can audit it manually: for each {{ if }} block in your templates, verify there's a test case with that condition true and one with it false. Build this into your PR review checklist.
Conclusion
Helm chart testing is low-investment for high return. helm-unittest tests run in under a second, catch template regressions immediately, and require no cluster. chart-testing's install tests add the confidence that your chart actually deploys healthy pods. Run both in CI on every PR that touches a chart, and you'll stop shipping broken Kubernetes configurations.