How to Add Unit Tests to Helm Charts (Step-by-Step Guide)

How to Add Unit Tests to a Helm Chart with helm-unittest

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-unittest plugin
  • A complete Helm unit test example
  • How to run tests and interpret results
  • Best practices for testing Helm templates
  • FAQ: helm unittest vs helm 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

  • suite gives the test suite a readable name.
  • templates defines which rendered template to test.
  • set overrides values for a single test case.
  • asserts checks 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 lint and helm unittest together 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

Popular Posts