oc_diagnostics.instrumentation_selftest_cli module

oc_diagnostics.instrumentation_selftest_cli module#

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).

oc_diagnostics.instrumentation_selftest_cli.main()[source]#
oc_diagnostics.instrumentation_selftest_cli.test_custom_component_behavior()[source]#
oc_diagnostics.instrumentation_selftest_cli.test_debug_levels()[source]#
oc_diagnostics.instrumentation_selftest_cli.test_static_basic()[source]#
oc_diagnostics.instrumentation_selftest_cli.test_static_nested()[source]#
oc_diagnostics.instrumentation_selftest_cli.test_structural_protection()[source]#