Run sequentially for run-parallel -p 0 instead of at CPU count (#3989)

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Signed-off-by: chuenchen309 <48723787+chuenchen309@users.noreply.github.com>

Author: 3 people

docs/changelog/3989.bugfix.rst

@@ -0,0 +1,2 @@
+Make ``tox run-parallel -p 0`` turn parallelism off and run sequentially, as the ``-p`` help ("zero is turn off") and
+the legacy command already promise, instead of running at the CPU count - by :user:`chuenchen309`.

src/tox/session/cmd/run/parallel.py

@@ -91,7 +91,7 @@ def run_parallel(state: State) -> int:
         raise SystemExit(msg)
     return execute(
         state,
-        max_workers=auto_detect_cpus() if option.parallel == 0 else option.parallel,
+        max_workers=1 if option.parallel == OFF_VALUE else option.parallel,
         has_spinner=option.parallel_no_spinner is False and option.parallel_live is False,
         live=option.parallel_live,
     )

tests/session/cmd/test_parallel.py

@@ -48,6 +48,16 @@ def test_parse_num_processes_minus_one() -> None:
         parse_num_processes("-1")
 
 
+def test_parallel_zero_turns_off(tox_project: ToxProjectCreator, mocker: MockerFixture) -> None:
+    # The -p help says "zero is turn off", so -p 0 must run sequentially (one
+    # worker) rather than auto-detecting the CPU count like -p auto.
+    execute = mocker.patch.object(parallel, "execute", return_value=0)
+    project = tox_project({"tox.ini": "[tox]\nno_package=true\nenv_list=a,b\n[testenv]\ncommands=python -c 'pass'\n"})
+    project.run("p", "-p", "0")
+
+    assert execute.call_args.kwargs["max_workers"] == 1
+
+
 def test_parallel_general(tox_project: ToxProjectCreator, monkeypatch: MonkeyPatch, mocker: MockerFixture) -> None:
     def setup(self: ToxEnv) -> None:
         if self.name == "f":