instrumentation_selftest_cli.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oc_diagnostics/instrumentation_selftest_cli.py
 
"""
Instrumentation Self-Test (CLI)
================================
 
Purpose
-------
This module performs Dash-based CLI tests of the instrumentation system.
It validates:
 
    - Static ID instrumentation
    - Nested component recursion
    - Structural ID protection
    - Custom component handling
    - Logging behavior under different debug levels
 
**Requires Dash to be installed** (``pip install oc_diagnostics[dash]``).
Dash component classes (``html.Div``, ``html.Button``, etc.) are used to
construct component trees for instrumentation testing.  No Dash server is
started and no browser interaction is required.
 
This CLI test suite is designed to be:
 
    - deterministic
    - isolated
    - assertion-driven (each test uses explicit ``if not: raise AssertionError``
      so checks survive ``python -O`` optimization)
    - safe for use in CI/CD pipelines
 
Responsibilities
----------------
- Parse CLI arguments (``--use-global``).
- Temporarily set ``INSTRUMENTATION_ENABLED=True`` and optionally force debug
  level=9 for the duration of the test run; restore all module state on exit.
- Run five deterministic test functions, each using ``assert`` to verify
  ID-rewriting invariants.
- Collect PASS/FAIL per test and print a structured summary.
- Exit with code ``0`` on full success or ``1`` on any failure.
 
Exit Codes
----------
``0`` — all tests passed.
``1`` — one or more tests failed or raised an unexpected exception.
 
---------------------------------------------------------------------------
Contract & Lifecycle
---------------------------------------------------------------------------
 
The CLI test suite follows this lifecycle:
 
    1. Parse command-line arguments
    2. Choose debug-level mode:
         - FORCE VERBOSE MODE (default): forces INSTRUMENTATION_ENABLED=True,
           INSTRUMENTATION level=9, UI level=9
         - USE GLOBAL LEVELS (--use-global)
    3. Run a series of deterministic instrumentation tests, each with
       explicit ``if not: raise AssertionError`` checks that verify actual
       ID rewriting behaviour and survive ``python -O``
    4. Restore original settings
    5. Print PASS/FAIL summary and exit with code 0 or 1
 
---------------------------------------------------------------------------
Debug-Level Modes
---------------------------------------------------------------------------
 
MODE A — FORCE VERBOSE (default)
---------------------------------
Force:
 
    INSTRUMENTATION_ENABLED = True
    DEBUG_LEVELS["INSTRUMENTATION"] = 9
    DEBUG_LEVELS["UI"] = 9
 
This ensures:
    - full recursion logs
    - full instrumentation logs
    - assertions that verify the rewritten IDs are correct
 
MODE B — RESPECT GLOBAL LEVELS
-------------------------------
Use whatever INSTRUMENTATION_ENABLED and levels are defined in
unified_debug.py.  Assertions check behaviour consistent with those levels.
 
Select mode via:
 
    python -m oc_diagnostics.instrumentation_selftest_cli --use-global
 
---------------------------------------------------------------------------
Diagnostics
---------------------------------------------------------------------------
 
Domain: TEST
Levels:
    L2 — lifecycle
    L3 — semantic details
    L4 — deep tracing
 
---------------------------------------------------------------------------
Contracts
---------------------------------------------------------------------------
 
- Must exit 0 only when all assertions pass.
- Must exit 1 when any test fails or raises an unexpected exception.
- Must restore INSTRUMENTATION_ENABLED and DEBUG_LEVELS after each run.
- Must not start a Dash server or require browser interaction.
- Must require ``oc_diagnostics[dash]`` (Dash component classes are used).
"""
 
import sys
import argparse
 
import oc_diagnostics.unified_debug as _ud
from dash import html
from oc_diagnostics.unified_debug import (
    _dbg,
    DEBUG_LEVELS,
)
from oc_diagnostics.instrumentation_middleware import apply_instrumentation
 
 
# ============================================================
# Helper: print section headers
# ============================================================
 
def _print_header(title: str):
    print("\n" + "=" * 70)
    print(title)
    print("=" * 70)
 
 
# ============================================================
# TEST 1 — Basic static instrumentation
# ============================================================
 
def test_static_basic():
    _print_header("TEST 1: Basic static instrumentation")
 
    comp = html.Div("Hello", id="hello")
    result = apply_instrumentation(comp)
 
    print("Instrumented ID:", result.id)
 
    if result is None:
        raise AssertionError("apply_instrumentation must return a component")
    if result is not comp:
        raise AssertionError(
            "apply_instrumentation should return the same object (mutates in place)"
        )
    if result.id != {"event": "hello"}:
        raise AssertionError(
            f"Expected {{'event': 'hello'}}, got: {result.id!r}"
        )
 
 
# ============================================================
# TEST 2 — Nested components
# ============================================================
 
def test_static_nested():
    _print_header("TEST 2: Nested components")
 
    comp = html.Div(
        [
            html.Button("A", id="btnA"),
            html.Div([html.Button("B", id="btnB")]),
        ]
    )
 
    result = apply_instrumentation(comp)
 
    print("btnA ->", result.children[0].id)
    print("btnB ->", result.children[1].children[0].id)
 
    if result is None:
        raise AssertionError("apply_instrumentation must return a component")
    if result.children[0].id != {"event": "btnA"}:
        raise AssertionError(
            f"Expected {{'event': 'btnA'}}, got: {result.children[0].id!r}"
        )
    if result.children[1].children[0].id != {"event": "btnB"}:
        raise AssertionError(
            f"Expected {{'event': 'btnB'}}, got: {result.children[1].children[0].id!r}"
        )
 
 
# ============================================================
# TEST 3 — Structural ID protection
# ============================================================
 
def test_structural_protection():
    _print_header("TEST 3: Structural ID protection")
 
    comp = html.Div("X", id="root-group-123")
    result = apply_instrumentation(comp)
 
    print("Structural ID preserved:", result.id)
 
    if result is None:
        raise AssertionError("apply_instrumentation must return a component")
    if result.id != "root-group-123":
        raise AssertionError(
            f"Structural IDs must never be rewritten, got: {result.id!r}"
        )
 
 
# ============================================================
# TEST 4 — Custom component behavior
# ============================================================
 
def test_custom_component_behavior():
    _print_header("TEST 4: Custom component behavior")
 
    class Custom:
        def __init__(self, id_val):
            self.id = id_val
            self.children = []
 
    # ----------------------------------------------------------------
    # 4a. At INSTRUMENTATION level >= 5, custom components ARE rewritten.
    # main() forces level 9 before running tests, so this must pass.
    # ----------------------------------------------------------------
    DEBUG_LEVELS["INSTRUMENTATION"] = 9
    comp_high = Custom("custom-high")
    result_high = apply_instrumentation(comp_high)
    print("Custom component ID (level 9):", result_high.id)
    if result_high is None:
        raise AssertionError("apply_instrumentation must return a component")
    if result_high.id != {"event": "custom-high"}:
        raise AssertionError(
            f"Level 9: expected {{'event': 'custom-high'}}, got: {result_high.id!r}"
        )
 
    # ----------------------------------------------------------------
    # 4b. At INSTRUMENTATION level < 5, custom components are NOT rewritten.
    # ----------------------------------------------------------------
    DEBUG_LEVELS["INSTRUMENTATION"] = 3
    comp_low = Custom("custom-low")
    result_low = apply_instrumentation(comp_low)
    print("Custom component ID (level 3):", result_low.id)
    if result_low.id != "custom-low":
        raise AssertionError(
            f"Level 3: expected 'custom-low' (no rewrite), got: {result_low.id!r}"
        )
 
    # Restore maximum verbosity for subsequent tests.
    DEBUG_LEVELS["INSTRUMENTATION"] = 9
 
 
# ============================================================
# TEST 5 — Debug level transitions
# ============================================================
 
def test_debug_levels():
    _print_header("TEST 5: Debug level transitions")
 
    for lvl in [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]:
        DEBUG_LEVELS["INSTRUMENTATION"] = lvl
        print(f"\n--- INSTRUMENTATION LEVEL = {lvl} ---")
 
        comp = html.Button("X", id="btnX")
        result = apply_instrumentation(comp)
        print("Result ID:", result.id)
 
        if lvl == 0:
            if result.id != "btnX":
                raise AssertionError(
                    f"At level 0, instrumentation must be inactive. "
                    f"Expected 'btnX', got: {result.id!r}"
                )
        else:
            if result.id != {"event": "btnX"}:
                raise AssertionError(
                    f"At level {lvl}, expected {{'event': 'btnX'}}, got: {result.id!r}"
                )
 
    # Restore maximum verbosity (main() will clean up to original on exit)
    DEBUG_LEVELS["INSTRUMENTATION"] = 9
 
 
# ============================================================
# MAIN ENTRY POINT
# ============================================================
 
def main():
    parser = argparse.ArgumentParser(description="Instrumentation Self-Test (CLI)")
    parser.add_argument(
        "--use-global",
        action="store_true",
        help="Use global debug levels instead of forcing maximum verbosity",
    )
    args = parser.parse_args()
 
    force_verbose = not args.use_global
 
    print("\nINSTRUMENTATION SELF-TEST (CLI)")
    print("Instrumentation enabled:", _ud.INSTRUMENTATION_ENABLED)
    print("FORCE VERBOSE MODE:", force_verbose)
 
    # ------------------------------------------------------------
    # Save state so it can be fully restored after the test run.
    # ------------------------------------------------------------
    _save_enabled = _ud.INSTRUMENTATION_ENABLED
    _save_instr_level = DEBUG_LEVELS.get("INSTRUMENTATION", 0)
    _save_ui_level = DEBUG_LEVELS.get("UI", 0)
 
    # ------------------------------------------------------------
    # Always enable instrumentation so that assertion-heavy tests
    # actually exercise the rewriting logic.
    # ------------------------------------------------------------
    _ud.INSTRUMENTATION_ENABLED = True
 
    if force_verbose:
        DEBUG_LEVELS["INSTRUMENTATION"] = 9
        DEBUG_LEVELS["UI"] = 9
        _dbg("TEST", "debug_levels", "FORCING MAX VERBOSITY", override=True)
    else:
        _dbg("TEST", "debug_levels", "Using GLOBAL debug levels", override=True)
 
    # ------------------------------------------------------------
    # Run tests, collecting failures.
    # ------------------------------------------------------------
    tests = [
        test_static_basic,
        test_static_nested,
        test_structural_protection,
        test_custom_component_behavior,
        test_debug_levels,
    ]
 
    failures: list[str] = []
 
    for fn in tests:
        try:
            fn()
            print(f"  PASS  {fn.__name__}")
        except AssertionError as exc:
            print(f"  FAIL  {fn.__name__}: {exc}")
            failures.append(fn.__name__)
        except Exception as exc:
            print(f"  ERROR {fn.__name__}: {type(exc).__name__}: {exc}")
            failures.append(fn.__name__)
 
    # ------------------------------------------------------------
    # Restore original state.
    # ------------------------------------------------------------
    _ud.INSTRUMENTATION_ENABLED = _save_enabled
    DEBUG_LEVELS["INSTRUMENTATION"] = _save_instr_level
    DEBUG_LEVELS["UI"] = _save_ui_level
 
    # ------------------------------------------------------------
    # Print summary and exit with the appropriate code.
    # ------------------------------------------------------------
    print("\n" + "=" * 70)
    if failures:
        print(
            f"CLI SELF-TEST FAILED: {len(failures)}/{len(tests)} test(s) failed"
        )
        print(f"  Failed: {', '.join(failures)}")
        print("=" * 70)
        sys.exit(1)
    else:
        print(f"CLI SELF-TEST PASSED: {len(tests)}/{len(tests)} tests passed")
        print("=" * 70)
        sys.exit(0)
 
 
if __name__ == "__main__":
    main()