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

my_project/
├── src/
│   ├── fpga/
│   │   └── my_top.vhd
│   └── ...
├── sim/
│   └── cocotb/
│       └── tests/
│           └── test_my_top.py   <-- Generated!
├── tools/
│   └── cocotb-testgen/
│       ├── gen_cocotb_structure.py
│       ├── templates/
│       │   ├── with_generics.py.j2
│       │   └── no_generics.py.j2
│       └── out.dot              <-- Generated!
│       └── my_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("my_top", entity_map, Path("my_top.dot"))

Then render:

dot -Tpng my_top.dot -o my_top_hierarchy.png

💡 Inside Docker? Works fine — rendering is headless.

🧠 Example: DOT Output

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

📜 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.