provide-testkit 0.0.0.dev0__py3-none-any.whl

provide/testkit/fixtures.py

@@ -0,0 +1,52 @@
+"""
+Common Test Fixtures for Foundation.
+
+Provides pytest fixtures for capturing output, setting up telemetry,
+and other common testing scenarios across the Foundation test suite.
+"""
+
+from collections.abc import Callable, Generator
+import io
+from typing import TextIO
+
+import pytest
+
+from provide.foundation import TelemetryConfig, get_hub
+from provide.testkit.streams import set_log_stream_for_testing
+
+
+@pytest.fixture
+def captured_stderr_for_foundation() -> Generator[TextIO]:
+    """
+    Fixture to capture stderr output from Foundation's logging system.
+
+    It redirects Foundation's log stream to an `io.StringIO` buffer, yields the buffer
+    to the test, and then restores the original stream.
+    """
+    current_test_stream = io.StringIO()
+    set_log_stream_for_testing(current_test_stream)
+    yield current_test_stream
+    set_log_stream_for_testing(None)
+    current_test_stream.close()
+
+
+@pytest.fixture
+def setup_foundation_telemetry_for_test(
+    captured_stderr_for_foundation: TextIO,
+) -> Callable[[TelemetryConfig | None], None]:
+    """
+    Fixture providing a function to set up Foundation Telemetry for tests.
+
+    This fixture captures stderr via `captured_stderr_for_foundation`
+    and provides a callable to configure telemetry with custom settings.
+    """
+
+    def _setup(config: TelemetryConfig | None = None) -> None:
+        if config is None:
+            config = TelemetryConfig()
+
+        # Use Hub API directly instead of deprecated setup_telemetry
+        hub = get_hub()
+        hub.initialize_foundation(config, force=True)
+
+    return _setup

provide/testkit/harness.py

@@ -0,0 +1,122 @@
+"""
+Harness Testing Utilities.
+
+Provides utilities for testing CLI harnesses with artifact management.
+"""
+
+from pathlib import Path
+
+from provide.foundation.process.runner import run_command
+
+
+class HarnessRunner:
+    """Test harness runner with artifact management."""
+
+    def __init__(self, artifact_root: Path):
+        """Initialize with artifact root directory."""
+        self.artifact_root = artifact_root
+
+    def run(
+        self,
+        command: list[str],
+        artifact_path: Path | str,
+        stdin: str | bytes | None = None,
+        timeout: float = 30.0,
+        cwd: Path | None = None,
+    ) -> tuple[int, str, str]:
+        """
+        Run command and return text output.
+
+        For binary output commands, use run_binary() instead.
+        """
+        exit_code, stdout_str, stderr_str, _, _ = self._run_internal(
+            command, artifact_path, stdin, timeout, cwd
+        )
+        return exit_code, stdout_str, stderr_str
+
+    def run_binary(
+        self,
+        command: list[str],
+        artifact_path: Path | str,
+        stdin: str | bytes | None = None,
+        timeout: float = 30.0,
+        cwd: Path | None = None,
+    ) -> tuple[int, bytes, bytes]:
+        """
+        Run command and return binary output.
+
+        Use this for commands that output binary data.
+        """
+        exit_code, _, _, stdout_bytes, stderr_bytes = self._run_internal(
+            command, artifact_path, stdin, timeout, cwd
+        )
+        return exit_code, stdout_bytes, stderr_bytes
+
+    def _run_internal(
+        self,
+        command: list[str],
+        artifact_path: Path | str,
+        stdin: str | bytes | None = None,
+        timeout: float = 30.0,
+        cwd: Path | None = None,
+    ) -> tuple[int, str, str, bytes, bytes]:
+        """
+        Internal run method that returns both text and binary outputs.
+
+        Returns:
+            Tuple of (exit_code, stdout_str, stderr_str, stdout_bytes, stderr_bytes)
+        """
+        # Create artifact directory
+        artifact_dir = self.artifact_root / artifact_path
+        artifact_dir.mkdir(parents=True, exist_ok=True)
+
+        # Save command and stdin
+        (artifact_dir / "cmd.txt").write_text(" ".join(command))
+        if stdin:
+            (artifact_dir / "stdin.txt").write_bytes(stdin.encode() if isinstance(stdin, str) else stdin)
+
+        # Run command in binary mode to handle binary outputs
+        result = run_command(
+            command,
+            cwd=cwd,
+            input=stdin,
+            timeout=timeout,
+            check=False,  # Don't raise on non-zero exit
+            text=False,  # Binary mode to handle binary data
+            env={"PROVIDE_TELEMETRY_DISABLED": "true"},
+        )
+
+        # Handle binary outputs - return as bytes for binary data, decode for text
+        stdout_bytes = result.stdout if isinstance(result.stdout, bytes) else result.stdout.encode()
+        stderr_bytes = result.stderr if isinstance(result.stderr, bytes) else result.stderr.encode()
+
+        # Try to decode as text for logging/artifacts, but preserve original bytes
+        try:
+            stdout_str = stdout_bytes.decode("utf-8")
+        except UnicodeDecodeError:
+            # For binary output, save as hex dump for debugging
+            import base64
+
+            stdout_str = f"[Binary data - base64]: {base64.b64encode(stdout_bytes).decode('ascii')}"
+
+        try:
+            stderr_str = stderr_bytes.decode("utf-8")
+        except UnicodeDecodeError:
+            stderr_str = f"[Binary stderr]: {stderr_bytes.decode('utf-8', errors='replace')}"
+
+        # Save outputs
+        (artifact_dir / "stdout.txt").write_text(stdout_str)
+        (artifact_dir / "stderr.txt").write_text(stderr_str)
+        (artifact_dir / "exitcode.txt").write_text(str(result.returncode))
+
+        # Save raw binary outputs for binary commands
+        if stdout_bytes:
+            (artifact_dir / "stdout.bin").write_bytes(stdout_bytes)
+        if stderr_bytes:
+            (artifact_dir / "stderr.bin").write_bytes(stderr_bytes)
+
+        # Return all formats
+        return result.returncode, stdout_str, stderr_str, stdout_bytes, stderr_bytes
+
+
+__all__ = ["HarnessRunner"]

provide/testkit/hub.py

@@ -0,0 +1,22 @@
+"""
+Hub Testing Fixtures for Foundation.
+
+Provides pytest fixtures for testing hub and component functionality,
+including container directories and component registration scenarios.
+"""
+
+import pytest
+
+from provide.foundation.file import temp_dir as foundation_temp_dir
+
+
+@pytest.fixture(scope="session")
+def default_container_directory():
+    """
+    Provides a default directory for container operations in tests.
+
+    This fixture is used by tests that need a temporary directory
+    for container-related operations.
+    """
+    with foundation_temp_dir() as tmp_dir:
+        yield tmp_dir

provide/testkit/logger/__init__.py

@@ -0,0 +1,39 @@
+#
+# __init__.py
+#
+"""
+Logger Testing Utilities.
+
+Provides utilities for logger testing, including state reset,
+mock fixtures, and pytest hooks for managing noisy loggers.
+"""
+
+# Import reset utilities
+# Import hook utilities
+from provide.testkit.logger.hooks import (
+    DEFAULT_NOISY_LOGGERS,
+    get_log_level_for_noisy_loggers,
+    get_noisy_loggers,
+    pytest_runtest_setup,
+    suppress_loggers,
+)
+from provide.testkit.logger.reset import (
+    mock_logger,
+    mock_logger_factory,
+    reset_foundation_setup_for_testing,
+    reset_foundation_state,
+)
+
+__all__ = [
+    # Reset utilities
+    "mock_logger",
+    "mock_logger_factory",
+    "reset_foundation_setup_for_testing",
+    "reset_foundation_state",
+    # Hook utilities
+    "DEFAULT_NOISY_LOGGERS",
+    "get_log_level_for_noisy_loggers",
+    "get_noisy_loggers",
+    "pytest_runtest_setup",
+    "suppress_loggers",
+]

provide/testkit/logger/hooks.py

@@ -0,0 +1,100 @@
+#
+# hooks.py
+#
+"""
+Pytest Hooks for Logger Management.
+
+Provides pytest hooks for suppressing noisy loggers during test runs.
+This helps reduce test output noise from third-party libraries.
+"""
+
+import logging
+import os
+
+import pytest
+
+# Default list of commonly noisy loggers to suppress during tests
+DEFAULT_NOISY_LOGGERS = [
+    "markdown_it",
+    "asyncio",
+    "urllib3.connectionpool",
+    "requests.packages.urllib3.connectionpool",
+    "botocore",
+    "boto3.resources",
+    "websockets.protocol",
+    "websockets.server",
+    "websockets.client",
+    "httpx",
+    "httpcore",
+]
+
+
+def get_noisy_loggers() -> list[str]:
+    """
+    Get the list of loggers to suppress during tests.
+
+    Can be customized via the TESTKIT_NOISY_LOGGERS environment variable,
+    which should be a comma-separated list of logger names.
+
+    Returns:
+        List of logger names to suppress.
+    """
+    env_loggers = os.getenv("TESTKIT_NOISY_LOGGERS")
+    if env_loggers:
+        return [name.strip() for name in env_loggers.split(",") if name.strip()]
+    return DEFAULT_NOISY_LOGGERS
+
+
+def get_log_level_for_noisy_loggers() -> int:
+    """
+    Get the log level to set for noisy loggers.
+
+    Can be customized via the TESTKIT_NOISY_LOG_LEVEL environment variable.
+    Defaults to WARNING level.
+
+    Returns:
+        Logging level (int) to set for noisy loggers.
+    """
+    level_name = os.getenv("TESTKIT_NOISY_LOG_LEVEL", "WARNING")
+    return getattr(logging, level_name.upper(), logging.WARNING)
+
+
+@pytest.hookimpl(tryfirst=True)
+def pytest_runtest_setup():
+    """
+    Hook that runs before each test setup.
+
+    This forcefully sets the log level for noisy libraries to WARNING (or custom level),
+    overriding any configuration that may have happened at import time
+    (e.g., by Textual or the application itself).
+    """
+    noisy_loggers = get_noisy_loggers()
+    log_level = get_log_level_for_noisy_loggers()
+
+    for logger_name in noisy_loggers:
+        logger = logging.getLogger(logger_name)
+        logger.setLevel(log_level)
+
+
+def suppress_loggers(logger_names: list[str], level: int = logging.WARNING) -> None:
+    """
+    Utility function to suppress specific loggers to a given level.
+
+    Can be used directly in tests or conftest.py files for custom suppression.
+
+    Args:
+        logger_names: List of logger names to suppress
+        level: Log level to set (defaults to WARNING)
+    """
+    for logger_name in logger_names:
+        logger = logging.getLogger(logger_name)
+        logger.setLevel(level)
+
+
+__all__ = [
+    "DEFAULT_NOISY_LOGGERS",
+    "get_log_level_for_noisy_loggers",
+    "get_noisy_loggers",
+    "pytest_runtest_setup",
+    "suppress_loggers",
+]

provide/testkit/logger/reset.py

@@ -0,0 +1,230 @@
+#
+# reset.py
+#
+"""
+Logger Testing Utilities for Foundation.
+
+Provides utilities for resetting logger state, managing configurations,
+and ensuring test isolation for the Foundation logging system.
+"""
+
+from unittest.mock import Mock
+
+import pytest
+
+# Note: Removed module-level imports to avoid circular imports
+# All Foundation imports will be done within functions when needed
+
+
+@pytest.fixture
+def mock_logger():
+    """
+    Comprehensive mock logger for testing.
+
+    Provides compatibility with both stdlib logging and structlog interfaces,
+    including method call tracking and common logger attributes.
+
+    Returns:
+        Mock logger with debug, info, warning, error methods and structlog compatibility.
+    """
+    logger = Mock()
+    logger.debug = Mock()
+    logger.info = Mock()
+    logger.warning = Mock()
+    logger.warn = Mock()  # Alias for warning
+    logger.error = Mock()
+    logger.exception = Mock()
+    logger.critical = Mock()
+    logger.fatal = Mock()  # Alias for critical
+
+    # Add common logger attributes
+    logger.name = "mock_logger"
+    logger.level = 10  # DEBUG level
+    logger.handlers = []
+    logger.disabled = False
+
+    # Add structlog compatibility methods
+    logger.bind = Mock(return_value=logger)
+    logger.unbind = Mock(return_value=logger)
+    logger.new = Mock(return_value=logger)
+    logger.msg = Mock()  # Alternative to info
+
+    # Add trace method for Foundation's extended logging
+    logger.trace = Mock()
+
+    return logger
+
+
+def mock_logger_factory():
+    """
+    Factory function to create mock loggers outside of pytest context.
+
+    Useful for unit tests that need a mock logger but aren't using pytest fixtures.
+
+    Returns:
+        Mock logger with the same interface as the pytest fixture.
+    """
+    logger = Mock()
+    logger.debug = Mock()
+    logger.info = Mock()
+    logger.warning = Mock()
+    logger.warn = Mock()
+    logger.error = Mock()
+    logger.exception = Mock()
+    logger.critical = Mock()
+    logger.fatal = Mock()
+
+    logger.name = "mock_logger"
+    logger.level = 10
+    logger.handlers = []
+    logger.disabled = False
+
+    logger.bind = Mock(return_value=logger)
+    logger.unbind = Mock(return_value=logger)
+    logger.new = Mock(return_value=logger)
+    logger.msg = Mock()
+    logger.trace = Mock()
+
+    return logger
+
+
+def _reset_opentelemetry_providers() -> None:
+    """
+    Reset OpenTelemetry providers to uninitialized state.
+
+    This prevents "Overriding of current TracerProvider/MeterProvider" warnings
+    and stream closure issues by properly resetting the global providers.
+    """
+    try:
+        # Reset tracing provider more thoroughly
+        import opentelemetry.trace as otel_trace
+
+        # Reset the Once flag to allow re-initialization
+        if hasattr(otel_trace, "_TRACER_PROVIDER_SET_ONCE"):
+            once_obj = otel_trace._TRACER_PROVIDER_SET_ONCE
+            if hasattr(once_obj, "_done"):
+                once_obj._done = False
+            if hasattr(once_obj, "_lock"):
+                with once_obj._lock:
+                    once_obj._done = False
+
+        # Reset to NoOpTracerProvider
+        from opentelemetry.trace import NoOpTracerProvider
+
+        otel_trace.set_tracer_provider(NoOpTracerProvider())
+
+    except ImportError:
+        # OpenTelemetry tracing not available
+        pass
+    except Exception:
+        # Ignore errors during reset - better to continue than fail
+        pass
+
+    try:
+        # Reset metrics provider more thoroughly
+        import opentelemetry.metrics as otel_metrics
+        import opentelemetry.metrics._internal as otel_metrics_internal
+
+        # Reset the Once flag to allow re-initialization
+        if hasattr(otel_metrics_internal, "_METER_PROVIDER_SET_ONCE"):
+            once_obj = otel_metrics_internal._METER_PROVIDER_SET_ONCE
+            if hasattr(once_obj, "_done"):
+                once_obj._done = False
+            if hasattr(once_obj, "_lock"):
+                with once_obj._lock:
+                    once_obj._done = False
+
+        # Reset to NoOpMeterProvider
+        from opentelemetry.metrics import NoOpMeterProvider
+
+        otel_metrics.set_meter_provider(NoOpMeterProvider())
+
+    except ImportError:
+        # OpenTelemetry metrics not available
+        pass
+    except Exception:
+        # Ignore errors during reset - better to continue than fail
+        pass
+
+
+def reset_foundation_state() -> None:
+    """
+    Internal function to reset structlog and Foundation's state using Hub-based approach.
+
+    This resets:
+    - structlog configuration to defaults
+    - Foundation Hub state (which manages all Foundation components)
+    - Stream state back to defaults
+    - Lazy setup state tracking (if available)
+    - OpenTelemetry provider state (if available)
+    """
+    # Use the new internal reset APIs from Foundation's testmode module
+    from provide.foundation.testmode.internal import (
+        reset_coordinator_state,
+        reset_eventsets_state,
+        reset_hub_state,
+        reset_logger_state,
+        reset_streams_state,
+        reset_structlog_state,
+    )
+
+    # Reset in the proper order to avoid triggering reinitialization
+    reset_structlog_state()
+    reset_streams_state()
+
+    # Reset OpenTelemetry providers to avoid "Overriding" warnings and stream closure
+    # Note: OpenTelemetry providers are designed to prevent override for safety.
+    # In test environments, we suppress this reset to avoid hanging/blocking.
+    # The warnings are harmless in test context.
+    _reset_opentelemetry_providers()
+
+    # Reset lazy setup state FIRST to prevent hub operations from triggering setup
+    reset_logger_state()
+
+    # Clear Hub (this handles all Foundation state including logger instances)
+    reset_hub_state()
+
+    # Reset coordinator and event set state
+    reset_coordinator_state()
+    reset_eventsets_state()
+
+    # Final reset of logger state (after all operations that might trigger setup)
+    reset_logger_state()
+
+
+def reset_foundation_setup_for_testing() -> None:
+    """
+    Public test utility to reset Foundation's internal state using Hub-based approach.
+
+    This function ensures clean test isolation by resetting all
+    Foundation state between test runs. Now uses Hub.clear_hub() which
+    properly resets all Foundation components.
+    """
+    # Full reset with Hub-based state management
+    reset_foundation_state()
+
+    # Re-register HTTP transport for tests that need it
+    try:
+        from provide.foundation.transport.http import _register_http_transport
+
+        _register_http_transport()
+    except ImportError:
+        # Transport module not available
+        pass
+
+    # Final reset of lazy setup state (after transport registration)
+    try:
+        from provide.foundation.logger.core import _LAZY_SETUP_STATE
+
+        _LAZY_SETUP_STATE.update({"done": False, "error": None, "in_progress": False})
+    except ImportError:
+        # Legacy state not available, skip
+        pass
+
+
+__all__ = [
+    "mock_logger",
+    "mock_logger_factory",
+    "reset_foundation_setup_for_testing",
+    "reset_foundation_state",
+]

provide/testkit/main.py

@@ -0,0 +1,22 @@
+"""Main CLI entry point for provide-testkit."""
+
+from __future__ import annotations
+
+import click
+
+from .quality.cli import quality_cli
+
+
+@click.group()
+@click.version_option()
+def main() -> None:
+    """Provide Testkit - Testing utilities for the provide ecosystem."""
+    pass
+
+
+# Add quality commands
+main.add_command(quality_cli)
+
+
+if __name__ == "__main__":
+    main()

provide/testkit/mocking/__init__.py

@@ -0,0 +1,46 @@
+"""
+Mocking utilities for the provide-io ecosystem.
+
+Standardized mocking patterns, fixtures, and utilities to reduce
+boilerplate and ensure consistent mocking across all tests.
+"""
+
+from provide.testkit.mocking.fixtures import (
+    ANY,
+    AsyncMock,
+    MagicMock,
+    Mock,
+    PropertyMock,
+    assert_mock_calls,
+    async_mock_factory,
+    auto_patch,
+    call,
+    magic_mock_factory,
+    mock_factory,
+    mock_open_fixture,
+    patch,
+    patch_fixture,
+    patch_multiple_fixture,
+    property_mock_factory,
+    spy_fixture,
+)
+
+__all__ = [
+    "ANY",
+    "AsyncMock",
+    "MagicMock",
+    "Mock",
+    "PropertyMock",
+    "assert_mock_calls",
+    "async_mock_factory",
+    "auto_patch",
+    "call",
+    "magic_mock_factory",
+    "mock_factory",
+    "mock_open_fixture",
+    "patch",
+    "patch_fixture",
+    "patch_multiple_fixture",
+    "property_mock_factory",
+    "spy_fixture",
+]