test_id_instrumentation.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# tests/test_id_instrumentation.py
 
"""
Regression Tests — id_instrumentation
=======================================
 
Purpose
-------
Verify the full behaviour of ``id_instrumentation``: structural-ID protection,
dict-ID passthrough, depth-limit guarding, recursive children traversal, and
project-defined custom structural ID extensions.
 
Responsibilities
----------------
- Confirm ``is_structural_id()`` correctly classifies built-in structural and
  non-structural IDs.
- Confirm ``instrument_ids()`` rewrites non-structural string IDs to
  ``{"event": "<id>"}``.
- Confirm dict IDs are never rewritten.
- Confirm components without an ``id`` attribute are returned unchanged.
- Confirm recursion stops at ``MAX_INSTRUMENT_DEPTH`` without raising.
- Confirm nested children are instrumented recursively.
- Confirm ``ADDITIONAL_STRUCTURAL_PREFIXES`` prevents instrumentation.
- Confirm ``ADDITIONAL_STRUCTURAL_EXACT`` prevents instrumentation.
 
Diagnostics
-----------
Domain: TEST
Levels:
    L2 — lifecycle
    L3 — semantic details
    L4 — deep tracing
 
Contracts
---------
- All Dash-dependent 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.id_instrumentation import (
    instrument_ids,
    is_structural_id,
    MAX_INSTRUMENT_DEPTH,
)
 
 
# ============================================================
# is_structural_id()
# ============================================================
 
def test_structural_id_protection():
    """is_structural_id() correctly classifies structural and non-structural IDs."""
    structural_ids = [
        "root-group-main",
        "tab-group-settings",
        "tab-content-data",
        "pane-group-left",
        "theme-root",
        "ui-theme-store",
        "init-once",
    ]
    for cid in structural_ids:
        assert is_structural_id(cid), f"Expected structural: {cid!r}"
 
    non_structural_ids = [
        "my-button",
        "dropdown-filter",
        "input-name",
        "custom123",
    ]
    for cid in non_structural_ids:
        assert not is_structural_id(cid), f"Expected non-structural: {cid!r}"
 
 
# ============================================================
# instrument_ids() — basic rewriting
# ============================================================
 
def test_instrument_ids_basic():
    """instrument_ids() rewrites a non-structural string ID to {"event": "<id>"}."""
    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("Click me", id="btn-test")
        result = instrument_ids(comp)
        assert result.id == {"event": "btn-test"}, (
            f"Expected {{'event': 'btn-test'}}, got: {result.id!r}"
        )
    finally:
        _ud.INSTRUMENTATION_ENABLED = old_enabled
        _ud.DEBUG_LEVELS["INSTRUMENTATION"] = old_level
 
 
# ============================================================
# Dict ID passthrough
# ============================================================
 
def test_dict_id_not_rewritten():
    """Components with dict IDs are returned unchanged — no double-wrapping."""
    old_enabled = _ud.INSTRUMENTATION_ENABLED
    old_level = _ud.DEBUG_LEVELS.get("INSTRUMENTATION", 0)
    _ud.INSTRUMENTATION_ENABLED = True
    _ud.DEBUG_LEVELS["INSTRUMENTATION"] = 9
    try:
        original_id = {"event": "already-instrumented"}
        comp = html.Button("X", id=original_id)
        result = instrument_ids(comp)
        assert result.id == original_id, (
            f"Dict ID must not be rewritten, got: {result.id!r}"
        )
    finally:
        _ud.INSTRUMENTATION_ENABLED = old_enabled
        _ud.DEBUG_LEVELS["INSTRUMENTATION"] = old_level
 
 
# ============================================================
# No-ID component passthrough
# ============================================================
 
def test_no_id_component_unchanged():
    """Components without an id attribute have their ID left as None."""
    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.Div("no id")
        result = instrument_ids(comp)
        # id should remain None (not rewritten to a dict)
        cid = getattr(result, "id", None)
        assert not isinstance(cid, dict), (
            f"Component without id must not receive a dict ID, got: {cid!r}"
        )
    finally:
        _ud.INSTRUMENTATION_ENABLED = old_enabled
        _ud.DEBUG_LEVELS["INSTRUMENTATION"] = old_level
 
 
# ============================================================
# Depth limit
# ============================================================
 
def test_max_depth_limit():
    """instrument_ids() stops recursion at MAX_INSTRUMENT_DEPTH without RecursionError."""
    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.Div("deep-component", id="deep-comp")
        # Calling with _depth > MAX_INSTRUMENT_DEPTH triggers the guard directly
        result = instrument_ids(comp, _depth=MAX_INSTRUMENT_DEPTH + 1)
        # Component must be returned unchanged (guard returns early)
        assert result is comp, (
            "instrument_ids must return the component unchanged at MAX_INSTRUMENT_DEPTH"
        )
        assert result.id == "deep-comp", (
            f"ID must not be rewritten at depth limit, got: {result.id!r}"
        )
    finally:
        _ud.INSTRUMENTATION_ENABLED = old_enabled
        _ud.DEBUG_LEVELS["INSTRUMENTATION"] = old_level
 
 
# ============================================================
# Nested children traversal
# ============================================================
 
def test_nested_children_traversal():
    """instrument_ids() recursively instruments children of a component."""
    old_enabled = _ud.INSTRUMENTATION_ENABLED
    old_level = _ud.DEBUG_LEVELS.get("INSTRUMENTATION", 0)
    _ud.INSTRUMENTATION_ENABLED = True
    _ud.DEBUG_LEVELS["INSTRUMENTATION"] = 9
    try:
        inner = html.Button("Click", id="inner-btn")
        outer = html.Div(inner, id="outer-div")
        result = instrument_ids(outer)
        assert result.id == {"event": "outer-div"}, (
            f"Outer ID must be instrumented, got: {result.id!r}"
        )
        assert result.children.id == {"event": "inner-btn"}, (
            f"Inner child ID must be instrumented, got: {result.children.id!r}"
        )
    finally:
        _ud.INSTRUMENTATION_ENABLED = old_enabled
        _ud.DEBUG_LEVELS["INSTRUMENTATION"] = old_level
 
 
# ============================================================
# Custom structural prefixes (FS-02 / OI-17)
# ============================================================
 
def test_additional_structural_prefixes():
    """ADDITIONAL_STRUCTURAL_PREFIXES prevents ID rewriting for matching components."""
    old_enabled = _ud.INSTRUMENTATION_ENABLED
    old_level = _ud.DEBUG_LEVELS.get("INSTRUMENTATION", 0)
    old_prefixes = _ud.ADDITIONAL_STRUCTURAL_PREFIXES
    _ud.INSTRUMENTATION_ENABLED = True
    _ud.DEBUG_LEVELS["INSTRUMENTATION"] = 9
    _ud.ADDITIONAL_STRUCTURAL_PREFIXES = ("custom-struct-",)
    try:
        comp = html.Div("protected", id="custom-struct-main")
        result = instrument_ids(comp)
        assert result.id == "custom-struct-main", (
            f"Custom structural prefix must prevent ID rewriting, got: {result.id!r}"
        )
    finally:
        _ud.INSTRUMENTATION_ENABLED = old_enabled
        _ud.DEBUG_LEVELS["INSTRUMENTATION"] = old_level
        _ud.ADDITIONAL_STRUCTURAL_PREFIXES = old_prefixes
 
 
# ============================================================
# Custom structural exact matches (FS-02 / OI-17)
# ============================================================
 
def test_additional_structural_exact():
    """ADDITIONAL_STRUCTURAL_EXACT prevents ID rewriting for exact-match IDs."""
    old_enabled = _ud.INSTRUMENTATION_ENABLED
    old_level = _ud.DEBUG_LEVELS.get("INSTRUMENTATION", 0)
    old_exact = _ud.ADDITIONAL_STRUCTURAL_EXACT
    _ud.INSTRUMENTATION_ENABLED = True
    _ud.DEBUG_LEVELS["INSTRUMENTATION"] = 9
    _ud.ADDITIONAL_STRUCTURAL_EXACT = frozenset(["my-special-store"])
    try:
        comp = html.Div("protected-exact", id="my-special-store")
        result = instrument_ids(comp)
        assert result.id == "my-special-store", (
            f"Custom structural exact ID must prevent rewriting, got: {result.id!r}"
        )
    finally:
        _ud.INSTRUMENTATION_ENABLED = old_enabled
        _ud.DEBUG_LEVELS["INSTRUMENTATION"] = old_level
        _ud.ADDITIONAL_STRUCTURAL_EXACT = old_exact