Helm Chart Testing with helm-unittest and ct

Helm Chart Testing with helm-unittest and ct

Helm charts are infrastructure code and deserve the same test discipline as application code. helm-unittest lets you write declarative YAML tests against rendered templates, while chart-testing (ct) handles lint, schema validation, and install tests in CI. Together they catch broken templates before they reach a cluster.

Key Takeaways

Test rendered output, not intent. helm-unittest renders your templates with given values and asserts the exact YAML output—no guessing whether a conditional block fires correctly.

Separate unit tests from install tests. Unit tests (helm-unittest) are fast and run everywhere; install tests (ct) deploy to a real cluster and are reserved for CI on PRs.

Test all value combinations that matter. If a value toggles a feature, write a test for both true and false. Untested code paths break in production.

Validate default values. Most breakage comes from missing or wrong defaults. Write a test that uses zero overrides and asserts the defaults produce valid output.

Use ct's version detection. chart-testing automatically detects which charts changed and only tests those—this keeps CI fast even in large monorepos with many charts.

The Case for Chart Tests

A Helm chart is a template program. It takes values as input and produces Kubernetes manifests as output. Every {{ if }}, {{ range }}, and {{ default }} is a code path that can produce wrong output if your values change or your template logic has a bug.

Without tests, you discover these bugs when helm upgrade fails in staging—or worse, when a pod won't start in production because a container image tag was wrong or a ConfigMap reference was missing.

helm-unittest and chart-testing (ct) give you two complementary layers: fast unit tests that run in seconds, and real install tests that verify your chart works against an actual Kubernetes API.

Installing the Tools

helm-unittest is a Helm plugin:

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

chart-testing is a standalone binary:

# macOS
brew install chart-testing

# Or download from GitHub releases
curl -Lo /tmp/ct.tar.gz https://github.com/helm/chart-testing/releases/latest/download/chart-testing_Linux_amd64.tar.gz
tar -xzf /tmp/ct.tar.gz -C /usr/local/bin ct

helm-unittest: Writing Your First Test Suite

Tests live alongside your chart in a tests/ directory. Each test file targets one template file:

charts/
  my-app/
    Chart.yaml
    values.yaml
    templates/
      deployment.yaml
      service.yaml
      ingress.yaml
      _helpers.tpl
    tests/
      deployment_test.yaml
      service_test.yaml
      ingress_test.yaml

A test file for deployment.yaml might look like:

# charts/my-app/tests/deployment_test.yaml
suite: deployment
templates:
  - deployment.yaml

tests:
  - it: should render with default values
    asserts:
      - isKind:
          of: Deployment
      - equal:
          path: metadata.name
          value: RELEASE-NAME-my-app
      - equal:
          path: spec.replicas
          value: 1
      - equal:
          path: spec.template.spec.containers[0].image
          value: nginx:latest
      - isNotEmpty:
          path: spec.selector.matchLabels

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

  - it: should apply resource limits when set
    set:
      resources:
        limits:
          cpu: "500m"
          memory: "256Mi"
        requests:
          cpu: "250m"
          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: "256Mi"

  - it: should not set resource limits by default
    asserts:
      - isNull:
          path: spec.template.spec.containers[0].resources.limits

  - it: should add environment variables
    set:
      env:
        - name: DATABASE_URL
          value: postgres://localhost:5432/app
        - name: REDIS_URL
          value: redis://localhost:6379
    asserts:
      - contains:
          path: spec.template.spec.containers[0].env
          content:
            name: DATABASE_URL
            value: postgres://localhost:5432/app
      - lengthEqual:
          path: spec.template.spec.containers[0].env
          count: 2

Run the suite:

helm unittest charts/my-app

Output shows pass/fail per test case, with diffs when assertions fail.

Testing Conditional Blocks

Conditional logic is where charts most often break. Test every branch:

# charts/my-app/tests/ingress_test.yaml
suite: ingress
templates:
  - ingress.yaml

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

  - it: should render ingress when enabled
    set:
      ingress.enabled: true
      ingress.hostname: app.example.com
    asserts:
      - hasDocuments:
          count: 1
      - isKind:
          of: Ingress
      - equal:
          path: spec.rules[0].host
          value: app.example.com

  - it: should use nginx ingress class by default
    set:
      ingress.enabled: true
      ingress.hostname: app.example.com
    asserts:
      - equal:
          path: metadata.annotations["kubernetes.io/ingress.class"]
          value: nginx

  - it: should support TLS configuration
    set:
      ingress.enabled: true
      ingress.hostname: app.example.com
      ingress.tls: true
      ingress.tlsSecret: my-tls-secret
    asserts:
      - isNotEmpty:
          path: spec.tls
      - equal:
          path: spec.tls[0].secretName
          value: my-tls-secret
      - contains:
          path: spec.tls[0].hosts
          content: app.example.com

  - it: should fail when ingress enabled but hostname missing
    set:
      ingress.enabled: true
    asserts:
      - failedTemplate:
          errorMessage: "ingress.hostname is required when ingress.enabled is true"

The failedTemplate assertion is particularly useful—it tests that your chart fails fast with a clear error rather than silently rendering broken YAML.

Testing with Values Files

For complex configurations, use values files instead of individual set directives:

# charts/my-app/tests/production_values_test.yaml
suite: production values
templates:
  - deployment.yaml
  - service.yaml

tests:
  - it: should render correctly with production values
    values:
      - ../ci/production-values.yaml
    asserts:
      - equal:
          path: spec.replicas
          value: 3
      - equal:
          path: spec.template.spec.containers[0].resources.limits.memory
          value: "1Gi"

Keep a ci/ directory with value files for each environment you support. This ensures your chart works for real-world configurations, not just defaults.

Testing Helper Templates

_helpers.tpl functions are often untested but frequently wrong. Test them by asserting on objects that use them:

suite: helpers
templates:
  - deployment.yaml

tests:
  - it: should generate correct chart labels
    release:
      name: my-release
      namespace: production
    chart:
      version: "1.2.3"
    asserts:
      - equal:
          path: metadata.labels["helm.sh/chart"]
          value: my-app-1.2.3
      - equal:
          path: metadata.labels["app.kubernetes.io/instance"]
          value: my-release
      - equal:
          path: metadata.labels["app.kubernetes.io/version"]
          value: "1.2.3"

chart-testing (ct): Lint and Install Tests

helm-unittest tests rendered YAML. chart-testing does two more things:

  1. Lint: validates Chart.yaml, checks for required fields, and runs helm lint
  2. Install: deploys your chart to a real cluster and checks pods become healthy

Create a ct.yaml configuration at the repo root:

# ct.yaml
remote: origin
target-branch: main
chart-dirs:
  - charts
chart-repos:
  - bitnami=https://charts.bitnami.com/bitnami
helm-extra-args: "--timeout 300s"
validate-maintainers: false
check-version-increment: true

With check-version-increment: true, ct will fail if you change a chart without bumping its version—good discipline for shared charts.

Run lint locally:

ct lint --config ct.yaml

Run install tests (requires a cluster):

ct install --config ct.yaml --all

The --all flag tests all charts. Without it, ct detects which charts changed since the target branch and only tests those.

GitHub Actions: Full CI Pipeline

# .github/workflows/helm-tests.yml
name: Helm Chart Tests

on:
  pull_request:
    paths:
      - 'charts/**'
  push:
    branches: [main]

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

      - name: Install Helm
        uses: azure/setup-helm@v3
        with:
          version: "3.14.0"

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

      - name: Run unit tests
        run: |
          for chart in charts/*/; do
            if [ -d "${chart}tests" ]; then
              echo "Testing ${chart}"
              helm unittest "${chart}"
            fi
          done

  lint:
    name: ct lint
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # ct needs full history to detect changes

      - name: Install Helm
        uses: azure/setup-helm@v3
        with:
          version: "3.14.0"

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

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

  install-tests:
    name: ct install
    runs-on: ubuntu-latest
    needs: [unit-tests, lint]
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Install Helm
        uses: azure/setup-helm@v3
        with:
          version: "3.14.0"

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

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

      - name: Run chart install tests
        run: ct install --config ct.yaml

The kind cluster is ephemeral—created fresh for each CI run, destroyed after. No shared cluster state, no flaky tests from leftover resources.

Structuring CI Values for Install Tests

Chart-testing looks for values files in charts/<chart-name>/ci/ automatically. Create one file per scenario:

charts/my-app/ci/
  default-values.yaml       # minimal config, tests defaults
  full-values.yaml          # all features enabled
  minimal-values.yaml       # only required values set

ct will run a separate install test for each values file in ci/. This gives you multi-scenario install testing without writing any test code.

Example full-values.yaml:

replicaCount: 2

image:
  repository: nginx
  tag: "1.25"

ingress:
  enabled: true
  hostname: test.example.com

autoscaling:
  enabled: true
  minReplicas: 2
  maxReplicas: 5

resources:
  limits:
    cpu: "500m"
    memory: "256Mi"
  requests:
    cpu: "250m"
    memory: "128Mi"

Testing Chart Dependencies

If your chart has dependencies (subcharts), test that they're configured correctly:

suite: redis dependency
templates:
  - charts/redis/templates/deployment.yaml

tests:
  - it: should configure redis with correct password
    set:
      redis.auth.password: supersecret
    asserts:
      - contains:
          path: spec.template.spec.containers[0].env
          content:
            name: REDIS_PASSWORD
            value: supersecret

You need to run helm dependency update before running unittest with subchart tests.

Schema Validation

Add a values.schema.json to your chart to validate inputs at helm install time:

{
  "$schema": "https://json-schema.org/draft-07/schema#",
  "properties": {
    "replicaCount": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "image": {
      "type": "object",
      "required": ["repository", "tag"],
      "properties": {
        "repository": { "type": "string" },
        "tag": { "type": "string" }
      }
    },
    "ingress": {
      "type": "object",
      "properties": {
        "enabled": { "type": "boolean" },
        "hostname": { "type": "string" }
      },
      "if": {
        "properties": { "enabled": { "const": true } }
      },
      "then": {
        "required": ["hostname"]
      }
    }
  },
  "required": ["image"]
}

This schema is enforced by Helm itself—before your templates even render. Combined with failedTemplate assertions in helm-unittest, you get defense at two layers.

Measuring Coverage

There's no built-in coverage tool for Helm charts, but you can audit it manually: for each {{ if }} block in your templates, verify there's a test case with that condition true and one with it false. Build this into your PR review checklist.

Conclusion

Helm chart testing is low-investment for high return. helm-unittest tests run in under a second, catch template regressions immediately, and require no cluster. chart-testing's install tests add the confidence that your chart actually deploys healthy pods. Run both in CI on every PR that touches a chart, and you'll stop shipping broken Kubernetes configurations.

Read more

Start now free