Skip to content
Tutorials Center
My learning

Topics

Lesson 30 of 38 ยท Testing and Security

Testing Charts: helm test, unittest and chart-testing

Test Helm charts at three levels: template unit tests with helm-unittest, in-cluster helm test hooks and chart-testing in CI, with a runnable unit-test stand-in.

A chart is code that generates configuration, and generated configuration breaks production when it is wrong. The cheapest bugs to catch are in the templates, long before any cluster is involved. Helm's ecosystem offers three testing levels, and a mature chart uses all of them.

flowchart LR
    A["Template unit tests<br/>(helm-unittest)"] --> B["Lint + schema<br/>(helm lint, kubeconform)"]
    B --> C["Install in a test cluster<br/>(chart-testing, kind)"]
    C --> D["helm test<br/>(test hooks)"]

Faster and cheaper on the left, more realistic on the right.

Level 1: template unit tests

The helm-unittest plugin renders templates with given values and asserts on the output. Tests are YAML files in tests/:

Terminal
helm plugin install https://github.com/helm-unittest/helm-unittest
helm unittest ./webapp
YAML
# tests/deployment_test.yaml
suite: deployment
templates:
  - templates/deployment.yaml
tests:
  - it: uses two replicas by default
    asserts:
      - equal:
          path: spec.replicas
          value: 2

  - it: honors replicaCount
    set:
      replicaCount: 5
    asserts:
      - equal:
          path: spec.replicas
          value: 5

  - it: pins the image tag
    set:
      image.repository: registry.example.com/shop
      image.tag: "1.8.2"
    asserts:
      - equal:
          path: spec.template.spec.containers[0].image
          value: registry.example.com/shop:1.8.2

  - it: is not rendered when disabled
    set:
      worker.enabled: false
    template: templates/worker.yaml
    asserts:
      - hasDocuments:
          count: 0

Useful assertions: equal, notEqual, matchRegex, contains (for lists), isKind, isNotNull, hasDocuments, failedTemplate (the template must fail with a message, handy for required and fail). Because tests only render, they run in milliseconds and need no cluster.

What to test: every conditional (if, condition:), every default that matters to operators (replicas, resources, security context), generated names, and each required or fail guard.

A stand-in test runner

The stand-in below mirrors the structure of helm-unittest: render a function that produces a manifest from values, then run assertions. The "chart" is a Python function standing in for a template.

Python Stand-in: unit-testing a chart's output

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Level 2: helm test in the cluster

Unit tests prove the YAML is what you expect; they cannot prove the application works once deployed. helm test runs Pods that you ship inside the chart, marked with the test hook:

YAML
# templates/tests/test-connection.yaml
apiVersion: v1
kind: Pod
metadata:
  name: "{{ include "webapp.fullname" . }}-test"
  annotations:
    "helm.sh/hook": test
    "helm.sh/hook-delete-policy": before-hook-creation,hook-succeeded
spec:
  restartPolicy: Never
  containers:
    - name: curl
      image: curlimages/curl:8.10.1
      command: ["curl", "--fail", "--silent", "http://{{ include "webapp.fullname" . }}:{{ .Values.service.port }}/healthz"]
Terminal
helm install shop ./webapp --wait
helm test shop --logs

A test passes when its Pod exits with code 0. Keep these tests small: a connectivity probe, a login, a read from the database. They are smoke tests, not a replacement for your application's own test suite. Remember the lifecycle from hooks: test hooks never run on install or upgrade, only on helm test.

Level 3: chart-testing (ct) in CI

chart-testing automates the whole pipeline for repositories with many charts:

Terminal
ct lint --target-branch main --check-version-increment
ct install --target-branch main
  • ct lint runs helm lint, YAML lint and a version increment check: a changed chart must bump its version.
  • ct install creates a disposable cluster namespace (usually in a kind cluster), installs each changed chart with every file in ci/*-values.yaml, runs helm test, then cleans up.

The ci/ folder inside the chart holds extra values files, one per scenario:

TEXT
webapp/
  ci/
    default-values.yaml
    ingress-values.yaml
    autoscaling-values.yaml

so every combination you support is installed in CI.

Python Stand-in: which charts must ct test?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Which level for which bug

Bug Caught by
Wrong default, missing conditional branch unittest
Typo in a Kubernetes field kubeconform, --dry-run=server
Pod crashes because of a bad probe path ct install, helm test
Forgot to bump the chart version ct lint
Breaking upgrade from the previous release install the old version, then upgrade in CI

The last row is worth the effort: install the previous published version, upgrade to the new one, run helm test. Many chart bugs only appear on upgrade, for example an immutable field such as a Deployment selector.

Never put tests that need credentials or public internet access in helm test for a shared chart. Consumers run them in their own clusters.

Check your understanding

Quick check ยท 3 questions

of 3 answered You scored / 3 ยท perfect!

  1. 1. Which test level needs no cluster?

    Template unit tests only render manifests and assert on them.
  2. 2. When does a Pod annotated helm.sh/hook: test run?

    Test hooks are executed only by the helm test command.
  3. 3. What does ct lint --check-version-increment enforce?

    It prevents publishing different content under an unchanged version.

Summary

  • Test in layers: unit tests for templates, lint and schema checks, install in a test cluster, helm test smoke tests.
  • helm-unittest asserts on rendered output; ct automates lint and install for changed charts.
  • Test upgrades from the previous published version, not only fresh installs.

Next: Validating Values with a JSON Schema