helm-unittest: YAML Unit Testing for Helm Charts

Why helm-unittest belongs in a Helm chart workflow

Helm charts contain templates, default values, conditionals, release metadata, and generated Kubernetes resources. A chart can look valid as YAML while producing the wrong Deployment name, image, selector, or resource kind after Helm renders it. helm-unittest addresses that specific gap by treating chart tests as YAML files and checking the rendered output locally.

The target user is a chart author or platform engineer who wants a fast feedback loop before packaging, publishing, or promoting a chart. The plugin creates nothing on a Kubernetes cluster, according to the README. That boundary is important. It can validate the manifests produced from a chart and a selected set of values, but the documentation does not claim that it validates a running workload, cluster admission behavior, controller reconciliation, external service connectivity, or image startup behavior.

The project is also useful when chart behavior varies by values. A test can set `image.tag` and then assert that the rendered container image becomes `nginx:latest`. Such checks are more specific than only checking whether Helm rendering succeeds. They can protect names, kinds, indexed fields, and other properties that chart users depend on.

This is a unit-testing layer for chart templates, not a replacement for integration tests. A chart may pass helm-unittest and still fail against a real API server because of admission policies, namespace rules, RBAC, quotas, or cluster-specific controllers. Those checks belong outside the scope documented by this project.

The rendering, assertion, and snapshot model

A normal suite selects chart templates, supplies values and release options, runs a local Helm render, and evaluates assertions against the resulting documents. The test file is pure YAML. By default, suites live under the chart's `tests/` directory and use the `_test.yaml` suffix, although the `-f, --file` option accepts glob patterns related to the chart directory.

Assertions use YAML paths and operators. The README's example checks `isKind` for `Deployment`, applies `matchRegex` to `metadata.name`, and uses `equal` against `spec.template.spec.containers[0].image`. The repository documentation also links wildcard template selection, values and release options, JSONPath support, and document selectors. Those mechanisms indicate that the plugin works on rendered documents rather than merely scanning source template text.

Snapshot testing adds a comparison-oriented mode. The README lists snapshot testing as a feature and points to `DOCUMENT.md`, but it does not show the snapshot file format or update command in the installation and getting-started sections. The exact workflow for accepting or regenerating snapshots should be checked in `DOCUMENT.md` before a team depends on it.

Templated test suites introduce another rendering layer. With `--chart-tests-path`, the test definitions can themselves be rendered as a Helm chart. The documented directory example contains a `tests-chart` with `Chart.yaml`, `values.yaml`, and `templates/per_env_snapshots.yaml`. After rendering, the resulting suite files are run automatically, without applying a filename suffix or glob to the generated output. This supports parameterized cases, but it adds chart-rendering complexity to what otherwise looks like a simple YAML test.

Installing helm-unittest and running the first chart test

For Helm 3, the README gives a Git-based plugin installation command. It installs the latest version when no version is defined, and an explicit version can be supplied in the release archive URL.

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

For Helm 4, the documented Git command disables webhook GPG verification because that verification path is not supported for this installation method.

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

The OCI installation path is also documented. Its package contains binaries for all operating systems and architectures, so its download is larger. The README says OCI download is supported for plugin version 1.1.0 and later.

helm plugin install oci://ghcr.io/helm-unittest/helm-unittest/unittest:latest

To create a first test, add `tests` to the chart's `.helmignore` and place a suite at `$YOUR_CHART/tests/deployment_test.yaml`. This example sets an image tag and checks the rendered Deployment.

suite: test deployment
templates:
  - deployment.yaml
tests:
  - it: should work
    set:
      image.tag: latest
    asserts:
      - isKind:
          of: Deployment
      - matchRegex:
          path: metadata.name
          pattern: -my-chart$
      - equal:
          path: spec.template.spec.containers[0].image
          value: nginx:latest

Run the suite against the chart directory:

helm unittest $YOUR_CHART

The command should evaluate the suite against locally rendered chart templates. The test creates no cluster resources. The README also documents custom suite locations through repeated `-f` and `--file` glob options, such as `my-tests/*.yaml` and `more-tests/**/*.yaml`.

Docker and CI use of the Helm plugin

The project provides a Docker image containing a Helm client and the helm-unittest plugin. The README says the image can run the latest Helm and plugin versions, or a specific pair identified in the image tag. A local directory is mounted at `/apps`, which makes the chart path available to the container.

For the latest image and command-line help:

docker run -ti --rm -v $(pwd):/apps helmunittest/helm-unittest

For a chart in the mounted directory, the README gives this command using a specific image tag:

docker run -ti --rm -v $(pwd):/apps helmunittest/helm-unittest:3.11.1-0.3.0 .

The image also supports Junit output. The documented option is `-o test-output.xml -t junit`, and the README says the resulting `test-output.xml` is available in the mounted local folder.

docker run -ti --rm -v $(pwd):/apps helmunittest/helm-unittest:3.11.1-0.3.0 -o test-output.xml -t junit .

This route is more reproducible than relying on whatever plugin is installed on a workstation, but the image tag still pins a specific relationship between Helm and plugin versions. The repository Dockerfile requires `HELM_VERSION` and `PLUGIN_VERSION` build arguments. For custom images, those values must be supplied during the build, and the README does not provide a single universal tag for every supported version combination.

What helm-unittest does not verify

The clearest limitation is scope. helm-unittest renders and inspects chart output, but the README does not document checks against a running cluster or external services. A passing test therefore says less about deployment success than its name may suggest.

The tool also depends on Helm's chart and template model. A suite can only exercise templates and values that Helm can render in the selected context. Tests involving environment-specific Kubernetes behavior may require separate validation. The repository includes `with-k8s-fake-client` and `with-post-renderer` in its Makefile test names, indicating coverage for those areas in the project's own development, but the README does not explain their full user-facing configuration.

There are installation trade-offs. Git installation is the documented path for Helm 3, while Helm 4 requires `--verify=false` for the Git method. OCI downloads are larger because all OS and architecture binaries are included. HTTP release archives support a fixed version that must be entered twice in the URL and do not auto-update the plugin. Users who need automatic plugin updates should account for those differences before standardizing installation in CI.

Snapshot testing also deserves process discipline. The README identifies snapshot testing as a feature, but it does not document how snapshots are reviewed or updated in the shown sections. A changed rendered manifest can be either a regression or an intended chart change. Teams should treat snapshot diffs as reviewable changes rather than accepting them automatically.

How Helm-native rendering compares with direct chart inspection

One alternative is a separate rendering-and-inspection workflow. Such a workflow can be useful for one-off checks, but selection, parsing, assertions, reporting, and parameterized-case handling must be built outside a chart test framework.

helm-unittest keeps those concerns in a chart-local format. The suite can select templates, define values and release options, use YAML assertions, and run repeatedly through one plugin command. Its snapshot and templated-suite features are designed for repeated chart maintenance rather than a single render inspection. The difference is not rendering capability by itself. Both approaches can expose rendered manifests; helm-unittest adds a declarative assertion layer and a Helm plugin workflow.

The trade-off is dependency on the plugin and its YAML test API. A plain render script may be easier to fit into an existing validation environment, especially when the required checks are simple. helm-unittest becomes more appropriate when several charts need consistent suites, CI needs a common command, and maintainers want assertions stored alongside the chart.

Maintenance, licensing, and upgrade implications

The repository is not archived, and its last push was on 2026-10-14. Recent releases include v1.2.1 on 2026-10-03, v1.2.0 on 2026-10-01, and v1.1.2 on 2026-07-24. Those dates describe repository activity and releases, not a guarantee that every future version will be compatible with every chart or Helm release.

The project is licensed under the MIT License. Review the repository's `LICENSE` file for the applicable terms and notices. The repository also includes `CONTRIBUTING.md`, `SECURITY.md`, `CHANGELOG.md`, and a public key. The public key documentation describes GPG import and conversion to Helm's legacy keyring format for release verification. Verification details differ by installation path, so an upgrade process should document whether the team uses Git, OCI, or fixed release archives.

The `go.mod` file identifies Go 1.26.0 as the module requirement and includes Helm 3 and Helm 4 dependencies. Contributors and maintainers should expect upgrade work to involve both plugin releases and Helm compatibility. The README explicitly differentiates Helm 3 and Helm 4 installation, so changing the plugin without checking the host Helm version can break an otherwise working setup.

Editorial conclusion

Adopt helm-unittest when a chart needs repeatable assertions against rendered templates and local or CI validation matters. Do not choose it for live-cluster behavior, admission checks, or chart rendering outside Helm's plugin model. Verify first that your Helm major version, installation source, test paths, and output format match the project documentation and your CI environment.

Frequently asked questions

Official sources

1. helm-unittest/helm-unittest on GitHub
2. Issues
3. License: MIT
4. README
5. Releases