How to Add Unit Tests to Helm Charts (Step-by-Step Guide)
Helm Testing Guide
How to Add Unit Tests to a Helm Chart with helm-unittest
If you maintain Helm charts, adding unit tests is one of the fastest ways to catch breaking template changes before they reach a cluster. In this post, I will show how to install the helm-unittest plugin, write your first Helm chart unit test, and run those tests locally as part of your development workflow.
What This Post Covers
- Why unit tests matter for Helm charts
- How to install the
helm-unittestplugin - A complete Helm unit test example
- How to run tests and interpret results
- Best practices for testing Helm templates
- FAQ:
helm unittestvshelm test
Why Add Unit Tests to a Helm Chart?
Helm charts often become the deployment contract for an application. A small template change can silently alter labels, container images, replica counts, resource limits, or service ports. Helm chart unit tests help verify the rendered YAML before anything is applied to Kubernetes.
- Catch template regressions early.
- Validate default values and override behavior.
- Refactor charts with more confidence.
- Run checks in CI without creating cluster resources.
That last point is important: helm-unittest renders your chart locally. It does not deploy anything to your cluster.
Install the Helm Unit Test Plugin
The most common way to add unit testing support to Helm is by installing the official helm-unittest plugin.
helm plugin install https://github.com/helm-unittest/helm-unittest.git
After installation, verify that Helm can see the plugin:
helm plugin list
You should see unittest in the output. Once installed, the main command you will use is:
helm unittest ./mychart
Tip
If you want to pin the plugin version in your CI environment, install a specific release tag instead of always pulling the latest version. That makes your Helm unit test pipeline more predictable.
Example Project Structure
A typical chart with Helm tests looks like this:
mychart/
├── Chart.yaml
├── values.yaml
├── .helmignore
├── templates/
│ └── deployment.yaml
└── tests/
└── deployment_test.yaml
Add tests to your .helmignore file so the test definitions are not packaged with the chart:
tests
Helm Template Example
Below is a simple deployment template we can test. The goal is to verify that values such as replica count, image tag, and container port render correctly.
apiVersion: apps/v1
kind: Deployment
metadata:
name: {{ include "mychart.fullname" . }}
spec:
replicas: {{ .Values.replicaCount }}
selector:
matchLabels:
app.kubernetes.io/name: {{ .Chart.Name }}
template:
metadata:
labels:
app.kubernetes.io/name: {{ .Chart.Name }}
spec:
containers:
- name: {{ .Chart.Name }}
image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
ports:
- containerPort: {{ .Values.service.port }}
And here is a matching values.yaml:
replicaCount: 2
image:
repository: nginx
tag: "1.27.0"
service:
port: 8080
How to Write a Unit Test for a Helm Chart
Create a file named tests/deployment_test.yaml. By default, helm-unittest looks for files in the tests directory that end with _test.yaml.
suite: deployment tests
templates:
- templates/deployment.yaml
tests:
- it: should render a Deployment object
asserts:
- isKind:
of: Deployment
- it: should set the replica count from values
set:
replicaCount: 3
asserts:
- equal:
path: spec.replicas
value: 3
- it: should build the full container image name
set:
image.repository: nginx
image.tag: "1.27.1"
asserts:
- equal:
path: spec.template.spec.containers[0].image
value: nginx:1.27.1
- it: should expose the configured container port
set:
service.port: 9090
asserts:
- equal:
path: spec.template.spec.containers[0].ports[0].containerPort
value: 9090
What This Test Is Doing
suitegives the test suite a readable name.templatesdefines which rendered template to test.setoverrides values for a single test case.assertschecks whether the rendered YAML matches expectations.
Run Helm Unit Tests
Once the test file is in place, run the following command from the chart directory or point it to the chart path directly:
helm unittest ./mychart
If you are already inside the chart directory, this also works:
helm unittest .
For teams using CI, the command is simple enough to add to GitHub Actions, GitLab CI, Jenkins, or any other pipeline runner.
Sample Output
A successful run usually looks similar to this:
PASS deployment tests
PASS should render a Deployment object
PASS should set the replica count from values
PASS should build the full container image name
PASS should expose the configured container port
Charts: 1 passed, 1 total
Test Suites: 1 passed, 1 total
Tests: 4 passed, 4 total
If a test fails, the plugin prints the assertion that failed and the actual rendered value, which makes template debugging much faster.
Best Practices for Helm Chart Unit Tests
- Test the most important templates first: Deployment, Service, Ingress, ConfigMap, and Secret references.
- Cover both defaults and overrides so chart consumers cannot accidentally break behavior.
- Use small, focused assertions instead of one huge snapshot for everything.
- Keep test names readable. Future you will debug faster.
- Run
helm lintandhelm unittesttogether in CI for better coverage.
Helm Unit Test vs Helm Test
What is the difference?
helm unittest validates rendered templates locally before deployment. helm test runs test pods against a deployed release inside Kubernetes. They solve different problems, and many teams use both.
Do Helm chart unit tests require a cluster?
No. The helm-unittest plugin renders templates on your machine or CI runner, so you can test chart logic without creating Kubernetes resources.
Can I use Helm unit tests in CI/CD?
Yes. This is one of the best use cases. Install the plugin in the pipeline, then run helm unittest as part of pull request validation.
Final Thoughts
If you publish or maintain Helm charts, unit tests are worth adding early. They are quick to run, easy to review, and very effective at catching mistakes in templating logic. The helm-unittest plugin gives you a practical way to test chart output before it ever reaches a Kubernetes cluster.
Comments
Post a Comment