Helm Chart Testing Strategies: Unit Tests, Integration Tests, and CI Validation

Helm Chart Testing Strategies: Unit Tests, Integration Tests, and CI Validation

Helm charts package Kubernetes applications into reusable, configurable units. They also concentrate complexity: a chart with 20 configurable values can produce hundreds of different Kubernetes manifests depending on those values. Testing every significant combination is the only way to ship a chart confidently.

This guide covers the full Helm chart testing stack: template unit tests, values schema validation, lint checks, and integration testing in a real cluster.

The Four Layers of Helm Chart Testing

Layer 1 — Schema validation: Verify that values conform to the expected types and constraints.

Layer 2 — Template unit tests: Verify that the rendered templates match expectations for given values.

Layer 3 — Lint and policy checks: Verify that rendered manifests follow Kubernetes best practices.

Layer 4 — Integration tests: Deploy the chart into a real cluster and verify it works.

Each layer catches different issues. Skip any one of them and you'll find its problems in production.

Layer 1: Values Schema Validation

Add a values.schema.json to your chart to enforce types and required fields:

// charts/myapp/values.schema.json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["image", "replicaCount"],
  "properties": {
    "replicaCount": {
      "type": "integer",
      "minimum": 1,
      "maximum": 20
    },
    "image": {
      "type": "object",
      "required": ["repository", "tag"],
      "properties": {
        "repository": { "type": "string", "minLength": 1 },
        "tag": { "type": "string", "minLength": 1 },
        "pullPolicy": {
          "type": "string",
          "enum": ["Always", "IfNotPresent", "Never"]
        }
      }
    },
    "resources": {
      "type": "object",
      "properties": {
        "limits": {
          "type": "object",
          "properties": {
            "cpu": { "type": "string" },
            "memory": { "type": "string" }
          }
        }
      }
    },
    "ingress": {
      "type": "object",
      "properties": {
        "enabled": { "type": "boolean" },
        "host": {
          "type": "string",
          "format": "hostname"
        }
      }
    }
  }
}

Test schema validation:

# Valid values — should succeed
helm install test-release ./charts/myapp \
  --set image.repository=myapp \
  --set image.tag=latest \
  --dry-run

# Invalid values — should fail with schema error
helm install test-release ./charts/myapp \
  --set replicaCount=0 \  # Below minimum
  --dry-run

Layer 2: Template Unit Tests With helm-unittest

helm-unittest tests rendered chart templates without deploying to a cluster:

# Install the plugin
helm plugin install https://github.com/helm-unittest/helm-unittest

# Run tests
helm unittest charts/myapp

Write test files in charts/myapp/tests/:

# charts/myapp/tests/deployment_test.yaml
suite: deployment tests

tests:
  - it: should render deployment with correct replicas
    set:
      replicaCount: 3
      image.repository: myapp
      image.tag: "1.0.0"
    asserts:
      - isKind:
          of: Deployment
      - equal:
          path: spec.replicas
          value: 3

  - it: should use correct image
    set:
      image.repository: registry.example.com/myapp
      image.tag: "2.0.0"
      image.pullPolicy: Always
    asserts:
      - equal:
          path: spec.template.spec.containers[0].image
          value: "registry.example.com/myapp:2.0.0"
      - equal:
          path: spec.template.spec.containers[0].imagePullPolicy
          value: Always

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

  - it: should not set resource limits when not provided
    set:
      resources: {}
    asserts:
      - notExists:
          path: spec.template.spec.containers[0].resources.limits
# charts/myapp/tests/ingress_test.yaml
suite: ingress tests

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

  - it: should render ingress when enabled
    set:
      ingress.enabled: true
      ingress.host: myapp.example.com
    asserts:
      - isKind:
          of: Ingress
      - equal:
          path: spec.rules[0].host
          value: myapp.example.com
    template: templates/ingress.yaml

  - it: ingress host is required when ingress is enabled
    set:
      ingress.enabled: true
      # ingress.host not set
    asserts:
      - failedTemplate:
          errorMessage: "ingress.host is required when ingress.enabled is true"
    template: templates/ingress.yaml
# charts/myapp/tests/security_test.yaml
suite: security tests

tests:
  - it: should run as non-root by default
    asserts:
      - equal:
          path: spec.template.spec.securityContext.runAsNonRoot
          value: true

  - it: should not use host network
    asserts:
      - equal:
          path: spec.template.spec.hostNetwork
          value: false

  - it: should have readOnlyRootFilesystem when enabled
    set:
      securityContext.readOnlyRootFilesystem: true
    asserts:
      - equal:
          path: spec.template.spec.containers[0].securityContext.readOnlyRootFilesystem
          value: true

Run with verbose output to see all test results:

helm unittest charts/myapp -v

Layer 3: Linting With chart-testing

chart-testing (ct) runs Helm lint plus additional checks:

# Install chart-testing
brew install chart-testing

# Run lint
ct lint --charts charts/myapp

# With custom configuration
ct lint --config ct.yaml
# ct.yaml
chart-dirs:
  - charts
target-branch: main
check-version-increment: true
validate-maintainers: false
helm-lint-extra-args:
  - "--strict"

chart-testing also validates:

  • Chart version incremented on change
  • Chart.yaml has required fields
  • values.yaml has documentation
  • All templates render without error for all ci/ values files

Layer 4: Integration Testing With chart-testing and kind

chart-testing can deploy charts into kind and run Helm tests:

# Install the chart and run tests
ct install --charts charts/myapp --cluster-name kind-chart-test

For this to work, add a test pod to your chart:

# charts/myapp/templates/tests/test-connection.yaml
apiVersion: v1
kind: Pod
metadata:
  name: "{{ include "myapp.fullname" . }}-test-connection"
  annotations:
    "helm.sh/hook": test
    "helm.sh/hook-delete-policy": before-hook-creation,hook-succeeded
spec:
  containers:
    - name: wget
      image: busybox
      command: ['wget']
      args: ['--spider', '--timeout=10', 'http://{{ include "myapp.fullname" . }}:{{ .Values.service.port }}/health']
  restartPolicy: Never

Run with:

helm test myapp-release

Testing Multiple Values Combinations

Create ci/ values files to test different configurations:

charts/myapp/ci/
├── minimal-values.yaml      # Minimum required values
├── production-values.yaml   # Production-like configuration
├── ha-values.yaml           # High availability configuration
└── ingress-values.yaml      # With ingress enabled
# charts/myapp/ci/minimal-values.yaml
image:
  repository: myapp
  tag: test

# charts/myapp/ci/ha-values.yaml
replicaCount: 3
image:
  repository: myapp
  tag: test
resources:
  limits:
    cpu: "1"
    memory: "256Mi"
  requests:
    cpu: "100m"
    memory: "64Mi"
podDisruptionBudget:
  enabled: true
  minAvailable: 2
affinity:
  podAntiAffinity:
    requiredDuringSchedulingIgnoredDuringExecution:
      - topologyKey: kubernetes.io/hostname

chart-testing will test each ci/*.yaml file:

ct install --charts charts/myapp
# Runs: helm install with each ci/*.yaml file, then helm test

Advanced Template Testing

For complex conditional logic in templates, test edge cases explicitly:

# charts/myapp/tests/hpa_test.yaml
suite: HorizontalPodAutoscaler tests

tests:
  - it: HPA is not created when autoscaling is disabled
    set:
      autoscaling.enabled: false
    asserts:
      - hasDocuments:
          count: 0
    template: templates/hpa.yaml

  - it: HPA uses correct min/max replicas
    set:
      autoscaling.enabled: true
      autoscaling.minReplicas: 2
      autoscaling.maxReplicas: 10
    asserts:
      - equal:
          path: spec.minReplicas
          value: 2
      - equal:
          path: spec.maxReplicas
          value: 10
    template: templates/hpa.yaml

  - it: HPA targets CPU utilization
    set:
      autoscaling.enabled: true
      autoscaling.targetCPUUtilizationPercentage: 75
    asserts:
      - contains:
          path: spec.metrics
          content:
            type: Resource
            resource:
              name: cpu
              target:
                type: Utilization
                averageUtilization: 75
    template: templates/hpa.yaml

  - it: replicaCount is ignored when HPA is enabled
    set:
      autoscaling.enabled: true
      replicaCount: 5
    asserts:
      - notExists:
          path: spec.replicas
    template: templates/deployment.yaml

CI Pipeline Configuration

# .github/workflows/helm-charts.yml
name: Helm Chart CI

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

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Needed for chart-testing to compare against target branch

      - uses: azure/setup-helm@v3

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

      - name: Lint charts
        run: ct lint --config ct.yaml

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

      - name: Run unit tests
        run: helm unittest charts/myapp -v

  integration:
    runs-on: ubuntu-latest
    needs: lint
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: azure/setup-helm@v3
      - uses: helm/chart-testing-action@v2.6.1

      - name: Create kind cluster
        uses: helm/kind-action@v1.9.0
        with:
          cluster_name: chart-test

      - name: Install chart (all ci/ values)
        run: ct install --config ct.yaml --cluster-name chart-test

The combination of helm-unittest (fast, no cluster) and chart-testing with kind (real deployment) gives you comprehensive coverage. Unit tests run on every commit. Integration tests run on PR merge.


HelpMeTest runs behavioral verification against applications deployed via Helm, confirming that chart updates produce the expected user-visible behavior. Start free →

Start now free