Skip to content

Helm Unit Testing📜

Overview📜

Helm unit tests provide a way to test Helm chart templates without deploying to a Kubernetes cluster. Big Bang uses the helm-unittest plugin to validate that Helm templates render correctly under various conditions and configurations.

Unlike Helm Chart Tests (which deploy pods to a live cluster and test runtime behavior), helm unit tests validate template rendering logic, schema validation, and expected output structure before any actual deployment occurs.

Prerequisites📜

Install Helm Unittest Plugin📜

The helm unittest plugin must be installed to run tests:

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

Note on Test Directory Location: The Helm unittest plugin conventionally looks for tests in chart/tests/, but Big Bang places unit tests in chart/unittests/ to avoid confusion with existing end-to-end (e2e) Helm Chart Tests that run in live Kubernetes clusters. This separation keeps unit tests (which validate template rendering) distinct from runtime integration tests.

Running Tests📜

Run All Tests📜

To run all unit tests in the Big Bang chart:

helm unittest chart -f "unittests/**/*_test.yaml"

Run Specific Test Suites📜

You can run specific test files or directories:

# Run schema validation tests only
helm unittest chart -f "unittests/schema/*_test.yaml"

# Run a specific test file
helm unittest chart -f "unittests/schema/umbrella_test.yaml"

# Run template helper tests
helm unittest chart -f "unittests/template:*_test.yaml"

Debugging Tests📜

To enable verbose output and view the rendered YAML templates during test execution, use the -d flag:

helm unittest chart -f "unittests/**/*_test.yaml" -d

When the -d (or --debugPlugin) flag is enabled, helm unittest creates a .debug/ directory containing the rendered YAML output for each template processed during the tests. This is useful for:

  • Inspecting the actual rendered templates to understand test failures
  • Verifying that your Helm values produce the expected template output
  • Debugging complex template logic and conditionals

Test Organization📜

Big Bang organizes helm unit tests into several categories:

Schema Validation Tests📜

Located in chart/unittests/schema/, these tests validate that the Helm chart’s values conform to the expected schema.

Example: Valid Configuration📜

suite: Schema Validation - Git Configuration
tests:
  - it: should pass validation with git credentials
    set:
      git:
        credentials:
          username: "myuser"
          password: "mypassword"
    asserts:
      - notFailedTemplate: {}

Example: Invalid Configuration📜

suite: Schema Validation - Git Configuration
tests:
  - it: should fail validation with username but no password
    set:
      git:
        credentials:
          username: "myuser"
          password: null
    asserts:
      - failedTemplate:
          errorPattern: ".*password.*"

Template Helper Tests📜

Located in chart/unittests/, these tests validate custom Helm template functions defined in _helpers.tpl.

Template helper tests ensure that custom template functions produce correct output across various input scenarios. For detailed information on Big Bang’s template self-testing framework and how to write tests for custom template helpers, see the Template Self-testing Guide.

Package-Specific Tests📜

Located in chart/unittests/packages/, these tests validate that package-specific templates render correctly for individual packages.

Additional Resources📜