instrumentation_selftest_app.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oc_diagnostics/instrumentation_selftest_app.py
 
"""
Instrumentation Self‑Test (Dash App)
====================================
 
Purpose
-------
A minimal, deterministic Dash application used exclusively for **manual**
validation of the instrumentation system:
 
- ID rewriting (instrument_ids)
- Dynamic instrumentation of callback outputs
- UI event logger integration
- Dispatcher patching (middleware)
- Logging behavior under different debug-level modes
 
This module is NOT used in production and is intentionally verbose.
 
.. warning::
    **This is a manual integration harness, not an automated test.**
    Running this module launches a Dash development server that blocks
    indefinitely until interrupted (Ctrl-C).  It produces no assertions,
    no exit code, and no machine-readable result.  It cannot be integrated
    into CI/CD pipelines.  Use ``instrumentation_selftest_cli.py`` for
    headless, non-blocking instrumentation checks.
 
Lifecycle
---------
1. Create Dash app
2. Build static layout (UNINSTRUMENTED — IDs must remain strings)
3. Register UI event logger
4. Register callbacks
5. Enable instrumentation middleware
6. Run the development server (blocks until Ctrl-C)
 
Static layout must NOT be instrumented because Dash callback decorators
match string IDs. Dynamic content *is* instrumented explicitly using:
 
    return apply_instrumentation(dynamic_component_tree)
 
Debug-Level Modes
-----------------
MODE A — FORCE VERBOSE (default)
    DEBUG_LEVELS["INSTRUMENTATION"] = 9
    DEBUG_LEVELS["UI"] = 9
 
MODE B — RESPECT GLOBAL LEVELS
    Use whatever levels are defined in unified_debug.py
 
Select mode via:
    python -m oc_diagnostics.instrumentation_selftest_app --use-global
 
Responsibilities
----------------
- Build a static Dash layout with string IDs (NOT instrumented at build
  time, so callback decorators can match by string ID).
- Register the UI event logger and all callbacks.
- Enable instrumentation middleware via ``enable_instrumentation_middleware()``
  after all callbacks are registered.
- Optionally force maximum verbosity (default) or use global levels.
- Launch the Dash development server (blocking call).
 
Diagnostics
-----------
Domain: INSTRUMENTATION
Levels:
    L2 — lifecycle
    L3 — semantic details
    L4 — deep tracing
 
Contracts
---------
- Must never be used in CI/CD or automated testing.
- Must not instrument the static layout at build time.
- Dynamic callback outputs must be instrumented via ``apply_instrumentation()``.
- Requires Dash (``pip install oc_diagnostics[dash]``).
"""
 
import argparse
from dash import Dash, html, dcc, Input, Output
 
from oc_diagnostics.instrumentation_middleware import (
    enable_instrumentation_middleware,
    apply_instrumentation,
)
from oc_diagnostics.unified_debug import _dbg, DEBUG_LEVELS
from oc_diagnostics.ui_event_logger import ui_event_logger
 
 
# ============================================================
# Create the test app
# ============================================================
 
def create_test_app(force_verbose: bool):
    """
    Build the test app following the same lifecycle as the main app.
 
    Parameters
    ----------
    force_verbose : bool
        If True, override global debug levels and force maximum verbosity.
    """
 
    # ------------------------------------------------------------
    # 0. Debug-level override (optional)
    # ------------------------------------------------------------
    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)
 
    # ------------------------------------------------------------
    # 1. Create Dash app
    # ------------------------------------------------------------
    app = Dash(__name__)
 
    # ------------------------------------------------------------
    # 2. Build static layout (UNINSTRUMENTED)
    # ------------------------------------------------------------
    app.layout = html.Div(
        [
            html.Button("Click me", id="btn"),
            html.Div(id="out"),
            dcc.Store(id="debug-settings-data-store"),
        ]
    )
 
    # ------------------------------------------------------------
    # 3. Register UI event logger
    # ------------------------------------------------------------
    ui_event_logger(app)
 
    # ------------------------------------------------------------
    # 4. Register callbacks
    # ------------------------------------------------------------
    @app.callback(
        Output("out", "children"),
        Input("btn", "n_clicks"),
    )
    def update_output(n):
        if n is None:
            return "Click the button"
        # Dynamic instrumentation
        return apply_instrumentation(html.Div(f"Clicked {n} times"))
 
    # ------------------------------------------------------------
    # 5. Enable instrumentation middleware
    # ------------------------------------------------------------
    enable_instrumentation_middleware(app)
 
    return app
 
 
# ============================================================
# CLI entry point
# ============================================================
 
def main():
    """
    CLI entry point for the Dash instrumentation test app.
    """
    parser = argparse.ArgumentParser(description="Instrumentation Self-Test App")
    parser.add_argument(
        "--use-global",
        action="store_true",
        help="Use global debug levels instead of forcing verbosity",
    )
    parser.add_argument(
        "--debug",
        action="store_true",
        help=(
            "Enable Dash debug mode (Werkzeug reloader + debugger).  "
            "Off by default to avoid spawning a second process and exposing "
            "the Werkzeug debug console.  See OI-18 in AI_REVIEW_SYNTHESIS V2.md."
        ),
    )
    args = parser.parse_args()
 
    app = create_test_app(force_verbose=not args.use_global)
    app.run_server(debug=args.debug)
 
 
if __name__ == "__main__":
    main()