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

provide/foundation/streams/file.py

@@ -0,0 +1,104 @@
+#
+# file.py
+#
+"""
+File stream management for Foundation.
+Handles file-based logging streams and file operations.
+"""
+
+import io
+from pathlib import Path
+import sys
+
+from provide.foundation.streams.core import (
+    _LOG_FILE_HANDLE,
+    _PROVIDE_LOG_STREAM,
+    _STREAM_LOCK,
+)
+from provide.foundation.utils.streams import get_safe_stderr
+
+
+def configure_file_logging(log_file_path: str | None) -> None:
+    """
+    Configure file logging if a path is provided.
+
+    Args:
+        log_file_path: Path to log file, or None to disable file logging
+    """
+    global _PROVIDE_LOG_STREAM, _LOG_FILE_HANDLE
+
+    # Import here to avoid circular dependency
+    from provide.foundation.streams.core import _is_in_click_testing
+
+    with _STREAM_LOCK:
+        # Don't modify streams if we're in Click testing context
+        if _is_in_click_testing():
+            return
+        # Close existing file handle if it exists
+        if _LOG_FILE_HANDLE and _LOG_FILE_HANDLE is not _PROVIDE_LOG_STREAM:
+            try:
+                _LOG_FILE_HANDLE.close()
+            except Exception:
+                pass
+            _LOG_FILE_HANDLE = None
+
+        # Check if we're in testing mode
+        is_test_stream = _PROVIDE_LOG_STREAM is not sys.stderr and not isinstance(
+            _PROVIDE_LOG_STREAM, io.TextIOWrapper
+        )
+
+        if log_file_path:
+            try:
+                Path(log_file_path).parent.mkdir(parents=True, exist_ok=True)
+                _LOG_FILE_HANDLE = open(
+                    log_file_path, "a", encoding="utf-8", buffering=1
+                )
+                _PROVIDE_LOG_STREAM = _LOG_FILE_HANDLE
+            except Exception as e:
+                # Log error to stderr and fall back
+                print(f"Failed to open log file {log_file_path}: {e}", file=sys.stderr)
+                _PROVIDE_LOG_STREAM = get_safe_stderr()
+        elif not is_test_stream:
+            _PROVIDE_LOG_STREAM = get_safe_stderr()
+
+
+def flush_log_streams() -> None:
+    """Flush all log streams."""
+    global _LOG_FILE_HANDLE
+
+    with _STREAM_LOCK:
+        if _LOG_FILE_HANDLE:
+            try:
+                _LOG_FILE_HANDLE.flush()
+            except Exception as e:
+                print(f"Failed to flush log file handle: {e}", file=sys.stderr)
+
+
+def close_log_streams() -> None:
+    """Close file log streams and reset to stderr."""
+    global _PROVIDE_LOG_STREAM, _LOG_FILE_HANDLE
+
+    # Import here to avoid circular dependency
+    from provide.foundation.streams.core import _is_in_click_testing
+
+    with _STREAM_LOCK:
+        if _LOG_FILE_HANDLE:
+            try:
+                _LOG_FILE_HANDLE.close()
+            except Exception:
+                pass
+            _LOG_FILE_HANDLE = None
+
+        # Don't reset stream to stderr if we're in Click testing context
+        if not _is_in_click_testing():
+            _PROVIDE_LOG_STREAM = sys.stderr
+
+
+def reset_streams() -> None:
+    """Reset all stream state (for testing)."""
+    # Import here to avoid circular dependency
+    from provide.foundation.streams.core import _is_in_click_testing
+
+    # Don't reset streams if we're in Click testing context
+    if not _is_in_click_testing():
+        close_log_streams()

provide/foundation/testing/__init__.py

@@ -0,0 +1,166 @@
+#
+# __init__.py
+#
+"""
+Foundation Testing Module.
+
+Unified testing utilities for Foundation with automatic context detection and warnings.
+This module consolidates all testing helpers in one place with clear warnings when active.
+"""
+
+import os
+import sys
+from typing import Any
+import warnings
+
+
+# Context detection functions
+def _is_testing_context() -> bool:
+    """Detect if we're running in a testing context."""
+    return (
+        "pytest" in sys.modules
+        or os.getenv("PYTEST_CURRENT_TEST") is not None
+        or "unittest" in sys.modules
+        or os.getenv("TESTING") == "true"
+        or any(arg.endswith(("pytest", "py.test")) for arg in sys.argv)
+    )
+
+
+def _warn_testing_active() -> None:
+    """Issue warning that testing helpers are active."""
+    if not os.getenv("FOUNDATION_SUPPRESS_TESTING_WARNINGS"):
+        warnings.warn(
+            "🚨 Foundation testing helpers are active - production behavior may differ",
+            UserWarning,
+            stacklevel=3,
+        )
+
+
+def _should_warn() -> bool:
+    """Check if we should issue testing warnings."""
+    # Don't warn if explicitly suppressed
+    if os.getenv("FOUNDATION_SUPPRESS_TESTING_WARNINGS"):
+        return False
+
+    # Don't warn if we're not in a testing context
+    if not _is_testing_context():
+        return False
+
+    # Don't warn if already warned (module-level state)
+    return not getattr(_should_warn, "_warned", False)
+
+
+# Issue warning on import if in testing context
+if _should_warn():
+    _warn_testing_active()
+    _should_warn._warned = True
+
+
+# Lazy imports to avoid importing testing utilities in production
+def __getattr__(name: str) -> Any:
+    """Lazy import testing utilities only when accessed."""
+
+    # CLI testing utilities
+    if name in [
+        "MockContext",
+        "isolated_cli_runner",
+        "temp_config_file",
+        "create_test_cli",
+        "mock_logger",
+        "CliTestCase",
+    ]:
+        import provide.foundation.testing.cli as cli_module
+
+        return getattr(cli_module, name)
+
+    # Logger testing utilities
+    elif name in ["reset_foundation_setup_for_testing", "reset_foundation_state"]:
+        import provide.foundation.testing.logger as logger_module
+
+        return getattr(logger_module, name)
+
+    # Stream testing utilities
+    elif name in ["set_log_stream_for_testing"]:
+        import provide.foundation.testing.streams as streams_module
+
+        return getattr(streams_module, name)
+
+    # Fixture utilities
+    elif name in [
+        "captured_stderr_for_foundation",
+        "setup_foundation_telemetry_for_test",
+    ]:
+        import provide.foundation.testing.fixtures as fixtures_module
+
+        return getattr(fixtures_module, name)
+
+    # Crypto fixtures (many fixtures)
+    elif name in [
+        "client_cert",
+        "server_cert",
+        "ca_cert",
+        "valid_cert_pem",
+        "valid_key_pem",
+        "invalid_cert_pem",
+        "invalid_key_pem",
+        "malformed_cert_pem",
+        "empty_cert",
+        "temporary_cert_file",
+        "temporary_key_file",
+        "cert_with_windows_line_endings",
+        "cert_with_utf8_bom",
+        "cert_with_extra_whitespace",
+        "external_ca_pem",
+    ]:
+        import provide.foundation.testing.crypto as crypto_module
+
+        return getattr(crypto_module, name)
+
+    # Hub fixtures
+    elif name in ["default_container_directory"]:
+        import provide.foundation.testing.hub as hub_module
+
+        return getattr(hub_module, name)
+
+    else:
+        raise AttributeError(f"module '{__name__}' has no attribute '{name}'")
+
+
+# Public API - these will be available for import but loaded lazily
+__all__ = [
+    # Context detection
+    "_is_testing_context",
+    # CLI testing
+    "MockContext",
+    "isolated_cli_runner",
+    "temp_config_file",
+    "create_test_cli",
+    "mock_logger",
+    "CliTestCase",
+    # Logger testing
+    "reset_foundation_setup_for_testing",
+    "reset_foundation_state",
+    # Stream testing
+    "set_log_stream_for_testing",
+    # Common fixtures
+    "captured_stderr_for_foundation",
+    "setup_foundation_telemetry_for_test",
+    # Crypto fixtures
+    "client_cert",
+    "server_cert",
+    "ca_cert",
+    "valid_cert_pem",
+    "valid_key_pem",
+    "invalid_cert_pem",
+    "invalid_key_pem",
+    "malformed_cert_pem",
+    "empty_cert",
+    "temporary_cert_file",
+    "temporary_key_file",
+    "cert_with_windows_line_endings",
+    "cert_with_utf8_bom",
+    "cert_with_extra_whitespace",
+    "external_ca_pem",
+    # Hub fixtures
+    "default_container_directory",
+]

provide/foundation/testing/cli.py

@@ -0,0 +1,227 @@
+"""
+CLI Testing Utilities for Foundation.
+
+Provides comprehensive testing support for CLI applications including
+context mocking, isolated runners, and configuration helpers.
+"""
+
+from contextlib import contextmanager
+import json
+import os
+from pathlib import Path
+import tempfile
+from typing import Any
+from unittest.mock import MagicMock
+
+import click
+from click.testing import CliRunner
+
+from provide.foundation.context import Context
+from provide.foundation.logger import get_logger
+
+log = get_logger(__name__)
+
+
+class MockContext(Context):
+    """Mock context for testing that tracks method calls."""
+
+    def __init__(self, **kwargs) -> None:
+        """Initialize mock context with tracking."""
+        super().__init__(**kwargs)
+        self.calls = []
+        self.saved_configs = []
+        self.loaded_configs = []
+
+    def save_config(self, path: str | Path) -> None:
+        """Track save_config calls."""
+        self.saved_configs.append(path)
+        super().save_config(path)
+
+    def load_config(self, path: str | Path) -> None:
+        """Track load_config calls."""
+        self.loaded_configs.append(path)
+        super().load_config(path)
+
+
+@contextmanager
+def isolated_cli_runner(
+    env: dict[str, str] | None = None,
+):
+    """
+    Create an isolated test environment for CLI testing.
+
+    Args:
+        env: Environment variables to set
+
+    Yields:
+        CliRunner instance in isolated filesystem
+    """
+    runner = CliRunner()
+
+    with runner.isolated_filesystem():
+        # Set up environment
+        old_env = {}
+        if env:
+            for key, value in env.items():
+                old_env[key] = os.environ.get(key)
+                os.environ[key] = value
+
+        try:
+            yield runner
+        finally:
+            # Restore environment
+            for key, old_value in old_env.items():
+                if old_value is None:
+                    os.environ.pop(key, None)
+                else:
+                    os.environ[key] = old_value
+
+
+@contextmanager
+def temp_config_file(
+    content: dict[str, Any] | str,
+    format: str = "json",
+) -> Path:
+    """
+    Create a temporary configuration file for testing.
+
+    Args:
+        content: Configuration content (dict or string)
+        format: File format (json, toml, yaml)
+
+    Yields:
+        Path to temporary config file
+    """
+    suffix = f".{format}"
+
+    with tempfile.NamedTemporaryFile(
+        mode="w",
+        suffix=suffix,
+        delete=False,
+    ) as f:
+        if isinstance(content, dict):
+            if format == "json":
+                json.dump(content, f, indent=2)
+            elif format == "toml":
+                try:
+                    import tomli_w
+
+                    # tomli_w needs the content as a string, not written to file handle
+                    toml_content = tomli_w.dumps(content)
+                    f.write(toml_content)
+                except ImportError:
+                    # Fall back to manual formatting
+                    for key, value in content.items():
+                        if isinstance(value, str):
+                            f.write(f'{key} = "{value}"\n')
+                        else:
+                            f.write(f"{key} = {value}\n")
+            elif format == "yaml":
+                try:
+                    import yaml
+
+                    yaml.safe_dump(content, f)
+                except ImportError:
+                    raise ImportError("PyYAML required for YAML testing")
+        else:
+            f.write(content)
+
+        config_path = Path(f.name)
+
+    try:
+        yield config_path
+    finally:
+        config_path.unlink(missing_ok=True)
+
+
+def create_test_cli(
+    name: str = "test-cli",
+    version: str = "1.0.0",
+    commands: list[click.Command] | None = None,
+) -> click.Group:
+    """
+    Create a test CLI group with standard options.
+
+    Args:
+        name: CLI name
+        version: CLI version
+        commands: Optional list of commands to add
+
+    Returns:
+        Click Group configured for testing
+    """
+    from provide.foundation.cli.decorators import standard_options
+
+    @click.group(name=name)
+    @standard_options
+    @click.pass_context
+    def cli(ctx, **kwargs) -> None:
+        """Test CLI for testing."""
+        ctx.obj = Context(**{k: v for k, v in kwargs.items() if v is not None})
+
+    if commands:
+        for cmd in commands:
+            cli.add_command(cmd)
+
+    return cli
+
+
+def mock_logger():
+    """
+    Create a mock logger for testing.
+
+    Returns:
+        MagicMock with common logger methods
+    """
+    mock = MagicMock()
+    mock.debug = MagicMock()
+    mock.info = MagicMock()
+    mock.warning = MagicMock()
+    mock.error = MagicMock()
+    mock.critical = MagicMock()
+    return mock
+
+
+class CliTestCase:
+    """Base class for CLI test cases with common utilities."""
+
+    def setup_method(self) -> None:
+        """Set up test case."""
+        self.runner = CliRunner()
+        self.temp_files = []
+
+    def teardown_method(self) -> None:
+        """Clean up test case."""
+        for path in self.temp_files:
+            if path.exists():
+                path.unlink()
+
+    def invoke(self, *args, **kwargs):
+        """Invoke CLI command."""
+        return self.runner.invoke(*args, **kwargs)
+
+    def create_temp_file(self, content: str = "", suffix: str = "") -> Path:
+        """Create a temporary file that will be cleaned up."""
+        with tempfile.NamedTemporaryFile(
+            mode="w",
+            suffix=suffix,
+            delete=False,
+        ) as f:
+            f.write(content)
+            path = Path(f.name)
+
+        self.temp_files.append(path)
+        return path
+
+    def assert_json_output(self, result, expected: dict[str, Any]) -> None:
+        """Assert that output is valid JSON matching expected."""
+        try:
+            output = json.loads(result.output)
+        except json.JSONDecodeError as e:
+            raise AssertionError(f"Output is not valid JSON: {e}\n{result.output}")
+
+        for key, value in expected.items():
+            assert key in output, f"Key '{key}' not in output"
+            assert output[key] == value, (
+                f"Value mismatch for '{key}': {output[key]} != {value}"
+            )

provide/foundation/testing/crypto.py

@@ -0,0 +1,163 @@
+"""
+Crypto Testing Fixtures for Foundation.
+
+Provides comprehensive pytest fixtures for testing certificate functionality,
+including valid/invalid certificates, keys, chains, and edge cases.
+"""
+
+import pytest
+
+from provide.foundation import logger
+from provide.foundation.crypto import Certificate
+
+
+@pytest.fixture(scope="module")
+def client_cert():
+    """Create a client certificate for testing."""
+    cert_pem = """-----BEGIN CERTIFICATE-----
+MIIB+jCCAYGgAwIBAgIJAPsxOr78BIU0MAoGCCqGSM49BAMEMCgxEjAQBgNVBAoM
+CUhhc2hpQ29ycDESMBAGA1UEAwwJbG9jYWxob3N0MB4XDTI1MDIwNTIzMTkzN1oX
+DTI2MDIwNTIzMTkzN1owKDESMBAGA1UECgwJSGFzaGlDb3JwMRIwEAYDVQQDDAls
+b2NhbGhvc3QwdjAQBgcqhkjOPQIBBgUrgQQAIgNiAARCi3SNYYDpSeScRM52tFYr
+URzsPOE/ad8BzvpvL+mfy1c5oHQhh6KPnxpoo1WyDJGYplwPTGS68DvvWmolrPAt
+C7I7r7spgyJS1358E5fA2NWk9/YPaiUzK2gsyrL9dKajdzB1MA8GA1UdEwEB/wQF
+MAMBAf8wFAYDVR0RBA0wC4IJbG9jYWxob3N0MB0GA1UdJQQWMBQGCCsGAQUFBwMC
+BggrBgEFBQcDATAOBgNVHQ8BAf8EBAMCA6gwHQYDVR0OBBYEFOwuttXPh5kTPSpX
+a2ex0+VKjlpaMAoGCCqGSM49BAMEA2cAMGQCMGbN17Zt1GxZ41cXTaQOKuv/BIQd
+nkaRz51XrITKaULNie4bgW6gT94cTUFQ9SNwEAIwOpmKeZqYG9WHcqol4QEUmMVM
+MY3jxMiLpb9Mt/ysstXmsrQY7UoLu+c6zfKwyTEJ
+-----END CERTIFICATE-----"""
+
+    key_pem = """-----BEGIN EC PRIVATE KEY-----
+MIGkAgEBBDAkxo19KczdciRiJjOWEKGY5mH9s1D0aUS5XBdvktcaonIOdqNrkCt1
+BC5YjEAVLNWgBwYFK4EEACKhZANiAARCi3SNYYDpSeScRM52tFYrURzsPOE/ad8B
+zvpvL+mfy1c5oHQhh6KPnxpoo1WyDJGYplwPTGS68DvvWmolrPAtC7I7r7spgyJS
+1358E5fA2NWk9/YPaiUzK2gsyrL9dKY=
+-----END EC PRIVATE KEY-----"""
+
+    logger.debug(f"Created CLIENT_CERT fixture: {cert_pem[:30]}...")
+    return Certificate(cert_pem_or_uri=cert_pem, key_pem_or_uri=key_pem)
+
+
+@pytest.fixture(scope="module")
+def server_cert():
+    """Create a server certificate for testing."""
+    cert_pem = """-----BEGIN CERTIFICATE-----
+MIIB+jCCAYGgAwIBAgIJAKrIoEQw7N9LMAoGCCqGSM49BAMEMCgxEjAQBgNVBAoM
+CUhhc2hpQ29ycDESMBAGA1UEAwwJbG9jYWxob3N0MB4XDTI1MDIwNTIzMTkzN1oX
+DTI2MDIwNTIzMTkzN1owKDESMBAGA1UECgwJSGFzaGlDb3JwMRIwEAYDVQQDDAls
+b2NhbGhvc3QwdjAQBgcqhkjOPQIBBgUrgQQAIgNiAARMxEVmGX3a4IWPOAJ2MX2s
+2Wj3KZ0Io5EwUPMkxknGheO2e55qeHp/tkEFzYt9AH8du1xJLKKFbsGV5q9vipGN
+x5XMbj2RMdH5VXHTAdc/bLFFy9kybQqo300Rv6ViW2KjdzB1MA8GA1UdEwEB/wQF
+MAMBAf8wFAYDVR0RBA0wC4IJbG9jYWxob3N0MB0GA1UdJQQWMBQGCCsGAQUFBwMC
+BggrBgEFBQcDATAOBgNVHQ8BAf8EBAMCA6gwHQYDVR0OBBYEFJy7Iz7whfiALYDB
+TsM+IHXb1E8+MAoGCCqGSM49BAMEA2cAMGQCMFwxBS3lZSUprvrNGfJL83oGVY97
+emQpHy/SEWpHBK8awn1XeTf+ZAwLaxc3K+AKqwIwPwIbIlmstd69zAYMFNHtzceN
+XOzBx35sWRw92gr/hbE4hYeDBqEUwstSFNZ6MZu0
+-----END CERTIFICATE-----"""
+
+    key_pem = """-----BEGIN EC PRIVATE KEY-----
+MIGkAgEBBDDZ1MORWFVI0HtgKv+zZys/5e1HVmfcs4bwdp3VEsuwS6an3gTwGnSP
+Ce+bI6f/TvGgBwYFK4EEACKhZANiAARMxEVmGX3a4IWPOAJ2MX2s2Wj3KZ0Io5Ew
+UPMkxknGheO2e55qeHp/tkEFzYt9AH8du1xJLKKFbsGV5q9vipGNx5XMbj2RMdH5
+VXHTAdc/bLFFy9kybQqo300Rv6ViW2I=
+-----END EC PRIVATE KEY-----"""
+
+    logger.debug(f"Created SERVER_CERT fixture: {cert_pem[:30]}...")
+    return Certificate(cert_pem_or_uri=cert_pem, key_pem_or_uri=key_pem)
+
+
+@pytest.fixture(scope="module")
+def ca_cert():
+    """Create a self-signed CA certificate for testing."""
+    return Certificate.create_ca(
+        common_name="Test CA", organization_name="Test Organization", validity_days=365
+    )
+
+
+@pytest.fixture(scope="module")
+def valid_key_pem(client_cert):
+    """Get a valid key PEM from the client cert fixture."""
+    return client_cert.key
+
+
+@pytest.fixture
+def valid_cert_pem(client_cert):
+    """Get a valid certificate PEM from the client cert fixture."""
+    return client_cert.cert
+
+
+@pytest.fixture
+def invalid_key_pem() -> str:
+    """Returns an invalid PEM key."""
+    return "INVALID KEY DATA"
+
+
+@pytest.fixture
+def invalid_cert_pem() -> str:
+    """Returns an invalid PEM certificate."""
+    return "INVALID CERTIFICATE DATA"
+
+
+@pytest.fixture
+def malformed_cert_pem() -> str:
+    """Returns a PEM certificate with incorrect headers."""
+    return "-----BEGIN CERT-----\nMALFORMED DATA\n-----END CERT-----"
+
+
+@pytest.fixture
+def empty_cert() -> str:
+    """Returns an empty certificate string."""
+    return ""
+
+
+@pytest.fixture
+def temporary_cert_file(tmp_path, client_cert) -> str:
+    """Creates a temporary file containing the client certificate."""
+    cert_file = tmp_path / "client_cert.pem"
+    cert_file.write_text(client_cert.cert)
+    return f"file://{cert_file}"
+
+
+@pytest.fixture
+def temporary_key_file(tmp_path, client_cert) -> str:
+    """Creates a temporary file containing the client private key."""
+    key_file = tmp_path / "client_key.pem"
+    key_file.write_text(client_cert.key)
+    return f"file://{key_file}"
+
+
+@pytest.fixture
+def cert_with_windows_line_endings(client_cert) -> str:
+    """Returns a certificate PEM with Windows line endings."""
+    return client_cert.cert.replace("\n", "\r\n")
+
+
+@pytest.fixture
+def cert_with_utf8_bom(client_cert) -> str:
+    """Returns a certificate PEM with UTF-8 BOM."""
+    return "\ufeff" + client_cert.cert
+
+
+@pytest.fixture
+def cert_with_extra_whitespace(client_cert) -> str:
+    """Returns a certificate PEM with extra whitespace."""
+    return f"   {client_cert.cert}   \n\n  "
+
+
+@pytest.fixture(scope="module")
+def external_ca_pem() -> str:
+    """Provides an externally generated CA certificate PEM."""
+    return """-----BEGIN CERTIFICATE-----
+MIIB4TCCAYegAwIBAgIJAPZ9vcVfR8AdMAoGCCqGSM49BAMCMFExCzAJBgNVBAYT
+AlVTMQswCQYDVQQIDAJDQTEUMBIGA1UEBwwLU2FuIEZyYW5jaXNjbzEOMAwGA1UE
+CgwFTXlPcmcxEzARBgNVBAMMCkV4dGVybmFsIENBMB4XDTI0MDgwMjEwNTgwMVoX
+DTM0MDczMDEwNTgwMVowUTELMAkGA1UEBhMCVVMxCzAJBgNVBAgMAkNBMREwDwYD
+VQQHDAhTYW5EaWVnbzEOMAwGA1UECgwFTXlPcmcxEzARBgNVBAMMCkV4dGVybmFs
+IENBMHYwEAYHKoZIzj0CAQYFK4EEACIDYgAEgyF5Y8upm+M3ZzO8P4n7q2sS+L4c
+mhl5XGg3vIOwFf7lG8XZCgJ6Xy4t1t8oD3zY0m9X8H8Z4YhY7K6b7c8Y7Xv6Y9fV
+Q8M7Jg9nJ0x5c1N40zQwZzKjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMBAf8E
+BTADAQH/MB0GA1UdDgQWBBTGX00Gq7b09y/0C9eK0XgJp0mY7DAKBggqhkjOPQQD
+AgNJADBGAiEAx1xH/b83/u5t7r29a/THZnFjQ7pvT2N0L4hG4BgGgXACIQD02W2+
+MHB78ZWM+JOgikYj99qD6nLp0nkMyGmkSC7RYg==
+-----END CERTIFICATE-----"""

provide/foundation/testing/fixtures.py

@@ -0,0 +1,49 @@
+"""
+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, setup_telemetry
+from provide.foundation.testing.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()
+        setup_telemetry(config)
+
+    return _setup