Functions
	_build_mock_settings ()
	test_config_loading ()
	test_config_source_populated ()
	test_dbg_silent_no_exception ()
	test_dbg_level_filtering ()
	test_dbg_override_flag ()
	test_dbg_before_init_warning ()
	test_adbg_does_not_raise ()
	test_init_idempotent ()
	test_stream_interceptor_interface ()
	test_debug_levels_dict_mutable ()
	test_set_debug_level_valid ()
	test_set_debug_level_invalid ()
	test_set_global_setting_valid ()
	test_set_global_setting_invalid ()
	test_json_output_mode ()
	test_dbg_timed ()
	test_dbg_scope ()
	test_dbg_profile ()
	test_prod_mode_env_var ()
	test_prod_mode_via_config ()
	test_log_rotation_count ()
	test_reload_stale_key_removed ()
	test_io_degradation_oserror ()
	test_dbg_assert_passes_silently ()
	test_dbg_assert_raises_on_false ()
	test_dbg_assert_prod_mode_noop ()
	test_dbg_trace_start_end ()
	test_dbg_trace_exception ()
	test_dbg_trace_preserves_name ()
	test_dbg_metrics_output ()
	test_ai_trace_console_suppressed ()
	test_ai_trace_file_written ()
	test_ai_trace_disabled_discards ()
	test_version_is_2_0 ()
	test_config_v2_debug_levels_key ()
	test_config_v2_nested_log_rotation ()
	test_env_var_level_override ()
	test_env_var_log_file_override ()
	test_redaction_in_prod_mode ()
	test_redaction_disabled_in_dev_mode ()
	test_redaction_quoted_double ()
	test_redaction_quoted_single ()
	test_redaction_bare_value_still_works ()
	test_global_debug_level_override ()
	test_bundled_config_schema_version ()
	_reset_prod_warnings ()
	test_prod_mode_suppresses_high_level ()
	test_prod_mode_allows_low_level ()
	test_prod_mode_warning_one_shot ()
	test_prod_max_level_configurable ()
	test_non_prod_mode_unaffected ()

Variables
	_REPO_ROOT = os.path.normpath(os.path.join(os.path.dirname(__file__), ".."))

Detailed Description

Regression Tests — unified_debug
=================================

Purpose
-------
Verify the full public and internal API surface of ``oc_diagnostics.unified_debug``,
covering configuration loading, the ``_dbg`` debug logger, async logging, runtime
overrides, profiling helpers, production mode, log rotation, and I/O fallback.

Responsibilities
----------------
- Test config loading returns the expected 4-tuple structure.
- Test ``_dbg()`` domain-level filtering and ``override=True`` bypass.
- Test ``_adbg()`` completes without raising.
- Test ``init()`` idempotency and the pre-init RuntimeWarning.
- Test runtime API: ``set_debug_level()``, ``set_global_setting()``.
- Test profiling helpers: ``dbg_timed()``, ``dbg_scope()``, ``dbg_profile()``.
- Test JSONL output mode and ``_StreamInterceptor`` interface.
- Test production mode activation via env var and via config file.
- Test log-file count-based rotation via ``_prune_old_log_files()``.
- Test config hot-reload stale-key pruning via ``_reload_config()``.
- Test I/O degradation fallback on ``OSError`` (FS-25).

Diagnostics
-----------
Domain: TEST
Levels:
    L2 — lifecycle
    L3 — semantic details
    L4 — deep tracing

Contracts
---------
- Must not permanently modify oc_diagnostics global state.
- Must restore all patched globals and mocked internals in finally blocks.
- Must not start servers, threads, or require network access.
- Must run deterministically across repeated invocations.

Function Documentation

◆ _build_mock_settings()

test_unified_debug._build_mock_settings ( )

protected

Return a minimal settings dict compatible with _reload_config().

Definition at line 77 of file test_unified_debug.py.

Here is the caller graph for this function:

◆ _reset_prod_warnings()

test_unified_debug._reset_prod_warnings ( )

protected

Definition at line 1267 of file test_unified_debug.py.

Here is the caller graph for this function:

◆ test_adbg_does_not_raise()

test_unified_debug.test_adbg_does_not_raise ( )

_adbg() completes without raising, in silent mode for cleanliness.

Definition at line 258 of file test_unified_debug.py.

◆ test_ai_trace_console_suppressed()

test_unified_debug.test_ai_trace_console_suppressed ( )

AI-Trace messages (level='ai_trace') do not reach the console.

Definition at line 877 of file test_unified_debug.py.

◆ test_ai_trace_disabled_discards()

test_unified_debug.test_ai_trace_disabled_discards ( )

AI-Trace messages are silently discarded when AI_TRACE_ENABLED is False.

Definition at line 944 of file test_unified_debug.py.

◆ test_ai_trace_file_written()

test_unified_debug.test_ai_trace_file_written ( )

AI-Trace messages are written to the log file.

Definition at line 906 of file test_unified_debug.py.

◆ test_bundled_config_schema_version()

test_unified_debug.test_bundled_config_schema_version ( )

Bundled debug_config.json uses V2.0 schema with DEBUG_LEVELS key.

Definition at line 1250 of file test_unified_debug.py.

◆ test_config_loading()

test_unified_debug.test_config_loading ( )

_load_debug_config() returns a 4-tuple with expected types.

Definition at line 104 of file test_unified_debug.py.

◆ test_config_source_populated()

test_unified_debug.test_config_source_populated ( )

CONFIG_SOURCE is a non-empty string after module load.

Definition at line 117 of file test_unified_debug.py.

◆ test_config_v2_debug_levels_key()

test_unified_debug.test_config_v2_debug_levels_key ( )

V2.0 config with 'DEBUG_LEVELS' key loads correctly.

Definition at line 978 of file test_unified_debug.py.

◆ test_config_v2_nested_log_rotation()

test_unified_debug.test_config_v2_nested_log_rotation ( )

V2.0 nested log_rotation object is parsed correctly.

Definition at line 1015 of file test_unified_debug.py.

◆ test_dbg_assert_passes_silently()

test_unified_debug.test_dbg_assert_passes_silently ( )

_dbg_assert() with truthy condition does not raise or emit.

Definition at line 705 of file test_unified_debug.py.

◆ test_dbg_assert_prod_mode_noop()

test_unified_debug.test_dbg_assert_prod_mode_noop ( )

_dbg_assert() in PROD_MODE is a complete no-op — condition not evaluated.

Definition at line 749 of file test_unified_debug.py.

◆ test_dbg_assert_raises_on_false()

test_unified_debug.test_dbg_assert_raises_on_false ( )

_dbg_assert() with falsy condition emits L1 override + raises AssertionError.

Definition at line 723 of file test_unified_debug.py.

◆ test_dbg_before_init_warning()

test_unified_debug.test_dbg_before_init_warning ( )

_dbg() before init() emits a one-shot RuntimeWarning; second call does not repeat it.

Definition at line 207 of file test_unified_debug.py.

◆ test_dbg_level_filtering()

test_unified_debug.test_dbg_level_filtering ( )

_dbg() message is suppressed when the call level exceeds the domain level.

Definition at line 138 of file test_unified_debug.py.

◆ test_dbg_metrics_output()

test_unified_debug.test_dbg_metrics_output ( )

@dbg_metrics emits structured JSON with duration_ms and memory_mb.

Definition at line 838 of file test_unified_debug.py.

◆ test_dbg_override_flag()

test_unified_debug.test_dbg_override_flag ( )

_dbg(..., override=True) always emits regardless of domain level.

Definition at line 177 of file test_unified_debug.py.

◆ test_dbg_profile()

test_unified_debug.test_dbg_profile ( )

dbg_profile() decorator wraps a function and preserves its return value.

Definition at line 515 of file test_unified_debug.py.

◆ test_dbg_scope()

test_unified_debug.test_dbg_scope ( )

dbg_scope() emits ENTER and EXIT lines without timing information (FS-19).

Definition at line 479 of file test_unified_debug.py.

◆ test_dbg_silent_no_exception()

test_unified_debug.test_dbg_silent_no_exception ( )

_dbg() with SILENT_MODE=True must not raise.

Definition at line 128 of file test_unified_debug.py.

◆ test_dbg_timed()

test_unified_debug.test_dbg_timed ( )

dbg_timed() context manager emits ENTER and EXIT lines with elapsed ms.

Definition at line 446 of file test_unified_debug.py.

◆ test_dbg_trace_exception()

test_unified_debug.test_dbg_trace_exception ( )

@dbg_trace logs exception at L1 and re-raises.

Definition at line 791 of file test_unified_debug.py.

◆ test_dbg_trace_preserves_name()

test_unified_debug.test_dbg_trace_preserves_name ( )

@dbg_trace preserves __name__ via functools.wraps.

Definition at line 823 of file test_unified_debug.py.

◆ test_dbg_trace_start_end()

test_unified_debug.test_dbg_trace_start_end ( )

@dbg_trace emits START and END messages.

Definition at line 764 of file test_unified_debug.py.

◆ test_debug_levels_dict_mutable()

test_unified_debug.test_debug_levels_dict_mutable ( )

DEBUG_LEVELS is a mutable dict and changes are reflected globally.

Definition at line 317 of file test_unified_debug.py.

◆ test_env_var_level_override()

test_unified_debug.test_env_var_level_override ( )

OC_DIAGNOSTICS_LEVEL env var overrides all domain levels.

Definition at line 1059 of file test_unified_debug.py.

◆ test_env_var_log_file_override()

test_unified_debug.test_env_var_log_file_override ( )

OC_DIAGNOSTICS_LOG_FILE env var sets LOG_FILE at load time.

Definition at line 1096 of file test_unified_debug.py.

◆ test_global_debug_level_override()

test_unified_debug.test_global_debug_level_override ( )

global_debug_level in config overrides all domain levels.

Definition at line 1209 of file test_unified_debug.py.

◆ test_init_idempotent()

test_unified_debug.test_init_idempotent ( )

init() can be called multiple times without error or side-effect duplication.

Definition at line 278 of file test_unified_debug.py.

◆ test_io_degradation_oserror()

test_unified_debug.test_io_degradation_oserror ( )

FS-25: _write_to_file() OSError triggers one-time warning and mode fallback.

Definition at line 666 of file test_unified_debug.py.

◆ test_json_output_mode()

test_unified_debug.test_json_output_mode ( )

OUTPUT_MODE='json' writes valid JSONL records to the log file.

Definition at line 387 of file test_unified_debug.py.

◆ test_log_rotation_count()

test_unified_debug.test_log_rotation_count ( )

_prune_old_log_files() removes the oldest files when count exceeds max.

Definition at line 614 of file test_unified_debug.py.

◆ test_non_prod_mode_unaffected()

test_unified_debug.test_non_prod_mode_unaffected ( )

Outside PROD_MODE, PROD_MAX_LEVEL has no effect.

Definition at line 1378 of file test_unified_debug.py.

Here is the call graph for this function:

◆ test_prod_max_level_configurable()

test_unified_debug.test_prod_max_level_configurable ( )

Setting PROD_MAX_LEVEL=3 allows L3 but still blocks L4.

Definition at line 1350 of file test_unified_debug.py.

Here is the call graph for this function:

◆ test_prod_mode_allows_low_level()

test_unified_debug.test_prod_mode_allows_low_level ( )

L1/L2 calls in PROD_MODE are still emitted normally.

Definition at line 1298 of file test_unified_debug.py.

Here is the call graph for this function:

◆ test_prod_mode_env_var()

test_unified_debug.test_prod_mode_env_var ( )

OC_DIAGNOSTICS_MODE=prod sets PROD_MODE=True at module load.

Definition at line 558 of file test_unified_debug.py.

◆ test_prod_mode_suppresses_high_level()

test_unified_debug.test_prod_mode_suppresses_high_level ( )

In PROD_MODE, _dbg() calls above PROD_MAX_LEVEL are suppressed (OI-407).

Definition at line 1271 of file test_unified_debug.py.

Here is the call graph for this function:

◆ test_prod_mode_via_config()

test_unified_debug.test_prod_mode_via_config ( )

mode='prod' in debug_config.json global_settings sets PROD_MODE=True.

Definition at line 576 of file test_unified_debug.py.

◆ test_prod_mode_warning_one_shot()

test_unified_debug.test_prod_mode_warning_one_shot ( )

Repeated L3 calls in PROD_MODE emit only one warning per (domain, level).

Definition at line 1324 of file test_unified_debug.py.

Here is the call graph for this function:

◆ test_redaction_bare_value_still_works()

test_unified_debug.test_redaction_bare_value_still_works ( )

Original bare-value redaction still works after regex update (OI-401).

Definition at line 1188 of file test_unified_debug.py.

◆ test_redaction_disabled_in_dev_mode()

test_unified_debug.test_redaction_disabled_in_dev_mode ( )

Redaction patterns are not applied when PROD_MODE is False.

Definition at line 1137 of file test_unified_debug.py.

◆ test_redaction_in_prod_mode()

test_unified_debug.test_redaction_in_prod_mode ( )

Redaction patterns scrub matching key=value pairs in production mode.

Definition at line 1118 of file test_unified_debug.py.

◆ test_redaction_quoted_double()

test_unified_debug.test_redaction_quoted_double ( )

Redaction handles double-quoted multi-word values (OI-401).

Definition at line 1154 of file test_unified_debug.py.

◆ test_redaction_quoted_single()

test_unified_debug.test_redaction_quoted_single ( )

Redaction handles single-quoted multi-word values (OI-401).

Definition at line 1171 of file test_unified_debug.py.

◆ test_reload_stale_key_removed()

test_unified_debug.test_reload_stale_key_removed ( )

_reload_config() prunes stale keys; DEBUG_LEVELS is never empty.

Definition at line 643 of file test_unified_debug.py.

Here is the call graph for this function:

◆ test_set_debug_level_invalid()

test_unified_debug.test_set_debug_level_invalid ( )

set_debug_level() with an out-of-range value emits UserWarning and does not update.

Definition at line 347 of file test_unified_debug.py.

◆ test_set_debug_level_valid()

test_unified_debug.test_set_debug_level_valid ( )

set_debug_level() updates DEBUG_LEVELS at runtime.

Definition at line 332 of file test_unified_debug.py.

◆ test_set_global_setting_invalid()

test_unified_debug.test_set_global_setting_invalid ( )

set_global_setting() with an unknown key emits UserWarning.

Definition at line 374 of file test_unified_debug.py.

◆ test_set_global_setting_valid()

test_unified_debug.test_set_global_setting_valid ( )

set_global_setting() updates SILENT_MODE at runtime.

Definition at line 364 of file test_unified_debug.py.

◆ test_stream_interceptor_interface()

test_unified_debug.test_stream_interceptor_interface ( )

_StreamInterceptor exposes the full io.TextIOBase-compatible interface.

Definition at line 301 of file test_unified_debug.py.

◆ test_version_is_2_0()

test_unified_debug.test_version_is_2_0 ( )

oc_diagnostics version must be 2.0.0.

Definition at line 966 of file test_unified_debug.py.

Variable Documentation

◆ _REPO_ROOT

test_unified_debug._REPO_ROOT = os.path.normpath(os.path.join(os.path.dirname(__file__), ".."))

protected

Definition at line 61 of file test_unified_debug.py.

Functions

Variables

Detailed Description

Function Documentation

◆ _build_mock_settings()

◆ _reset_prod_warnings()

◆ test_adbg_does_not_raise()

◆ test_ai_trace_console_suppressed()

◆ test_ai_trace_disabled_discards()

◆ test_ai_trace_file_written()

◆ test_bundled_config_schema_version()

◆ test_config_loading()

◆ test_config_source_populated()

◆ test_config_v2_debug_levels_key()

◆ test_config_v2_nested_log_rotation()

◆ test_dbg_assert_passes_silently()

◆ test_dbg_assert_prod_mode_noop()

◆ test_dbg_assert_raises_on_false()

◆ test_dbg_before_init_warning()

◆ test_dbg_level_filtering()

◆ test_dbg_metrics_output()

◆ test_dbg_override_flag()

◆ test_dbg_profile()

◆ test_dbg_scope()

◆ test_dbg_silent_no_exception()

◆ test_dbg_timed()

◆ test_dbg_trace_exception()

◆ test_dbg_trace_preserves_name()

◆ test_dbg_trace_start_end()

◆ test_debug_levels_dict_mutable()

◆ test_env_var_level_override()

◆ test_env_var_log_file_override()

◆ test_global_debug_level_override()

◆ test_init_idempotent()

◆ test_io_degradation_oserror()

◆ test_json_output_mode()

◆ test_log_rotation_count()

◆ test_non_prod_mode_unaffected()

◆ test_prod_max_level_configurable()

◆ test_prod_mode_allows_low_level()

◆ test_prod_mode_env_var()

◆ test_prod_mode_suppresses_high_level()

◆ test_prod_mode_via_config()

◆ test_prod_mode_warning_one_shot()

◆ test_redaction_bare_value_still_works()

◆ test_redaction_disabled_in_dev_mode()

◆ test_redaction_in_prod_mode()

◆ test_redaction_quoted_double()

◆ test_redaction_quoted_single()

◆ test_reload_stale_key_removed()

◆ test_set_debug_level_invalid()

◆ test_set_debug_level_valid()

◆ test_set_global_setting_invalid()

◆ test_set_global_setting_valid()

◆ test_stream_interceptor_interface()

◆ test_version_is_2_0()

Variable Documentation

◆ _REPO_ROOT