---
id: cocotb-test
version: "0.2.6"
license: BSD
license_treatment: permissive
maintenance: dormant
---

# cocotb-test

License: permissive · Maintenance: dormant · Downloads: 242.3K/mo

## 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 above — 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

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

- License: BSD (permissive)
- Python support: supports_current
- Install friction: high
- Maintenance: dormant
- Downloads: 242.3K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

pytest cocotb integration, hardware simulation testing, verilog vhdl unit tests, cocotb python runner, HDL testbench framework, digital design verification, simulation test automation, hardware-verification, eda, pytest-plugin

[View on SkillFed](https://skillfed.io/packages/cocotb-test) · [View on PyPI](https://pypi.org/project/cocotb-test/)