test(control_mode): add ControlMode context manager for client-dependent tests

why: Commands like display-popup and detach-client require an attached tmux
client. ControlMode spawns a real control-mode client via tmux -C, avoiding
mocks while enabling tests for client-dependent commands.
what:
- Add ControlMode context manager in src/libtmux/test/control_mode.py
  using FIFO + subprocess.Popen for tmux -C attach-session
- Add control_mode pytest fixture as a factory in pytest_plugin.py
- Add ControlMode and control_mode to doctest_namespace in conftest.py
- Add tests verifying client creation, cleanup, and client name
- No time.sleep — uses retry_until for client registration

Author: tony

conftest.py

@@ -10,12 +10,14 @@
 
 from __future__ import annotations
 
+import functools
 import shutil
 import typing as t
 
 import pytest
 from _pytest.doctest import DoctestItem
 
+from libtmux._internal.control_mode import ControlMode
 from libtmux.pane import Pane
 from libtmux.pytest_plugin import USING_ZSH
 from libtmux.server import Server
@@ -47,6 +49,12 @@ def add_doctest_fixtures(
         doctest_namespace["window"] = session.active_window
         doctest_namespace["pane"] = session.active_pane
         doctest_namespace["request"] = request
+        doctest_namespace["ControlMode"] = ControlMode
+        doctest_namespace["control_mode"] = functools.partial(
+            ControlMode,
+            server=session.server,
+            session=session,
+        )
 
 
 @pytest.fixture(autouse=True)

src/libtmux/_internal/control_mode.py

@@ -0,0 +1,133 @@
+"""Control-mode client context manager for tmux testing.
+
+Provides a context manager that spawns a ``tmux -C attach-session``
+subprocess, creating a real tmux client that satisfies commands
+requiring an attached client (e.g. ``display-popup``, ``detach-client``).
+"""
+
+from __future__ import annotations
+
+import os
+import pathlib
+import subprocess
+import tempfile
+import typing as t
+
+from libtmux.test.retry import retry_until
+
+if t.TYPE_CHECKING:
+    import types
+
+    from libtmux.server import Server
+    from libtmux.session import Session
+
+
+class ControlMode:
+    """Context manager that spawns a tmux control-mode client.
+
+    Creates a real client attached to the session, visible in
+    ``Server.list_clients()``. The client communicates via the tmux
+    control protocol on stdout.
+
+    While active, ``Server.list_clients()`` will include this client.
+
+    Parameters
+    ----------
+    server : Server
+        The tmux server instance.
+    session : Session
+        The session to attach to.
+
+    Examples
+    --------
+    >>> with ControlMode(server=server, session=session) as ctl:
+    ...     clients = server.list_clients()
+    ...     assert len(clients) > 0
+    ...     assert ctl.client_name != ''
+    """
+
+    server: Server
+    session: Session
+    client_name: str
+    stdout: t.IO[str]
+
+    _proc: subprocess.Popen[str]
+    _fifo_path: str
+    _write_fd: int
+
+    def __init__(self, server: Server, session: Session) -> None:
+        self.server = server
+        self.session = session
+
+    def __enter__(self) -> ControlMode:
+        """Spawn control-mode client and wait for registration."""
+        self._fifo_path = tempfile.mktemp(prefix="libtmux_ctl_")
+        os.mkfifo(self._fifo_path)
+
+        tmux_bin = self.server.tmux_bin or "tmux"
+        cmd = [
+            tmux_bin,
+            "-L",
+            str(self.server.socket_name),
+            "-C",
+            "attach-session",
+            "-t",
+            str(self.session.session_id),
+        ]
+
+        # Open read end for subprocess stdin
+        read_fd = os.open(self._fifo_path, os.O_RDONLY | os.O_NONBLOCK)
+
+        self._proc = subprocess.Popen(
+            cmd,
+            stdin=read_fd,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+        )
+        os.close(read_fd)
+
+        # Open write end to keep FIFO alive
+        self._write_fd = os.open(self._fifo_path, os.O_WRONLY)
+
+        self.stdout = self._proc.stdout  # type: ignore[assignment]
+
+        # Wait for client to register
+        def client_registered() -> bool:
+            clients = self.server.list_clients()
+            return len(clients) > 0
+
+        retry_until(client_registered, 3, raises=True)
+
+        # Capture client name
+        result = self.server.cmd(
+            "list-clients",
+            "-F",
+            "#{client_name}",
+        )
+        self.client_name = result.stdout[0].strip() if result.stdout else ""
+
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: types.TracebackType | None,
+    ) -> None:
+        """Terminate control-mode client and clean up FIFO."""
+        # Close write end — causes the control-mode client to exit
+        os.close(self._write_fd)
+
+        # Terminate and wait for subprocess
+        self._proc.terminate()
+        try:
+            self._proc.wait(timeout=5)
+        except subprocess.TimeoutExpired:
+            self._proc.kill()
+            self._proc.wait()
+
+        # Remove FIFO
+        fifo = pathlib.Path(self._fifo_path)
+        if fifo.exists():
+            fifo.unlink()

src/libtmux/pytest_plugin.py

@@ -13,6 +13,7 @@
 import pytest
 
 from libtmux import exc
+from libtmux._internal.control_mode import ControlMode
 from libtmux.server import Server
 from libtmux.test.constants import TEST_SESSION_PREFIX
 from libtmux.test.random import get_test_session_name, namer
@@ -265,6 +266,30 @@ def session(
     return session
 
 
+@pytest.fixture
+def control_mode(
+    server: Server,
+    session: Session,
+) -> t.Callable[[], ControlMode]:
+    """Return :class:`ControlMode` context manager factory.
+
+    Returns a callable that creates :class:`ControlMode` context managers
+    bound to the test's server and session. Use as a context manager to
+    spawn a control-mode tmux client.
+
+    While the control-mode client is active, ``Server.list_clients()``
+    will include it.
+
+    Examples
+    --------
+    >>> from libtmux._internal.control_mode import ControlMode
+    >>> def test_example(control_mode):
+    ...     with control_mode() as ctl:
+    ...         assert ctl.client_name != ''
+    """
+    return functools.partial(ControlMode, server=server, session=session)
+
+
 @pytest.fixture
 def TestServer(
     request: pytest.FixtureRequest,

tests/test_control_mode.py

@@ -0,0 +1,42 @@
+"""Tests for ControlMode context manager."""
+
+from __future__ import annotations
+
+import typing as t
+
+from libtmux._internal.control_mode import ControlMode
+
+if t.TYPE_CHECKING:
+    from libtmux.server import Server
+
+
+def test_control_mode_creates_client(
+    control_mode: t.Callable[[], ControlMode],
+    server: Server,
+) -> None:
+    """ControlMode creates a client visible in list-clients."""
+    with control_mode() as ctl:
+        clients = server.list_clients()
+        assert len(clients) > 0
+        assert ctl.client_name != ""
+
+
+def test_control_mode_cleanup(
+    control_mode: t.Callable[[], ControlMode],
+    server: Server,
+) -> None:
+    """Client is removed after ControlMode context exits."""
+    with control_mode():
+        assert len(server.list_clients()) > 0
+
+    # After context exit, client should be gone
+    clients = server.list_clients()
+    assert len(clients) == 0
+
+
+def test_control_mode_client_name(
+    control_mode: t.Callable[[], ControlMode],
+) -> None:
+    """ControlMode.client_name contains the tmux client identifier."""
+    with control_mode() as ctl:
+        assert "client-" in ctl.client_name