fix(config): resolve overrides with alias config keys

When using TOX_OVERRIDE with += (append) and the override key differs
from the config file key (e.g., pass_env vs passenv), the config
value was lost. Now Loader.load() checks all alias keys for both
raw config values and overrides.

Fixes #3127, fixes #3348.

Author: gaborbernat

docs/changelog/3127.bugfix.rst

@@ -0,0 +1,2 @@
+``TOX_OVERRIDE`` with ``+=`` (append) now works correctly when the override key name differs from the config file key
+name (e.g., overriding ``pass_env`` when config uses ``passenv``, or vice versa) - by :user:`gaborbernat`.

src/tox/config/loader/api.py

@@ -2,7 +2,7 @@
 
 from abc import abstractmethod
 from argparse import ArgumentTypeError
-from collections.abc import Mapping
+from collections.abc import Iterable, Mapping
 from typing import TYPE_CHECKING, Any, TypeVar, cast
 
 from tox.plugin import impl
@@ -120,13 +120,14 @@ def __repr__(self) -> str:
     def __contains__(self, item: str) -> bool:
         return item in self.found_keys()
 
-    def load(
+    def load(  # noqa: PLR0913
         self,
         key: str,
         of_type: type[V] | UnionType,
         factory: Factory[V],
         conf: Config | None,
         args: ConfigLoadArgs,
+        all_keys: Iterable[str] = (),
     ) -> V:
         """Load a value (raw and then convert).
 
@@ -135,22 +136,18 @@ def load(
         :param factory: factory method to build the object
         :param conf: the configuration object of this tox session (needed to manifest the value)
         :param args: the config load arguments
+        :param all_keys: all alias keys for this config entry (to collect overrides from any alias)
 
         :returns: the converted type
 
         """
         from tox.config.set_env import SetEnv  # noqa: PLC0415
 
-        overrides = self.overrides.get(key, [])
-
-        try:
-            raw = self.load_raw(key, conf, args.env_name)
-        except KeyError:
-            converted = None
-            if not overrides:
-                raise
-        else:
-            converted = self.build(key, of_type, factory, conf, raw, args)
+        overrides = [o for alias in (key, *all_keys) for o in self.overrides.get(alias, [])]
+        if (
+            converted := self._load_raw_with_aliases(key, of_type, factory, conf, args, all_keys)
+        ) is None and not overrides:
+            raise KeyError(key)
 
         for override in overrides:
             converted_override = _STR_CONVERT.to(override.value, of_type, factory)
@@ -171,6 +168,23 @@ def load(
 
         return cast("V", converted)  # guaranteed non-None: either build() succeeded or overrides set it
 
+    def _load_raw_with_aliases(  # noqa: PLR0913
+        self,
+        key: str,
+        of_type: type[V] | UnionType,
+        factory: Factory[V],
+        conf: Config | None,
+        args: ConfigLoadArgs,
+        all_keys: Iterable[str],
+    ) -> V | None:
+        for alias in (key, *all_keys):
+            try:
+                raw = self.load_raw(alias, conf, args.env_name)
+            except KeyError:
+                continue
+            return self.build(alias, of_type, factory, conf, raw, args)
+        return None
+
     def build(  # noqa: PLR0913
         self,
         key: str,  # noqa: ARG002

src/tox/config/of_type.py

@@ -3,7 +3,6 @@
 from __future__ import annotations
 
 from abc import ABC, abstractmethod
-from itertools import product
 from typing import TYPE_CHECKING, Generic, TypeVar, cast
 
 from tox.config.loader.api import ConfigLoadArgs, Loader
@@ -100,8 +99,9 @@ def __call__(
         args: ConfigLoadArgs,
     ) -> T:
         if self._cache is _PLACE_HOLDER:
-            for key, loader in product(self.keys, loaders):
-                chain_key = f"{loader.section.key}.{key}"
+            primary_key, *alias_keys = self.keys
+            for loader in loaders:
+                chain_key = f"{loader.section.key}.{primary_key}"
                 try:
                     if chain_key in args.chain:
                         values = args.chain[args.chain.index(chain_key) :]
@@ -110,7 +110,7 @@ def __call__(
                 finally:
                     args.chain.append(chain_key)
                 try:
-                    value = loader.load(key, self.of_type, self.factory, conf, args)
+                    value = loader.load(primary_key, self.of_type, self.factory, conf, args, all_keys=alias_keys)
                 except KeyError:
                     continue
                 else:

tests/config/test_main.py

@@ -95,6 +95,25 @@ def test_config_override_appends_to_empty_list(tox_ini_conf: ToxIniCreator) -> N
     assert conf["passenv"] == ["bar"]
 
 
+@pytest.mark.parametrize(
+    ("ini_key", "override_key"),
+    [
+        pytest.param("passenv", "pass_env", id="ini_old_override_new"),
+        pytest.param("pass_env", "passenv", id="ini_new_override_old"),
+    ],
+)
+def test_config_override_append_alias_key(tox_ini_conf: ToxIniCreator, ini_key: str, override_key: str) -> None:
+    example = f"""
+    [testenv]
+    {ini_key} = foo
+    """
+    conf = tox_ini_conf(example, override=[Override(f"testenv.{override_key}+=bar")]).get_env("testenv")
+    conf.add_config(["pass_env", "passenv"], of_type=list[str], default=[], desc="desc")
+    result = conf["pass_env"]
+    assert "foo" in result
+    assert "bar" in result
+
+
 def test_config_override_appends_to_setenv(tox_ini_conf: ToxIniCreator) -> None:
     example = """
     [testenv]