Chart Tests

A chart contains a number of Kubernetes resources and components that work together. As a chart author, you may want to write some tests that validate that your chart works as expected when it is installed. These tests also help the chart consumer understand what your chart is supposed to do.

A test in a helm chart lives under the templates/ directory and is a job definition that specifies a container with a given command to run. The container should exit successfully (exit 0) for a test to be considered a success. The job definition must contain the helm test hook annotation: helm.sh/hook: test.

Note that until Helm v3, the job definition needed to contain one of these helm test hook annotations: helm.sh/hook: test-success or helm.sh/hook: test-failure. helm.sh/hook: test-success is still accepted as a backwards-compatible alternative to helm.sh/hook: test.

Example tests:

  • Validate that your configuration from the values.yaml file was properly injected.
    • Make sure your username and password work correctly
    • Make sure an incorrect username and password does not work
  • Assert that your services are up and correctly load balancing
  • etc.

You can run the pre-defined tests in Helm on a release using the command helm test <RELEASE_NAME>. For a chart consumer, this is a great way to check that their release of a chart (or application) works as expected.

Example Test

Here is an example of a helm test pod definition in the bitnami wordpress chart. If you download a copy of the chart, you can look at the files locally:

  1. $ helm repo add bitnami https://charts.bitnami.com/bitnami
  2. $ helm pull bitnami/wordpress --untar
  1. wordpress/
  2.   Chart.yaml
  3.   README.md
  4.   values.yaml
  5.   charts/
  6.   templates/
  7.   templates/tests/test-mariadb-connection.yaml

In wordpress/templates/tests/test-mariadb-connection.yaml, you’ll see a test you can try:

  1. {{- if .Values.mariadb.enabled }}
  2. apiVersion: v1
  3. kind: Pod
  4. metadata:
  5.   name: "{{ .Release.Name }}-credentials-test"
  6.   annotations:
  7.     "helm.sh/hook": test
  8. spec:
  9.   containers:
  10.     - name: {{ .Release.Name }}-credentials-test
  11.       image: {{ template "wordpress.image" . }}
  12.       imagePullPolicy: {{ .Values.image.pullPolicy | quote }}
  13.       {{- if .Values.securityContext.enabled }}
  14.       securityContext:
  15.         runAsUser: {{ .Values.securityContext.runAsUser }}
  16.       {{- end }}
  17.       env:
  18.         - name: MARIADB_HOST
  19.           value: {{ template "mariadb.fullname" . }}
  20.         - name: MARIADB_PORT
  21.           value: "3306"
  22.         - name: WORDPRESS_DATABASE_NAME
  23.           value: {{ default "" .Values.mariadb.db.name | quote }}
  24.         - name: WORDPRESS_DATABASE_USER
  25.           value: {{ default "" .Values.mariadb.db.user | quote }}
  26.         - name: WORDPRESS_DATABASE_PASSWORD
  27.           valueFrom:
  28.             secretKeyRef:
  29.               name: {{ template "mariadb.fullname" . }}
  30.               key: mariadb-password
  31.       command:
  32.         - /bin/bash
  33.         - -ec
  34.         - |
  35.                     mysql --host=$MARIADB_HOST --port=$MARIADB_PORT --user=$WORDPRESS_DATABASE_USER --password=$WORDPRESS_DATABASE_PASSWORD
  36.   restartPolicy: Never
  37. {{- end }}

Steps to Run a Test Suite on a Release

First, install the chart on your cluster to create a release. You may have to wait for all pods to become active; if you test immediately after this install, it is likely to show a transitive failure, and you will want to re-test.

  1. $ helm install quirky-walrus wordpress --namespace default
  2. $ helm test quirky-walrus
  3. Pod quirky-walrus-credentials-test pending
  4. Pod quirky-walrus-credentials-test pending
  5. Pod quirky-walrus-credentials-test pending
  6. Pod quirky-walrus-credentials-test succeeded
  7. Pod quirky-walrus-mariadb-test-dqas5 pending
  8. Pod quirky-walrus-mariadb-test-dqas5 pending
  9. Pod quirky-walrus-mariadb-test-dqas5 pending
  10. Pod quirky-walrus-mariadb-test-dqas5 pending
  11. Pod quirky-walrus-mariadb-test-dqas5 succeeded
  12. NAME: quirky-walrus
  13. LAST DEPLOYED: Mon Jun 22 17:24:31 2020
  14. NAMESPACE: default
  15. STATUS: deployed
  16. REVISION: 1
  17. TEST SUITE:     quirky-walrus-mariadb-test-dqas5
  18. Last Started:   Mon Jun 22 17:27:19 2020
  19. Last Completed: Mon Jun 22 17:27:21 2020
  20. Phase:          Succeeded
  21. TEST SUITE:     quirky-walrus-credentials-test
  22. Last Started:   Mon Jun 22 17:27:17 2020
  23. Last Completed: Mon Jun 22 17:27:19 2020
  24. Phase:          Succeeded
  25. [...]

Notes

  • You can define as many tests as you would like in a single yaml file or spread across several yaml files in the templates/ directory.
  • You are welcome to nest your test suite under a tests/ directory like <chart-name>/templates/tests/ for more isolation.
  • A test is a Helm hook, so annotations like helm.sh/hook-weight and helm.sh/hook-delete-policy may be used with test resources.