Tests: Coverage for libtmux.test helpers (#580)

This PR completes the refactoring of test helpers started in PR #578 by removing direct imports from the `libtmux.test` root module. Users must now import from specific submodules like `libtmux.test.named` and `libtmux.test.constants`.

Improvements include:
- Enhanced `EnvironmentVarGuard` for more reliable environment variable handling
- Added comprehensive test suites for constants and environment utilities
- Improved code coverage with proper exclusion markers for type checking blocks
- Better docstrings and examples in the random module

These changes improve maintainability and robustness of test helpers that are used both internally and by downstream packages that depend on libtmux.

Author: tony

CHANGES

@@ -15,6 +15,54 @@ $ pip install --user --upgrade --pre libtmux
 
 - _Future release notes will be placed here_
 
+### Breaking
+
+#### Imports removed from libtmux.test (#580)
+
+Root-level of imports from `libtmux.test` are no longer possible.
+
+```python
+# Before 0.46.0
+from libtmux.test import namer
+```
+
+```python
+# From 0.46.0 onward
+from libtmux.test.named import namer
+```
+
+Same thing with constants:
+
+```python
+# Before 0.46.0
+from libtmux.test import (
+  RETRY_INTERVAL_SECONDS,
+  RETRY_TIMEOUT_SECONDS,
+  TEST_SESSION_PREFIX
+)
+```
+
+```python
+# From 0.46.0 onward
+from libtmux.test.constants import (
+  RETRY_INTERVAL_SECONDS,
+  RETRY_TIMEOUT_SECONDS,
+  TEST_SESSION_PREFIX
+)
+```
+
+### Development
+
+#### Test helpers: Increased coverage (#580)
+
+Several improvements to the test helper modules:
+
+- Enhanced `EnvironmentVarGuard` in `libtmux.test.environment` to better handle variable cleanup
+- Added comprehensive test suites for test constants and environment utilities
+- Improved docstrings and examples in `libtmux.test.random` with test coverage annotations
+- Fixed potential issues with environment variable handling during tests
+- Added proper coverage markers to exclude type checking blocks from coverage reports
+
 ## libtmux 0.45.0 (2025-02-23)
 
 ### Breaking Changes

MIGRATION

@@ -25,6 +25,40 @@ _Detailed migration steps for the next version will be posted here._
 
 <!-- To the maintainers and contributors: please add migration details for the upcoming release here -->
 
+#### Imports removed from libtmux.test (#580)
+
+Root-level of imports from `libtmux.test` are no longer possible.
+
+```python
+# Before 0.46.0
+from libtmux.test import namer
+```
+
+```python
+# From 0.46.0 onward
+from libtmux.test.named import namer
+```
+
+Same thing with constants:
+
+```python
+# Before 0.46.0
+from libtmux.test import (
+  RETRY_INTERVAL_SECONDS,
+  RETRY_TIMEOUT_SECONDS,
+  TEST_SESSION_PREFIX
+)
+```
+
+```python
+# From 0.46.0 onward
+from libtmux.test.constants import (
+  RETRY_INTERVAL_SECONDS,
+  RETRY_TIMEOUT_SECONDS,
+  TEST_SESSION_PREFIX
+)
+```
+
 ## libtmux 0.45.0 (2025-02-23)
 
 ### Test helpers: Module moves

pyproject.toml

@@ -150,7 +150,9 @@ exclude_lines = [
   "if TYPE_CHECKING:",
   "if t.TYPE_CHECKING:",
   "@overload( |$)",
+  'class .*\bProtocol\):',
   "from __future__ import annotations",
+  "import typing as t",
 ]
 
 [tool.ruff]

src/libtmux/test/__init__.py

@@ -1,36 +1 @@
 """Helper methods for libtmux and downstream libtmux libraries."""
-
-from __future__ import annotations
-
-import contextlib
-import logging
-import os
-import pathlib
-import random
-import time
-import typing as t
-
-from libtmux.exc import WaitTimeout
-from libtmux.test.constants import (
-    RETRY_INTERVAL_SECONDS,
-    RETRY_TIMEOUT_SECONDS,
-    TEST_SESSION_PREFIX,
-)
-
-from .random import namer
-
-logger = logging.getLogger(__name__)
-
-if t.TYPE_CHECKING:
-    import sys
-    import types
-    from collections.abc import Callable, Generator
-
-    from libtmux.server import Server
-    from libtmux.session import Session
-    from libtmux.window import Window
-
-    if sys.version_info >= (3, 11):
-        from typing import Self
-    else:
-        from typing_extensions import Self

src/libtmux/test/environment.py

@@ -52,7 +52,12 @@ def set(self, envvar: str, value: str) -> None:
     def unset(self, envvar: str) -> None:
         """Unset environment variable."""
         if envvar in self._environ:
-            self._reset[envvar] = self._environ[envvar]
+            # If we previously set this variable in this context, remove it from _unset
+            if envvar in self._unset:
+                self._unset.remove(envvar)
+            # If we haven't saved the original value yet, save it
+            if envvar not in self._reset:
+                self._reset[envvar] = self._environ[envvar]
             del self._environ[envvar]
 
     def __enter__(self) -> Self:
@@ -69,4 +74,5 @@ def __exit__(
         for envvar, value in self._reset.items():
             self._environ[envvar] = value
         for unset in self._unset:
-            del self._environ[unset]
+            if unset not in self._reset:  # Don't delete variables that were reset
+                del self._environ[unset]

src/libtmux/test/random.py

@@ -1,35 +1,29 @@
 """Random helpers for libtmux and downstream libtmux libraries."""
 
-from __future__ import annotations
+from __future__ import annotations  # pragma: no cover
 
 import logging
 import random
-import typing as t
+import typing as t  # pragma: no cover
 
 from libtmux.test.constants import (
     TEST_SESSION_PREFIX,
 )
 
-logger = logging.getLogger(__name__)
-
-if t.TYPE_CHECKING:
-    import sys
+if t.TYPE_CHECKING:  # pragma: no cover
+    import sys  # pragma: no cover
 
-    from libtmux.server import Server
-    from libtmux.session import Session
+    from libtmux.server import Server  # pragma: no cover
+    from libtmux.session import Session  # pragma: no cover
 
-    if sys.version_info >= (3, 11):
-        pass
+    if sys.version_info >= (3, 11):  # pragma: no cover
+        pass  # pragma: no cover
+    else:  # pragma: no cover
+        pass  # pragma: no cover
 
 
 logger = logging.getLogger(__name__)
 
-if t.TYPE_CHECKING:
-    import sys
-
-    if sys.version_info >= (3, 11):
-        pass
-
 
 class RandomStrSequence:
     """Factory to generate random string."""
@@ -40,12 +34,12 @@ def __init__(
     ) -> None:
         """Create a random letter / number generator. 8 chars in length.
 
-        >>> rng = RandomStrSequence()
-        >>> next(rng)
+        >>> rng = RandomStrSequence()  # pragma: no cover
+        >>> next(rng)  # pragma: no cover
         '...'
-        >>> len(next(rng))
+        >>> len(next(rng))  # pragma: no cover
         8
-        >>> type(next(rng))
+        >>> type(next(rng))  # pragma: no cover
         <class 'str'>
         """
         self.characters: str = characters
@@ -81,11 +75,13 @@ def get_test_session_name(server: Server, prefix: str = TEST_SESSION_PREFIX) ->
 
     Examples
     --------
-    >>> get_test_session_name(server=server)
+    >>> get_test_session_name(server=server)  # pragma: no cover
     'libtmux_...'
 
     Never the same twice:
-    >>> get_test_session_name(server=server) != get_test_session_name(server=server)
+    >>> name1 = get_test_session_name(server=server)  # pragma: no cover
+    >>> name2 = get_test_session_name(server=server)  # pragma: no cover
+    >>> name1 != name2  # pragma: no cover
     True
     """
     while True:
@@ -119,12 +115,13 @@ def get_test_window_name(
 
     Examples
     --------
-    >>> get_test_window_name(session=session)
+    >>> get_test_window_name(session=session)  # pragma: no cover
     'libtmux_...'
 
     Never the same twice:
-
-    >>> get_test_window_name(session=session) != get_test_window_name(session=session)
+    >>> name1 = get_test_window_name(session=session)  # pragma: no cover
+    >>> name2 = get_test_window_name(session=session)  # pragma: no cover
+    >>> name1 != name2  # pragma: no cover
     True
     """
     assert prefix is not None

tests/test/test_constants.py

@@ -0,0 +1,51 @@
+"""Tests for libtmux's test constants."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from libtmux.test.constants import (
+    RETRY_INTERVAL_SECONDS,
+    RETRY_TIMEOUT_SECONDS,
+    TEST_SESSION_PREFIX,
+)
+
+if TYPE_CHECKING:
+    import pytest
+
+
+def test_test_session_prefix() -> None:
+    """Test TEST_SESSION_PREFIX is correctly defined."""
+    assert TEST_SESSION_PREFIX == "libtmux_"
+
+
+def test_retry_timeout_seconds_default() -> None:
+    """Test RETRY_TIMEOUT_SECONDS default value."""
+    assert RETRY_TIMEOUT_SECONDS == 8
+
+
+def test_retry_timeout_seconds_env(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Test RETRY_TIMEOUT_SECONDS can be configured via environment variable."""
+    monkeypatch.setenv("RETRY_TIMEOUT_SECONDS", "10")
+    from importlib import reload
+
+    import libtmux.test.constants
+
+    reload(libtmux.test.constants)
+    assert libtmux.test.constants.RETRY_TIMEOUT_SECONDS == 10
+
+
+def test_retry_interval_seconds_default() -> None:
+    """Test RETRY_INTERVAL_SECONDS default value."""
+    assert RETRY_INTERVAL_SECONDS == 0.05
+
+
+def test_retry_interval_seconds_env(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Test RETRY_INTERVAL_SECONDS can be configured via environment variable."""
+    monkeypatch.setenv("RETRY_INTERVAL_SECONDS", "0.1")
+    from importlib import reload
+
+    import libtmux.test.constants
+
+    reload(libtmux.test.constants)
+    assert libtmux.test.constants.RETRY_INTERVAL_SECONDS == 0.1