Add logging isolation for Pytest compatibility

Author: Copilot

cli_test_helpers/decorators.py

@@ -3,6 +3,7 @@
 """
 
 import contextlib
+import logging
 import os
 import sys
 from tempfile import TemporaryDirectory
@@ -11,7 +12,36 @@
 __all__ = []
 
 
-class ArgvContext:
+class LoggingIsolationMixin:
+    """
+    Mixin that provides automatic logging configuration isolation.
+
+    Isolates logging configuration by temporarily clearing logging handlers
+    when entering the context and restoring them when exiting.  This allows
+    code under test to call ``logging.basicConfig()`` successfully even when
+    test frameworks (like pytest) have already configured logging handlers.
+    """
+
+    def __enter__(self):
+        """Save and clear logging handlers before entering the context."""
+        self._old_handlers = logging.root.handlers[:]
+        logging.root.handlers.clear()
+        # Call parent __enter__ if it exists (for cooperative inheritance)
+        if hasattr(super(), "__enter__"):
+            return super().__enter__()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Restore logging handlers after exiting the context."""
+        if hasattr(self, "_old_handlers"):
+            logging.root.handlers[:] = self._old_handlers
+        # Call parent __exit__ if it exists (for cooperative inheritance)
+        if hasattr(super(), "__exit__"):
+            return super().__exit__(exc_type, exc_val, exc_tb)
+        return None
+
+
+class ArgvContext(LoggingIsolationMixin):
     """
     A simple context manager allowing to temporarily override ``sys.argv``.
 
@@ -25,13 +55,16 @@ def __init__(self, *new_args):
         self.args = type(self._old)(new_args)
 
     def __enter__(self):
+        super().__enter__()
         sys.argv = self.args
+        return self
 
     def __exit__(self, exc_type, exc_val, exc_tb):
         sys.argv = self._old
+        super().__exit__(exc_type, exc_val, exc_tb)
 
 
-class EnvironContext(patch.dict):
+class EnvironContext(LoggingIsolationMixin, patch.dict):
     """
     A simple context manager allowing to temporarily set environment values.
 
@@ -57,8 +90,13 @@ def __enter__(self):
             with contextlib.suppress(KeyError):
                 self.in_dict.pop(key)
 
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        return super().__exit__(exc_type, exc_val, exc_tb)
+
 
-class RandomDirectoryContext(TemporaryDirectory):
+class RandomDirectoryContext(LoggingIsolationMixin, TemporaryDirectory):
     """
     Change the execution directory to a random location, temporarily.
 
@@ -69,10 +107,14 @@ class RandomDirectoryContext(TemporaryDirectory):
         https://docs.python.org/3/library/tempfile.html#tempfile.TemporaryDirectory
     """
 
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+
     def __enter__(self):
         """Create a temporary directory and ``cd`` into it."""
-        self.__prev_dir = os.getcwd()
         super().__enter__()
+
+        self.__prev_dir = os.getcwd()
         os.chdir(self.name)
         return os.getcwd()
 

docs/tutorial.rst

@@ -92,6 +92,13 @@ this approach with mocking a target function, e.g.
 
         assert mock_command.called
 
+``ArgvContext`` also provides automatic logging isolation. When test
+frameworks like pytest set up logging handlers, they can interfere with
+code under test that calls ``logging.basicConfig()``. ``ArgvContext``
+automatically saves and clears logging handlers when entering the context,
+then restores them when exiting, allowing your CLI code to configure
+logging as expected.
+
 See more |example code (argparse-cli)|_.
 
 ``EnvironContext``
@@ -111,6 +118,10 @@ See more |example code (argparse-cli)|_.
                 foobar.command.baz()
                 pytest.fail("CLI doesn't abort with missing SECRET")
 
+``EnvironContext`` also provides automatic logging isolation, just like
+``ArgvContext``. This allows code under test to configure logging as expected
+even when test frameworks have already set up handlers.
+
 See more |example code (click-command)|_.
 
 ``RandomDirectoryContext``
@@ -127,6 +138,10 @@ system:
         with ArgvContext('foobar', 'load'), RandomDirectoryContext():
             foobar.cli.main()
 
+``RandomDirectoryContext`` also provides automatic logging isolation, ensuring
+that code under test can call ``logging.basicConfig()`` successfully regardless
+of test framework logging configuration.
+
 
 .. |example code (argparse-cli)| replace:: example code
 .. |example code (click-cli)| replace:: example code

tests/test_logisolation.py

@@ -0,0 +1,117 @@
+"""Tests for our tests helpers.  8-}."""
+
+import logging
+import tempfile
+from pathlib import Path
+
+from cli_test_helpers import ArgvContext, EnvironContext, RandomDirectoryContext
+
+
+def test_argv_context_logging_isolation():
+    """
+    Does ArgvContext isolate logging configuration?
+
+    Verifies that ArgvContext temporarily clears logging handlers, allowing
+    code under test to call logging.basicConfig() successfully even when
+    test frameworks have already configured logging.
+    """
+    original_handlers = logging.root.handlers[:]
+    mock_handler = logging.NullHandler()
+    logging.root.handlers.append(mock_handler)
+
+    try:
+        assert mock_handler in logging.root.handlers, "Test setup failed"
+
+        with tempfile.TemporaryDirectory() as tmpdir:
+            logfile = Path(tmpdir) / "test.log"
+
+            with ArgvContext("test_script.py", str(logfile)):
+                handlers_before = logging.root.handlers[:]
+                assert not handlers_before, "Handlers not cleared"
+
+                logging.basicConfig(filename=str(logfile), level=logging.INFO)
+
+                logger = logging.getLogger(__name__)
+                logger.info("Test message")
+
+            assert mock_handler in logging.root.handlers, "Handlers not restored"
+
+            assert logfile.exists(), "Log file should have been created"
+            log_content = logfile.read_text()
+            assert "Test message" in log_content, "Unexpected log file content"
+
+    finally:
+        logging.root.handlers = original_handlers
+
+
+def test_environ_context_logging_isolation():
+    """
+    Does EnvironContext isolate logging configuration?
+
+    Verifies that EnvironContext temporarily clears logging handlers, allowing
+    code under test to call logging.basicConfig() successfully even when test
+    frameworks have already configured logging.
+    """
+    original_handlers = logging.root.handlers[:]
+    mock_handler = logging.NullHandler()
+    logging.root.handlers.append(mock_handler)
+
+    try:
+        assert mock_handler in logging.root.handlers, "Test setup failed"
+
+        with tempfile.TemporaryDirectory() as tmpdir:
+            logfile = Path(tmpdir) / "environ_test.log"
+
+            with EnvironContext(TEST_VAR="test_value"):
+                handlers_before = logging.root.handlers[:]
+                assert not handlers_before, "Handlers not cleared"
+
+                logging.basicConfig(filename=str(logfile), level=logging.INFO)
+
+                logger = logging.getLogger(__name__)
+                logger.info("Test message from EnvironContext")
+
+            assert mock_handler in logging.root.handlers, "Handlers not restored"
+
+            assert logfile.exists(), "Log file should have been created"
+            log_content = logfile.read_text()
+            assert "Test message" in log_content, "Unexpected log file content"
+
+    finally:
+        logging.root.handlers = original_handlers
+
+
+def test_random_directory_context_logging_isolation():
+    """
+    Does RandomDirectoryContext isolate logging configuration?
+
+    Verifies that RandomDirectoryContext temporarily clears logging handlers,
+    allowing code under test to call logging.basicConfig() successfully even
+    when test frameworks have already configured logging.
+    """
+    original_handlers = logging.root.handlers[:]
+    mock_handler = logging.NullHandler()
+    logging.root.handlers.append(mock_handler)
+
+    try:
+        assert mock_handler in logging.root.handlers, "Test setup failed"
+
+        with RandomDirectoryContext():
+            logfile = Path("random_dir_test.log")
+
+            handlers_before = logging.root.handlers[:]
+            assert not handlers_before, "Handlers not cleared"
+
+            logging.basicConfig(filename=str(logfile), level=logging.INFO)
+
+            logger = logging.getLogger(__name__)
+            logger.info("Test message from RandomDirectoryContext")
+
+            assert logfile.exists(), "Log file should have been created"
+            log_content = logfile.read_text()
+            assert "Test message" in log_content, "Unexpected log file content"
+
+        assert mock_handler in logging.root.handlers, "Handlers not restored"
+
+    finally:
+        logging.root.handlers = original_handlers