cocotb-test
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.pyfile (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.svanddff_cocotb.pyin same directory where runningpytest):
SIM=icarus pytest -o log_cli=True test_dff.py
- To clean (remove all
sim_buildfolders):
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 directories to search for python/cocotb modules. -
verilog_sources: Verilog source files to include. Can be specified as alistor as adictoflists with the library name as key, if the simulator supports named libraries. -
vhdl_sources: VHDL source files to include. Can be specified as alistor as adictoflists 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 assim_buildargument) -
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 (Verilatoronly).
Environmental variables:
SIM: Selects which simulator to use. (default:icarus)WAVES: Overwrite enable wave dumps argument. Example useWAVES=1 pytest test_dff.py.
pytest arguments
cocotbxml: Combines and saves junitxml reports from cocotb tests. Example usepytest --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
Metadata
Release files for cocotb-test 0.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| cocotb_test-0.3.0.tar.gz | 21.4 kB | Without provenance | Details for cocotb_test-0.3.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| cocotb_test-0.3.0-py3-none-any.whl | Python 3 | none | any | Details for cocotb_test-0.3.0-py3-none-any.whl |
Total release size: 38.7 kB
Release files / cocotb_test-0.3.0.tar.gz
| Download URL | cocotb_test-0.3.0.tar.gz |
|---|---|
| Size | 21.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ec4e79ce3c279abc9902653367a3900d4574bd78d29aff8b43e335eef13a7f0a
|
|
BLAKE2b-256 checksum How to use checksums |
82afa4f6e790ba26c2d7c1ea0335d84dce209913f4218739759a35114d3fe0a6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.7
|
Release files / cocotb_test-0.3.0-py3-none-any.whl
| Download URL | cocotb_test-0.3.0-py3-none-any.whl |
|---|---|
| Size | 17.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
bd2dcdd6d7249b6d27e8db78533c64a86dc38e3584a235d7cddcd2bf8b953ea6
|
|
BLAKE2b-256 checksum How to use checksums |
d323d05a24988b212d1dee66c221710508ce647655656b8b6d43b109e7bac7c8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.7
|
Security for cocotb-test 0.3.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.