test_logging_handler.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# tests/test_logging_handler.py
 
"""
Regression Tests — logging_handler
====================================
 
Purpose
-------
Verify that ``OcDiagnosticsHandler`` correctly bridges Python's ``logging``
module into ``oc_diagnostics._dbg()``, including level mapping, custom domain
routing, and the non-raising contract on internal exceptions.
 
Responsibilities
----------------
- Confirm that ``OcDiagnosticsHandler.emit()`` routes a LogRecord without raising.
- Confirm the default level map: DEBUG→L4, INFO→L2, WARNING/ERROR/CRITICAL→L1.
- Confirm that the handler's ``domain`` argument is forwarded to ``_dbg()``.
- Confirm that internal exceptions are swallowed (delegated to ``handleError``).
 
Diagnostics
-----------
Domain: TEST
Levels:
    L2 — lifecycle
    L3 — semantic details
    L4 — deep tracing
 
Contracts
---------
- Must not permanently modify oc_diagnostics global state.
- Must not start servers or require network access.
- Must run deterministically across repeated invocations.
"""
 
import logging
import os
import sys
import unittest.mock as mock
 
# ---------------------------------------------------------------------------
# Ensure oc_diagnostics is importable when run from the project root or the
# tests/ subdirectory.
# ---------------------------------------------------------------------------
_REPO_ROOT = os.path.normpath(os.path.join(os.path.dirname(__file__), ".."))
if _REPO_ROOT not in sys.path:
    sys.path.insert(0, _REPO_ROOT)
 
import oc_diagnostics.unified_debug as _ud
from oc_diagnostics.logging_handler import OcDiagnosticsHandler
 
 
def _make_record(level: int, msg: str = "test message") -> logging.LogRecord:
    """Build a minimal LogRecord for testing."""
    return logging.LogRecord(
        name="test.logger",
        level=level,
        pathname="test_file.py",
        lineno=1,
        msg=msg,
        args=(),
        exc_info=None,
    )
 
 
# ============================================================
# BASIC EMIT
# ============================================================
 
def test_handler_emit_info():
    """OcDiagnosticsHandler.emit() routes an INFO LogRecord through _dbg() without raising."""
    handler = OcDiagnosticsHandler(domain="GENERAL")
    record = _make_record(logging.INFO, "test handler message")
    old_silent = _ud.SILENT_MODE
    _ud.SILENT_MODE = True
    try:
        handler.emit(record)  # must not raise
    finally:
        _ud.SILENT_MODE = old_silent
 
 
# ============================================================
# LEVEL MAPPING
# ============================================================
 
def test_handler_level_mapping():
    """Default level map routes Python levels to oc_diagnostics levels correctly.
 
    DEBUG→L4, INFO→L2, WARNING→L1, ERROR→L1, CRITICAL→L1.
    """
    handler = OcDiagnosticsHandler(domain="_LEVEL_MAP_TEST_")
    expected = [
        (logging.DEBUG,    4),
        (logging.INFO,     2),
        (logging.WARNING,  1),
        (logging.ERROR,    1),
        (logging.CRITICAL, 1),
    ]
 
    for py_level, expected_diag_level in expected:
        with mock.patch("oc_diagnostics.logging_handler._dbg") as mock_dbg:
            record = _make_record(py_level)
            handler.emit(record)
            assert mock_dbg.called, (
                f"_dbg was not called for Python level {py_level}"
            )
            _, kwargs = mock_dbg.call_args
            actual_level = kwargs.get("level")
            assert actual_level == expected_diag_level, (
                f"Python level {py_level}: expected oc_diagnostics L{expected_diag_level}, "
                f"got L{actual_level}"
            )
 
 
# ============================================================
# CUSTOM DOMAIN
# ============================================================
 
def test_handler_custom_domain():
    """Handler's domain argument is forwarded as the first positional arg to _dbg()."""
    handler = OcDiagnosticsHandler(domain="MY_CUSTOM_DOMAIN")
    record = _make_record(logging.INFO, "domain check")
 
    with mock.patch("oc_diagnostics.logging_handler._dbg") as mock_dbg:
        handler.emit(record)
        assert mock_dbg.called, "_dbg was not called"
        args, _ = mock_dbg.call_args
        assert args[0] == "MY_CUSTOM_DOMAIN", (
            f"Expected domain 'MY_CUSTOM_DOMAIN', got {args[0]!r}"
        )
 
 
# ============================================================
# NON-RAISING CONTRACT
# ============================================================
 
def test_handler_never_raises():
    """OcDiagnosticsHandler.emit() must not propagate exceptions from _dbg()."""
    handler = OcDiagnosticsHandler(domain="GENERAL")
    record = _make_record(logging.INFO, "exception test")
 
    # Patch handleError to suppress the default stderr output during the test
    with mock.patch.object(handler, "handleError"):
        with mock.patch(
            "oc_diagnostics.logging_handler._dbg",
            side_effect=RuntimeError("deliberate internal failure"),
        ):
            handler.emit(record)  # must not raise — exception handled internally