Testing Your Charts

In Chapters 1-5, you built a production-ready Helm chart: templates that render correctly, values that adapt to environments, and helper functions that eliminate boilerplate. But before deploying to production, you need confidence that the chart works as intended. This means catching errors early through validation, verifying template rendering produces correct manifests, and testing that deployed resources actually function.

This chapter teaches the testing safety net that stands between a working chart in development and a broken deployment in production. You'll use helm lint to validate chart structure, helm template to inspect rendered manifests, test pods to verify connectivity, and helm test to run validation against live deployments. Together, these tools catch the mistakes that would otherwise cost hours to debug in production.

---

What You'll Learn

This chapter covers Helm testing approaches from static validation to live deployment verification:

Prerequisites:

• Completed Chapters 1-5 (templates, values, helpers, conditionals, dependencies)
• Access to a Kubernetes cluster (minikube, kind, or cloud provider)
• Helm 3.x installed locally
• Basic understanding of exit codes and shell scripting

Time Estimate: 45 minutes

---

Concept 1: Validating Charts with helm lint

helm lint checks your chart for structural errors, missing required fields, and configuration problems. It runs before installation, catching issues early.

Understanding helm lint Output

Create a chart with an intentional error to see how lint catches it:

Output:

What helm lint Validates

Fixing Errors: Add Required Description

Output:

---

Concept 2: Rendering Templates to Inspect Output

helm template renders your templates locally without connecting to a Kubernetes cluster. This shows exactly what manifests will be created.

Basic Template Rendering

Output:

Rendering with Environment-Specific Values

Output:

Why This Matters

Before deploying, you can verify:

• Variable substitution works correctly
• Conditionals produce expected output
• Resource definitions are valid Kubernetes YAML

---

Concept 3: Debugging Template Rendering with --debug

When templates produce unexpected output, helm template --debug shows each rendering step with line numbers, making errors easy to locate.

Broken Conditional Example

Create a template with a conditional that references a nonexistent value:

Without the flag, you see nothing if the value is missing. With --debug:

Output:

Using --debug for Line-by-Line Inspection

For more detailed inspection:

Output shows template variables, function evaluations, and which conditionals evaluated to true/false.

---

Checkpoint

Before moving to runtime testing, verify your understanding:

✅ You can run helm lint on any chart directory and interpret the output ✅ You understand what helm template produces and how it differs from helm install ✅ You can use --debug to troubleshoot template rendering issues ✅ You've tested rendering a chart with multiple values files

Self-Check: Create a chart with a broken conditional ({{- if .Values.nonexistent }}). Use helm template --debug to confirm the conditional evaluates to false and produces no output.

---

Concept 4: Test Pods and the helm.sh/hook: test Annotation

Test pods are Kubernetes Pods that verify a deployed release works correctly. They're executed when you run helm test and removed afterward.

Creating a Test Pod

Test pods use the helm.sh/hook: test annotation. Create a file templates/test-pod.yaml:

Output (when running helm test):

Understanding Test Pod Annotations

---

Concept 5: Test Exit Codes—What Passes and What Fails

Test pods use exit codes to signal success (0) or failure (non-zero). Helm interprets these to report test results.

Exit Code Semantics

Output:

Exit Code Semantics

Output:

---

Concept 6: Running Tests with helm test

helm test executes all test pods in a release and reports results. Run it after deploying with helm install or helm upgrade.

Full Testing Workflow

Output:

Output:

Testing with Timeout

If tests take longer than the default 300 seconds:

Output:

---

Concept 7: Unit Testing with helm-unittest Framework

For testing template logic (conditionals, loops, variable substitution), use helm-unittest. This tests chart templates without deploying to Kubernetes.

Installing helm-unittest

Output:

Writing a Unit Test

Create tests/deployment_test.yaml:

Running Unit Tests

Output:

---

Concept 8: Integration Testing—Testing Deployed Resources

Integration tests verify that deployed resources (Deployments, Services, ConfigMaps) behave correctly in a live Kubernetes cluster.

Integration Test Pattern

Create templates/integration-test.yaml:

Output (when helm test runs):

---

Decision Framework: Unit vs Integration Testing

Decision rule: Start with unit tests for template logic. Add integration tests only if deployment behavior needs verification (service connectivity, data persistence, etc.).

---

Checkpoint

Before the exercise, confirm you can:

✅ Write a test pod with helm.sh/hook: test annotation ✅ Use exit codes to signal test success (0) or failure (non-zero) ✅ Run helm test against a deployed release ✅ Distinguish when to use unit tests vs integration tests ✅ Install and run helm-unittest for template logic testing

Self-Check: Write a test pod that verifies a ConfigMap exists with kubectl get configmap <name>. Deploy the chart, run helm test, and confirm the test passes.

---

Common Mistakes

Mistake 1: Running helm test Before Deployment

Problem: Running helm test my-release when the release doesn't exist.

Error:

Fix: Always deploy first with helm install or helm upgrade, then run helm test.

Mistake 2: Forgetting the Test Hook Annotation

Problem: Creating a test pod without helm.sh/hook: test.

Result: Pod is created during deployment instead of during testing phase. It runs immediately and may fail before dependencies are ready.

Fix:

Mistake 3: Test Pod Doesn't Clean Up

Problem: Test pods remain after testing completes, cluttering the namespace.

Fix: Add deletion policy:

Mistake 4: Assuming helm lint Catches All Errors

Problem: helm lint passes but deployment fails because of Kubernetes-specific validation (resource limits, invalid service types, etc.).

Reality: helm lint validates chart structure and template syntax, NOT Kubernetes resource semantics.

Fix: Combine helm lint with helm template --validate (requires cluster connection) or deploy to a test namespace.

Mistake 5: Testing Without Timeouts

Problem: Test pods hang indefinitely waiting for external dependencies (databases, APIs).

Fix: Always specify a timeout:

Mistake 6: Unit Tests That Depend on Cluster State

Problem: Writing helm-unittest tests that expect certain cluster resources to exist.

Reality: Unit tests run locally without a cluster—they test template logic only.

Fix: Use integration test pods for cluster-dependent validation.

---

Try With AI

Setup

You'll test a sample Helm chart that deploys a simple agent API. Create a working directory:

Step 1: Create a Chart and Run helm lint

Ask AI to create a Helm chart with intentional issues:

"Create a Helm chart for an agent service with:

• Chart.yaml with a missing description field (to trigger lint error)
• A Deployment template
• A Service template
• A values.yaml with image, replicas, and service type"

Apply the chart to your directory and run helm lint to verify it catches the error. Note how the error message guides you to fix it.

Step 2: Inspect Template Rendering

Ask AI to render the chart with different values files:

"Now create a values-prod.yaml with different replica count (5 instead of 3) and nodePort service type. Show me what helm template outputs with and without this values file."

Compare the two outputs. What changed? Why would this difference matter in production?

Step 3: Create a Test Pod

Ask AI to create a test pod that:

• Uses curl to verify the Service is accessible
• Returns exit code 0 if the service responds, exit code 1 if it doesn't
• Includes the helm.sh/hook: test annotation

Deploy the chart with helm install and run helm test to verify your test pod works.

Step 4: Write a Unit Test

Ask AI to create a helm-unittest test file that:

• Verifies the Deployment has the correct number of replicas from values
• Verifies the image tag is correctly substituted
• Tests conditional logic (e.g., "if serviceEnabled is true, Service should exist")

Run helm unittest to verify your tests pass.

Step 5: Reflection

Compare what each testing approach revealed:

• What did helm lint catch that you might have missed manually?
• What did helm template show that helped you understand the manifest?
• What did unit testing verify about template logic?
• What would integration testing verify that unit tests cannot?

---

Reflect on Your Skill

You built a helm-chart skill in Chapter 0. Test and improve it based on what you learned.

Test Your Skill

Improve Your Skill

If you found gaps: