Skip to main content

No project description provided

Project description


Build Status PyPI version

cocotb-test provides standard python unit testing capabilities for cocotb

  • allow the look and feel of Python unit testing
  • remove the need for Makefiles (includes Makefile compatibility mode)
  • allow easy customization of simulation flow
  • allow to use pytest-xdist or pytest-parallel for parallel runs


conda install -c conda-forge iverilog==10.3
  • Install the package via pip:
pip install cocotb-test

 or development version

pip install -v


git clone
pip install -v -e cocotb-test
  • Create a file (check test folder for more examples):
from cocotb_test.simulator import run
def test_dff():
        verilog_sources=[""], # sources
        toplevel="dff",            # top level HDL
        module="dff_cocotb"        # name of cocotb test module
  • Run pytest (need and in same directory where running pytest):
SIM=icarus pytest -o log_cli=True
  • To clean (remove all sim_build folders):
cocotb-clean -r

Arguments for

  • toplevel: Top level module name to indicate the instance in the hierarchy to use as the DUT. Multiple top levels can be specified as a list, if the simulator supports it.

  • module: The name of the module(s) to search for test functions (see MODULE ).

  • python_search : List of additional directoreis to search for python/cocotb modules.

  • verilog_sources: Verilog source files to include. Can be specified as a list or as a dict of lists with the library name as key, if the simulator supports named libraries.

  • vhdl_sources: VHDL source files to include. Can be specified as a list or as a dict of lists with the library name as key, if the simulator supports named libraries.

  • toplevel_lang: see TOPLEVEL_LANG. (default: verilog)

  • includes: A list of directories to search for includes.

  • defines: A list of the defines.

  • parameters: A dictionary of top-level parameters/generics.

  • compile_args: Any arguments or flags to pass to the compile stage of the simulation.

    • vhdl_compile_args: Additional arguments or flags passed only when compiling VHDL sources.
    • verilog_compile_args: Additional arguments or flags passed only when compiling Verilog sources.
  • sim_args: Any arguments or flags to pass to the execution of the compiled simulation.

  • extra_args: Passed to both the compile and execute phases of simulators.

  • plus_args: plusargs arguments passed to simulator.

  • force_compile: Force compilation even if sources did not change. (default: False)

  • compile_only: Only compile sources. Do not run simulation. (default: False)

  • testcase: The name of the test function(s) to run (see TESTCASE ).

  • sim_build: The directory used to compile the tests. (default: sim_build)

  • work_dir: The directory used to tun the tests. (default: same as sim_build argument)

  • seed: Seed the Python random module to recreate a previous test stimulus (see RANDOM_SEED ).

  • extra_env: A dictionary of extra environment variables set in simulator process.

  • waves: Enable wave dumps (not all simulators supported).

  • timescale: Set simulator time unit/precision (default: None)

  • gui: Starts in gui mode (not all simulators supported).

  • make_args: Arguments passed to make phase (Verilator only).

Environmental variables:

  • SIM: Selects which simulator to use. (default: icarus)
  • WAVES: Overwrite enable wave dumps argument. Example use WAVES=1 pytest

pytest arguments

  • cocotbxml: Combines and saves junitxml reports from cocotb tests. Example use pytest --cocotbxml=test-cocotb.xml.

Tips and tricks:

  • List all available test:
pytest --collect-only
  • Run only selected test:
pytest -k test_dff_verilog_param[3]
@pytest.mark.parametrize("width", [{"WIDTH_IN": "8"}, {"WIDTH_IN": "16"}])
def test_dff_verilog_testcase(width):
        sim_build="sim_build/" + "_".join(("{}={}".format(*i) for i in width.items())),
pytest -n NUMCPUS

Running (some) tests and examples from cocotb

For cocotb tests/examples install cocotb in editable mode

git clone
pip install -e cocotb
SIM=icarus pytest -o log_cli=True --junitxml=test-results.xml --cocotbxml=test-cocotb.xml tests

Related resources

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

cocotb-test-0.2.5.tar.gz (20.6 kB view hashes)

Uploaded source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page