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_TESTNAME pick 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.

A UVM test at the top of the testbench hierarchy, containing the environment, agents and scoreboard

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

Class hierarchy of uvm_test: uvm_void, uvm_object, uvm_report_object, uvm_component, uvm_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:

Output
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() takes the test name from +UVM_TESTNAME or its argument, the factory creates the test as uvm_test_top, and phasing runs build, connect, end_of_elaboration and run

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() in end_of_elaboration_phase prints the finished hierarchy, with the test at uvm_test_top
  • run_test() creates the test named by +UVM_TESTNAME through 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_phase and inherit build_phase unchanged, avoiding duplicated environment-building code

Going Deeper

Did you find what you were looking for?

Quiz

Test Your Knowledge

1 of 5 Score: 0 / 5