🐛 fix(config): substitute inside override values (#4048)

Author: gaborbernat

docs/changelog/4047.bugfix.rst

@@ -0,0 +1,2 @@
+Values passed via ``--override``/``-x`` or ``TOX_OVERRIDE`` now resolve substitutions such as ``{posargs}``,
+``{env:VAR}`` and ``{env_name}``, instead of reaching the environment as literal text - by :user:`gaborbernat`.

docs/explanation.rst

@@ -347,6 +347,18 @@ shape one more key.
 
 For the configuration reference, see :ref:`env-base-templates`. For practical recipes, see :ref:`howto_env_base_matrix`.
 
+Overrides and substitution
+==========================
+
+An override arrives as one command line string, whatever the configuration file format, so tox converts it with the ini
+string rules rather than the TOML ones. That is why ``-x env_run_base.commands=pytest tests`` works in a TOML project
+even though the file itself spells commands as a list of lists.
+
+The value still goes through the substitution pass belonging to the loader it overrides, which is what lets
+``{posargs}`` and ``{env:VAR}`` resolve inside it. Skipping that pass would make an override the one place in tox where
+a ``{...}`` reference means nothing, and a command overridden for a single run would stop forwarding the arguments given
+to it with no sign that it had.
+
 .. _work-dir-placement:
 
 Work directory placement

docs/how-to/usage.rst

@@ -191,6 +191,13 @@ location can be changed via the ``TOX_CONFIG_FILE`` environment variable.
     # Force editable install for a specific environment
     tox run -e 3.13 -x "testenv:3.13.package=editable"
 
+An override value takes substitutions, so it can reach the same values the configuration file can:
+
+.. code-block:: bash
+
+    # Swap the test command for one run, keeping the positional arguments working
+    tox run -e 3.13 -x 'env_run_base.commands=pytest {posargs:tests}' -- -k slow
+
 .. _howto_out_of_tree_envs:
 
 ********************************************

docs/reference/config.rst

@@ -2281,6 +2281,21 @@ Or reset override and append to that (note the first override is ``=`` and not `
 
        tox -x testenv.deps=pytest-xdist -x testenv.deps+=pytest-cov
 
+Substitutions inside an override
+================================
+
+.. versionadded:: 4.61
+
+An override value goes through the same substitution pass as a value written in the configuration file, so
+``{posargs}``, ``{env:VAR}``, ``{env_name}`` and the rest resolve there too:
+
+.. code-block:: bash
+
+    $ tox -x env_run_base.commands='pytest {posargs:tests}' -e py -- -k slow
+
+This runs ``pytest -k slow``. Overrides carry a command line string whatever the configuration file format, so the ini
+spelling of a substitution applies in a TOML project as well.
+
 Overrides propagate through references
 ======================================
 

docs/tutorial/getting-started.rst

@@ -257,7 +257,8 @@ Pass extra arguments to the underlying tool using ``--``:
     tox run -e lint -- src/mymodule.py
 
 The ``{ replace = "posargs" }`` in TOML (or ``{posargs}`` in INI) is a placeholder that gets replaced by whatever you
-pass after ``--``.
+pass after ``--``. The same placeholder works in a ``-x`` override, so you can swap a command for one run without losing
+the arguments you pass it.
 
 **************************
  Understanding the output

src/tox/config/loader/api.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import inspect
 from abc import abstractmethod
 from argparse import ArgumentTypeError
 from collections.abc import Iterable, Mapping
@@ -179,8 +180,15 @@ def load(  # ruff:ignore[too-many-arguments]
             if not overrides:
                 raise KeyError(key)
 
+        delay_replace = inspect.isclass(of_type) and issubclass(of_type, SetEnv)
         for override in overrides:
-            converted_override = _STR_CONVERT.to(override.value, of_type, factory)
+            # an override arrives as a raw CLI string, so it has not been through the loader's substitution pass yet
+            raw_override = (
+                override.value
+                if delay_replace or conf is None  # set_env expands later, the CLI config file never does
+                else self.substitute(override.value, conf, args)
+            )
+            converted_override = _STR_CONVERT.to(raw_override, of_type, factory)
             if override.append and converted is not None:
                 if isinstance(converted, list) and isinstance(converted_override, list):
                     converted += converted_override
@@ -219,6 +227,18 @@ def build(  # ruff:ignore[too-many-arguments]
         """
         return self.to(raw, of_type, factory)
 
+    def substitute(self, value: str, conf: Config, args: ConfigLoadArgs) -> str:
+        """Apply this loader's replacements to a raw string.
+
+        :param value: the raw string
+        :param conf: the global config
+        :param args: env args
+
+        :returns: the string with every substitution this loader understands resolved
+
+        """
+        raise NotImplementedError
+
 
 def apply_overrides_to_raw(overrides: Iterable[Override], key: str, value: T) -> T:
     """Fold the overrides targeting ``key`` onto a raw (pre-conversion) value.

src/tox/config/loader/ini/__init__.py

@@ -112,6 +112,9 @@ def replacer(raw_: str, args_: ConfigLoadArgs) -> str:
             cast("SetEnv", converted).use_replacer(replacer, args)  # delay_replace means of_type is SetEnv
         return converted
 
+    def substitute(self, value: str, conf: Config, args: ConfigLoadArgs) -> str:
+        return replace(conf, ReplaceReferenceIni(conf, self), value, args)
+
     def found_keys(self) -> set[str]:
         return set(self._section_proxy.keys())
 

src/tox/config/loader/toml/__init__.py

@@ -92,6 +92,9 @@ def _toml_replacer(value: str, args_: ConfigLoadArgs) -> str:
             cast("SetEnv", result).use_replacer(_toml_replacer, args=args)  # delay_replace means of_type is SetEnv
         return result
 
+    def substitute(self, value: str, conf: Config, args: ConfigLoadArgs) -> str:
+        return replace(conf, TomlReplaceLoader(conf, self), value, args)
+
     def found_keys(self) -> set[str]:
         return set(self.content.keys()) - self._unused_exclude
 

tests/config/loader/test_loader.py

@@ -8,7 +8,7 @@
 from tox.config.loader.api import Override, apply_overrides_to_raw
 
 if TYPE_CHECKING:
-    from tox.pytest import CaptureFixture
+    from tox.pytest import CaptureFixture, ToxProjectCreator
 
 
 @pytest.mark.parametrize("flag", ["-x", "--override"])
@@ -109,3 +109,46 @@ def test_apply_overrides_to_raw_ignores_other_keys() -> None:
 def test_apply_overrides_to_raw_append_unsupported_type() -> None:
     with pytest.raises(ValueError, match="Only able to append to lists, dicts and strings"):
         apply_overrides_to_raw([Override("ns.k+=1")], "k", 0)
+
+
+@pytest.mark.parametrize(
+    ("filename", "content", "namespace"),
+    [
+        pytest.param(
+            "tox.toml",
+            'env_list = ["a"]\n[env_run_base]\nskip_install = true\ncommands = [["python"]]\n',
+            "env_run_base",
+            id="toml",
+        ),
+        pytest.param(
+            "tox.ini",
+            "[tox]\nenv_list = a\n[testenv]\nskip_install = true\ncommands = python\n",
+            "testenv",
+            id="ini",
+        ),
+    ],
+)
+@pytest.mark.parametrize(
+    ("override", "posargs", "expected"),
+    [
+        pytest.param("python {posargs}", ["--", "tests", "src"], "python tests src", id="posargs"),
+        pytest.param("python {posargs:tests}", [], "python tests", id="posargs-default"),
+        pytest.param("python {env:MAGIC}", [], "python from-env", id="env"),
+        pytest.param("python {env_name}", [], "python a", id="env-name"),
+    ],
+)
+def test_override_value_is_substituted(
+    tox_project: ToxProjectCreator,
+    monkeypatch: pytest.MonkeyPatch,
+    filename: str,
+    content: str,
+    namespace: str,
+    override: str,
+    posargs: list[str],
+    expected: str,
+) -> None:
+    monkeypatch.setenv("MAGIC", "from-env")
+    project = tox_project({filename: content})
+    outcome = project.run("c", "-e", "a", "-k", "commands", "-x", f"{namespace}.commands={override}", *posargs)
+    outcome.assert_success()
+    outcome.assert_out_err(f"[testenv:a]\ncommands = {expected}\n", "")