Test Library Organization: Scalable Structure and Naming

Repository structure

A clean structure helps engineers find the right test quickly and lowers onboarding time.

[TEST][ENV] recommended layout

tb/
  env/
    my_env.sv
    cfg/
  tests/
    base/base_test.sv
    smoke/smoke_test.sv
    protocol/protocol_error_test.sv
    stress/high_bw_test.sv
    debug/repro_bug123_test.sv
  sequences/
    virtual/
  testlists/
    smoke.list
    nightly.list
    weekly.list

package tests_pkg;
  import uvm_pkg::*;
  `include "uvm_macros.svh"

  `include "base/base_test.sv"
  `include "smoke/smoke_test.sv"
  `include "protocol/protocol_error_test.sv"
  `include "stress/high_bw_test.sv"
endpackage

Key takeaways

• Structure directories around scenario purpose, not author names.

• Keep base classes in dedicated folders with ownership.

• Testlists should map directly to CI stages.

Common pitfalls

• Flat folders with hundreds of test files.

• Inconsistent naming that hides scenario intent.

• No separation between reusable base tests and scenario tests.

Naming and metadata conventions

Consistent naming enables scriptable test selection and faster triage dashboards.

Class naming guide

• `*_test` suffix for runnable tests.

• `base_*` prefix for non-runnable shared classes.

• `repro_*` prefix for temporary debug tests.

• Include protocol mode in stress test names when relevant.

[TEST] examples

base_test
smoke_sanity_test
protocol_illegal_len_test
stress_backpressure_mix_test
repro_crc_timeout_test

Metadata pattern

virtual function string scenario_group();
  return "protocol";
endfunction

virtual function string scenario_goal();
  return "exercise illegal packet length handling";
endfunction

[UVM] reporting use

UVM_INFO @ start:
  group=<scenario_group()>
  goal=<scenario_goal()>

dashboard can bucket failures by group automatically

Common pitfalls

• Using abbreviations that differ across teams.

• No metadata API for grouping tests in reports.

• Keeping obsolete repro tests in main nightly lists.