/cocotb-test

Unit testing for cocotb

Primary LanguagePythonBSD 2-Clause "Simplified" LicenseBSD-2-Clause

cocotb-test

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

Usage:

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

 or development version

pip install -v https://github.com/themperek/cocotb-test/archive/master.zip

 or

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

Arguments for simulator.run:

  • 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 test_dff.py.

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):
    run(
        ...
        parameters=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 https://github.com/potentialventures/cocotb.git
pip install -e cocotb
SIM=icarus pytest -o log_cli=True --junitxml=test-results.xml --cocotbxml=test-cocotb.xml tests

Related resources