tests(engine): parameterize server fixtures by engine option/marker

Author: tony

conftest.py

@@ -73,3 +73,36 @@ def setup_session(
     """Session-level test configuration for pytest."""
     if USING_ZSH:
         request.getfixturevalue("zshrc")
+
+
+def pytest_addoption(parser: pytest.Parser) -> None:
+    """Add CLI options for selecting tmux engine."""
+    parser.addoption(
+        "--engine",
+        action="store",
+        default="subprocess",
+        choices=["subprocess", "control"],
+        help="Select tmux engine for fixtures (default: subprocess).",
+    )
+
+
+def pytest_configure(config: pytest.Config) -> None:
+    """Register custom markers."""
+    config.addinivalue_line(
+        "markers",
+        (
+            "engines(names): run the test once for each engine in 'names' "
+            "(e.g. ['control', 'subprocess'])."
+        ),
+    )
+
+
+def pytest_generate_tests(metafunc: pytest.Metafunc) -> None:
+    """Parametrize engine_name when requested by tests."""
+    if "engine_name" in metafunc.fixturenames:
+        marker = metafunc.definition.get_closest_marker("engines")
+        if marker:
+            params = list(marker.args[0])
+        else:
+            params = [metafunc.config.getoption("--engine")]
+        metafunc.parametrize("engine_name", params, indirect=True)

docs/pytest-plugin/index.md

@@ -137,6 +137,31 @@ def set_home(
     monkeypatch.setenv("HOME", str(user_path))
 ```
 
+## Selecting tmux engines (experimental)
+
+Fixtures can run against different execution engines. By default the
+`subprocess` engine is used. You can choose control mode globally:
+
+```console
+$ pytest --engine=control
+```
+
+Or per-test via the `engines` marker (uses parametrization) and the `engine_name`
+fixture:
+
+```python
+import pytest
+
+@pytest.mark.engines(["subprocess", "control"])
+def test_my_flow(server, engine_name):
+    # server uses the selected engine, engine_name reflects the current one
+    assert engine_name in {"subprocess", "control"}
+    assert server.is_alive()
+```
+
+`TestServer` also respects the selected engine. Control mode is experimental and
+its APIs may change between releases.
+
 ## Fixtures
 
 ```{eval-rst}

src/libtmux/pytest_plugin.py

@@ -12,6 +12,9 @@
 import pytest
 
 from libtmux import exc
+from libtmux._internal.engines.base import Engine
+from libtmux._internal.engines.control_mode import ControlModeEngine
+from libtmux._internal.engines.subprocess_engine import SubprocessEngine
 from libtmux.server import Server
 from libtmux.test.constants import TEST_SESSION_PREFIX
 from libtmux.test.random import get_test_session_name, namer
@@ -115,6 +118,7 @@ def server(
     request: pytest.FixtureRequest,
     monkeypatch: pytest.MonkeyPatch,
     config_file: pathlib.Path,
+    engine_name: str,
 ) -> Server:
     """Return new, temporary :class:`libtmux.Server`.
 
@@ -141,7 +145,10 @@ def server(
 
         >>> result.assert_outcomes(passed=1)
     """
-    server = Server(socket_name=f"libtmux_test{next(namer)}")
+    server = Server(
+        socket_name=f"libtmux_test{next(namer)}",
+        engine=_build_engine(engine_name),
+    )
 
     def fin() -> None:
         server.kill()
@@ -311,5 +318,26 @@ def fin() -> None:
             Server,
             on_init=on_init,
             socket_name_factory=socket_name_factory,
+            engine=_build_engine(request.getfixturevalue("engine_name")),
         ),
     )
+
+
+@pytest.fixture
+def engine_name(request: pytest.FixtureRequest) -> str:
+    """Engine selector fixture, driven by CLI or parametrization."""
+    if hasattr(request, "param"):
+        return t.cast(str, request.param)
+    try:
+        return t.cast(str, request.config.getoption("--engine"))
+    except ValueError:
+        # Option may not be registered when libtmux is used purely as a plugin
+        # dependency in downstream projects. Default to subprocess for safety.
+        return "subprocess"
+
+
+def _build_engine(engine_name: str) -> Engine:
+    """Return engine instance by name."""
+    if engine_name == "control":
+        return ControlModeEngine()
+    return SubprocessEngine()