cocotb-test

What it is and what it does

cocotb-test is a pytest plugin that bridges cocotb (a Python-based hardware simulation framework) with standard Python unit testing. Instead of writing Makefiles and shell scripts to orchestrate HDL simulations, you write pytest test functions that call cocotb-test's `run()` function with your Verilog or VHDL sources, top-level module name, and cocotb test module. The package handles compilation, simulation, and result collection, letting you use pytest's full ecosystem—parameterization, filtering, parallel execution via pytest-xdist, and reporting plugins.

The package depends on cocotb (the core simulation engine), pytest (the test runner), and find_libpython (a utility for locating Python libraries). It supports Python 3.7 and later. Maintenance is dormant, with no activity for 587 days, though a release occurred on 2025-01-04. Installation requires a working simulator and environment setup, making it a high-friction dependency for teams not already running hardware simulations.

Use it for:

• Run Verilog or VHDL testbenches as pytest tests without writing Makefiles or shell scripts.
• Parameterize HDL simulations using pytest.mark.parametrize to test designs across multiple configurations.
• Parallelize simulation runs across CPU cores using pytest-xdist for faster design verification.
• Integrate hardware verification into CI/CD pipelines alongside software unit tests.
• Generate junitxml or HTML reports from cocotb test results using pytest plugins.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

cocotb-test wraps cocotb hardware simulations in pytest, letting you write and run HDL testbenches as standard Python unit tests without Makefiles.

Yes, if you are already using cocotb and pytest in a hardware design flow and want to eliminate Makefiles and gain pytest's testing ecosystem. No, if you are new to hardware simulation or lack a simulator installed—the high install friction and dormant maintenance make this a specialist tool. Yes-with-conditions: verify compatibility with your cocotb version and simulator before adopting in a new project.

Install

cocotb-test on PyPI

pip install cocotb-test

uv add cocotb-test

poetry add cocotb-test

Installing cocotb-test

Before you install

High install friction: requires cocotb, a simulator (e.g. Icarus Verilog), and find_libpython as runtime dependencies. Maintenance is dormant—last release was 587 days ago, though the package did receive a release on 2025-01-04.

License in practice

BSD permissive license means you can use, modify, and distribute cocotb-test freely in commercial and open-source projects with minimal restrictions.

Quickstart

pip install cocotb-test

from cocotb_test.simulator import run

def test_dff():
    run(
        verilog_sources=["dff.sv"],
        toplevel="dff",
        module="dff_cocotb"
    )

# Run: SIM=icarus pytest test_dff.py

Requires a simulator (e.g. Icarus Verilog) installed and SIM environment variable set; cocotb must be installed first.

Verify before relying

• Whether the package actively maintains compatibility with current cocotb versions given dormant maintenance status.
• Performance characteristics when running large test suites or using pytest-xdist parallelization.
• Support status for simulators other than Icarus Verilog (e.g. Verilator, commercial tools).

Package facts

Evidence: cocotb_test-0.2.6.tar.gz

Tags

More Electronic Design Automation (EDA) packages