Test Base Debug: Symptom-First Hierarchy Triage

Debug boundary order

Troubleshoot base-test problems in strict order: class selection, config push, override scope, run hooks, end criteria.

[TEST][UVM] triage matrix

wrong test runs:
  +UVM_TESTNAME mismatch / factory registration issue

env missing cfg:
  config_db set/get path mismatch

unexpected component type:
  override scope or order problem

hang at end:
  objection leak or bad quiescence predicate

task base_test_smoke();
  run_test("smoke_sanity_test");
  // verify these logs appear in order:
  // 1) apply_defaults
  // 2) configure_scenario
  // 3) run_main_sequence
  // 4) drop_objection
endtask

Key takeaways

• Boundary-first debugging localizes failures quickly.

• Ordered lifecycle logs are the best early triage tool.

• Most hangs are objection/timeout policy mismatches.

Common pitfalls

• Jumping into sequence internals before checking base hooks.

• Debugging random seeds without proving smoke determinism first.

• Ignoring factory printout when component type is unexpected.

Deterministic debug toolkit

Keep low-cost diagnostics always enabled in base_test to reduce time-to-root-cause.

Instrumentation primitives

function void log_stage(string stage);
  `uvm_info("TEST_STAGE",
    $sformatf("%s test=%s seed=%0d", stage, get_type_name(), $get_initial_random_seed()),
    UVM_LOW)
endfunction

function void report_phase(uvm_phase phase);
  super.report_phase(phase);
  `uvm_info("TEST_SUMMARY",
    $sformatf("timeouts=%0d objections_open=%0d", timeout_hits, objection_leaks),
    UVM_NONE)
endfunction

[TEST][ENV] recommended always-on counters

- build_cfg_push_count
- override_apply_count
- hook_enter_count(pre/main/post)
- timeout_guard_trips
- objection_balance_delta

Issue reproduction checklist

1. Reproduce with one deterministic seed and verbosity UVM_LOW.

2. Capture stage log timeline from build to report.

3. Validate config_db paths before sequence-level analysis.

4. Confirm factory print includes expected substitutions.

5. Check objection balance and timeout guard statistics.

6. Only then inspect sequence/env internals.

[DEBUG] pass criteria

smoke seed passes twice identically
and
hook timeline stays stable
and
no objection leak reported

Key takeaways

• Persistent diagnostics in base_test are high leverage.

• Stable reproduction is mandatory before deep root-cause work.

• A short checklist avoids expensive random bug hunts.

Common pitfalls

• Turning on excessive verbosity before establishing boundaries.

• Changing test code while still collecting first baseline logs.

• Skipping post-fix rerun of the exact failing seed.