Helm Chart Testing: helm unittest, chart-testing, and Local Kubernetes Validation

Helm Chart Testing: helm unittest, chart-testing, and Local Kubernetes Validation

Helm charts generate Kubernetes manifests from templates and values. The same testing problem applies here as with CloudFormation: templates can render syntactically valid YAML that deploys incorrectly, and by the time you discover the problem, you've disrupted a running cluster.

The Helm testing ecosystem provides tools for different testing depths: helm-unittest for template unit tests, helm lint and helm template for basic validation, chart-testing (ct) for CI integration, and kind/minikube for actual Kubernetes deployment testing.

The Helm Testing Toolkit

Tool What it validates Speed
helm lint Basic chart structure, YAML syntax Seconds
helm template Template rendering, values substitution Seconds
helm-unittest Template output assertions Seconds
chart-testing (ct) Chart installation in real cluster Minutes
kind/minikube Full cluster integration Minutes

Use all of them at appropriate stages of your CI pipeline.

Basic Validation with helm lint and helm template

Before any other testing, run basic validation:

# Lint the chart (validates structure and syntax)
helm lint ./my-chart

# Render templates without deploying (validate Kubernetes resource structure)
helm template my-release ./my-chart --values values-staging.yaml | kubectl apply --dry-run=client -f -

# Validate with specific values sets
helm template my-release ./my-chart \
  --values values-production.yaml \
  --set image.tag=latest \
  | kubectl apply --dry-run=client -f -

kubectl apply --dry-run=client validates the rendered manifests against the Kubernetes API schema without sending them to a cluster — all locally.

Unit Testing with helm-unittest

helm-unittest is a Helm plugin that lets you write assertion-based unit tests for your chart templates.

Installation:

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

Test structure:

my-chart/
├── Chart.yaml
├── values.yaml
├── templates/
│   ├── deployment.yaml
│   ├── service.yaml
│   └── ingress.yaml
└── tests/
    ├── deployment_test.yaml
    ├── service_test.yaml
    └── ingress_test.yaml

Deployment test example:

# tests/deployment_test.yaml
suite: Deployment tests
templates:
  - deployment.yaml

tests:
  - it: should create a deployment
    asserts:
      - isKind:
          of: Deployment
      - isAPIVersion:
          of: apps/v1

  - it: should have correct replica count from values
    set:
      replicaCount: 3
    asserts:
      - equal:
          path: spec.replicas
          value: 3

  - it: should use image from values
    set:
      image.repository: nginx
      image.tag: "1.24"
    asserts:
      - equal:
          path: spec.template.spec.containers[0].image
          value: "nginx:1.24"

  - it: should not include resource limits when not set
    set:
      resources: {}
    asserts:
      - notExists:
          path: spec.template.spec.containers[0].resources.limits

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

  - it: should set correct environment variables
    set:
      env:
        - name: DATABASE_URL
          value: postgresql://db:5432/app
    asserts:
      - contains:
          path: spec.template.spec.containers[0].env
          content:
            name: DATABASE_URL
            value: postgresql://db:5432/app

  - it: should not mount volumes by default
    asserts:
      - notExists:
          path: spec.template.spec.volumes

  - it: should have readiness probe configured
    asserts:
      - exists:
          path: spec.template.spec.containers[0].readinessProbe
      - equal:
          path: spec.template.spec.containers[0].readinessProbe.httpGet.path
          value: /healthz

Service test example:

# tests/service_test.yaml
suite: Service tests
templates:
  - service.yaml

tests:
  - it: should create ClusterIP service by default
    asserts:
      - isKind:
          of: Service
      - equal:
          path: spec.type
          value: ClusterIP

  - it: should create LoadBalancer service when type is set
    set:
      service.type: LoadBalancer
    asserts:
      - equal:
          path: spec.type
          value: LoadBalancer

  - it: should expose correct port
    set:
      service.port: 8080
    asserts:
      - equal:
          path: spec.ports[0].port
          value: 8080

Ingress test example:

# tests/ingress_test.yaml
suite: Ingress tests
templates:
  - ingress.yaml

tests:
  - it: should not create ingress when disabled
    set:
      ingress.enabled: false
    asserts:
      - hasDocuments:
          count: 0

  - it: should create ingress with correct host when enabled
    set:
      ingress.enabled: true
      ingress.hosts:
        - host: app.example.com
          paths:
            - path: /
              pathType: Prefix
    asserts:
      - isKind:
          of: Ingress
      - equal:
          path: spec.rules[0].host
          value: app.example.com

  - it: should set TLS configuration when provided
    set:
      ingress.enabled: true
      ingress.tls:
        - secretName: app-tls
          hosts:
            - app.example.com
    asserts:
      - exists:
          path: spec.tls
      - equal:
          path: spec.tls[0].secretName
          value: app-tls

Running tests:

# Run all tests
helm unittest ./my-chart

# Run with verbose output
helm unittest -v ./my-chart

# Run specific test file
helm unittest -f 'tests/deployment_test.yaml' ./my-chart

# Output in JUnit format for CI
helm unittest ./my-chart -o xml -t test-results.xml

chart-testing (ct)

chart-testing is a tool from the Helm project for CI testing of Helm charts. It automates:

  • Detecting which charts changed (to avoid testing unmodified charts)
  • Linting changed charts
  • Installing changed charts into a real Kubernetes cluster
  • Running Helm test hooks
  • Upgrading charts from previous versions

Installation:

brew install chart-testing  # macOS

# Or using Docker
docker run --rm -it quay.io/helmpack/chart-testing:latest

Configuration (ct.yaml):

# ct.yaml
remote: origin
target-branch: main
chart-dirs:
  - charts
helm-extra-args: --timeout 600s
validate-maintainers: false
lint-conf: .yamllint.yaml

Usage:

# Lint changed charts
ct lint --config ct.yaml

# Install changed charts (requires cluster access)
ct install --config ct.yaml

# Lint and install (full test)
ct lint-and-install --config ct.yaml

GitHub Actions workflow:

lint-and-test:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
      with:
        fetch-depth: 0  # Required for detecting changes

    - name: Set up Helm
      uses: azure/setup-helm@v3

    - name: Set up chart-testing
      uses: helm/chart-testing-action@v2.6.1

    - name: Run chart-testing lint
      run: ct lint --config ct.yaml

    - name: Create kind cluster
      uses: helm/kind-action@v1.9.0
      if: steps.list-changed.outputs.changed == 'true'

    - name: Run chart-testing install
      run: ct install --config ct.yaml
      if: steps.list-changed.outputs.changed == 'true'

Helm Test Hooks

Helm supports test hooks — Kubernetes Jobs that run after helm install to verify the deployment. These run when you execute helm test <release>:

# templates/tests/test-connection.yaml
apiVersion: v1
kind: Pod
metadata:
  name: "{{ include "my-chart.fullname" . }}-test-connection"
  labels:
    {{- include "my-chart.labels" . | nindent 4 }}
  annotations:
    "helm.sh/hook": test
    "helm.sh/hook-delete-policy": hook-succeeded
spec:
  restartPolicy: Never
  containers:
    - name: wget
      image: busybox:1.36
      command:
        - wget
        - "--spider"
        - "http://{{ include "my-chart.fullname" . }}:{{ .Values.service.port }}"
# templates/tests/test-database-connection.yaml
apiVersion: v1
kind: Pod
metadata:
  name: "{{ include "my-chart.fullname" . }}-test-db"
  annotations:
    "helm.sh/hook": test
    "helm.sh/hook-delete-policy": hook-succeeded
spec:
  restartPolicy: Never
  containers:
    - name: postgres-test
      image: postgres:14
      env:
        - name: DATABASE_URL
          valueFrom:
            secretKeyRef:
              name: "{{ include "my-chart.fullname" . }}-secret"
              key: database-url
      command:
        - sh
        - -c
        - |
          psql $DATABASE_URL -c "SELECT 1" && echo "Database connection: OK"

Run tests after deployment:

helm install my-release ./my-chart
helm test my-release

If any test pod exits with a non-zero code, helm test fails.

Integration Testing with kind

kind (Kubernetes in Docker) runs a real Kubernetes cluster in Docker containers, suitable for local development and CI:

# Install kind
go install sigs.k8s.io/kind@latest
# or: brew install kind

# Create a cluster
kind create cluster --name test-cluster --config kind-config.yaml
# kind-config.yaml
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
  - role: control-plane
  - role: worker
  - role: worker

Testing a chart against a kind cluster:

#!/bin/bash
# scripts/test-chart.sh

# Create cluster
kind create cluster --name test-chart

# Load local images into kind (avoids DockerHub rate limits)
kind load docker-image myapp:latest --name test-chart

# Install the chart
helm install my-release ./my-chart \
  --set image.tag=latest \
  --wait \
  --timeout 5m

# Run Helm tests
helm test my-release

# Additional smoke tests
kubectl get pods -l app.kubernetes.io/name=my-chart
kubectl wait --for=condition=ready pod -l app.kubernetes.io/name=my-chart --timeout=120s

# Clean up
kind delete cluster --name test-chart

GitLab CI with kind:

helm-integration-test:
  stage: test
  image: docker:24
  services:
    - docker:24-dind
  variables:
    DOCKER_HOST: tcp://docker:2376
    DOCKER_TLS_CERTDIR: "/certs"
  script:
    - apk add --no-cache curl bash
    - curl -Lo /usr/local/bin/kind "https://kind.sigs.k8s.io/dl/v0.22.0/kind-linux-amd64"
    - chmod +x /usr/local/bin/kind
    - curl -LO "https://dl.k8s.io/release/$(curl -sL https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
    - chmod +x kubectl && mv kubectl /usr/local/bin/
    - kind create cluster
    - helm install test-release ./my-chart --wait --timeout 5m
    - helm test test-release
    - kind delete cluster

Validating values.yaml Schema

Add a JSON schema (values.schema.json) to your chart for validation:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "replicaCount": {
      "type": "integer",
      "minimum": 1,
      "description": "Number of replicas"
    },
    "image": {
      "type": "object",
      "required": ["repository", "tag"],
      "properties": {
        "repository": { "type": "string" },
        "tag": { "type": "string" },
        "pullPolicy": {
          "type": "string",
          "enum": ["Always", "IfNotPresent", "Never"]
        }
      }
    },
    "resources": {
      "type": "object",
      "properties": {
        "limits": {
          "type": "object",
          "properties": {
            "cpu": { "type": "string" },
            "memory": { "type": "string" }
          }
        }
      }
    }
  },
  "required": ["replicaCount", "image"]
}

Helm validates values against this schema during helm install, helm upgrade, and helm template. Invalid values fail immediately with a clear error message.

Testing Multiple Values Combinations

For charts with complex configuration options, testing multiple values combinations catches edge cases:

# tests/comprehensive_test.yaml
suite: Comprehensive values tests
templates:
  - deployment.yaml
  - service.yaml

tests:
  - it: default values should produce valid resources
    # No set directives - uses values.yaml defaults
    asserts:
      - isKind:
          of: Deployment
      - isNotEmpty:
          path: spec.template.spec.containers

  - it: production values override
    values:
      - ../values-production.yaml
    asserts:
      - equal:
          path: spec.replicas
          value: 3

  - it: minimal configuration
    set:
      replicaCount: 1
      image.repository: nginx
      image.tag: "1.24"
      ingress.enabled: false
      resources: {}
    asserts:
      - isKind:
          of: Deployment

The combination of helm-unittest for template assertions, chart-testing for CI integration, and kind for actual deployment testing gives you confidence in your Helm charts before they reach production clusters.

Read more

Start now free