test_instrumentation_middleware.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# tests/test_instrumentation_middleware.py
 
"""
Regression Tests — instrumentation_middleware
==============================================
 
Purpose
-------
Verify the public API of ``instrumentation_middleware``: the no-op contract
when instrumentation is disabled, list/tuple container preservation, single-
component instrumentation, and the double-wrapping prevention guard.
 
Responsibilities
----------------
- Confirm ``apply_instrumentation()`` returns the component unchanged when
  ``INSTRUMENTATION_ENABLED=False``.
- Confirm list inputs are instrumented element-by-element with the list type
  preserved.
- Confirm tuple inputs are instrumented element-by-element with the tuple type
  preserved.
- Confirm a single component has its string ID rewritten.
- Confirm a component whose ID is already a dict is not double-wrapped.
 
Diagnostics
-----------
Domain: TEST
Levels:
    L2 — lifecycle
    L3 — semantic details
    L4 — deep tracing
 
Contracts
---------
- All tests are skipped automatically when Dash is not installed.
- Must not permanently modify oc_diagnostics global state.
- Must restore all patched globals in finally blocks.
- Must not start servers or require network access.
- Must run deterministically across repeated invocations.
"""
 
import os
import sys
 
# ---------------------------------------------------------------------------
# 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 pytest
 
# Skip the entire module when Dash is not installed
dash_html = pytest.importorskip("dash.html", reason="Dash not installed")
html = dash_html
 
import oc_diagnostics.unified_debug as _ud
from oc_diagnostics.instrumentation_middleware import apply_instrumentation
 
 
# ============================================================
# NO-OP WHEN DISABLED
# ============================================================
 
def test_apply_instrumentation_no_op():
    """apply_instrumentation() returns the component unchanged when disabled."""
    old_enabled = _ud.INSTRUMENTATION_ENABLED
    _ud.INSTRUMENTATION_ENABLED = False
    try:
        comp = html.Div("X", id="test-noop")
        result = apply_instrumentation(comp)
        assert result is comp, "Component must be returned unchanged when disabled"
        assert result.id == "test-noop", (
            f"ID must not change when disabled, got: {result.id!r}"
        )
    finally:
        _ud.INSTRUMENTATION_ENABLED = old_enabled
 
 
# ============================================================
# LIST HANDLING
# ============================================================
 
def test_apply_list_return():
    """apply_instrumentation() instruments each element of a list and preserves the type."""
    old_enabled = _ud.INSTRUMENTATION_ENABLED
    old_level = _ud.DEBUG_LEVELS.get("INSTRUMENTATION", 0)
    _ud.INSTRUMENTATION_ENABLED = True
    _ud.DEBUG_LEVELS["INSTRUMENTATION"] = 9
    try:
        comps = [html.Button("A", id="btn-a"), html.Div("B", id="div-b")]
        result = apply_instrumentation(comps)
        assert isinstance(result, list), f"Expected list, got {type(result)}"
        assert result[0].id == {"event": "btn-a"}, (
            f"Expected instrumented ID for list[0], got: {result[0].id!r}"
        )
        assert result[1].id == {"event": "div-b"}, (
            f"Expected instrumented ID for list[1], got: {result[1].id!r}"
        )
    finally:
        _ud.INSTRUMENTATION_ENABLED = old_enabled
        _ud.DEBUG_LEVELS["INSTRUMENTATION"] = old_level
 
 
# ============================================================
# TUPLE HANDLING
# ============================================================
 
def test_apply_tuple_return():
    """apply_instrumentation() instruments each element of a tuple and preserves the type."""
    old_enabled = _ud.INSTRUMENTATION_ENABLED
    old_level = _ud.DEBUG_LEVELS.get("INSTRUMENTATION", 0)
    _ud.INSTRUMENTATION_ENABLED = True
    _ud.DEBUG_LEVELS["INSTRUMENTATION"] = 9
    try:
        comps = (html.Button("X", id="btn-x"),)
        result = apply_instrumentation(comps)
        assert isinstance(result, tuple), f"Expected tuple, got {type(result)}"
        assert result[0].id == {"event": "btn-x"}, (
            f"Expected instrumented ID for tuple[0], got: {result[0].id!r}"
        )
    finally:
        _ud.INSTRUMENTATION_ENABLED = old_enabled
        _ud.DEBUG_LEVELS["INSTRUMENTATION"] = old_level
 
 
# ============================================================
# SINGLE COMPONENT
# ============================================================
 
def test_apply_single_component():
    """apply_instrumentation() rewrites the ID of a single component."""
    old_enabled = _ud.INSTRUMENTATION_ENABLED
    old_level = _ud.DEBUG_LEVELS.get("INSTRUMENTATION", 0)
    _ud.INSTRUMENTATION_ENABLED = True
    _ud.DEBUG_LEVELS["INSTRUMENTATION"] = 9
    try:
        comp = html.Button("Solo", id="solo-btn")
        result = apply_instrumentation(comp)
        assert result.id == {"event": "solo-btn"}, (
            f"Expected instrumented ID, got: {result.id!r}"
        )
    finally:
        _ud.INSTRUMENTATION_ENABLED = old_enabled
        _ud.DEBUG_LEVELS["INSTRUMENTATION"] = old_level
 
 
# ============================================================
# NO DOUBLE-WRAPPING
# ============================================================
 
def test_no_double_wrapping():
    """apply_instrumentation() does not re-wrap a component whose ID is already a dict."""
    old_enabled = _ud.INSTRUMENTATION_ENABLED
    old_level = _ud.DEBUG_LEVELS.get("INSTRUMENTATION", 0)
    _ud.INSTRUMENTATION_ENABLED = True
    _ud.DEBUG_LEVELS["INSTRUMENTATION"] = 9
    try:
        already_wrapped_id = {"event": "already-wrapped"}
        comp = html.Button("Wrapped", id=already_wrapped_id)
        result = apply_instrumentation(comp)
        assert result.id == already_wrapped_id, (
            f"Dict ID must not be double-wrapped, got: {result.id!r}"
        )
    finally:
        _ud.INSTRUMENTATION_ENABLED = old_enabled
        _ud.DEBUG_LEVELS["INSTRUMENTATION"] = old_level