Index

provide.testkit.streams

Stream Testing Utilities.

Provides utilities for redirecting and managing streams during testing.

Functions

enable_file_logging_for_testing

enable_file_logging_for_testing(
    log_file_path: str,
) -> object

Enable file logging specifically for testing scenarios.

This function bypasses the normal testmode detection that prevents file logging during tests. It should only be used in tests that specifically need to test file logging functionality.

Parameters:

Name	Type	Description	Default
log_file_path	str	Path to the log file to write to	required

Returns:

Type	Description
object	Context manager that keeps the file logging enabled

Note

This is a specialized utility for testing file logging behavior. Most tests should use captured_stderr_for_foundation fixture instead.

Source code in provide/testkit/streams/testing.py

def enable_file_logging_for_testing(log_file_path: str) -> object:
    """Enable file logging specifically for testing scenarios.

    This function bypasses the normal testmode detection that prevents
    file logging during tests. It should only be used in tests that
    specifically need to test file logging functionality.

    Args:
        log_file_path: Path to the log file to write to

    Returns:
        Context manager that keeps the file logging enabled

    Note:
        This is a specialized utility for testing file logging behavior.
        Most tests should use captured_stderr_for_foundation fixture instead.
    """
    from contextlib import contextmanager
    from unittest.mock import patch

    @contextmanager
    def file_logging_context() -> Any:
        # Patch the testmode detection function at the module level
        patcher = patch("provide.foundation.testmode.detection.is_in_click_testing", return_value=False)
        patcher.start()

        # Create a helper object that the test can use to trigger file logging setup
        class FileLoggingHelper:
            def setup_after_reset(self) -> None:
                from provide.foundation.streams.file import configure_file_logging

                configure_file_logging(log_file_path)

        try:
            yield FileLoggingHelper()
        finally:
            # Clean up patch
            patcher.stop()

    return file_logging_context()

get_current_log_stream

get_current_log_stream() -> TextIO

Get the currently active log stream.

Returns:

Type	Description
TextIO	The current log stream being used by Foundation

Source code in provide/testkit/streams/testing.py

def get_current_log_stream() -> TextIO:
    """
    Get the currently active log stream.

    Returns:
        The current log stream being used by Foundation
    """
    return get_log_stream()

reset_log_stream

reset_log_stream() -> None

Reset log stream back to stderr.

Source code in provide/testkit/streams/testing.py

def reset_log_stream() -> None:
    """Reset log stream back to stderr."""
    set_log_stream_for_testing(None)

set_log_stream_for_testing

set_log_stream_for_testing(stream: TextIO | None) -> None

Set the log stream for testing purposes.

This allows tests to redirect Foundation's log output to a custom stream (like StringIO) for capturing and verifying log messages.

Parameters:

Name	Type	Description	Default
stream	TextIO | None	Stream to redirect to, or None to reset to stderr	required

Source code in provide/testkit/streams/testing.py

def set_log_stream_for_testing(stream: TextIO | None) -> None:
    """
    Set the log stream for testing purposes.

    This allows tests to redirect Foundation's log output to a custom stream
    (like StringIO) for capturing and verifying log messages.

    Args:
        stream: Stream to redirect to, or None to reset to stderr
    """
    # Import the actual implementation from streams.core
    from provide.foundation.streams.core import (
        set_log_stream_for_testing as _set_stream,
    )

    _set_stream(stream)