Functions
	_print_header (str title)
	test_static_basic ()
	test_static_nested ()
	test_structural_protection ()
	test_custom_component_behavior ()
	test_debug_levels ()
	main ()

Variables
	id = id_val
list	children = []

Detailed Description

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