git:20260706.4e1409c to git:20260718.ab29907

---

name: helm-chart-tester

description: "Configures helm-unittest for Helm chart unit testing - installs `helm-unittest` plugin, authors `tests/*.yaml` per template, asserts on rendered manifests (`isKind`, `isAPIVersion`, `equal`, `matchRegex`), runs via `helm unittest`. Plus chart linting (`helm lint`) and render testing (`helm template`). Use when the team ships Helm charts and needs unit-level verification of the templates."

---

# helm-chart-tester

## Overview

**helm-unittest** (Helm plugin) unit-tests the rendered chart

output - assert specific fields, conditional behaviors, value

substitutions - to catch template bugs before deploying.

## When to use

- Team ships Helm charts (in-house apps, OSS contributions).

- A chart has conditional logic (`{{ if .Values.foo }}`); tests

verify both branches.

- A chart's rendered output must satisfy specific shape contracts

(env vars, ports, labels).

## Step 1 - Install

```bash

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

helm plugin list # verify

```

## Step 2 - Author a test

```yaml

# charts/mychart/tests/deployment_test.yaml

suite: deployment template

templates:

- templates/deployment.yaml

tests:

- it: should set the right image

set:

image.repository: myapp

image.tag: v1.2.3

asserts:

- isKind:

of: Deployment

- equal:

path: spec.template.spec.containers[0].image

value: myapp:v1.2.3

- it: should add the configured env vars

set:

env:

- name: API_URL

value: https://api.example.com

- name: LOG_LEVEL

value: debug

asserts:

- contains:

path: spec.template.spec.containers[0].env

content:

name: API_URL

value: https://api.example.com

- it: should add resource limits when set

set:

resources:

limits:

memory: 512Mi

cpu: 500m

asserts:

- equal:

path: spec.template.spec.containers[0].resources.limits.memory

value: 512Mi

- it: should NOT add resource limits when unset

asserts:

- notExists:

path: spec.template.spec.containers[0].resources.limits

```

The `set:` block overrides values; `asserts:` checks the rendered

output.

## Step 3 - Common assertions

| Assertion | Use |

|-------------------|----------------------------------------------------|

| `equal` | Exact value match |

| `notEqual` | Inverse |

| `isKind` | Document is the expected Kind |

| `isAPIVersion` | Specific API version |

| `isNullOrEmpty` | Field is null / empty |

| `notNullOrEmpty` | Field has a value |

| `exists` | Field exists |

| `notExists` | Field absent |

| `contains` | Array contains an item |

| `notContains` | Inverse |

| `matchRegex` | Field matches regex |

| `notMatchRegex` | Inverse |

| `failedTemplate` | Template should fail to render (negative test) |

## Step 4 - Run

```bash

# All tests for a chart

helm unittest charts/mychart/

# Specific test file

helm unittest charts/mychart/ -f tests/deployment_test.yaml

# Update snapshots (if using snapshot assertions)

helm unittest charts/mychart/ -u

```

## Step 5 - Snapshot testing

For complex rendered manifests, snapshot the output:

```yaml

tests:

- it: should render the full deployment correctly

asserts:

- matchSnapshot: {}

```

First run captures the snapshot; subsequent runs compare. A diff

fails the test. Useful for catching unintended template changes.

sanitize the snapshots (strip volatile fields like timestamps).

## Step 6 - Chart linting

```bash

helm lint charts/mychart/

```

Catches:

- Missing required fields (`name`, `version`, `appVersion`).

- Broken template syntax.

- YAML formatting issues.

- Schema violations (if `values.schema.json` present).

Run alongside unit tests in CI.

## Step 7 - Render testing

```bash

# See the rendered output without applying

helm template myrelease charts/mychart/ -f values.test.yaml

# Compare two renders (e.g., before / after a change)

helm template myrelease charts/mychart/ -f values.test.yaml > new.yaml

git stash

helm template myrelease charts/mychart/ -f values.test.yaml > old.yaml

git stash pop

diff old.yaml new.yaml

```

Useful for review: "what does this change actually produce?"

## Step 8 - CI integration

```yaml

jobs:

helm:

runs-on: ubuntu-latest

steps:

- uses: actions/checkout@v5

- uses: azure/setup-helm@v4

with: { version: 'v3.16.4' }

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

- run: helm lint charts/mychart/

- run: helm unittest charts/mychart/

```

## Step 9 - Kubernetes admission integration

For deeper verification, render charts and run them through OPA /

Conftest:

```bash

helm template myrelease charts/mychart/ -f values.yaml | conftest test -

```

The Conftest step catches policy violations the unit tests don't

cover (e.g., "all containers must have resource limits"). See

[`policy-as-code-runner`](../policy-as-code-runner/SKILL.md).

## Anti-patterns

| Anti-pattern | Why it fails | Fix |

|-----------------------------------------------------------------------|---------------------------------------------------------------------------|-----|

| Skipping `helm lint` | Schema violations slip; install fails at deploy. | Always lint (Step 6). |

| Snapshot-only tests (no `equal` checks) | Snapshots accept any change; explicit assertions catch intent. | Mix snapshots + explicit (Step 2 + Step 5). |

| One mega-test file per chart | Test file becomes unreadable; merge conflicts. | One test file per template. |

| Hardcoded image tags in tests | Tests pass against the wrong tag if values default. | Set image tag explicitly via `set:`. |

| Skipping the negative tests (`notExists`, `failedTemplate`) | Unintended additions slip through. | Test absences too (Step 2 example). |

## Limitations

- **Unit-level only.** helm-unittest renders templates; doesn't

install. For install verification, use Helm's `helm install

--dry-run` + admission webhooks.

- **Snapshot maintenance.** Snapshots accumulate; periodic review

needed.

- **No cross-chart testing.** Per-chart only; cross-chart

interactions need integration testing.

## References

- helm-unittest at `github.com/helm-unittest/helm-unittest`.

- Helm docs at `helm.sh/docs/`.

- [`policy-as-code-runner`](../policy-as-code-runner/SKILL.md) -

policy-level testing of rendered manifests.