cocotb-test

cocotb-test

[!NOTE]
Since version 1.8 cocotb supports python based runner.

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:

• Install cocotb.

• Install simulator (for Icarus Verilog with conda, on widows use 10.3 or devel steveicarus/iverilog#395 ):

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]

• Test parameterization (for more see: test_parameters.py )

@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())),
    )

• Run test in parallel (after installing pytest-xdist )

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

• pytest logging - pytest logging documentation
• pytest-xdist - test run parallelization (see test_parallel)
• pytest-parallel - parallel and concurrent testing (see test_parallel)
• pytest-html - generates a HTML report for the test results
• pytest-sugar - sugar