Helm Chart Unit Testing with helm-unittest

Helm Chart Unit Testing with helm-unittest

helm-unittest renders your Helm templates with given values and lets you assert the resulting YAML with a simple test DSL. It catches configuration bugs before any cluster is involved — and runs in seconds. Add it to CI and never ship a broken chart again.

Helm is the de facto package manager for Kubernetes. Most teams use it to manage their application deployments, and most teams test their charts by deploying them to a cluster and hoping nothing breaks. That works until it doesn't — until a values override silently produces wrong resource limits, until a conditional block renders the wrong secret, until a required annotation is missing in production but not staging.

Helm chart unit testing with helm-unittest solves this. It renders templates locally, without a cluster, and lets you assert the resulting Kubernetes manifests. The feedback loop is seconds, not minutes. This post walks through everything you need to adopt it.

What helm-unittest Does

helm-unittest is a Helm plugin. You give it test files written in YAML, and it:

  1. Renders your chart templates using specified values
  2. Runs assertions against the rendered YAML output
  3. Reports pass/fail with context on what was expected vs. what was produced

It supports the same templating engine Helm uses internally, so what you test is exactly what Helm would produce. No surprises from rendering differences.

Installation

Install as a Helm plugin:

helm plugin install https://github.com/helm-unittest/helm-unittest

Verify:

helm unittest --help

For CI, use the Docker image instead of installing the plugin:

docker run --rm -v $(pwd):/apps helmunittest/helm-unittest:latest /apps/mychart

Chart Structure

Assume a chart with this layout:

mychart/
  Chart.yaml
  values.yaml
  templates/
    deployment.yaml
    service.yaml
    ingress.yaml
    _helpers.tpl
  tests/
    deployment_test.yaml
    service_test.yaml
    ingress_test.yaml

By convention, tests live in a tests/ directory inside the chart. helm-unittest discovers them automatically when you run:

helm unittest mychart/

Writing Your First Test Suite

A test suite is a YAML file with one or more test cases. Each test case specifies values to use and a set of assertions.

tests/deployment_test.yaml:

suite: Deployment tests
templates:
  - templates/deployment.yaml
tests:
  - it: should render with default values
    asserts:
      - isKind:
          of: Deployment
      - equal:
          path: metadata.name
          value: mychart
      - equal:
          path: spec.replicas
          value: 1
      - equal:
          path: spec.template.spec.containers[0].image
          value: nginx:1.25

  - it: should use custom replica count
    set:
      replicaCount: 3
    asserts:
      - equal:
          path: spec.replicas
          value: 3

  - it: should set resource limits when provided
    set:
      resources.limits.cpu: "500m"
      resources.limits.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"

Run it:

helm unittest mychart/

Output:

### Chart [ mychart ] mychart/

 PASS  Deployment tests    mychart/tests/deployment_test.yaml

Charts:      1 passed, 1 total
Test Suites: 1 passed, 1 total
Tests:       3 passed, 3 total

Assertion Types

helm-unittest provides a rich assertion vocabulary. Here are the most useful ones:

Equality and matching:

- equal:
    path: metadata.labels.app
    value: mychart

- matchRegex:
    path: spec.template.spec.containers[0].image
    pattern: "^nginx:"

- contains:
    path: spec.template.spec.containers[0].env
    content:
      name: MY_ENV_VAR
      value: hello

Existence checks:

- isNotNull:
    path: spec.template.spec.containers[0].resources

- isNull:
    path: spec.template.spec.hostNetwork

- isNotEmpty:
    path: metadata.annotations

Document structure:

- isKind:
    of: Deployment

- isAPIVersion:
    of: apps/v1

- hasDocuments:
    count: 1

Negation:

- notEqual:
    path: spec.template.spec.containers[0].securityContext.runAsRoot
    value: true

Testing Values Overrides and Conditionals

The most valuable tests cover conditional blocks — the {{- if .Values.ingress.enabled }} sections that are easy to get wrong.

templates/ingress.yaml:

{{- if .Values.ingress.enabled }}
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: {{ include "mychart.fullname" . }}
  {{- if .Values.ingress.annotations }}
  annotations:
    {{- toYaml .Values.ingress.annotations | nindent 4 }}
  {{- end }}
spec:
  rules:
  {{- range .Values.ingress.hosts }}
  - host: {{ .host }}
    http:
      paths:
      {{- range .paths }}
      - path: {{ .path }}
        pathType: {{ .pathType }}
        backend:
          service:
            name: {{ include "mychart.fullname" $ }}
            port:
              number: {{ $.Values.service.port }}
      {{- end }}
  {{- end }}
{{- end }}

tests/ingress_test.yaml:

suite: Ingress tests
templates:
  - templates/ingress.yaml
tests:
  - it: should not render when ingress is disabled
    set:
      ingress.enabled: false
    asserts:
      - hasDocuments:
          count: 0

  - it: should render when ingress is enabled
    set:
      ingress.enabled: true
      ingress.hosts[0].host: myapp.example.com
      ingress.hosts[0].paths[0].path: /
      ingress.hosts[0].paths[0].pathType: Prefix
    asserts:
      - hasDocuments:
          count: 1
      - isKind:
          of: Ingress
      - equal:
          path: spec.rules[0].host
          value: myapp.example.com

  - it: should include annotations when provided
    set:
      ingress.enabled: true
      ingress.annotations.kubernetes\.io/ingress\.class: nginx
      ingress.hosts[0].host: myapp.example.com
      ingress.hosts[0].paths[0].path: /
      ingress.hosts[0].paths[0].pathType: Prefix
    asserts:
      - equal:
          path: metadata.annotations["kubernetes.io/ingress.class"]
          value: nginx

Testing with Multiple Value Files

For charts with complex environments (dev, staging, prod), test with actual values files:

suite: Production deployment tests
templates:
  - templates/deployment.yaml
tests:
  - it: should have correct replica count in production
    values:
      - values.yaml
      - values-production.yaml
    asserts:
      - equal:
          path: spec.replicas
          value: 5
      - equal:
          path: spec.template.spec.containers[0].resources.requests.memory
          value: "512Mi"

This is more realistic than set: for production validation — it uses the same values files your deployment pipeline uses.

Security and Policy Tests

helm-unittest is excellent for enforcing security policies across all workloads:

suite: Security policy tests
templates:
  - templates/deployment.yaml
tests:
  - it: should not run as root
    asserts:
      - equal:
          path: spec.template.spec.securityContext.runAsNonRoot
          value: true

  - it: should drop all capabilities
    asserts:
      - contains:
          path: spec.template.spec.containers[0].securityContext.capabilities.drop
          content: ALL

  - it: should have read-only root filesystem
    asserts:
      - equal:
          path: spec.template.spec.containers[0].securityContext.readOnlyRootFilesystem
          value: true

  - it: should not allow privilege escalation
    asserts:
      - equal:
          path: spec.template.spec.containers[0].securityContext.allowPrivilegeEscalation
          value: false

These tests document your security requirements and catch regressions when someone modifies the chart.

CI Integration

GitHub Actions:

name: Helm Chart Tests

on:
  push:
    paths:
      - 'charts/**'
  pull_request:
    paths:
      - 'charts/**'

jobs:
  helm-unittest:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Helm
        uses: azure/setup-helm@v3
        with:
          version: v3.14.0

      - name: Install helm-unittest plugin
        run: helm plugin install https://github.com/helm-unittest/helm-unittest

      - name: Run chart tests
        run: |
          for chart in charts/*/; do
            echo "Testing $chart..."
            helm unittest "$chart"
          done

      - name: Lint charts
        run: |
          for chart in charts/*/; do
            helm lint "$chart"
          done

Using Docker for faster CI (no plugin install):

      - name: Run helm-unittest
        run: |
          docker run --rm \
            -v ${{ github.workspace }}:/apps \
            helmunittest/helm-unittest:latest \
            /apps/charts/mychart

The Docker approach is faster in CI because it skips plugin installation and uses a pinned image version.

Combining with helm lint and helm template

helm-unittest sits in a quality chain alongside other tools:

# 1. Lint: check chart syntax and best practices
helm lint mychart/ -f mychart/values-prod.yaml

# 2. Unit test: assert rendered output
helm unittest mychart/

# 3. Dry-run against a real cluster (catches CRD issues helm-unittest can't)
helm install mychart ./mychart/ --dry-run --generate-name

# 4. Deploy to staging
helm upgrade --install mychart ./mychart/ -n staging

Don't skip steps 1 and 2 just because you have step 3. Dry-run requires cluster access and is slow. helm-unittest catches 80% of issues in milliseconds.

Common Pitfalls

Pitfall 1: Testing the wrong template. The templates: key in your test suite must match the actual file path. A mismatch silently produces zero documents and your hasDocuments: count: 1 test fails with a confusing error.

Pitfall 2: Path syntax for keys with dots. Annotation keys like kubernetes.io/ingress.class must be quoted: metadata.annotations["kubernetes.io/ingress.class"].

Pitfall 3: Not testing the disabled case. Conditional templates need a test for enabled: false that asserts hasDocuments: count: 0. Without it, a broken conditional that always renders is never caught.

Pitfall 4: Ignoring _helpers.tpl coverage. Helper templates affect many resources. Test the outputs that depend on helpers rather than trying to test helpers directly.

What to Test

A minimal but effective test suite for any chart covers:

  • Default values produce valid, runnable manifests
  • Each optional feature (ingress, HPA, PDB, ServiceAccount) renders correctly when enabled and does not render when disabled
  • Values overrides (replica count, image tag, resource limits) are reflected in the output
  • Security context settings are enforced
  • Labels and annotations are consistently applied

That is typically 15–30 tests per chart, and they run in under two seconds. There is no good reason not to have them.

Read more

Start now free