cocotb-testgen — VHDL Testbench Generator & Dependency Visualizer

cocotb-testgen is an automated tool that:

Parses a VHDL source tree,
Extracts entity definitions and generics,
Resolves recursive module dependencies,
Generates cocotb-based test stubs per module,
And visualizes the design hierarchy using Graphviz.

This tool is headless-Docker friendly, CLI-driven, and easily extendable.

🔧 Features

✅ Auto-detects VHDL entities and their generics ✅ Supports both entity LIB.ENTITY and component ENTITY instantiations ✅ Automatically creates test files (test_<module>.py) using Jinja2 templates ✅ Recursively resolves dependencies and module instantiations ✅ Exports a DOT graph for the entity hierarchy ✅ Renders PNG visualization of the design hierarchy (even in headless mode) ✅ Robust Path Detection: Automatically finds the project root to ensure tests run from anywhere

📂 Project Structure


tich/
├── src/
│   ├── fpga/
│   │   └── ssi_top.vhd
│   └── ...
├── sim/
│   └── cocotb/
│       └── tests/
│           └── test_ssi_top.py   <-- Generated!
├── tools/
│   └── cocotb-testgen/
│       ├── gen_cocotb_structure.py
│       ├── templates/
│       │   ├── with_generics.py.j2
│       │   └── no_generics.py.j2
│       └── out.dot              <-- Generated!
│       └── ssi_top_hierarchy.png  <-- Rendered!

🚀 Quick Start

1. Run the Generator


python gen_cocotb_structure.py --src ../../src --out ../../sim/cocotb/tests --dry-run --verbose

Options

--src: Source root directory (default: src).
--out: Output directory for generated tests (default: sim/cocotb/tests).
--absolute-paths: Use absolute paths for VHDL sources (default: False).
--excludes: List of filename patterns to exclude (default: ['_pkg.vhd', 'wrapper_', 'top.vhd']).
--dry-run: Do not create files, just print what would be done.
--graph: Export a dependency graph for a specific entity (requires --root).
--root: Root entity name for the dependency graph.
--verbose: Enable detailed debug output.

2. View What Would Be Created


[DEBUG] Parsed generics for endpoint_fifo: DEPTH=512, WIDTH=32
[DEBUG] All dependencies for endpoint_fifo: ['endpoint_fifo.vhd', 'sync_cdc.vhd', 'fifo_xpm_async.vhd']
Would create:
  - sim/cocotb/tests/fpga/test_endpoint_fifo.py

3. Generate Graph (Optional)


from gen_cocotb_structure import export_entity_graph, build_entity_map
entity_map = build_entity_map(Path("../../src"))
export_entity_graph("ssi_top", entity_map, Path("ssi_top.dot"))

Then render:


dot -Tpng ssi_top.dot -o ssi_top_hierarchy.png

💡 Inside Docker? Works fine — rendering is headless.

🧠 Example: DOT Output


digraph EntityHierarchy {
  "ssi_top" -> "sniffer_gather";
  "sniffer_gather" -> "i2c_sniffer";
  "i2c_sniffer" -> "edge_detector";
  "ssi_top" -> "clk_mgr";
  ...
}

ssi_top_hierarchy

📜 Template Example

`with_generics.py.j2`


import cocotb
from cocotb.clock import Clock
from cocotb.triggers import RisingEdge, Timer

# ... setup imports ...

def main():
    setup_simulation(
        top_level="{module_name}",
        module="test_{module_name}",
        # ...
        parameters={{
            {param_dict}
        }},
    )

@cocotb.test()
async def test_basic_behavior(dut):
    """Basic test for {module_name}"""
    PERIOD = 10
    cocotb.start_soon(Clock(dut.CLK, PERIOD, unit="ns").start())
    # ...

🧱 Supported VHDL Constructs

✅ label : entity lib.module
✅ label : component module (as long as component keyword is present)

❌ Not yet: inference-based or generic-mapped instantiations ✅ Easily extendable by modifying find_instantiated_entities().

� Upcoming Features & Improvement Hints

The following features are planned or suggested for future contributors:

Multi-Language Support: Add support for parsing Verilog/SystemVerilog modules (.v, .sv).
Robust Parsing: Move from Regex-based parsing to a proper AST-based parser (e.g., using pyvhdlmodel or hdlConvertor) to handle complex constructs like records, custom types, and conditional instantiations.
Test Factory Integration: Update templates to use cocotb.regression.TestFactory for cleaner parameterization instead of ad-hoc loops.
Heuristic Auto-Verification: Generate basic scoreboards or assertions based on port naming conventions (e.g., axi_* ports triggering AXI VIP instantiations).
Graph Interaction: Generate interactive SVG/HTML graphs where nodes are clickable links to source files.
CI Integration: Add a GitHub Actions workflow example to run these tests automatically on PRs.

cocotb testgen