A UVM test is the top-level class of a UVM testbench: it extends uvm_test, builds the environment, configures it and starts the sequences that exercise one feature of the design. In this tutorial, reg_env is fully built, but nothing has ever actually instantiated it. This article writes the component that finally does: a test that builds reg_env, starts reg_sequence against it, and gives the tutorial's testbench its first real run.
10 min read | Intermediate Level
What You'll Learn
- What a test does, and why the same environment gets reused across many of them
- How to build reg_test, print the testbench topology and start reg_sequence inside
run_phase - How
run_test()and+UVM_TESTNAMEpick which test runs - How to write a derivative test that reuses reg_test but runs a different sequence
- How to set a real default sequence, now that every name it depends on actually exists
What Is a Test?
A test verifies a specific feature or behavior of a design. Real verification plans typically need many tests: one for basic writes and reads, one for boundary addresses, one for back-to-back operations with no idle cycles, and so on.
Rewriting the entire environment for each one would be wasteful. Instead, the same reg_env gets reused across all of them, and each test only changes what it actually needs to: which sequence runs, and which knobs are tweaked beforehand.
uvm_test itself adds no new methods to uvm_component. Extending it, rather than uvm_component directly, marks the class as a test, so run_test() can create it by name and the class picks up anything added to uvm_test in later UVM versions.
Building reg_test
1. Declare the Class
class reg_test extends uvm_test;
`uvm_component_utils(reg_test)
function new(string name, uvm_component parent);
super.new(name, parent);
endfunction
// Code for rest of the steps come here
endclass
`uvm_component_utils registers reg_test with the factory. That registration is what lets run_test() create the test from a string later, so a test without it cannot be selected by name.
2. Declare and Build the Environment
reg_env m_top_env;
virtual function void build_phase(uvm_phase phase);
super.build_phase(phase);
m_top_env = reg_env::type_id::create("m_top_env", this);
endfunction
Many tests also build a configuration object here and pass it down with uvm_config_db, which is useful once an environment has knobs worth bundling into one object. That pattern is covered in this chapter's deep dive on multi-agent environments. reg_env doesn't need one: it always builds the same agent and the same scoreboard, so there's nothing for reg_test to configure before building it.
3. Print the Topology
virtual function void end_of_elaboration_phase(uvm_phase phase);
uvm_top.print_topology();
endfunction
By end_of_elaboration_phase, every component this tutorial has built is guaranteed to already exist: reg_test, reg_env, reg_agent and everything inside it, and reg_scoreboard. print_topology() prints the entire hierarchy as built, which is a quick way to confirm nothing was left out or built in the wrong place before the simulation starts running anything.
The printout below comes from a cut-down version of this testbench with only a sequencer and a driver, so the tree is short. The test always appears as uvm_test_top, the instance name run_test() gives it, whatever its class is called:
UVM_INFO @ 0: reporter [UVMTOP] UVM testbench topology:
Name Type Size Value
<unnamed> uvm_root - @62
uvm_test_top reg_test - @151
m_top_env reg_env - @220
m_driver reg_driver - @352
rsp_port uvm_analysis_port - @369
seq_item_port uvm_seq_item_pull_port - @360
m_sequencer uvm_sequencer - @228
rsp_export uvm_analysis_export - @236
seq_item_export uvm_seq_item_pull_imp - @343
arbitration_queue array 0 -
lock_queue array 0 -
num_last_reqs integral 32 'd1
num_last_rsps integral 32 'd1
uvm_top is the handle to uvm_root, the implicit top of every UVM hierarchy. Setting uvm_top.enable_print_topology = 1 before run_test() prints the same tree automatically at the end of elaboration, with no code in the test.
4. Start a Sequence in run_phase
virtual task run_phase(uvm_phase phase);
reg_sequence m_seq = reg_sequence::type_id::create("m_seq");
phase.raise_objection(this);
m_seq.start(m_top_env.m_agent.m_sequencer);
phase.drop_objection(this);
endtask
Every piece of this code was established and explained in its own article: the objection-raising pattern from How to Create and Use a Sequence, reg_sequence itself, and the path m_top_env.m_agent.m_sequencer.
That path only resolves to something real because reg_env owns m_agent and reg_agent owns m_sequencer. Nothing about any of those three classes needed to change to make this call work.
Quick Check
Q: Would m_seq.start(m_top_env.m_agent.m_sequencer) still work if reg_agent were configured as passive?
Show Answer
No. A passive reg_agent never builds m_sequencer in the first place, so m_top_env.m_agent.m_sequencer would be a null handle by the time run_phase tries to call start() on it. Starting a sequence against an agent only makes sense when that agent is active.
Running a Test with run_test()
A test class does nothing until something creates it. That is the job of the global task run_test(), called once from an initial block in the top-level module:
module tb_top;
// ... DUT, interface and uvm_config_db::set of the virtual interface ...
initial run_test();
endmodule
run_test() asks the factory to create the test class named on the simulator command line with +UVM_TESTNAME, names the instance uvm_test_top, and then runs every component through all the UVM phases. The same compiled testbench can run any registered test:
<sim command> +UVM_TESTNAME=reg_test <sim command> +UVM_TESTNAME=reg_write_only_test
A name can also be passed as an argument, run_test("reg_test"), but +UVM_TESTNAME on the command line takes priority over it. If the factory has no class registered under the requested name, UVM stops with a fatal error. How the top module also hands the test its virtual interface is covered in UVM Testbench Top.
Setting a Real Default Sequence
How to Create and Use a Sequence introduced default sequences with a placeholder path, since reg_sequencer didn't have a fixed position in any hierarchy yet. It does now:
function void start_of_simulation_phase(uvm_phase phase);
super.start_of_simulation_phase(phase);
uvm_config_db #(uvm_object_wrapper)::set(this, "m_top_env.m_agent.m_sequencer.run_phase",
"default_sequence", reg_sequence::type_id::get());
endfunction
"m_top_env.m_agent.m_sequencer.run_phase" is no longer a stand-in for a path that doesn't exist. It's the actual location of reg_sequencer inside reg_test's own hierarchy.
Setting this means reg_sequencer starts reg_sequence automatically once its run phase begins, with no explicit start() call needed anywhere. It is an alternative to the run_phase code shown in step 4, not something used alongside it.
A Derivative Test
reg_test only ever starts reg_sequence: the same five-transaction, random read/write sequence every time. A second test that needs different stimulus doesn't have to rebuild reg_env from scratch.
The cleanest way to give it different stimulus is a derivative sequence, extending reg_sequence with one extra constraint inside body(), the same inline with pattern already used in that article's own practice exercise:
class reg_write_only_sequence extends reg_sequence;
`uvm_object_utils(reg_write_only_sequence)
function new(string name = "reg_write_only_sequence");
super.new(name);
endfunction
virtual task body();
repeat (5) begin
req = reg_transaction::type_id::create("req");
start_item(req);
assert(req.randomize() with { wr_en == 1; });
finish_item(req);
end
endtask
endclass
With that sequence written, the derivative test itself only needs to override which sequence it starts:
class reg_write_only_test extends reg_test;
`uvm_component_utils(reg_write_only_test)
function new(string name, uvm_component parent);
super.new(name, parent);
endfunction
virtual task run_phase(uvm_phase phase);
reg_write_only_sequence m_seq = reg_write_only_sequence::type_id::create("m_seq");
phase.raise_objection(this);
m_seq.start(m_top_env.m_agent.m_sequencer);
phase.drop_objection(this);
endtask
endclass
Because reg_write_only_test doesn't define its own build_phase at all, it inherits reg_test's exactly as written, so m_top_env still gets built the same way, with no duplicated code. Only the sequence being started changes, and that change lives entirely in run_phase. Running it is just +UVM_TESTNAME=reg_write_only_test.
Common Mistakes
Mistake #1: Forgetting to raise an objection in run_phase
Without phase.raise_objection(this), the run phase has nothing telling it to stay alive, and the simulation can end before m_seq.start(...) ever finishes, or before it even begins.
Mistake #2: Defining build_phase in a derivative test when nothing about it actually changes
Copying reg_test's build_phase into reg_write_only_test unchanged works, but it means any later change to how reg_env gets built has to be repeated in every derivative test that copied it. Leaving build_phase out entirely, as reg_write_only_test does, means it's inherited automatically and only ever needs updating in one place.
Mistake #3: Misspelling the test name in +UVM_TESTNAME
The name must match the class name registered with `uvm_component_utils exactly, including case. A typo does not fall back to a default test: the factory cannot create the class, and UVM ends the simulation with a fatal error.
Practice Exercise
Challenge: A Read-Only Derivative Test
Following the same shape as reg_write_only_sequence and reg_write_only_test, write a reg_read_only_sequence and a reg_read_only_test that bias every generated transaction toward reads instead of writes.
Hint
This is structurally identical to the write-only pair: same two classes, same inherited build_phase on the test side, only the constraint condition itself changes on the sequence side.
Solution
class reg_read_only_sequence extends reg_sequence;
`uvm_object_utils(reg_read_only_sequence)
function new(string name = "reg_read_only_sequence");
super.new(name);
endfunction
virtual task body();
repeat (5) begin
req = reg_transaction::type_id::create("req");
start_item(req);
assert(req.randomize() with { rd_en == 1; });
finish_item(req);
end
endtask
endclass
class reg_read_only_test extends reg_test;
`uvm_component_utils(reg_read_only_test)
function new(string name, uvm_component parent);
super.new(name, parent);
endfunction
virtual task run_phase(uvm_phase phase);
reg_read_only_sequence m_seq = reg_read_only_sequence::type_id::create("m_seq");
phase.raise_objection(this);
m_seq.start(m_top_env.m_agent.m_sequencer);
phase.drop_objection(this);
endtask
endclass
Only the constrained field changed, from wr_en == 1 to rd_en == 1, on the sequence side. The test side is structurally identical to reg_write_only_test, down to the inherited build_phase.
Summary
In this article, you learned:
- A test extends
uvm_test, builds an environment and starts a sequence against it, reusing the same environment across many different tests uvm_top.print_topology()inend_of_elaboration_phaseprints the finished hierarchy, with the test atuvm_test_toprun_test()creates the test named by+UVM_TESTNAMEthrough the factory, so one compiled testbench can run every registered test- reg_test starts reg_sequence on
m_top_env.m_agent.m_sequencer, a path that only resolves because every component along it is built correctly - A derivative test can override just
run_phaseand inheritbuild_phaseunchanged, avoiding duplicated environment-building code
Going Deeper
- The module that calls
run_test(): UVM Testbench Top - A complete testbench with several tests: UVM Testbench Example 1
- Replacing components and transactions from a test: UVM Factory Override
- Every phase and its execution order: UVM Phases
- Objections in full: UVM Objection