diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
new file mode 100644
index 0000000..def4fb3
--- /dev/null
+++ b/.github/workflows/test.yml
@@ -0,0 +1,66 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Shellcheck
+        # uses the shellcheck version pinned in the Makefile, not the runner's
+        run: make lint
+
+  tests:
+    name: Tests (${{ matrix.name }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          # Versions pinned in docker/Dockerfile (what the image ships).
+          - name: image versions
+            id: image
+            make_args: ""
+          # Oldest helmfile that supports Helm 4.
+          - name: minimum helm 4
+            id: helm4-min
+            make_args: HELM_VERSION=v4.0.0 HELMFILE_VERSION=1.2.0
+          # Helm 3 is still usable via HELM_BINARY until its EOL (2026-11-11).
+          - name: helm 3
+            id: helm3
+            make_args: HELM_VERSION=v3.19.4
+          - name: helm 3, minimum helmfile
+            id: helm3-helmfile-min
+            make_args: HELM_VERSION=v3.19.4 HELMFILE_VERSION=1.0.0
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Cache tools
+        uses: actions/cache@v5
+        with:
+          path: .tools
+          key: tools-${{ runner.os }}-${{ matrix.id }}-${{ hashFiles('docker/Dockerfile', 'Makefile') }}
+
+      - name: Show tool versions under test
+        run: make versions ${{ matrix.make_args }}
+
+      - name: Run tests
+        run: make test ${{ matrix.make_args }}
+
+  docker:
+    name: Docker image
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Build image and run smoke test
+        run: make test-docker
\ No newline at end of file
diff --git a/.gitignore b/.gitignore
index 485dee6..bbe1cef 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1 +1,2 @@
 .idea
+.tools/
\ No newline at end of file
diff --git a/CHANGELOG.md b/CHANGELOG.md
index b5eb4ef..998f1b8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,41 @@ The format is based on Keep a Changelog (https://keepachangelog.com/en/1.1.0/)
 and this project adheres to Semantic Versioning (https://semver.org/).
 ---
 
+## [1.3.2]
+### Removed
+- Dead code: `if [[ true ]]` wrappers, duplicate `PATH` expansion, unused `print_env_vars`, unused `/tmp/__<script>__/bin` directory, unreachable block after `exit 0` in `parameters`, commented-out `find` blocks.
+- Remaining Helm 2 code: `helm init --client-only`, Helm 2 `--kube-version` handling and comments.
+- `HELMFILE_HELM3` export (no-op since helmfile v1).
+
+### Changed
+- Helm version is detected with `helm version --template '{{.Version}}'` instead of parsing `--short` output.
+- `init` and `generate` fail with a clear error for Helm < 3, helmfile < 1 or unparsable versions.
+- `discover` and `parameters` no longer run `helm`/`helmfile`.
+- Minimum versions: helm >= 3.6, helmfile >= 1 (>= 1.2 with Helm 4).
+- Script runs with `set -Eeuo pipefail` and reports the failing phase and line on errors.
+- `discover` writes "no match" and "forced response: disabled" messages to stderr; stdout is only used for a match.
+- Options in `HELMFILE_GLOBAL_OPTIONS` / `HELMFILE_TEMPLATE_OPTIONS` are split into words without glob expansion; multi-line values are supported.
+- `ARGOCD_ENV_*` / `PARAM_*` with names that are not valid shell variables are skipped with a warning instead of failing.
+- Missing `helm` / `helmfile` binaries fail with a clear message.
+- `KUBE_VERSION` is passed with helmfile's `--kube-version` flag; `KUBE_API_VERSIONS` as one comma-separated `--api-versions`. `--args` is only passed when needed.
+
+### Deprecated
+- `HELM_HOME`: use `PLUGIN_APP_HOME`. `HELM_HOME` is still accepted with a warning and is exported with the same value.
+
+### Fixed
+- `truthy_test` evaluated values as arithmetic expressions, which could run command substitutions from parameter values; it now compares strings only (`true`, `1`, `yes`, any case).
+- Non-numeric `HELMFILE_REPO_CACHE_TIMEOUT` no longer causes errors; it disables the cache.
+- Helm 4: `KUBE_VERSION` and `KUBE_API_VERSIONS` were ignored, so charts rendered with Helm's default capabilities instead of the destination cluster's.
+- `KUBE_VERSION` with vendor suffixes was corrupted (`1.29.0+k3s1` became `1.29.031`); it is now normalized, invalid values are ignored with a warning.
+- `HELMFILE_HELMFILE_STRATEGY=INCLUDE` aborted `init` silently when any helmfile source existed (`((count++))` under `set -e`).
+
+### Added
+- `PLUGIN_APP_HOME` environment variable.
+- bats test suite (`test/`) covering the `discover`, `parameters`, `init` and `generate` phases, environment handling and Kubernetes capabilities.
+- Docker image smoke test (`test/docker-smoke.sh`).
+- `Makefile` with `tools`, `lint`, `test` and `test-docker` targets.
+- GitHub Actions workflow `Test` running shellcheck, bats and the Docker smoke test on pushes to `main` and pull requests.
+
 ## [1.3.1] - 2026-05-27
 ### Fixed 
  - Fixed plugin installation and compatibility issues for Helm v4, ensuring proper support for CLI plugins including helm-secrets as described in the updated installation guide: https://github.com/jkroepke/helm-secrets/wiki/Installation
diff --git a/Makefile b/Makefile
new file mode 100644
index 0000000..d215fe8
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,93 @@
+# Local developer entrypoints. CI calls the same targets.
+
+SHELL := /bin/bash
+
+TOOLS_DIR   := $(CURDIR)/.tools
+BATS_DIR    := $(TOOLS_DIR)/bats
+DOCKERFILE  := docker/Dockerfile
+IMAGE       ?= argocd-helmfile-plugin:test
+
+# Tool versions under test are taken from the Dockerfile so tests always
+# run against what the image ships. Override on the command line if needed.
+HELM_VERSION     ?= $(shell sed -n 's/^ARG HELM_VERSION="\(.*\)"/\1/p' $(DOCKERFILE))
+HELMFILE_VERSION ?= $(shell sed -n 's/^ARG HELMFILE_VERSION="\(.*\)"/\1/p' $(DOCKERFILE))
+
+SHELLCHECK_VERSION   := v0.11.0
+BATS_CORE_VERSION    := v1.14.0
+BATS_SUPPORT_VERSION := v0.3.0
+BATS_ASSERT_VERSION  := v2.2.4
+
+GO_ARCH := $(shell uname -m | sed -e 's/x86_64/amd64/' -e 's/aarch64/arm64/')
+
+# Each version lives in its own directory so switching versions never mixes binaries.
+HELM_DIR     := $(TOOLS_DIR)/helm/$(HELM_VERSION)
+HELMFILE_DIR := $(TOOLS_DIR)/helmfile/$(HELMFILE_VERSION)
+SHELLCHECK_DIR := $(TOOLS_DIR)/shellcheck/$(SHELLCHECK_VERSION)
+SHELLCHECK     := $(SHELLCHECK_DIR)/shellcheck
+
+export PATH := $(HELM_DIR):$(HELMFILE_DIR):$(PATH)
+
+.PHONY: help tools lint test test-docker clean versions
+
+help:
+	@echo "make tools        - download helm, helmfile and bats into $(TOOLS_DIR)"
+	@echo "make lint         - run shellcheck (pinned $(SHELLCHECK_VERSION), downloaded if needed)"
+	@echo "make test         - run bats tests (downloads tools if needed)"
+	@echo "make test-docker  - build the image and run a smoke test inside it"
+	@echo "make clean        - remove $(TOOLS_DIR)"
+
+versions:
+	@echo "helm:     $(HELM_VERSION)"
+	@echo "helmfile: $(HELMFILE_VERSION)"
+
+$(HELM_DIR)/helm:
+	@mkdir -p $(HELM_DIR)
+	wget -qO- "https://get.helm.sh/helm-$(HELM_VERSION)-linux-$(GO_ARCH).tar.gz" \
+	  | tar zx --strip-components=1 -C $(HELM_DIR) linux-$(GO_ARCH)/helm
+
+$(HELMFILE_DIR)/helmfile:
+	@mkdir -p $(HELMFILE_DIR)
+	wget -qO- "https://github.com/helmfile/helmfile/releases/download/v$(HELMFILE_VERSION)/helmfile_$(HELMFILE_VERSION)_linux_$(GO_ARCH).tar.gz" \
+	  | tar zx -C $(HELMFILE_DIR) helmfile
+
+# shellcheck is pinned: newer versions know more about bats and report different warnings
+$(SHELLCHECK):
+	@mkdir -p $(SHELLCHECK_DIR)
+	wget -qO- "https://github.com/koalaman/shellcheck/releases/download/$(SHELLCHECK_VERSION)/shellcheck-$(SHELLCHECK_VERSION).linux.$(shell uname -m).tar.xz" \
+	  | tar xJ --strip-components=1 -C $(SHELLCHECK_DIR) shellcheck-$(SHELLCHECK_VERSION)/shellcheck
+
+$(BATS_DIR)/.installed:
+	@mkdir -p $(BATS_DIR)
+	git clone -q --depth 1 --branch $(BATS_CORE_VERSION)    https://github.com/bats-core/bats-core    $(BATS_DIR)/bats-core
+	git clone -q --depth 1 --branch $(BATS_SUPPORT_VERSION) https://github.com/bats-core/bats-support $(BATS_DIR)/bats-support
+	git clone -q --depth 1 --branch $(BATS_ASSERT_VERSION)  https://github.com/bats-core/bats-assert  $(BATS_DIR)/bats-assert
+	@touch $@
+
+tools: $(HELM_DIR)/helm $(HELMFILE_DIR)/helmfile $(BATS_DIR)/.installed
+
+# For .bats files:
+#   SC2030/SC2031  each @test runs in a subshell by design
+#   SC2154         $$output, $$stderr, $$status are set by bats "run"
+#   SC2016         single-quoted $${VAR} is intentional (tests variable expansion)
+lint: $(SHELLCHECK)
+	$(SHELLCHECK) --version | sed -n 2p
+	$(SHELLCHECK) src/*.sh
+	$(SHELLCHECK) test/*.bash test/*.sh
+	$(SHELLCHECK) -s bash -e SC2030,SC2031,SC2016,SC2154 test/*.bats
+	@# Removed code must not come back: Helm 2 support and legacy constructs.
+	@if grep -nE 'init --client-only|HELMFILE_HELM3|helm_major_version\} -eq 2' src/*.sh; then \
+	  echo "Helm 2 code found in src/"; exit 1; fi
+	@if grep -nE '\[\[ true \]\]|print_env_vars|\$$\(which |-eq 1 \]\]' src/*.sh; then \
+	  echo "legacy construct found in src/"; exit 1; fi
+
+test: tools
+	@helm version --short
+	@helmfile --version
+	BATS_LIB_PATH=$(BATS_DIR) $(BATS_DIR)/bats-core/bin/bats --print-output-on-failure test/
+
+test-docker:
+	docker build -f $(DOCKERFILE) -t $(IMAGE) .
+	docker run --rm -v $(CURDIR)/test:/test:ro --entrypoint /bin/bash $(IMAGE) /test/docker-smoke.sh
+
+clean:
+	rm -rf $(TOOLS_DIR)
diff --git a/README.md b/README.md
index 8120ba9..c8b8079 100644
--- a/README.md
+++ b/README.md
@@ -30,6 +30,35 @@ Consider these implications for your environment and act appropriately.
 - https://github.com/helmfile/helmfile/pull/1 (can disable `exec` using env vars)
 - the execution pod/context is the `argocd-repo-server`
 
+# Requirements
+
+- `helm` >= 3.6 (Helm 4 recommended; Helm 2 is not supported)
+- `helmfile` >= 1, and >= 1.2 when used with Helm 4
+
+The plugin checks both versions in the `init` and `generate` phases and fails
+with a clear message if they are not supported.
+
+## Kubernetes capabilities
+
+Argo CD passes the destination cluster's version and APIs as `KUBE_VERSION` and
+`KUBE_API_VERSIONS`. The plugin passes them to `helm template`, so charts can use
+`.Capabilities.KubeVersion` and `.Capabilities.APIVersions.Has`:
+
+- `KUBE_VERSION` is normalized first: a leading `v` and anything after the first
+  `+` or `-` are removed (`v1.29.0+k3s1` → `1.29.0`, `1.29.0-eks-5e0fdde` → `1.29.0`).
+  Values that are still not `<major>.<minor>[.<patch>]` are ignored with a warning.
+- `KUBE_API_VERSIONS` is passed as `--api-versions`.
+
+## Helm 4 notes
+
+- Post-renderers are Helm plugins in Helm 4. `--post-renderer` in
+  `HELM_TEMPLATE_OPTIONS` or `postRenderer:` in helmfile must name an installed
+  plugin, not an executable path.
+- `helm registry login` takes a domain name only (no path). Check
+  `HELMFILE_INIT_SCRIPT_FILE` scripts that log in to OCI registries.
+- Plugins installed via `HELMFILE_INIT_SCRIPT_FILE` need `--verify=false` unless
+  they are signed and their key is available.
+
 # Installation
 
 - https://argo-cd.readthedocs.io/en/stable/operator-manual/config-management-plugins/
@@ -101,6 +130,11 @@ optional):
     `HELMFILE_HELMFILE` should the same release name be declared in multiple
     files
 - `HELMFILE_CACHE_CLEANUP` - run helmfile cache cleanup on init
+- `PLUGIN_APP_HOME` - per-application directory used as `HOME` while running
+  `helm`/`helmfile`, so applications do not share repositories, registry
+  logins or caches. Defaults to `/tmp/__argocd-helmfile-plugin.sh__/apps/${ARGOCD_APP_NAME}`
+- `HELM_HOME` - **deprecated** alias for `PLUGIN_APP_HOME` (Helm itself ignores
+  it since v3). Still accepted with a warning; `PLUGIN_APP_HOME` wins if both are set
 
 Of the above `ENV` variables, the following do variable expansion on the value:
 
@@ -108,6 +142,9 @@ Of the above `ENV` variables, the following do variable expansion on the value:
 - `HELMFILE_TEMPLATE_OPTIONS`
 - `HELM_TEMPLATE_OPTIONS`
 - `HELMFILE_INIT_SCRIPT_FILE`
+- `PLUGIN_APP_HOME` (and deprecated `HELM_HOME`)
+- `HELM_CACHE_HOME`
+- `HELM_CONFIG_HOME`
 - `HELM_DATA_HOME`
 
 Meaning, you can do things like:
@@ -147,7 +184,7 @@ prevents the plugin(s) from being downloaded over and over each run.
   - mountPath: /helm/data
     name: helm-data-home
 
-    [[ ! -d "${HELM_DATA_HOME}/plugins/helm-secrets" ]] && /custom-tools/helm-v3 plugin install https://github.com/jkroepke/helm-secrets --version ${HELM_SECRETS_VERSION}
+    [[ ! -d "${HELM_DATA_HOME}/plugins/helm-secrets" ]] && /custom-tools/helm plugin install https://github.com/jkroepke/helm-secrets --version ${HELM_SECRETS_VERSION} --verify=false
     chown -R 999:999 "${HELM_DATA_HOME}"
 
 # lastly, in your app definition
@@ -171,6 +208,27 @@ etc. The value can be a relative or absolute path and the file itself can be
 injected using an `initContainers` or stored in the application git repository.
 
 ## Development
+
+### Tests
+
+Tests use [bats-core](https://github.com/bats-core/bats-core) and run the plugin
+against the real `helm` and `helmfile` binaries, using the versions pinned in
+`docker/Dockerfile`. No cluster or network access to chart repositories is needed.
+
+```bash
+make test         # downloads helm, helmfile and bats into .tools/, then runs test/*.bats
+make lint         # shellcheck
+make test-docker  # builds the image and runs test/docker-smoke.sh inside it
+```
+
+Requirements: `bash`, `git`, `wget`, `xz`, `jq`, `make` (and `docker` for `test-docker`).
+`make` downloads pinned `shellcheck`, `helm`, `helmfile` and bats into `.tools/`.
+Override tool versions with e.g. `make test HELM_VERSION=v3.19.4`.
+
+Tests for known bugs are marked with `skip "known bug: ..."`. Remove the skip
+together with the fix.
+
+### Contributing
 ```declarative
 # Create fork.
 # Add the original repository as a new remote called "upstream" (only once, if not done before)
diff --git a/docker/Dockerfile b/docker/Dockerfile
index 3617d92..d2ddbbb 100644
--- a/docker/Dockerfile
+++ b/docker/Dockerfile
@@ -31,6 +31,7 @@ RUN groupadd -g $ARGOCD_USER_ID argocd && \
 # Binary versions
 # https://github.com/helm/helm/releases
 # Supported Kubernetes Versions 1.35.x - 1.32.x (https://helm.sh/docs/topics/version_skew/)
+# Plugin requires helm >= 3.6; with helm 4, helmfile >= 1.2
 ARG HELM_VERSION="v4.2.3"
 # https://github.com/helmfile/helmfile/releases
 ARG HELMFILE_VERSION="1.5.2"
@@ -94,7 +95,10 @@ ARG HELM_GIT_VERSION="1.5.2"
 # https://github.com/jkroepke/helm-secrets/releases
 ARG HELM_SECRETS_VERSION="4.7.6"
 
-# TODO... HELM 4+ WARNING: Skipping plugin signature verification. Use --verify=false to skip verification
+# Helm 4 verifies plugin signatures by default:
+# - helm-diff and helm-git are installed from git, which cannot be verified
+# - helm-secrets tarballs are signed, but need the publisher key in a gpg keyring
+# so verification is skipped explicitly; versions are pinned above.
 RUN \
   helm plugin install https://github.com/databus23/helm-diff   --version ${HELM_DIFF_VERSION} --verify=false && \
   helm plugin install https://github.com/aslafy-z/helm-git     --version ${HELM_GIT_VERSION} --verify=false && \
diff --git a/src/argocd-helmfile-plugin.sh b/src/argocd-helmfile-plugin.sh
old mode 100755
new mode 100644
index 0b3ba78..171ee83
--- a/src/argocd-helmfile-plugin.sh
+++ b/src/argocd-helmfile-plugin.sh
@@ -14,7 +14,8 @@
 # HELMFILE_REPO_CACHE_TIMEOUT - seconds to cache the repo update process
 # HELMFILE_USE_CONTEXT_NAMESPACE - do not set helmfile namespace to ARGOCD_APP_NAMESPACE (for multi-namespace apps)
 # HELMFILE_DISCOVERY_RESPONSE - truthy value for forced response
-# HELM_HOME - perform variable expansion
+# PLUGIN_APP_HOME - per-application HOME directory, perform variable expansion
+# HELM_HOME - deprecated alias for PLUGIN_APP_HOME
 # HELM_CACHE_HOME - perform variable expansion
 # HELM_CONFIG_HOME - perform variable expansion
 # HELM_DATA_HOME - perform variable expansion
@@ -45,63 +46,75 @@
 # init is called before every manifest generation
 # it can be used to download dependencies, etc, etc
 
-# does not have "v" in front
-# KUBE_VERSION="<major>.<minor>"
+# set by Argo CD from the destination cluster, see normalize_kube_version()
+# KUBE_VERSION="<major>.<minor>[.<patch>]" (may carry a "v" prefix or vendor suffix)
 # KUBE_API_VERSIONS="v1,apps/v1,..."
 
-# error/exit on any failure
-set -e
+# exit on errors, unset variables and failures
+set -Eeuo pipefail
 
 # debugging execution
 #
 # Enable this only if you are debugging an issue.
 # Leaving this on causes excessive space consumption on etcd database.
-if [[ "${DEBUG}" == "1" ]]; then
+if [[ "${DEBUG:-}" == "1" ]]; then
   set -x
 fi
 
 echoerr() { printf "%s\n" "$*" >&2; }
 
+# report where a failure happened, the failing tool prints its own error
+trap 'echoerr "${SCRIPT_NAME:-plugin}: ${phase:-startup} failed (exit $?) at line ${LINENO}"' ERR
+
 # https://unix.stackexchange.com/questions/294835/replace-environment-variables-in-a-file-with-their-actual-values
 variable_expansion() {
   # prefer envsubst if available, fallback to perl
-  if [[ $(which envsubst) ]]; then
-    echo -n "${@}" | envsubst
+  if command -v envsubst >/dev/null; then
+    printf "%s" "$*" | envsubst
   else
-    echo -n "${@}" | perl -pe 's/\$(\{)?([a-zA-Z_]\w*)(?(1)\})/$ENV{$2}/g'
+    printf "%s" "$*" | perl -pe 's/\$(\{)?([a-zA-Z_]\w*)(?(1)\})/$ENV{$2}/g'
   fi
 }
 
-print_env_vars() {
-  while IFS='=' read -r -d '' n v; do
-    printf "'%s'='%s'\n" "$n" "$v"
-  done < <(env -0)
-}
-
-#truthy_test ${FOO:-false} && echo "yes \$FOO"
+# truthy_test "${FOO:-false}" && echo "yes \$FOO"
+# true, 1 and yes (any case) are truthy, everything else is not
 truthy_test() {
-  val="${1}"
-  if [[ $val == true ]]; then
-    return 0
-  fi
-
-  if [[ ${val} -eq 1 ]]; then
-    return 0
-  fi
+  case "${1,,}" in
+    true | 1 | yes) return 0 ;;
+    *) return 1 ;;
+  esac
+}
 
-  if [[ ${val,,} == "1" ]]; then
-    return 0
-  fi
+# split a free-form options string into words (no glob expansion)
+# usage: split_words <array name> <string>
+split_words() {
+  local -n _split_words_out="${1}"
+  read -r -d '' -a _split_words_out <<<"${2}" || true
+}
 
-  if [[ ${val,,} == "true" ]]; then
-    return 0
-  fi
+# export <prefix>NAME=value as NAME=value
+# https://argo-cd.readthedocs.io/en/latest/operator-manual/upgrading/2.3-2.4/
+export_prefixed_env() {
+  local prefix="${1}" n v name
+  while IFS='=' read -r -d '' n v; do
+    [[ "${n}" == "${prefix}"* ]] || continue
+    name="${n#"${prefix}"}"
+    if [[ ! "${name}" =~ ^[A-Za-z_][A-Za-z0-9_]*$ ]]; then
+      echoerr "WARNING: ignoring ${n}, '${name}' is not a valid variable name"
+      continue
+    fi
+    export "${name}=${v}"
+  done < <(env -0)
+}
 
-  if [[ ${val,,} == "yes" ]]; then
-    return 0
+# https://github.com/argoproj/argo-cd/issues/8249
+# Prints "<major>.<minor>[.<patch>]", or nothing if the value is not usable.
+normalize_kube_version() {
+  local version="${1#v}"
+  version="${version%%[+-]*}"
+  if [[ "${version}" =~ ^[0-9]+\.[0-9]+(\.[0-9]+)?$ ]]; then
+    echo "${version}"
   fi
-
-  return 1
 }
 
 cache_set_time() {
@@ -112,214 +125,209 @@ cache_set_time() {
 cache_get_time() {
   local key="${1}"
   if [[ -f "${HOME}/${key}" ]]; then
-    echo $(stat -c %Y "${HOME}/${key}")
+    stat -c %Y "${HOME}/${key}"
   fi
 }
 
 cache_is_valid() {
   local key="${1}"
   local timeout="${2}"
+  local cache_time current_time
 
   if [[ -z "${key}" ]]; then
     return 1
   fi
 
-  if [[ -z ${timeout} || ${timeout} -lt 1 ]]; then
+  if [[ ! "${timeout}" =~ ^[0-9]+$ || "${timeout}" -lt 1 ]]; then
     return 1
   fi
 
-  local cache_time=$(cache_get_time "${key}")
-  if [[ -z $cache_time ]]; then
+  cache_time=$(cache_get_time "${key}")
+  if [[ -z "${cache_time}" ]]; then
     return 1
   fi
 
-  local current_time=$(date +%s)
-  local cache_time_diff=$(($current_time - $cache_time))
-
-  if [[ "${cache_time_diff}" -gt "${timeout}" ]]; then
+  current_time=$(date +%s)
+  if ((current_time - cache_time > timeout)); then
     return 1
   fi
 }
 
 cache_is_expired() {
-  local key="${1}"
-  local timeout="${2}"
+  ! cache_is_valid "${1}" "${2}"
+}
+
+# detect and validate tool versions, only needed for phases that run them
+check_tool_versions() {
+  local helm_version helmfile_version
+  local helm_major helm_minor helmfile_major helmfile_minor
+
+  if ! helm_version=$("${helm}" version --template '{{.Version}}' 2>/dev/null); then
+    echoerr "failed to run '${helm} version', helm >= 3.6 is required"
+    exit 1
+  fi
+  echoerr "helm version ${helm_version}"
+
+  if [[ ! "${helm_version}" =~ ^v([0-9]+)\.([0-9]+)\. ]]; then
+    echoerr "unable to parse helm version '${helm_version}', helm >= 3.6 is required"
+    exit 1
+  fi
+  helm_major="${BASH_REMATCH[1]}"
+  helm_minor="${BASH_REMATCH[2]}"
+
+  # 3.6 added "helm template --kube-version"
+  if ((helm_major < 3 || (helm_major == 3 && helm_minor < 6))); then
+    echoerr "helm ${helm_version} is not supported, helm >= 3.6 is required"
+    exit 1
+  fi
 
-  ! cache_is_valid "${key}" "${timeout}"
+  if ! helmfile_version=$("${helmfile}" --version 2>/dev/null); then
+    echoerr "failed to run '${helmfile} --version', helmfile >= 1 is required"
+    exit 1
+  fi
+  echoerr "${helmfile_version}"
+
+  if [[ ! "${helmfile_version}" =~ version\ v?([0-9]+)\.([0-9]+)\. ]]; then
+    echoerr "unable to parse helmfile version '${helmfile_version}', helmfile >= 1 is required"
+    exit 1
+  fi
+  helmfile_major="${BASH_REMATCH[1]}"
+  helmfile_minor="${BASH_REMATCH[2]}"
+
+  if ((helmfile_major < 1)); then
+    echoerr "${helmfile_version} is not supported, helmfile >= 1 is required"
+    exit 1
+  fi
+
+  # https://github.com/helmfile/helmfile/issues/2268
+  if ((helm_major >= 4 && helmfile_major == 1 && helmfile_minor < 2)); then
+    echoerr "${helmfile_version} does not support helm ${helm_version}, helmfile >= 1.2 is required for helm 4"
+    exit 1
+  fi
+}
+
+# resolve a binary from an explicit path or PATH
+resolve_binary() {
+  local name="${1}" custom="${2}"
+  if [[ "${custom}" ]]; then
+    echo "${custom}"
+  elif ! command -v "${name}"; then
+    echoerr "${name} not found in PATH"
+    return 1
+  fi
 }
 
 # exit immediately if no phase is passed in
-if [[ -z "${1}" ]]; then
+if [[ -z "${1:-}" ]]; then
   echoerr "invalid invocation"
   exit 1
 fi
 
+phase="${1}"
 SCRIPT_NAME=$(basename "${0}")
 
-# export vars unprefixed
-# ARGOCD_ENV_
-# https://argo-cd.readthedocs.io/en/latest/operator-manual/upgrading/2.3-2.4/
-if [[ true ]]; then
-  while IFS='=' read -r -d '' n v; do
-    if [[ "${n}" = ARGOCD_ENV_* ]]; then
-      export ${n##ARGOCD_ENV_}="${v}"
-    fi
-  done < <(env -0)
-fi
-
-# immediately correct PATH if necessary
-export PATH=$(variable_expansion "${PATH}")
-
-# export params unprefixed (prefer these over ENV vars above)
-# PARAM_
 # https://github.com/argoproj/argo-cd/blob/master/docs/proposals/parameterized-config-management-plugins.md#how-will-the-cmp-know-what-parameter-values-are-set
-if [[ true ]]; then
-  while IFS='=' read -r -d '' n v; do
-    if [[ "${n}" = PARAM_* ]]; then
-      export ${n##PARAM_}="${v}"
-    fi
-  done < <(env -0)
-fi
+export_prefixed_env "ARGOCD_ENV_"
+export_prefixed_env "PARAM_"
 
 # immediately correct PATH if necessary
-export PATH=$(variable_expansion "${PATH}")
+PATH=$(variable_expansion "${PATH}")
+export PATH
 
 # expand nested variables
-if [[ "${HELMFILE_GLOBAL_OPTIONS}" ]]; then
-  HELMFILE_GLOBAL_OPTIONS=$(variable_expansion "${HELMFILE_GLOBAL_OPTIONS}")
-fi
-
-if [[ "${HELMFILE_TEMPLATE_OPTIONS}" ]]; then
-  HELMFILE_TEMPLATE_OPTIONS=$(variable_expansion "${HELMFILE_TEMPLATE_OPTIONS}")
-fi
-
-if [[ "${HELM_TEMPLATE_OPTIONS}" ]]; then
-  HELM_TEMPLATE_OPTIONS=$(variable_expansion "${HELM_TEMPLATE_OPTIONS}")
-fi
-
-if [[ "${HELMFILE_INIT_SCRIPT_FILE}" ]]; then
-  HELMFILE_INIT_SCRIPT_FILE=$(variable_expansion "${HELMFILE_INIT_SCRIPT_FILE}")
-fi
-
-: "${HELMFILE_ENV_FILE:=".argo-cd-helmfile-env"}"
-if [[ "${HELMFILE_ENV_FILE}" ]]; then
-  HELMFILE_ENV_FILE=$(variable_expansion "${HELMFILE_ENV_FILE}")
-fi
+for var in HELMFILE_GLOBAL_OPTIONS HELMFILE_TEMPLATE_OPTIONS HELM_TEMPLATE_OPTIONS HELMFILE_INIT_SCRIPT_FILE; do
+  if [[ "${!var:-}" ]]; then
+    printf -v "${var}" "%s" "$(variable_expansion "${!var}")"
+  fi
+done
 
+HELMFILE_ENV_FILE=$(variable_expansion "${HELMFILE_ENV_FILE:-.argo-cd-helmfile-env}")
 if [[ -f "${HELMFILE_ENV_FILE}" ]]; then
   echoerr "sourcing env file: ${HELMFILE_ENV_FILE}"
+  # env files are user content and may reference unset variables
+  set +u
+  # shellcheck disable=SC1090
   source "${HELMFILE_ENV_FILE}"
+  set -u
 fi
 
-if [[ "${HELM_CACHE_HOME}" ]]; then
-  export HELM_CACHE_HOME=$(variable_expansion "${HELM_CACHE_HOME}")
-fi
-
-if [[ "${HELM_CONFIG_HOME}" ]]; then
-  export HELM_CONFIG_HOME=$(variable_expansion "${HELM_CONFIG_HOME}")
-fi
+for var in HELM_CACHE_HOME HELM_CONFIG_HOME HELM_DATA_HOME; do
+  if [[ "${!var:-}" ]]; then
+    export "${var}=$(variable_expansion "${!var}")"
+  fi
+done
 
-if [[ "${HELM_DATA_HOME}" ]]; then
-  export HELM_DATA_HOME=$(variable_expansion "${HELM_DATA_HOME}")
+# HELM_HOME is accepted as a deprecated alias (helm ignores it since v3).
+PLUGIN_APP_HOME="${PLUGIN_APP_HOME:-}"
+if [[ -z "${PLUGIN_APP_HOME}" && "${HELM_HOME:-}" ]]; then
+  echoerr "WARNING: HELM_HOME is deprecated, use PLUGIN_APP_HOME instead"
+  PLUGIN_APP_HOME="${HELM_HOME}"
 fi
 
-# setup the env
-# HELM_HOME is deprecated with helm-v3, uses XDG dirs
-if [[ "${HELM_HOME}" ]]; then
-  export HELM_HOME=$(variable_expansion "${HELM_HOME}")
+if [[ "${PLUGIN_APP_HOME}" ]]; then
+  PLUGIN_APP_HOME=$(variable_expansion "${PLUGIN_APP_HOME}")
 else
-  export HELM_HOME="/tmp/__${SCRIPT_NAME}__/apps/${ARGOCD_APP_NAME}"
+  PLUGIN_APP_HOME="/tmp/__${SCRIPT_NAME}__/apps/${ARGOCD_APP_NAME:-}"
 fi
 
-# ensure dir(s)
-# rm -rf "${HELM_HOME}"
-if [[ ! -d "${HELM_HOME}" ]]; then
-  mkdir -p "${HELM_HOME}"
-fi
+export PLUGIN_APP_HOME
+export HELM_HOME="${PLUGIN_APP_HOME}"
 
-export HELMFILE_HELMFILE_HELMFILED="${PWD}/.__${SCRIPT_NAME}__helmfile.d"
-
-phase=$1
+mkdir -p "${PLUGIN_APP_HOME}"
 
-if [[ ! -d "/tmp/__${SCRIPT_NAME}__/bin" ]]; then
-  mkdir -p "/tmp/__${SCRIPT_NAME}__/bin"
-fi
+export HELMFILE_HELMFILE_HELMFILED="${PWD}/.__${SCRIPT_NAME}__helmfile.d"
 
 # set binary paths and base options
-if [[ "${HELM_BINARY}" ]]; then
-  helm="${HELM_BINARY}"
-else
-  helm="$(which helm)"
-fi
-
-if [[ "${HELMFILE_BINARY}" ]]; then
-  helmfile="${HELMFILE_BINARY}"
-else
-  helmfile="$(which helmfile)"
-fi
-
-echoerr "helm version $(${helm} version --short)"
-echoerr "$(${helmfile} --version)"
+case "${phase}" in
+  "init" | "generate")
+    helm=$(resolve_binary helm "${HELM_BINARY:-}")
+    helmfile=$(resolve_binary helmfile "${HELMFILE_BINARY:-}")
+    check_tool_versions
+    ;;
+esac
 
-helmfile="${helmfile} --helm-binary ${helm} --no-color --allow-no-matching-release"
+helmfile_cmd=("${helmfile:-helmfile}" --helm-binary "${helm:-helm}" --no-color --allow-no-matching-release)
 
-if [[ "${ARGOCD_APP_NAMESPACE}" ]]; then
-  truthy_test ${HELMFILE_USE_CONTEXT_NAMESPACE:-false} || {
-    helmfile="${helmfile} --namespace ${ARGOCD_APP_NAMESPACE}"
-  }
+if [[ "${ARGOCD_APP_NAMESPACE:-}" ]] && ! truthy_test "${HELMFILE_USE_CONTEXT_NAMESPACE:-false}"; then
+  helmfile_cmd+=(--namespace "${ARGOCD_APP_NAMESPACE}")
 fi
 
-if [[ "${HELMFILE_GLOBAL_OPTIONS}" ]]; then
-  helmfile="${helmfile} ${HELMFILE_GLOBAL_OPTIONS}"
+if [[ "${HELMFILE_GLOBAL_OPTIONS:-}" ]]; then
+  global_options=()
+  split_words global_options "${HELMFILE_GLOBAL_OPTIONS}"
+  helmfile_cmd+=("${global_options[@]}")
 fi
 
 if [[ -v HELMFILE_HELMFILE ]]; then
-  helmfile="${helmfile} --file ${HELMFILE_HELMFILE_HELMFILED}"
-  HELMFILE_HELMFILE_STRATEGY=${HELMFILE_HELMFILE_STRATEGY:=REPLACE}
+  helmfile_cmd+=(--file "${HELMFILE_HELMFILE_HELMFILED}")
 fi
 
 # TODO: parse helmfile here to detect the operative -f or --file
 
-# these should work for both v2 and v3
-helm_full_version=$(${helm} version --short | cut -d " " -f2)
-helm_major_version=$(echo "${helm_full_version%+*}" | cut -d "." -f1 | sed 's/[^0-9]//g')
-helm_minor_version=$(echo "${helm_full_version%+*}" | cut -d "." -f2 | sed 's/[^0-9]//g')
-helm_patch_version=$(echo "${helm_full_version%+*}" | cut -d "." -f3 | sed 's/[^0-9]//g')
-
-if [[ ${helm_major_version} -eq 3 ]]; then
-  # https://github.com/roboll/helmfile/issues/1015#issuecomment-563488649
-  export HELMFILE_HELM3="1"
-fi
-
-# fix scenarios where KUBE_VERSION is improperly set with trailing +
-# https://github.com/argoproj/argo-cd/issues/8249
-KUBE_VERSION=$(echo "${KUBE_VERSION}" | sed 's/[^0-9\.]*//g')
-
 # set home variable to ensure apps do NOT overlap settings/repos/etc
-export HOME="${HELM_HOME}"
+export HOME="${PLUGIN_APP_HOME}"
 
 echoerr "starting ${phase}"
 
-case $phase in
+case "${phase}" in
   "init")
-    truthy_test "${HELMFILE_CACHE_CLEANUP:-false}" && {
-      ${helmfile} cache cleanup
-    }
+    if truthy_test "${HELMFILE_CACHE_CLEANUP:-false}"; then
+      "${helmfile_cmd[@]}" cache cleanup
+    fi
 
     if [[ -v HELMFILE_HELMFILE ]]; then
       rm -rf "${HELMFILE_HELMFILE_HELMFILED}"
       mkdir -p "${HELMFILE_HELMFILE_HELMFILED}"
 
-      case "${HELMFILE_HELMFILE_STRATEGY}" in
+      case "${HELMFILE_HELMFILE_STRATEGY:-REPLACE}" in
         "INCLUDE")
-
           count=0
 
-          [[ -f "helmfile.yaml" ]] && ((count++))
-          [[ -f "helmfile.yaml.gotmpl" ]] && ((count++))
-          [[ -d "helmfile.d" ]] && ((count++))
+          [[ -f "helmfile.yaml" ]] && count=$((count + 1))
+          [[ -f "helmfile.yaml.gotmpl" ]] && count=$((count + 1))
+          [[ -d "helmfile.d" ]] && count=$((count + 1))
 
-          if [[ $count -gt 1 ]]; then
+          if [[ "${count}" -gt 1 ]]; then
             echoerr "You can have either helmfile.yaml, helmfile.yaml.gotmpl, or helmfile.d, but not more than one"
           fi
 
@@ -347,100 +355,74 @@ case $phase in
       echo "${HELMFILE_HELMFILE}" >"${HELMFILE_HELMFILE_HELMFILED}/ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ__argocd__helmfile__.yaml"
     fi
 
-    if [[ ${helm_major_version} -eq 2 ]]; then
-      ${helm} init --client-only
-    fi
-
-    if [ ! -z "${HELMFILE_INIT_SCRIPT_FILE}" ]; then
-      HELMFILE_INIT_SCRIPT_FILE=$(realpath "${HELMFILE_INIT_SCRIPT_FILE}")
-      bash "${HELMFILE_INIT_SCRIPT_FILE}"
+    if [[ "${HELMFILE_INIT_SCRIPT_FILE:-}" ]]; then
+      bash "$(realpath "${HELMFILE_INIT_SCRIPT_FILE}")"
     fi
 
     # using app revision here to ensure if the git repo is updated the cache is busted
-    cache_key="plugin-${phase}-repos-${ARGOCD_APP_REVISION}"
+    cache_key="plugin-${phase}-repos-${ARGOCD_APP_REVISION:-}"
 
-    if cache_is_expired "${cache_key}" "${HELMFILE_REPO_CACHE_TIMEOUT}"; then
+    if cache_is_expired "${cache_key}" "${HELMFILE_REPO_CACHE_TIMEOUT:-}"; then
       # https://github.com/roboll/helmfile/issues/1064
-      ${helmfile} repos
+      "${helmfile_cmd[@]}" repos
       cache_set_time "${cache_key}"
-      # TODO: fetch here?
-      #${helmfile} fetch
     else
       echoerr "skipping repos update due to cache"
     fi
     ;;
 
   "generate")
-    INTERNAL_HELMFILE_TEMPLATE_OPTIONS=
-    INTERNAL_HELM_TEMPLATE_OPTIONS=
-
-    # helmfile args
-    # --environment default, -e default       specify the environment name. defaults to default
-    # --namespace value, -n value             Set namespace. Uses the namespace set in the context by default, and is available in templates as {{ .Namespace }}
-    # --selector value, -l value              Only run using the releases that match labels. Labels can take the form of foo=bar or foo!=bar.
-    #                                         A release must match all labels in a group in order to be used. Multiple groups can be specified at once.
-    #                                         --selector tier=frontend,tier!=proxy --selector tier=backend. Will match all frontend, non-proxy releases AND all backend releases.
-    #                                         The name of a release can be used as a label. --selector name=myrelease
-    # --allow-no-matching-release             Do not exit with an error code if the provided selector has no matching releases.
-
-    # apply custom args passed from helmfile down to helm
-    # https://github.com/helm/helm/pull/7054/files (--is-upgrade added to v3)
-    # --args --kube-version=1.16,--api-versions=foo
-    #
-    # v2
-    # --is-upgrade               set .Release.IsUpgrade instead of .Release.IsInstall
-    # --kube-version string      kubernetes version used as Capabilities.KubeVersion.Major/Minor (default "1.9")
-    # v3
-    # -a, --api-versions stringArray   Kubernetes api versions used for Capabilities.APIVersions
-    # --no-hooks                   prevent hooks from running during install
-    # --skip-crds                  if set, no CRDs will be installed. By default, CRDs are installed if not already present
-
-    if [[ ${helm_major_version} -eq 2 && "${KUBE_VERSION}" ]]; then
-      INTERNAL_HELM_TEMPLATE_OPTIONS="${INTERNAL_HELM_TEMPLATE_OPTIONS} --kube-version=${KUBE_VERSION}"
+
+    # options for "helmfile template"
+    helmfile_template_args=(--skip-deps)
+    # options passed by helmfile to "helm template" (--args, split on spaces)
+    helm_template_args=()
+
+    # Capabilities.KubeVersion
+    kube_version=$(normalize_kube_version "${KUBE_VERSION:-}")
+    if [[ "${kube_version}" ]]; then
+      helmfile_template_args+=(--kube-version "${kube_version}")
+    elif [[ "${KUBE_VERSION:-}" ]]; then
+      echoerr "WARNING: ignoring invalid KUBE_VERSION '${KUBE_VERSION}'"
+    fi
+
+    # Capabilities.APIVersions, helm accepts a comma-separated list
+    if [[ "${KUBE_API_VERSIONS:-}" ]]; then
+      helm_template_args+=("--api-versions=${KUBE_API_VERSIONS}")
+    fi
+
+    if [[ "${HELM_TEMPLATE_OPTIONS:-}" ]]; then
+      helm_template_args+=("${HELM_TEMPLATE_OPTIONS}")
     fi
 
-    # support added for --kube-version in 3.6
-    # https://github.com/helm/helm/pull/9040
-    if [[ ${helm_major_version} -eq 3 && ${helm_minor_version} -ge 6 && "${KUBE_VERSION}" ]]; then
-      INTERNAL_HELM_TEMPLATE_OPTIONS="${INTERNAL_HELM_TEMPLATE_OPTIONS} --kube-version=${KUBE_VERSION}"
+    if [[ ${#helm_template_args[@]} -gt 0 ]]; then
+      helmfile_template_args+=(--args "${helm_template_args[*]}")
     fi
 
-    if [[ ${helm_major_version} -eq 3 && "${KUBE_API_VERSIONS}" ]]; then
-      INTERNAL_HELM_API_VERSIONS=""
-      for v in ${KUBE_API_VERSIONS//,/ }; do
-        INTERNAL_HELM_API_VERSIONS="${INTERNAL_HELM_API_VERSIONS} --api-versions=$v"
-      done
-      INTERNAL_HELM_TEMPLATE_OPTIONS="${INTERNAL_HELM_TEMPLATE_OPTIONS} ${INTERNAL_HELM_API_VERSIONS}"
+    if [[ "${HELMFILE_TEMPLATE_OPTIONS:-}" ]]; then
+      template_options=()
+      split_words template_options "${HELMFILE_TEMPLATE_OPTIONS}"
+      helmfile_template_args+=("${template_options[@]}")
     fi
 
     # TODO: support post process pipeline here
-    ${helmfile} \
-      template \
-      --skip-deps ${INTERNAL_HELMFILE_TEMPLATE_OPTIONS} \
-      --args "${INTERNAL_HELM_TEMPLATE_OPTIONS} ${HELM_TEMPLATE_OPTIONS}" \
-      ${HELMFILE_TEMPLATE_OPTIONS}
+    "${helmfile_cmd[@]}" template "${helmfile_template_args[@]}"
     ;;
 
   "discover")
     # https://github.com/argoproj/argo-cd/issues/4831
     # discovery by default is not executed in the ARGOCD_APP_SOURCE_PATH
-    # discovery broken in 2.7.4
-    if [[ ! -z "${HELMFILE_DISCOVERY_RESPONSE}" ]]; then
-      truthy_test "${HELMFILE_DISCOVERY_RESPONSE}" && {
+    # stdout plus exit code 0 means "use this plugin", diagnostics go to stderr_APP_SOURCE_PATH
+    if [[ "${HELMFILE_DISCOVERY_RESPONSE:-}" ]]; then
+      if truthy_test "${HELMFILE_DISCOVERY_RESPONSE}"; then
         echo "forced discovery response: enabled"
         exit 0
-      } || {
-        echo "forced discovery response: disabled"
-        exit 1
-      }
+      fi
+      echoerr "forced discovery response: disabled"
+      exit 1
     fi
 
-    if [[ "${HELMFILE_GLOBAL_OPTIONS}" == *--file* ]]; then
-      echo "custom file path provided, assumed proper"
-      exit 0
-    fi
-
-    if [[ "${HELMFILE_GLOBAL_OPTIONS}" == *-f* ]]; then
+    if [[ "${HELMFILE_GLOBAL_OPTIONS:-}" == *--file* || "${HELMFILE_GLOBAL_OPTIONS:-}" == *-f* ]]; then
       echo "custom file path provided, assumed proper"
       exit 0
     fi
@@ -450,39 +432,17 @@ case $phase in
       exit 0
     fi
 
-    if [[ -f "helmfile.yaml" ]]; then
+    if [[ -f "helmfile.yaml" || -f "helmfile.yaml.gotmpl" || -d "helmfile.d" ]]; then
       echo "valid helmfile content discovered"
       exit 0
     fi
 
-    if [[ -f "helmfile.yaml.gotmpl" ]]; then
-      echo "valid helmfile content discovered"
-      exit 0
-    fi
-
-    if [[ -d "helmfile.d" ]]; then
-      echo "valid helmfile content discovered"
-      exit 0
-    fi
-
-    # provides false positive if --file or -f is omitted
-    #test -n "$(find . -type d -name "helmfile.d")" && {
-    #  echo "valid helmfile content discovered"
-    #  exit 0
-    #}
-
-    # provides false positive if --file or -f is omitted
-    #test -n "$(find . -type f -name "helmfile.yaml")" && {
-    #  echo "valid helmfile content discovered"
-    #  exit 0
-    #}
-
-    echo "no valid helmfile content discovered"
+    echoerr "no valid helmfile content discovered"
     exit 1
     ;;
 
   "parameters")
-    cat <<-"EOF"
+    cat <<"EOF"
 [
   {
     "name": "HELM_TEMPLATE_OPTIONS",
@@ -527,39 +487,6 @@ case $phase in
     "itemType": "boolean"
   }
 ]
-EOF
-
-    exit 0
-
-    # not including these are params as they are explicitly used as ENV vars
-    read -r -d '' USE_AS_ENVS_TO_NOT_CONFUSE_PEOPLE <<'EOF'
-[
-  {
-    "name": "HELM_BINARY",
-    "title": "HELM_BINARY",
-    "tooltip": "custom path to helm binary"
-  },
-  {
-    "name": "HELMFILE_BINARY",
-    "title": "HELMFILE_BINARY",
-    "tooltip": "custom path to helmfile binary"
-  },
-  {
-    "name": "HELM_CACHE_HOME",
-    "title": "HELM_CACHE_HOME",
-    "tooltip": "perform variable expansion"
-  },
-  {
-    "name": "HELM_CONFIG_HOME",
-    "title": "HELM_CONFIG_HOME",
-    "tooltip": "perform variable expansion"
-  },
-  {
-    "name": "HELM_DATA_HOME",
-    "title": "HELM_DATA_HOME",
-    "tooltip": "perform variable expansion"
-  }
-]
 EOF
 
     exit 0
diff --git a/test/capabilities.bats b/test/capabilities.bats
new file mode 100644
index 0000000..93aeb42
--- /dev/null
+++ b/test/capabilities.bats
@@ -0,0 +1,148 @@
+#!/usr/bin/env bats
+# Kubernetes capabilities: KUBE_VERSION and KUBE_API_VERSIONS from Argo CD
+# must reach helm template (.Capabilities.KubeVersion / .APIVersions).
+
+setup() {
+  load helpers
+  common_setup
+  write_helmfile helmfile.yaml
+}
+
+@test "capabilities: renders without KUBE_VERSION and KUBE_API_VERSIONS" {
+  plugin_init
+  run_plugin generate
+  assert_success
+  assert_equal "$(probe_value hasProbeApi)" "false"
+  refute_regex "${stderr}" "WARNING"
+}
+
+@test "capabilities: KUBE_VERSION is passed to helm" {
+  export KUBE_VERSION="1.29"
+  plugin_init
+  run_plugin generate
+  assert_success
+  # helm keeps the two-part form: --kube-version 1.29 renders as v1.29
+  assert_equal "$(probe_value kubeVersion)" "v1.29"
+}
+
+@test "capabilities: KUBE_VERSION is passed with the native helmfile flag" {
+  HELMFILE_BINARY="$(make_call_logger helmfile)"
+  export HELMFILE_BINARY KUBE_VERSION="1.29.3"
+  plugin_init
+  run_plugin generate
+  assert_success
+  run grep -- ' template --skip-deps --kube-version 1.29.3' "${BATS_TEST_TMPDIR}/helmfile-calls.log"
+  assert_success
+}
+
+@test "capabilities: KUBE_API_VERSIONS is passed to helm" {
+  export KUBE_API_VERSIONS="v1,apps/v1,probe.example.com/v1"
+  plugin_init
+  run_plugin generate
+  assert_success
+  assert_equal "$(probe_value hasProbeApi)" "true"
+}
+
+@test "capabilities: single KUBE_API_VERSIONS entry is passed to helm" {
+  export KUBE_API_VERSIONS="probe.example.com/v1"
+  plugin_init
+  run_plugin generate
+  assert_success
+  assert_equal "$(probe_value hasProbeApi)" "true"
+}
+
+@test "capabilities: KUBE_API_VERSIONS without the probe API is honoured" {
+  export KUBE_API_VERSIONS="v1,apps/v1"
+  plugin_init
+  run_plugin generate
+  assert_success
+  assert_equal "$(probe_value hasProbeApi)" "false"
+}
+
+@test "capabilities: KUBE_VERSION, KUBE_API_VERSIONS and HELM_TEMPLATE_OPTIONS together" {
+  export KUBE_VERSION="v1.30.2+k3s1"
+  export KUBE_API_VERSIONS="v1,probe.example.com/v1"
+  export ARGOCD_ENV_HELM_TEMPLATE_OPTIONS="--set marker=combined"
+  plugin_init
+  run_plugin generate
+  assert_success
+  assert_equal "$(probe_value kubeVersion)" "v1.30.2"
+  assert_equal "$(probe_value hasProbeApi)" "true"
+  assert_equal "$(probe_value marker)" "combined"
+}
+
+@test "capabilities: --args is not passed when there is nothing to pass" {
+  HELMFILE_BINARY="$(make_call_logger helmfile)"
+  export HELMFILE_BINARY
+  plugin_init
+  run_plugin generate
+  assert_success
+  run grep -- '--args' "${BATS_TEST_TMPDIR}/helmfile-calls.log"
+  assert_failure
+}
+
+@test "capabilities: --args has no leading or double spaces" {
+  HELMFILE_BINARY="$(make_call_logger helmfile)"
+  export HELMFILE_BINARY KUBE_API_VERSIONS="v1"
+  export ARGOCD_ENV_HELM_TEMPLATE_OPTIONS="--set marker=x"
+  plugin_init
+  run_plugin generate
+  assert_success
+  run grep -- '--args --api-versions=v1 --set marker=x' "${BATS_TEST_TMPDIR}/helmfile-calls.log"
+  assert_success
+}
+
+# KUBE_VERSION normalization. Argo CD passes the cluster's version, which may
+# carry a leading "v" or vendor suffixes (argoproj/argo-cd#8249).
+kube_version_case() {
+  local input="$1" expected="$2"
+  export KUBE_VERSION="${input}"
+  plugin_init
+  run_plugin generate
+  assert_success
+  assert_equal "$(probe_value kubeVersion)" "${expected}"
+  refute_regex "${stderr}" "WARNING"
+}
+
+@test "capabilities: KUBE_VERSION 1.29.3 -> v1.29.3" {
+  kube_version_case "1.29.3" "v1.29.3"
+}
+
+@test "capabilities: KUBE_VERSION v1.29.3 -> v1.29.3" {
+  kube_version_case "v1.29.3" "v1.29.3"
+}
+
+@test "capabilities: KUBE_VERSION 1.29+ -> v1.29" {
+  kube_version_case "1.29+" "v1.29"
+}
+
+@test "capabilities: KUBE_VERSION 1.29.0+k3s1 -> v1.29.0" {
+  kube_version_case "1.29.0+k3s1" "v1.29.0"
+}
+
+@test "capabilities: KUBE_VERSION 1.29.0-eks-5e0fdde -> v1.29.0" {
+  kube_version_case "1.29.0-eks-5e0fdde" "v1.29.0"
+}
+
+@test "capabilities: KUBE_VERSION v1.31.1-gke.1678000 -> v1.31.1" {
+  kube_version_case "v1.31.1-gke.1678000" "v1.31.1"
+}
+
+@test "capabilities: KUBE_VERSION 1.30.4+rke2r1 -> v1.30.4" {
+  kube_version_case "1.30.4+rke2r1" "v1.30.4"
+}
+
+@test "capabilities: invalid KUBE_VERSION is ignored with a warning" {
+  local v default
+  plugin_init
+  run_plugin generate
+  default="$(probe_value kubeVersion)"
+
+  for v in "latest" "1" "v" "1.x" "one.two"; do
+    export KUBE_VERSION="${v}"
+    run_plugin generate
+    assert_success
+    assert_regex "${stderr}" "WARNING: ignoring invalid KUBE_VERSION '${v}'"
+    assert_equal "$(probe_value kubeVersion)" "${default}"
+  done
+}
diff --git a/test/discover.bats b/test/discover.bats
new file mode 100644
index 0000000..fb429bf
--- /dev/null
+++ b/test/discover.bats
@@ -0,0 +1,105 @@
+#!/usr/bin/env bats
+# discover phase: decides whether Argo CD should use this plugin for a source.
+
+setup() {
+  load helpers
+  common_setup
+}
+
+@test "discover: empty directory does not match" {
+  run_plugin discover
+  assert_failure
+}
+
+@test "discover: helmfile.yaml matches" {
+  write_helmfile helmfile.yaml
+  run_plugin discover
+  assert_success
+}
+
+@test "discover: helmfile.yaml.gotmpl matches" {
+  write_helmfile helmfile.yaml.gotmpl
+  run_plugin discover
+  assert_success
+}
+
+@test "discover: helmfile.d directory matches" {
+  write_helmfile helmfile.d/10-probe.yaml
+  run_plugin discover
+  assert_success
+}
+
+@test "discover: helmfile.yaml in a subdirectory only does not match" {
+  write_helmfile nested/helmfile.yaml
+  run_plugin discover
+  assert_failure
+}
+
+@test "discover: HELMFILE_HELMFILE set matches without files" {
+  export ARGOCD_ENV_HELMFILE_HELMFILE="releases: []"
+  run_plugin discover
+  assert_success
+}
+
+@test "discover: --file in HELMFILE_GLOBAL_OPTIONS matches without files" {
+  export ARGOCD_ENV_HELMFILE_GLOBAL_OPTIONS="--file custom/helmfile.yaml"
+  run_plugin discover
+  assert_success
+}
+
+@test "discover: -f in HELMFILE_GLOBAL_OPTIONS matches without files" {
+  export ARGOCD_ENV_HELMFILE_GLOBAL_OPTIONS="-f custom/helmfile.yaml"
+  run_plugin discover
+  assert_success
+}
+
+@test "discover: PARAM_ values are honoured like ARGOCD_ENV_ values" {
+  export PARAM_HELMFILE_GLOBAL_OPTIONS="--file custom/helmfile.yaml"
+  run_plugin discover
+  assert_success
+}
+
+@test "discover: option merely containing '-f' does not match" {
+  skip "known bug: *-f* glob matches e.g. --kube-context=prod-frontend (fix planned)"
+  export ARGOCD_ENV_HELMFILE_GLOBAL_OPTIONS="--kube-context=prod-frontend"
+  run_plugin discover
+  assert_failure
+}
+
+@test "discover: diagnostics do not go to stdout on no match" {
+  run_plugin discover
+  assert_failure
+  assert_output ""
+  assert_regex "${stderr}" "no valid helmfile content discovered"
+}
+
+# HELMFILE_DISCOVERY_RESPONSE also exercises truthy_test.
+@test "discover: forced response is truthy for true/1/yes (any case)" {
+  local v
+  for v in true TRUE True 1 yes YES Yes; do
+    export ARGOCD_ENV_HELMFILE_DISCOVERY_RESPONSE="${v}"
+    run_plugin discover
+    assert_success
+    assert_output --partial "enabled"
+  done
+}
+
+@test "discover: forced response is falsy for other values even if files exist" {
+  write_helmfile helmfile.yaml
+  local v
+  for v in false FALSE 0 no off random 2; do
+    export ARGOCD_ENV_HELMFILE_DISCOVERY_RESPONSE="${v}"
+    run_plugin discover
+    assert_failure
+    assert_output ""
+    assert_regex "${stderr}" "forced discovery response: disabled"
+  done
+}
+
+@test "discover: forced response is not evaluated as arithmetic" {
+  # [[ $val -eq 1 ]] used to evaluate the value, running command substitutions
+  export ARGOCD_ENV_HELMFILE_DISCOVERY_RESPONSE='a[$(touch pwned)]'
+  run_plugin discover
+  assert_failure
+  refute [ -e pwned ]
+}
diff --git a/test/docker-smoke.sh b/test/docker-smoke.sh
new file mode 100644
index 0000000..36fd4b1
--- /dev/null
+++ b/test/docker-smoke.sh
@@ -0,0 +1,34 @@
+#!/bin/bash
+set -euo pipefail
+
+fail() { echo "FAIL: $*" >&2; exit 1; }
+
+work="$(mktemp -d)"
+trap 'rm -rf "${work}"' EXIT
+cp -r /test/fixtures/chart-probe "${work}/chart"
+cd "${work}"
+
+cat >helmfile.yaml <<YAML
+releases:
+  - name: probe
+    chart: ${work}/chart
+YAML
+
+export ARGOCD_APP_NAME="smoke" ARGOCD_APP_NAMESPACE="smoke-ns" ARGOCD_APP_REVISION="smoke"
+export PLUGIN_APP_HOME="${work}/home"
+
+plugin="argocd-helmfile-plugin.sh"
+command -v "${plugin}" >/dev/null || fail "${plugin} not on PATH"
+
+"${plugin}" discover >/dev/null || fail "discover did not match helmfile.yaml"
+"${plugin}" parameters | jq -e 'length > 0' >/dev/null || fail "parameters is not valid JSON"
+"${plugin}" init >/dev/null || fail "init failed"
+out="$("${plugin}" generate)" || fail "generate failed"
+grep -q 'releaseNamespace: "smoke-ns"' <<<"${out}" || fail "unexpected generate output: ${out}"
+
+plugins="$(helm plugin list)"
+for p in diff helm-git secrets; do
+  grep -q "^${p}\b" <<<"${plugins}" || fail "helm plugin ${p} missing"
+done
+
+echo "OK: docker smoke test passed"
diff --git a/test/env.bats b/test/env.bats
new file mode 100644
index 0000000..a016c88
--- /dev/null
+++ b/test/env.bats
@@ -0,0 +1,228 @@
+#!/usr/bin/env bats
+# Environment handling: ARGOCD_ENV_/PARAM_ export, binaries, HOME isolation.
+
+setup() {
+  load helpers
+  common_setup
+}
+
+@test "env: ARGOCD_ENV_ variables are available unprefixed to helmfile" {
+  cat >helmfile.yaml.gotmpl <<YAML
+releases:
+  - name: probe
+    chart: ${WORK}/chart
+    set:
+      - name: marker
+        value: {{ requiredEnv "PROBE_MARKER" }}
+YAML
+  export ARGOCD_ENV_PROBE_MARKER="from-argocd-env"
+  plugin_init
+  run_plugin generate
+  assert_success
+  assert_equal "$(probe_value marker)" "from-argocd-env"
+}
+
+@test "env: PARAM_ variables take precedence over ARGOCD_ENV_" {
+  write_helmfile helmfile.yaml
+  export ARGOCD_ENV_HELM_TEMPLATE_OPTIONS="--set marker=from-env"
+  export PARAM_HELM_TEMPLATE_OPTIONS="--set marker=from-param"
+  plugin_init
+  run_plugin generate
+  assert_success
+  assert_equal "$(probe_value marker)" "from-param"
+}
+
+@test "env: HOME is isolated to PLUGIN_APP_HOME for helmfile" {
+  cat >helmfile.yaml.gotmpl <<YAML
+releases:
+  - name: probe
+    chart: ${WORK}/chart
+    set:
+      - name: marker
+        value: {{ env "HOME" | quote }}
+YAML
+  plugin_init
+  run_plugin generate
+  assert_success
+  assert_equal "$(probe_value marker)" "${PLUGIN_APP_HOME}"
+  assert [ -d "${PLUGIN_APP_HOME}" ]
+}
+
+@test "env: PLUGIN_APP_HOME is variable-expanded" {
+  write_helmfile helmfile.yaml
+  export PROBE_BASE="${BATS_TEST_TMPDIR}/expanded"
+  export PLUGIN_APP_HOME='${PROBE_BASE}/home'
+  plugin_init
+  assert [ -d "${BATS_TEST_TMPDIR}/expanded/home" ]
+  refute_regex "${stderr}" "HELM_HOME is deprecated"
+}
+
+@test "env: HELM_HOME still works as deprecated alias with a warning" {
+  write_helmfile helmfile.yaml
+  unset PLUGIN_APP_HOME
+  export PROBE_BASE="${BATS_TEST_TMPDIR}/legacy"
+  export HELM_HOME='${PROBE_BASE}/home'
+  plugin_init
+  assert [ -d "${BATS_TEST_TMPDIR}/legacy/home" ]
+  assert_regex "${stderr}" "WARNING: HELM_HOME is deprecated, use PLUGIN_APP_HOME instead"
+}
+
+@test "env: HELM_HOME from the application spec is accepted as alias" {
+  write_helmfile helmfile.yaml
+  unset PLUGIN_APP_HOME
+  export ARGOCD_ENV_HELM_HOME="${BATS_TEST_TMPDIR}/legacy-env"
+  plugin_init
+  assert [ -d "${BATS_TEST_TMPDIR}/legacy-env" ]
+  assert_regex "${stderr}" "HELM_HOME is deprecated"
+}
+
+@test "env: PLUGIN_APP_HOME wins over HELM_HOME" {
+  write_helmfile helmfile.yaml
+  export HELM_HOME="${BATS_TEST_TMPDIR}/legacy"
+  plugin_init
+  assert [ -d "${PLUGIN_APP_HOME}" ]
+  refute [ -d "${BATS_TEST_TMPDIR}/legacy" ]
+  refute_regex "${stderr}" "HELM_HOME is deprecated"
+}
+
+@test "env: HELM_HOME is exported equal to PLUGIN_APP_HOME for init scripts" {
+  write_helmfile helmfile.yaml
+  cat >init.sh <<'SH'
+echo "${HELM_HOME}" >homes.txt
+echo "${PLUGIN_APP_HOME}" >>homes.txt
+echo "${HOME}" >>homes.txt
+SH
+  export ARGOCD_ENV_HELMFILE_INIT_SCRIPT_FILE="init.sh"
+  plugin_init
+  run cat homes.txt
+  assert_line --index 0 "${PLUGIN_APP_HOME}"
+  assert_line --index 1 "${PLUGIN_APP_HOME}"
+  assert_line --index 2 "${PLUGIN_APP_HOME}"
+}
+
+@test "env: default PLUGIN_APP_HOME is per application" {
+  write_helmfile helmfile.yaml
+  unset PLUGIN_APP_HOME
+  export ARGOCD_APP_NAME="bats-$$-${BATS_TEST_NUMBER}"
+  local expected="/tmp/__argocd-helmfile-plugin.sh__/apps/${ARGOCD_APP_NAME}"
+  plugin_init
+  assert [ -d "${expected}" ]
+  rm -rf "${expected}"
+}
+
+@test "env: HELM_CACHE_HOME is variable-expanded and exported" {
+  cat >helmfile.yaml.gotmpl <<YAML
+releases:
+  - name: probe
+    chart: ${WORK}/chart
+    set:
+      - name: marker
+        value: {{ env "HELM_CACHE_HOME" | quote }}
+YAML
+  export PROBE_BASE="${BATS_TEST_TMPDIR}/cachebase"
+  export ARGOCD_ENV_HELM_CACHE_HOME='${PROBE_BASE}/cache'
+  plugin_init
+  run_plugin generate
+  assert_success
+  assert_equal "$(probe_value marker)" "${BATS_TEST_TMPDIR}/cachebase/cache"
+}
+
+@test "env: HELM_BINARY is used for helm calls" {
+  write_helmfile helmfile.yaml
+  HELM_BINARY="$(make_call_logger helm)"
+  export HELM_BINARY
+  plugin_init
+  run_plugin generate
+  assert_success
+  run grep -c '^helm template' "${BATS_TEST_TMPDIR}/helm-calls.log"
+  assert_success
+}
+
+@test "env: HELMFILE_BINARY is used for helmfile calls" {
+  write_helmfile helmfile.yaml
+  HELMFILE_BINARY="$(make_call_logger helmfile)"
+  export HELMFILE_BINARY
+  plugin_init
+  run_plugin generate
+  assert_success
+  run grep -c ' template ' "${BATS_TEST_TMPDIR}/helmfile-calls.log"
+  assert_success
+}
+
+@test "env: PATH from ARGOCD_ENV_ is variable-expanded" {
+  write_helmfile helmfile.yaml
+  make_call_logger helm >/dev/null
+  export PROBE_WRAP="${BATS_TEST_TMPDIR}/wrap"
+  export ARGOCD_ENV_PATH="\${PROBE_WRAP}:${PATH}"
+  plugin_init
+  assert [ -s "${BATS_TEST_TMPDIR}/helm-calls.log" ]
+}
+
+@test "env: invalid variable names are ignored with a warning" {
+  write_helmfile helmfile.yaml
+  run --separate-stderr env "ARGOCD_ENV_BAD-NAME=x" "PARAM_1BAD=y" bash "${PLUGIN}" discover
+  assert_success
+  assert_regex "${stderr}" "WARNING: ignoring ARGOCD_ENV_BAD-NAME"
+  assert_regex "${stderr}" "WARNING: ignoring PARAM_1BAD"
+}
+
+@test "env: values with spaces, quotes and newlines are exported unchanged" {
+  cat >helmfile.yaml.gotmpl <<YAML
+releases:
+  - name: probe
+    chart: ${WORK}/chart
+    set:
+      - name: marker
+        value: {{ env "PROBE_MARKER" | b64enc }}
+YAML
+  local value
+  value=$'a b "c" \'d\' $e\nline2'
+  export ARGOCD_ENV_PROBE_MARKER="${value}"
+  plugin_init
+  run_plugin generate
+  assert_success
+  assert_equal "$(probe_value marker | base64 -d)" "${value}"
+}
+
+@test "env: env file may reference unset variables" {
+  write_helmfile helmfile.yaml
+  cat >.argo-cd-helmfile-env <<'ENV'
+HELM_TEMPLATE_OPTIONS="--set marker=x${PROBE_UNSET_VARIABLE}y"
+ENV
+  plugin_init
+  run_plugin generate
+  assert_success
+  assert_equal "$(probe_value marker)" "xy"
+}
+
+@test "env: works without optional Argo CD variables" {
+  write_helmfile helmfile.yaml
+  unset ARGOCD_APP_NAMESPACE ARGOCD_APP_REVISION ARGOCD_APP_SOURCE_PATH \
+    ARGOCD_APP_SOURCE_REPO_URL ARGOCD_APP_SOURCE_TARGET_REVISION
+  plugin_init
+  run_plugin generate
+  assert_success
+  assert_equal "$(probe_value releaseName)" "probe"
+}
+
+@test "env: non-numeric HELMFILE_REPO_CACHE_TIMEOUT disables the cache" {
+  write_helmfile helmfile.yaml
+  export ARGOCD_ENV_HELMFILE_REPO_CACHE_TIMEOUT="5m"
+  plugin_init
+  run_plugin init
+  assert_success
+  refute_regex "${stderr}" "skipping repos update due to cache"
+}
+
+@test "env: missing helm binary fails with a clear message" {
+  write_helmfile helmfile.yaml
+  local helmfile_dir
+  helmfile_dir="$(dirname "$(command -v helmfile)")"
+  export PATH="${helmfile_dir}:/usr/bin:/bin"
+  if command -v helm >/dev/null; then
+    skip "helm is installed in a system path"
+  fi
+  run_plugin init
+  assert_failure
+  assert_regex "${stderr}" "helm not found in PATH"
+}
diff --git a/test/fixtures/chart-probe/Chart.yaml b/test/fixtures/chart-probe/Chart.yaml
new file mode 100644
index 0000000..80442b1
--- /dev/null
+++ b/test/fixtures/chart-probe/Chart.yaml
@@ -0,0 +1,4 @@
+apiVersion: v2
+name: chart-probe
+description: Local test chart that echoes what the plugin passed to helm. No network access needed.
+version: 0.1.0
diff --git a/test/fixtures/chart-probe/templates/probe.yaml b/test/fixtures/chart-probe/templates/probe.yaml
new file mode 100644
index 0000000..d911160
--- /dev/null
+++ b/test/fixtures/chart-probe/templates/probe.yaml
@@ -0,0 +1,11 @@
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: {{ .Release.Name }}
+  namespace: {{ .Release.Namespace }}
+data:
+  releaseName: {{ .Release.Name | quote }}
+  releaseNamespace: {{ .Release.Namespace | quote }}
+  marker: {{ .Values.marker | quote }}
+  kubeVersion: {{ .Capabilities.KubeVersion.Version | quote }}
+  hasProbeApi: {{ .Capabilities.APIVersions.Has "probe.example.com/v1" | quote }}
diff --git a/test/fixtures/chart-probe/values.yaml b/test/fixtures/chart-probe/values.yaml
new file mode 100644
index 0000000..fc651f2
--- /dev/null
+++ b/test/fixtures/chart-probe/values.yaml
@@ -0,0 +1 @@
+marker: default
diff --git a/test/generate.bats b/test/generate.bats
new file mode 100644
index 0000000..0e8d2a3
--- /dev/null
+++ b/test/generate.bats
@@ -0,0 +1,223 @@
+#!/usr/bin/env bats
+# generate phase: renders manifests to stdout.
+
+setup() {
+  load helpers
+  common_setup
+}
+
+@test "generate: renders helmfile.yaml" {
+  write_helmfile helmfile.yaml
+  plugin_init
+  run_plugin generate
+  assert_success
+  assert_equal "$(probe_value releaseName)" "probe"
+}
+
+@test "generate: renders helmfile.yaml.gotmpl with templating" {
+  cat >helmfile.yaml.gotmpl <<YAML
+releases:
+  - name: {{ "probe" }}
+    chart: ${WORK}/chart
+    set:
+      - name: marker
+        value: {{ printf "%s-%s" "from" "gotmpl" }}
+YAML
+  plugin_init
+  run_plugin generate
+  assert_success
+  assert_equal "$(probe_value marker)" "from-gotmpl"
+}
+
+@test "generate: renders all files in helmfile.d" {
+  write_helmfile helmfile.d/10-one.yaml one
+  write_helmfile helmfile.d/20-two.yaml two
+  plugin_init
+  run_plugin generate
+  assert_success
+  assert_equal "$(probe_value releaseName one)" "one"
+  assert_equal "$(probe_value releaseName two)" "two"
+}
+
+@test "generate: stdout contains only manifests" {
+  write_helmfile helmfile.yaml
+  plugin_init
+  run_plugin generate
+  assert_success
+  refute_output --partial "starting generate"
+  refute_output --partial "helm version"
+  refute_output --partial "helmfile version"
+  # Output starts with a YAML document marker.
+  assert_line --index 0 "---"
+  # Diagnostics go to stderr.
+  assert_regex "${stderr}" "starting generate"
+}
+
+@test "generate: uses ARGOCD_APP_NAMESPACE as release namespace" {
+  write_helmfile helmfile.yaml
+  plugin_init
+  run_plugin generate
+  assert_success
+  assert_equal "$(probe_value releaseNamespace)" "test-ns"
+}
+
+@test "generate: HELMFILE_USE_CONTEXT_NAMESPACE=true does not force ARGOCD_APP_NAMESPACE" {
+  write_helmfile helmfile.yaml
+  export ARGOCD_ENV_HELMFILE_USE_CONTEXT_NAMESPACE="true"
+  plugin_init
+  run_plugin generate
+  assert_success
+  refute [ "$(probe_value releaseNamespace)" = "test-ns" ]
+}
+
+@test "generate: namespace set on a release wins with HELMFILE_USE_CONTEXT_NAMESPACE" {
+  cat >helmfile.yaml <<YAML
+releases:
+  - name: probe
+    namespace: other-ns
+    chart: ${WORK}/chart
+YAML
+  export ARGOCD_ENV_HELMFILE_USE_CONTEXT_NAMESPACE="true"
+  plugin_init
+  run_plugin generate
+  assert_success
+  assert_equal "$(probe_value releaseNamespace)" "other-ns"
+}
+
+@test "generate: HELM_TEMPLATE_OPTIONS is passed to helm template" {
+  write_helmfile helmfile.yaml
+  export ARGOCD_ENV_HELM_TEMPLATE_OPTIONS="--set marker=from-helm-options"
+  plugin_init
+  run_plugin generate
+  assert_success
+  assert_equal "$(probe_value marker)" "from-helm-options"
+}
+
+@test "generate: HELMFILE_TEMPLATE_OPTIONS is passed to helmfile template" {
+  write_helmfile helmfile.yaml
+  export ARGOCD_ENV_HELMFILE_TEMPLATE_OPTIONS="--set marker=from-helmfile-options"
+  plugin_init
+  run_plugin generate
+  assert_success
+  assert_equal "$(probe_value marker)" "from-helmfile-options"
+}
+
+@test "generate: HELMFILE_GLOBAL_OPTIONS selects the environment" {
+  cat >helmfile.yaml.gotmpl <<YAML
+environments:
+  default: {}
+  staging: {}
+---
+releases:
+  - name: probe
+    chart: ${WORK}/chart
+    set:
+      - name: marker
+        value: env-{{ .Environment.Name }}
+YAML
+  export ARGOCD_ENV_HELMFILE_GLOBAL_OPTIONS="--environment staging"
+  plugin_init
+  run_plugin generate
+  assert_success
+  assert_equal "$(probe_value marker)" "env-staging"
+}
+
+@test "generate: HELMFILE_GLOBAL_OPTIONS selector limits releases" {
+  write_helmfile helmfile.d/10-one.yaml one
+  write_helmfile helmfile.d/20-two.yaml two
+  export ARGOCD_ENV_HELMFILE_GLOBAL_OPTIONS="--selector name=two"
+  plugin_init
+  run_plugin generate
+  assert_success
+  assert_equal "$(probe_value releaseName one)" ""
+  assert_equal "$(probe_value releaseName two)" "two"
+}
+
+@test "generate: selector without matches is not an error" {
+  write_helmfile helmfile.yaml
+  export ARGOCD_ENV_HELMFILE_GLOBAL_OPTIONS="--selector name=does-not-exist"
+  plugin_init
+  run_plugin generate
+  assert_success
+}
+
+@test "generate: helmfile errors fail the phase" {
+  printf 'releases: [this is: not valid\n' >helmfile.yaml
+  run_plugin generate
+  assert_failure
+}
+
+@test "generate: HELMFILE_ENV_FILE is sourced" {
+  write_helmfile helmfile.yaml
+  cat >custom.env <<'ENV'
+HELM_TEMPLATE_OPTIONS="--set marker=from-env-file"
+ENV
+  export ARGOCD_ENV_HELMFILE_ENV_FILE="custom.env"
+  plugin_init
+  run_plugin generate
+  assert_success
+  assert_equal "$(probe_value marker)" "from-env-file"
+}
+
+@test "generate: default env file .argo-cd-helmfile-env is sourced" {
+  write_helmfile helmfile.yaml
+  cat >.argo-cd-helmfile-env <<'ENV'
+HELM_TEMPLATE_OPTIONS="--set marker=from-default-env-file"
+ENV
+  plugin_init
+  run_plugin generate
+  assert_success
+  assert_equal "$(probe_value marker)" "from-default-env-file"
+}
+
+@test "generate: variables in HELM_TEMPLATE_OPTIONS are expanded" {
+  write_helmfile helmfile.yaml
+  export PROBE_MARKER="from-expansion"
+  export ARGOCD_ENV_HELM_TEMPLATE_OPTIONS='--set marker=${PROBE_MARKER}'
+  plugin_init
+  run_plugin generate
+  assert_success
+  assert_equal "$(probe_value marker)" "from-expansion"
+}
+
+@test "generate: options are not glob-expanded" {
+  write_helmfile helmfile.yaml
+  touch "marker=globbed"
+  export ARGOCD_ENV_HELMFILE_TEMPLATE_OPTIONS="--set marker=*"
+  plugin_init
+  run_plugin generate
+  assert_success
+  assert_equal "$(probe_value marker)" "*"
+}
+
+@test "generate: multi-line HELMFILE_GLOBAL_OPTIONS are all applied" {
+  cat >helmfile.yaml.gotmpl <<YAML
+environments:
+  default: {}
+  staging: {}
+---
+releases:
+  - name: one
+    chart: ${WORK}/chart
+    set:
+      - name: marker
+        value: env-{{ .Environment.Name }}
+  - name: two
+    chart: ${WORK}/chart
+YAML
+  export ARGOCD_ENV_HELMFILE_GLOBAL_OPTIONS=$'--environment staging\n--selector name=one'
+  plugin_init
+  run_plugin generate
+  assert_success
+  assert_equal "$(probe_value marker one)" "env-staging"
+  assert_equal "$(probe_value releaseName two)" ""
+}
+
+@test "generate: failures report the phase once" {
+  printf 'releases: [this is: not valid\n' >helmfile.yaml
+  run_plugin generate
+  assert_failure
+  assert_output ""
+  run grep -c "generate failed" <<<"${stderr}"
+  assert_output "1"
+}
diff --git a/test/helpers.bash b/test/helpers.bash
new file mode 100644
index 0000000..114b73f
--- /dev/null
+++ b/test/helpers.bash
@@ -0,0 +1,108 @@
+# shellcheck shell=bash
+
+bats_require_minimum_version 1.5.0
+
+bats_load_library bats-support
+bats_load_library bats-assert
+
+REPO_ROOT="$(cd "${BATS_TEST_DIRNAME}/.." && pwd)"
+PLUGIN="${REPO_ROOT}/src/argocd-helmfile-plugin.sh"
+FIXTURES="${BATS_TEST_DIRNAME}/fixtures"
+
+# shellcheck disable=SC2034 # used by the .bats files
+INJECTED_DIR=".__argocd-helmfile-plugin.sh__helmfile.d"
+
+common_setup() {
+  WORK="${BATS_TEST_TMPDIR}/src"
+  mkdir -p "${WORK}"
+  cp -r "${FIXTURES}/chart-probe" "${WORK}/chart"
+  cd "${WORK}" || return 1
+
+  # Standard Argo CD build environment.
+  export ARGOCD_APP_NAME="test-app"
+  export ARGOCD_APP_NAMESPACE="test-ns"
+  export ARGOCD_APP_REVISION="0000000000000000000000000000000000000000"
+  export ARGOCD_APP_SOURCE_PATH="."
+  export ARGOCD_APP_SOURCE_REPO_URL="https://example.invalid/repo.git"
+  export ARGOCD_APP_SOURCE_TARGET_REVISION="main"
+
+  # Isolate helm/helmfile state per test.
+  unset HELM_HOME
+  export PLUGIN_APP_HOME="${BATS_TEST_TMPDIR}/home"
+  export HELM_CACHE_HOME="${BATS_TEST_TMPDIR}/helm/cache"
+  export HELM_CONFIG_HOME="${BATS_TEST_TMPDIR}/helm/config"
+  export HELM_DATA_HOME="${BATS_TEST_TMPDIR}/helm/data"
+
+  unset DEBUG KUBE_VERSION KUBE_API_VERSIONS \
+    HELM_BINARY HELMFILE_BINARY \
+    HELM_TEMPLATE_OPTIONS HELMFILE_TEMPLATE_OPTIONS HELMFILE_GLOBAL_OPTIONS \
+    HELMFILE_HELMFILE HELMFILE_HELMFILE_STRATEGY HELMFILE_INIT_SCRIPT_FILE \
+    HELMFILE_ENV_FILE HELMFILE_CACHE_CLEANUP HELMFILE_REPO_CACHE_TIMEOUT \
+    HELMFILE_USE_CONTEXT_NAMESPACE HELMFILE_DISCOVERY_RESPONSE
+  export KUBECONFIG="${BATS_TEST_TMPDIR}/no-kubeconfig"
+}
+
+# Usage: write_helmfile [file] [release-name]
+write_helmfile() {
+  local file="${1:-helmfile.yaml}" name="${2:-probe}"
+  mkdir -p "$(dirname "${file}")"
+  cat >"${file}" <<YAML
+releases:
+  - name: ${name}
+    chart: ${WORK}/chart
+YAML
+}
+
+run_plugin() {
+  run --separate-stderr bash "${PLUGIN}" "$@"
+}
+
+# Run init and fail the test if it fails.
+plugin_init() {
+  run_plugin init
+  assert_success
+}
+
+# Usage: make_fake_version <helm|helmfile> <version output>
+make_fake_version() {
+  local tool="$1" version_output="$2" real dir
+  real="$(command -v "${tool}")"
+  dir="${BATS_TEST_TMPDIR}/fake-${tool}"
+  mkdir -p "${dir}"
+  cat >"${dir}/${tool}" <<SH
+#!/bin/bash
+case "\$*" in
+  "version --template {{.Version}}" | "--version") echo "${version_output}" ;;
+  *) exec "${real}" "\$@" ;;
+esac
+SH
+  chmod +x "${dir}/${tool}"
+  echo "${dir}/${tool}"
+}
+
+# Usage: make_call_logger <helm|helmfile>
+make_call_logger() {
+  local tool="$1" real dir
+  real="$(command -v "${tool}")"
+  dir="${BATS_TEST_TMPDIR}/wrap"
+  mkdir -p "${dir}"
+  cat >"${dir}/${tool}" <<SH
+#!/bin/bash
+echo "${tool} \$*" >>"${BATS_TEST_TMPDIR}/${tool}-calls.log"
+exec "${real}" "\$@"
+SH
+  chmod +x "${dir}/${tool}"
+  echo "${dir}/${tool}"
+}
+
+# shellcheck disable=SC2154 # $output is set by bats "run"
+# Usage: probe_value <key> [release-name]
+probe_value() {
+  local key="$1" name="${2:-probe}"
+  printf '%s\n' "${output}" |
+    awk -v name="${name}" -v key="${key}" '
+      /^---/                          { in_doc = 0 }
+      $1 == "name:" && $2 == name     { in_doc = 1 }
+      in_doc && $1 == key ":"         { v = $2; gsub(/"/, "", v); print v; exit }
+    '
+}
\ No newline at end of file
diff --git a/test/init.bats b/test/init.bats
new file mode 100644
index 0000000..403a621
--- /dev/null
+++ b/test/init.bats
@@ -0,0 +1,230 @@
+#!/usr/bin/env bats
+# init phase: runs before every generate. Prepares helmfile input and repos.
+
+setup() {
+  load helpers
+  common_setup
+}
+
+
+@test "init: succeeds for a plain helmfile.yaml" {
+  write_helmfile helmfile.yaml
+  run_plugin init
+  assert_success
+  assert_regex "${stderr}" "starting init"
+}
+
+@test "init: fails without a phase argument" {
+  run_plugin
+  assert_failure
+  assert_regex "${stderr}" "invalid invocation"
+}
+
+@test "init: fails for an unknown phase" {
+  run_plugin bogus
+  assert_failure
+  assert_regex "${stderr}" "invalid invocation"
+}
+
+# --- repo cache -------------------------------------------------------------
+
+@test "init: repos update runs every time without HELMFILE_REPO_CACHE_TIMEOUT" {
+  write_helmfile helmfile.yaml
+  plugin_init
+  run_plugin init
+  assert_success
+  refute_regex "${stderr}" "skipping repos update due to cache"
+}
+
+@test "init: repos update is skipped within HELMFILE_REPO_CACHE_TIMEOUT" {
+  write_helmfile helmfile.yaml
+  export ARGOCD_ENV_HELMFILE_REPO_CACHE_TIMEOUT="300"
+  plugin_init
+  refute_regex "${stderr}" "skipping repos update due to cache"
+  run_plugin init
+  assert_success
+  assert_regex "${stderr}" "skipping repos update due to cache"
+}
+
+@test "init: a new revision busts the repo cache" {
+  write_helmfile helmfile.yaml
+  export ARGOCD_ENV_HELMFILE_REPO_CACHE_TIMEOUT="300"
+  plugin_init
+  export ARGOCD_APP_REVISION="1111111111111111111111111111111111111111"
+  run_plugin init
+  assert_success
+  refute_regex "${stderr}" "skipping repos update due to cache"
+}
+
+@test "init: HELMFILE_CACHE_CLEANUP=true succeeds" {
+  write_helmfile helmfile.yaml
+  export ARGOCD_ENV_HELMFILE_CACHE_CLEANUP="true"
+  run_plugin init
+  assert_success
+}
+
+# --- init script ------------------------------------------------------------
+
+@test "init: HELMFILE_INIT_SCRIPT_FILE is executed in the source directory" {
+  write_helmfile helmfile.yaml
+  cat >init.sh <<'SH'
+pwd >init-ran.txt
+SH
+  export ARGOCD_ENV_HELMFILE_INIT_SCRIPT_FILE="init.sh"
+  plugin_init
+  assert [ -f init-ran.txt ]
+  assert_equal "$(cat init-ran.txt)" "${WORK}"
+}
+
+@test "init: HELMFILE_INIT_SCRIPT_FILE path is variable-expanded" {
+  write_helmfile helmfile.yaml
+  mkdir scripts
+  printf 'touch init-ran.txt\n' >scripts/init.sh
+  export PROBE_SCRIPTS_DIR="scripts"
+  export ARGOCD_ENV_HELMFILE_INIT_SCRIPT_FILE='${PROBE_SCRIPTS_DIR}/init.sh'
+  plugin_init
+  assert [ -f init-ran.txt ]
+}
+
+@test "init: a failing HELMFILE_INIT_SCRIPT_FILE fails init" {
+  write_helmfile helmfile.yaml
+  printf 'exit 3\n' >init.sh
+  export ARGOCD_ENV_HELMFILE_INIT_SCRIPT_FILE="init.sh"
+  run_plugin init
+  assert_failure
+}
+
+# --- HELMFILE_HELMFILE ------------------------------------------------------
+
+@test "init: HELMFILE_HELMFILE defaults to REPLACE and ignores repo helmfile" {
+  write_helmfile helmfile.yaml from-repo
+  write_helmfile "${BATS_TEST_TMPDIR}/injected.yaml" from-param
+  ARGOCD_ENV_HELMFILE_HELMFILE="$(cat "${BATS_TEST_TMPDIR}/injected.yaml")"
+  export ARGOCD_ENV_HELMFILE_HELMFILE
+  plugin_init
+  run ls -A "${INJECTED_DIR}"
+  assert_output "ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ__argocd__helmfile__.yaml"
+
+  run_plugin generate
+  assert_success
+  assert_equal "$(probe_value releaseName from-param)" "from-param"
+  assert_equal "$(probe_value releaseName from-repo)" ""
+}
+
+@test "init: HELMFILE_HELMFILE with INCLUDE renders repo helmfile.yaml and param" {
+  write_helmfile helmfile.yaml from-repo
+  write_helmfile "${BATS_TEST_TMPDIR}/injected.yaml" from-param
+  ARGOCD_ENV_HELMFILE_HELMFILE="$(cat "${BATS_TEST_TMPDIR}/injected.yaml")"
+  export ARGOCD_ENV_HELMFILE_HELMFILE
+  export ARGOCD_ENV_HELMFILE_HELMFILE_STRATEGY="INCLUDE"
+  plugin_init
+  assert [ -f "${INJECTED_DIR}/helmfile.yaml" ]
+
+  run_plugin generate
+  assert_success
+  assert_equal "$(probe_value releaseName from-param)" "from-param"
+  assert_equal "$(probe_value releaseName from-repo)" "from-repo"
+}
+
+@test "init: INCLUDE copies helmfile.yaml.gotmpl" {
+  write_helmfile helmfile.yaml.gotmpl from-repo
+  export ARGOCD_ENV_HELMFILE_HELMFILE="releases: []"
+  export ARGOCD_ENV_HELMFILE_HELMFILE_STRATEGY="INCLUDE"
+  plugin_init
+  assert [ -f "${INJECTED_DIR}/helmfile.yaml.gotmpl" ]
+}
+
+@test "init: INCLUDE copies the contents of helmfile.d" {
+  write_helmfile helmfile.d/10-one.yaml one
+  write_helmfile helmfile.d/20-two.yaml two
+  export ARGOCD_ENV_HELMFILE_HELMFILE="releases: []"
+  export ARGOCD_ENV_HELMFILE_HELMFILE_STRATEGY="INCLUDE"
+  plugin_init
+  assert [ -f "${INJECTED_DIR}/10-one.yaml" ]
+  assert [ -f "${INJECTED_DIR}/20-two.yaml" ]
+
+  run_plugin generate
+  assert_success
+  assert_equal "$(probe_value releaseName one)" "one"
+  assert_equal "$(probe_value releaseName two)" "two"
+}
+
+@test "init: INCLUDE warns when more than one helmfile source exists" {
+  # Current behaviour is a warning only; planned to become a hard failure.
+  write_helmfile helmfile.yaml
+  write_helmfile helmfile.d/10-one.yaml one
+  export ARGOCD_ENV_HELMFILE_HELMFILE="releases: []"
+  export ARGOCD_ENV_HELMFILE_HELMFILE_STRATEGY="INCLUDE"
+  run_plugin init
+  assert_regex "${stderr}" "but not more than one"
+}
+
+@test "init: invalid HELMFILE_HELMFILE_STRATEGY fails" {
+  export ARGOCD_ENV_HELMFILE_HELMFILE="releases: []"
+  export ARGOCD_ENV_HELMFILE_HELMFILE_STRATEGY="MERGE"
+  run_plugin init
+  assert_failure
+  assert_regex "${stderr}" "invalid .HELMFILE_HELMFILE_STRATEGY"
+}
+
+@test "init: re-running init removes stale injected files" {
+  write_helmfile helmfile.yaml
+  export ARGOCD_ENV_HELMFILE_HELMFILE="releases: []"
+  export ARGOCD_ENV_HELMFILE_HELMFILE_STRATEGY="INCLUDE"
+  plugin_init
+  assert [ -f "${INJECTED_DIR}/helmfile.yaml" ]
+  export ARGOCD_ENV_HELMFILE_HELMFILE_STRATEGY="REPLACE"
+  plugin_init
+  refute [ -f "${INJECTED_DIR}/helmfile.yaml" ]
+}
+
+@test "init: INCLUDE keeps relative chart paths working" {
+  # INCLUDE copies the repo helmfile into ${INJECTED_DIR}. With a directory of
+  # helmfiles, helmfile >= 1.2 resolves relative chart paths against the
+  # working directory, older versions against the copied file (known bug).
+  local version
+  version="$(helmfile --version | sed -E 's/.*version v?([0-9]+\.[0-9]+).*/\1/')"
+  if [[ "$(printf '%s\n' "${version}" 1.2 | sort -V | head -1)" != "1.2" ]]; then
+    skip "known bug: relative chart paths break with INCLUDE on helmfile ${version} < 1.2 (fix planned)"
+  fi
+  cat >helmfile.yaml <<'YAML'
+releases:
+  - name: probe
+    chart: ./chart
+YAML
+  export ARGOCD_ENV_HELMFILE_HELMFILE="releases: []"
+  export ARGOCD_ENV_HELMFILE_HELMFILE_STRATEGY="INCLUDE"
+  plugin_init
+  run_plugin generate
+  assert_success
+  assert_equal "$(probe_value releaseName)" "probe"
+}
+
+@test "init: INCLUDE keeps relative values paths working" {
+  skip "known bug: files are copied into ${INJECTED_DIR}, relative values paths break (fix planned)"
+  printf 'marker: from-values-file\n' >values-probe.yaml
+  cat >helmfile.yaml <<YAML
+releases:
+  - name: probe
+    chart: ${WORK}/chart
+    values:
+      - values-probe.yaml
+YAML
+  export ARGOCD_ENV_HELMFILE_HELMFILE="releases: []"
+  export ARGOCD_ENV_HELMFILE_HELMFILE_STRATEGY="INCLUDE"
+  plugin_init
+  run_plugin generate
+  assert_success
+  assert_equal "$(probe_value marker)" "from-values-file"
+}
+
+@test "init: templated HELMFILE_HELMFILE is rendered" {
+  skip "known bug: injected file is written as .yaml, helmfile v1 only templates .gotmpl (fix planned)"
+  export ARGOCD_ENV_HELMFILE_HELMFILE="releases:
+  - name: {{ \"probe\" }}
+    chart: ${WORK}/chart"
+  plugin_init
+  run_plugin generate
+  assert_success
+  assert_equal "$(probe_value releaseName)" "probe"
+}
diff --git a/test/parameters.bats b/test/parameters.bats
new file mode 100644
index 0000000..6d3bd71
--- /dev/null
+++ b/test/parameters.bats
@@ -0,0 +1,44 @@
+#!/usr/bin/env bats
+# parameters phase: dynamic parameter announcement for the Argo CD UI.
+
+setup() {
+  load helpers
+  common_setup
+}
+
+@test "parameters: prints valid JSON array on stdout" {
+  run_plugin parameters
+  assert_success
+  run jq -e 'type == "array" and length > 0' <<<"${output}"
+  assert_success
+}
+
+@test "parameters: every entry has name, title and tooltip" {
+  run_plugin parameters
+  assert_success
+  run jq -e 'all(.[]; has("name") and has("title") and has("tooltip"))' <<<"${output}"
+  assert_success
+}
+
+@test "parameters: announces the expected parameter names" {
+  run_plugin parameters
+  assert_success
+  run jq -r '.[].name' <<<"${output}"
+  assert_success
+  assert_output "$(printf '%s\n' \
+    HELM_TEMPLATE_OPTIONS \
+    HELMFILE_TEMPLATE_OPTIONS \
+    HELMFILE_GLOBAL_OPTIONS \
+    HELMFILE_HELMFILE \
+    HELMFILE_HELMFILE_STRATEGY \
+    HELMFILE_INIT_SCRIPT_FILE \
+    HELMFILE_CACHE_CLEANUP \
+    HELMFILE_USE_CONTEXT_NAMESPACE)"
+}
+
+@test "parameters: boolean parameters are typed as boolean" {
+  run_plugin parameters
+  assert_success
+  run jq -r '.[] | select(.itemType == "boolean") | .name' <<<"${output}"
+  assert_output "$(printf '%s\n' HELMFILE_CACHE_CLEANUP HELMFILE_USE_CONTEXT_NAMESPACE)"
+}
diff --git a/test/versions.bats b/test/versions.bats
new file mode 100644
index 0000000..259cc5e
--- /dev/null
+++ b/test/versions.bats
@@ -0,0 +1,185 @@
+#!/usr/bin/env bats
+# Tool version detection: Helm 2 is not supported, Helm >= 3.6 and
+# helmfile >= 1 (>= 1.2 with Helm 4) are required. Versions are only checked in init/generate.
+
+setup() {
+  load helpers
+  common_setup
+  write_helmfile helmfile.yaml
+}
+
+@test "versions: helm and helmfile versions are logged to stderr" {
+  run_plugin init
+  assert_success
+  assert_regex "${stderr}" "helm version v[0-9]+\.[0-9]+\.[0-9]+"
+  assert_regex "${stderr}" "helmfile version v?[0-9]+\.[0-9]+"
+  refute_output --partial "version"
+}
+
+@test "versions: current helm is accepted in init and generate" {
+  plugin_init
+  run_plugin generate
+  assert_success
+}
+
+@test "versions: helm 2 is rejected" {
+  HELM_BINARY="$(make_fake_version helm "v2.17.0")"
+  export HELM_BINARY
+  run_plugin init
+  assert_failure
+  assert_regex "${stderr}" "helm v2.17.0 is not supported, helm >= 3.6 is required"
+}
+
+@test "versions: helm 2 is rejected in generate" {
+  HELM_BINARY="$(make_fake_version helm "v2.17.0")"
+  export HELM_BINARY
+  run_plugin generate
+  assert_failure
+  assert_output ""
+  assert_regex "${stderr}" "helm >= 3.6 is required"
+}
+
+@test "versions: helm 3 and 4 versions are accepted" {
+  local v
+  # fake a helm 4 compatible helmfile so the real helmfile version does not matter
+  HELMFILE_BINARY="$(make_fake_version helmfile "helmfile version 1.2.0")"
+  export HELMFILE_BINARY
+  for v in v3.6.0 v3.19.4 v4.0.0 v4.2.3; do
+    HELM_BINARY="$(make_fake_version helm "${v}")"
+    export HELM_BINARY
+    run_plugin init
+    assert_success
+    assert_regex "${stderr}" "helm version ${v}"
+  done
+}
+
+@test "versions: helm older than 3.6 is rejected" {
+  local v
+  for v in v3.0.0 v3.5.4; do
+    HELM_BINARY="$(make_fake_version helm "${v}")"
+    export HELM_BINARY
+    run_plugin init
+    assert_failure
+    assert_regex "${stderr}" "helm ${v} is not supported, helm >= 3.6 is required"
+  done
+}
+
+@test "versions: helmfile older than 1.2 is rejected with helm 4" {
+  HELM_BINARY="$(make_fake_version helm "v4.0.0")"
+  HELMFILE_BINARY="$(make_fake_version helmfile "helmfile version 1.1.9")"
+  export HELM_BINARY HELMFILE_BINARY
+  run_plugin init
+  assert_failure
+  assert_regex "${stderr}" "helmfile >= 1.2 is required for helm 4"
+}
+
+@test "versions: helmfile 1.2 is accepted with helm 4" {
+  HELM_BINARY="$(make_fake_version helm "v4.0.0")"
+  HELMFILE_BINARY="$(make_fake_version helmfile "helmfile version 1.2.0")"
+  export HELM_BINARY HELMFILE_BINARY
+  run_plugin init
+  assert_success
+}
+
+@test "versions: helmfile older than 1.2 is accepted with helm 3" {
+  HELM_BINARY="$(make_fake_version helm "v3.19.4")"
+  HELMFILE_BINARY="$(make_fake_version helmfile "helmfile version 1.1.9")"
+  export HELM_BINARY HELMFILE_BINARY
+  run_plugin init
+  assert_success
+}
+
+@test "versions: unparsable helm version is rejected" {
+  HELM_BINARY="$(make_fake_version helm "<no value>")"
+  export HELM_BINARY
+  run_plugin init
+  assert_failure
+  assert_regex "${stderr}" "unable to parse helm version"
+}
+
+@test "versions: failing helm binary is rejected" {
+  export HELM_BINARY="${BATS_TEST_TMPDIR}/does-not-exist/helm"
+  run_plugin init
+  assert_failure
+  assert_regex "${stderr}" "failed to run .* version"
+}
+
+@test "versions: helmfile 0.x is rejected" {
+  HELMFILE_BINARY="$(make_fake_version helmfile "helmfile version v0.171.0")"
+  export HELMFILE_BINARY
+  run_plugin init
+  assert_failure
+  assert_regex "${stderr}" "helmfile >= 1 is required"
+}
+
+@test "versions: helmfile 1.x is accepted with and without v prefix" {
+  local v
+  for v in "helmfile version 1.5.2" "helmfile version v1.2.0"; do
+    HELMFILE_BINARY="$(make_fake_version helmfile "${v}")"
+    export HELMFILE_BINARY
+    run_plugin init
+    assert_success
+  done
+}
+
+@test "versions: unparsable helmfile version is rejected" {
+  HELMFILE_BINARY="$(make_fake_version helmfile "something else")"
+  export HELMFILE_BINARY
+  run_plugin init
+  assert_failure
+  assert_regex "${stderr}" "unable to parse helmfile version"
+}
+
+@test "versions: discover and parameters do not run helm or helmfile" {
+  HELM_BINARY="$(make_call_logger helm)"
+  HELMFILE_BINARY="$(make_call_logger helmfile)"
+  export HELM_BINARY HELMFILE_BINARY
+  run_plugin discover
+  assert_success
+  run_plugin parameters
+  assert_success
+  refute [ -e "${BATS_TEST_TMPDIR}/helm-calls.log" ]
+  refute [ -e "${BATS_TEST_TMPDIR}/helmfile-calls.log" ]
+}
+
+@test "versions: discover and parameters work even with helm 2" {
+  HELM_BINARY="$(make_fake_version helm "v2.17.0")"
+  export HELM_BINARY
+  run_plugin discover
+  assert_success
+  run_plugin parameters
+  assert_success
+}
+
+@test "versions: plugin queries the helm version once per phase" {
+  HELM_BINARY="$(make_call_logger helm)"
+  export HELM_BINARY
+  plugin_init
+  # helmfile runs its own "helm version --short"; only count the plugin's query
+  run grep -c '^helm version --template' "${BATS_TEST_TMPDIR}/helm-calls.log"
+  assert_output "1"
+}
+
+@test "versions: helm init is never called" {
+  HELM_BINARY="$(make_call_logger helm)"
+  export HELM_BINARY
+  plugin_init
+  run grep '^helm init' "${BATS_TEST_TMPDIR}/helm-calls.log"
+  assert_failure
+}
+
+@test "versions: HELMFILE_HELM3 is not exported" {
+  cat >helmfile.yaml.gotmpl <<YAML
+releases:
+  - name: probe
+    chart: ${WORK}/chart
+    set:
+      - name: marker
+        value: helm3-[{{ env "HELMFILE_HELM3" }}]
+YAML
+  rm helmfile.yaml
+  plugin_init
+  run_plugin generate
+  assert_success
+  assert_equal "$(probe_value marker)" "helm3-[]"
+}