refactor!(pytest_plugin): Remove all autouse from default usage

This prevents plugins from being invoked simply by having libtmux
installed. We don't want that - it would interrupt systems. Explicit is
better than implicit.

Move autouse for libtmux itself to the appropriate places.

Author: tony

docs/conftest.py

@@ -0,0 +1 @@
+from libtmux.conftest import *  # NOQA: F4

libtmux/conftest.py

@@ -0,0 +1,44 @@
+import pathlib
+import shutil
+import typing as t
+
+import pytest
+
+from _pytest.doctest import DoctestItem
+
+from libtmux.pytest_plugin import USING_ZSH
+
+if t.TYPE_CHECKING:
+    from libtmux.session import Session
+
+
+@pytest.fixture(autouse=True)
+def add_doctest_fixtures(
+    request: pytest.FixtureRequest,
+    doctest_namespace: t.Dict[str, t.Any],
+) -> None:
+    if isinstance(request._pyfuncitem, DoctestItem) and shutil.which("tmux"):
+        request.getfixturevalue("set_home")
+        doctest_namespace["server"] = request.getfixturevalue("server")
+        session: "Session" = request.getfixturevalue("session")
+        doctest_namespace["session"] = session
+        doctest_namespace["window"] = session.attached_window
+        doctest_namespace["pane"] = session.attached_pane
+
+
+@pytest.fixture(autouse=True, scope="function")
+def set_home(
+    monkeypatch: pytest.MonkeyPatch,
+    user_path: pathlib.Path,
+) -> None:
+    monkeypatch.setenv("HOME", str(user_path))
+
+
+@pytest.fixture(autouse=True, scope="session")
+@pytest.mark.usefixtures("clear_env")
+def setup(
+    request: pytest.FixtureRequest,
+    config_file: pathlib.Path,
+) -> None:
+    if USING_ZSH:
+        request.getfixturevalue("zshrc")

libtmux/pytest_plugin.py

@@ -2,15 +2,10 @@
 import logging
 import os
 import pathlib
-import shutil
 import typing as t
 
 import pytest
 
-from _pytest.doctest import DoctestItem
-from _pytest.fixtures import SubRequest
-from _pytest.monkeypatch import MonkeyPatch
-
 from libtmux import exc
 from libtmux.server import Server
 from libtmux.test import TEST_SESSION_PREFIX, get_test_session_name, namer
@@ -22,20 +17,35 @@
 USING_ZSH = "zsh" in os.getenv("SHELL", "")
 
 
-@pytest.fixture(autouse=True, scope="session")
+@pytest.fixture(scope="session")
 def home_path(tmp_path_factory: pytest.TempPathFactory) -> pathlib.Path:
+    """Temporary `/home/` path."""
     return tmp_path_factory.mktemp("home")
 
 
-@pytest.fixture(autouse=True, scope="session")
-def user_path(home_path: pathlib.Path) -> pathlib.Path:
-    p = home_path / getpass.getuser()
+@pytest.fixture(scope="session")
+def home_user_name() -> str:
+    """Default username to set for :func:`user_path` fixture."""
+    return getpass.getuser()
+
+
+@pytest.fixture(scope="session")
+def user_path(home_path: pathlib.Path, home_user_name: str) -> pathlib.Path:
+    """Default temporary user directory.
+
+    Used by:
+
+    - :func:`config_file`
+
+    Note: You will need to set the home directory, see :ref:`set_home`.
+    """
+    p = home_path / home_user_name
     p.mkdir()
     return p
 
 
 @pytest.mark.skipif(USING_ZSH, reason="Using ZSH")
-@pytest.fixture(autouse=USING_ZSH, scope="session")
+@pytest.fixture(scope="session")
 def zshrc(user_path: pathlib.Path) -> pathlib.Path:
     """This quiets ZSH default message.
 
@@ -46,11 +56,15 @@ def zshrc(user_path: pathlib.Path) -> pathlib.Path:
     return p
 
 
-@pytest.fixture(scope="function")
+@pytest.fixture(scope="session")
 def config_file(user_path: pathlib.Path) -> pathlib.Path:
-    """Set default tmux configuration (base indexes for windows, panes)
+    """Default `.tmux.conf` configuration.
+
+    - ``base-index -g 1``
 
-    We need this for tests to work across tmux versions in our CI matrix.
+    These guarantee pane and windows targets can be reliably referenced and asserted.
+
+    Note: You will need to set the home directory, see :ref:`set_home`.
     """
     c = user_path / ".tmux.conf"
     c.write_text(
@@ -62,8 +76,8 @@ def config_file(user_path: pathlib.Path) -> pathlib.Path:
     return c
 
 
-@pytest.fixture(autouse=True)
-def clear_env(monkeypatch: MonkeyPatch) -> None:
+@pytest.fixture
+def clear_env(monkeypatch: pytest.MonkeyPatch) -> None:
     """Clear out any unnecessary environment variables that could interrupt tests.
 
     tmux show-environment tests were being interrupted due to a lot of crazy env vars.
@@ -92,9 +106,12 @@ def clear_env(monkeypatch: MonkeyPatch) -> None:
 
 @pytest.fixture(scope="function")
 def server(
-    request: SubRequest, monkeypatch: MonkeyPatch, config_file: pathlib.Path
+    request: pytest.FixtureRequest,
+    monkeypatch: pytest.MonkeyPatch,
+    config_file: pathlib.Path,
 ) -> Server:
-    t = Server(config_file=str(config_file.absolute()))
+    """Returns a new, temporary :class:`libtmux.Server`"""
+    t = Server()
     t.socket_name = "libtmux_test%s" % next(namer)
 
     def fin() -> None:
@@ -106,7 +123,8 @@ def fin() -> None:
 
 
 @pytest.fixture(scope="function")
-def session(request: SubRequest, server: Server) -> "Session":
+def session(request: pytest.FixtureRequest, server: Server) -> "Session":
+    """Returns a new, temporary :class:`libtmux.Session`"""
     session_name = "tmuxp"
 
     if not server.has_session(session_name):
@@ -146,16 +164,3 @@ def session(request: SubRequest, server: Server) -> "Session":
     assert TEST_SESSION_NAME != "tmuxp"
 
     return session
-
-
-@pytest.fixture(autouse=True)
-def add_doctest_fixtures(
-    request: SubRequest,
-    doctest_namespace: t.Dict[str, t.Any],
-) -> None:
-    if isinstance(request._pyfuncitem, DoctestItem) and shutil.which("tmux"):
-        doctest_namespace["server"] = request.getfixturevalue("server")
-        session: "Session" = request.getfixturevalue("session")
-        doctest_namespace["session"] = session
-        doctest_namespace["window"] = session.attached_window
-        doctest_namespace["pane"] = session.attached_pane

tests/conftest.py

@@ -0,0 +1 @@
+from libtmux.conftest import *  # NOQA: F4