Detail Tools¶

Get comprehensive details about specific verification artifacts.

tests.get¶

Retrieve complete test case information.

Purpose¶

Get full test details including configuration, execution metadata, and failure references.

Input Schema¶

class TestsGetInput(BaseModel):
    test_id: str

Output Schema¶

class TestsGetOutput(BaseModel):
    schema_version: str = "1.0.0"
    item: TestCase

class TestCase(BaseModel):
    test_id: str
    name: str
    classname: str | None
    framework: str  # "uvm" | "cocotb" | "sv_unit"
    status: str  # "pass" | "fail" | "error" | "skipped"
    duration_ms: int | None
    timestamp: str
    run_id: str
    config: dict[str, Any]
    failure_refs: list[EvidenceRef]
    stdout_ref: EvidenceRef | None
    stderr_ref: EvidenceRef | None
    waveform_ref: EvidenceRef | None
    coverage_ref: EvidenceRef | None

Example¶

Query:

{
  "test_id": "T20260125_143000_axi_burst_test"
}

Response:

id=__codelineno-3-1 name=__codelineno-3-1 href=#__codelineno-3-1>{ "schema_version": "1.0.0", "item": { "test_id": "T20260125_143000_axi_burst_test", "name": "axi_burst_test", "classname": "axi_tests.AXIBurstTest", "framework": "uvm", "status": "fail", "duration_ms": 15420, "timestamp": "2026-01-25T14:35:20Z", "run_id": "R20260125_143000", "config": { "seed": 42, "verbosity": "UVM_MEDIUM", "timeout_ns": 1000000 }, "failure_refs": [ { "type": "assertion", "path": "axi_master_if.axi_awvalid_awready_check", "time_ns": 12450 }, { "type": "uvm_error", "path": "uvm_test_top.env.axi_agent.monitor", "time_ns": 12451 } ], "stdout_ref": { "type": "log", "path": "artifacts/R20260125_143000/axi_burst_test/run.log" }, "stderr_ref": null, "waveform_ref": { "type": "waveform", "path": "artifacts/R20260125_143000/axi_burst_test/waves.vcd" }, "coverage_ref": { "type": "coverage", "path": "artifacts/R20260125_143000/axi_burst_test/coverage.xml" } } class=p>}

tests.topology¶

Retrieve test execution topology (sequences, components, phases).

Purpose¶

Understand test structure, UVM component hierarchy, and execution flow.

Input Schema¶

class TestsTopologyInput(BaseModel):
    test_id: str

Output Schema¶

class TestsTopologyOutput(BaseModel):
    schema_version: str = "1.0.0"
    item: TestTopology

class TestTopology(BaseModel):
    test_id: str
    sequences: list[SequenceInfo]
    components: list[ComponentInfo]
    phases: list[PhaseInfo]

class SequenceInfo(BaseModel):
    name: str
    type: str
    parent: str | None

class ComponentInfo(BaseModel):
    name: str
    type: str
    parent: str | None

class PhaseInfo(BaseModel):
    name: str
    start_time_ns: int | None
    end_time_ns: int | None

Example¶

Query:

{
  "test_id": "T20260125_143000_axi_burst_test"
}

Response:

{
  "schema_version": "1.0.0",
  "item": {
    "test_id": "T20260125_143000_axi_burst_test",
    "sequences": [
      {
        "name": "axi_write_burst_seq",
        "type": "axi_base_seq",
        "parent": "axi_virtual_seq"
      },
      {
        "name": "axi_read_burst_seq",
        "type": "axi_base_seq",
        "parent": "axi_virtual_seq"
      }
    ],
    "components": [
      {
        "name": "uvm_test_top",
        "type": "axi_burst_test",
        "parent": null
      },
      {
        "name": "env",
        "type": "axi_env",
        "parent": "uvm_test_top"
      },
      {
        "name": "axi_agent",
        "type": "axi_master_agent",
        "parent": "env"
      },
      {
        "name": "monitor",
        "type": "axi_monitor",
        "parent": "axi_agent"
      }
    ],
    "phases": [
      {
        "name": "build_phase",
        "start_time_ns": 0,
        "end_time_ns": 100
      },
      {
        "name": "connect_phase",
        "start_time_ns": 100,
        "end_time_ns": 150
      },
      {
        "name": "run_phase",
        "start_time_ns": 150,
        "end_time_ns": 15420000
      }
    ]
  }
}

assertions.get¶

Get comprehensive assertion definition and runtime information.

Purpose¶

View assertion details including intent, severity, source location, and firing history.

Input Schema¶

class AssertionsGetInput(BaseModel):
    name: str
    scope: str

Output Schema¶

class AssertionsGetOutput(BaseModel):
    schema_version: str = "1.0.0"
    item: AssertionDetail

class AssertionDetail(BaseModel):
    name: str
    scope: str
    file: str | None
    line: int | None
    protocol: str | None
    category: str
    severity: str
    intent: str
    description: str | None
    tags: list[str]
    total_firings: int
    tests_affected: list[str]

Example¶

Query:

{
  "name": "axi_awvalid_awready_check",
  "scope": "axi_master_if"
}

Response:

{
  "schema_version": "1.0.0",
  "item": {
    "name": "axi_awvalid_awready_check",
    "scope": "axi_master_if",
    "file": "rtl/axi_master_if.sv",
    "line": 145,
    "protocol": "AXI4",
    "category": "protocol",
    "severity": "error",
    "intent": "AWVALID must remain high until AWREADY asserted",
    "description": "Once AWVALID is asserted, it must remain high until the corresponding AWREADY is asserted in the same cycle (handshake). This is a fundamental AXI4 protocol requirement.",
    "tags": ["handshake", "axi4", "write-channel"],
    "total_firings": 12,
    "tests_affected": [
      "T20260125_143000_axi_burst_test",
      "T20260125_143000_axi_protocol_test",
      "T20260124_091500_axi_stress_test"
    ]
  }
}

Common Patterns¶

Evidence References¶

Tests reference external artifacts using EvidenceRef:

class EvidenceRef(BaseModel):
    type: str  # "log" | "waveform" | "coverage" | "assertion" | "uvm_error"
    path: str
    time_ns: int | None  # For failures/assertions

Use Cases:

Log Files

{
  "type": "log",
  "path": "artifacts/R20260125_143000/test/run.log"
}

Waveforms

{
  "type": "waveform",
  "path": "artifacts/R20260125_143000/test/waves.vcd"
}

Coverage

{
  "type": "coverage",
  "path": "artifacts/R20260125_143000/test/coverage.xml"
}

Assertion Failures

{
  "type": "assertion",
  "path": "axi_master_if.axi_awvalid_awready_check",
  "time_ns": 12450
}

Test Configuration¶

The config field captures test parameters:

{
  "seed": 42,
  "verbosity": "UVM_MEDIUM",
  "timeout_ns": 1000000,
  "plusargs": {
    "+UVM_TESTNAME": "axi_burst_test",
    "+UVM_VERBOSITY": "UVM_MEDIUM"
  }
}

Topology Hierarchies¶

Component and sequence hierarchies use parent references:

{
  "name": "monitor",
  "type": "axi_monitor",
  "parent": "axi_agent"
}

Build the full path by traversing parents:

uvm_test_top.env.axi_agent.monitor

Phase Timing¶

UVM phases have optional timing information:

{
  "name": "run_phase",
  "start_time_ns": 150,
  "end_time_ns": 15420000
}

Duration: end_time_ns - start_time_ns = 15419850 ns

Error Handling¶

Test Not Found¶

Query:

{"test_id": "nonexistent"}

Response:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Test 'nonexistent' not found"
  }
}

Assertion Not Found¶

Query:

{"name": "unknown_check", "scope": "unknown_scope"}

Response:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Assertion 'unknown_check' in scope 'unknown_scope' not found"
  }
}

Best Practices¶

Cache Test Details

# ✅ Good - single query
test = client.tests.get(test_id="T20260125_143000_axi_burst_test")

# ❌ Bad - multiple queries
for test_id in test_ids:
    test = client.tests.get(test_id=test_id)

Use Topology for Debugging

# Get test topology to understand structure
topology = client.tests.topology(test_id="...")

# Find component in hierarchy
monitor = next(c for c in topology.components if c.type == "axi_monitor")

Follow Evidence References

# Get test with failure references
test = client.tests.get(test_id="...")

# Investigate each failure
for failure_ref in test.failure_refs:
    if failure_ref.type == "assertion":
        assertion = client.assertions.get(
            name=failure_ref.path.split(".")[-1],
            scope=".".join(failure_ref.path.split(".")[:-1])
        )

Next Steps¶

Analysis Tools → - Analyze failure patterns
Regression Tools → - Compare test results
Discovery Tools → - Find related tests