test: Add Helm chart E2E testing via K3s + testcontainers

[everettbu]

Mirror of n8n-io/n8n#26155
Original author: shortstacked

---

Summary

• Deploys n8n via its Helm chart into a real K3s cluster (inside Docker via ``@testcontainers/k3s) and runs Playwright E2E tests against it
• Uses NodePort routing instead of kubectl port-forward for reliable traffic delivery under sustained test load
• Supports standalone (SQLite) and queue (PostgreSQL + Redis + workers) deployment modes
• Manual dispatch workflow with dropdowns for mode and chart ref

New Files

File	Purpose
packages/testing/containers/helm-stack.ts	Core module: K3s lifecycle, image preloading, Helm install, NodePort routing
packages/testing/containers/helm-start-stack.ts	CLI wrapper (pnpm stack:helm) with --mode, --image, --chart-ref flags
.github/workflows/test-e2e-helm.yml	Manual dispatch workflow with K8s diagnostics on failure
packages/testing/containers/HELM-TESTING.md	Prerequisites, architecture diagram, troubleshooting guide

Why NodePort over port-forward

kubectl port-forward silently stops routing traffic after ~6 concurrent connections. The process stays alive, no error is emitted, but HTTP requests return nothing — causing cascade test timeouts. NodePort uses kube-proxy for stateless per-connection routing, which is reliable under sustained load.

What this enables

This infrastructure validates Kubernetes-specific deployment concerns that can't be tested with testcontainers alone:

Concern	Example	Why K8s is needed
readOnlyRootFilesystem	npm cache/tmp dirs must redirect to writable volumes (#26032)	SecurityContext is a K8s-only concept
Shared PVC for community nodes	Mount a ReadWriteMany PVC at the community nodes path so install-once is available across all pods in queue mode	PVC access modes, mount propagation, and multi-pod sharing only exist in K8s
Helm chart value correctness	Verify that chart defaults actually produce a working deployment	Catches misconfigured env vars, missing secrets, bad resource limits
Queue mode pod coordination	Workers pick up jobs, webhooks route correctly, leader election works	Requires real K8s service discovery and DNS
Security contexts & RBAC	Non-root UID, dropped capabilities, read-only filesystem	Enforced by kubelet, not Docker

Future: Playwright fixture integration

The createHelmStack API is designed to plug into the existing Playwright fixture system (same pattern as chaos tests). A test file could use test.use({ capability: { helmMode: 'queue', helmOverrides: { ... } } }) to spin up a Helm stack with custom overrides per test suite — enabling infrastructure-level E2E tests alongside existing feature tests.

Test plan

• Run manual dispatch with standalone mode — verify 35/35 building-blocks tests pass
• Run manual dispatch with queue mode — verify deployment succeeds (queue mode has tighter resource constraints)
• Local: pnpm stack:helm --image n8nio/n8n:latest starts stack, Ctrl+C cleans up

🤖 Generated with Claude Code