| Name | cocotb-test JSON |
| Version |
0.2.5
JSON |
| download |
| home_page | |
| Summary | |
| upload_time | 2024-02-07 19:53:43 |
| maintainer | |
| docs_url | None |
| author | Tomasz Hemperek |
| requires_python | >=3.7 |
| license | BSD |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# cocotb-test
[](https://dev.azure.com/themperek/themperek/_build/latest?definitionId=2&branchName=master)
[](https://badge.fury.io/py/cocotb-test)
``cocotb-test`` provides standard python unit testing capabilities for [cocotb](https://github.com/cocotb/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](https://pypi.org/project/pytest-xdist/) or [pytest-parallel](https://github.com/browsertron/pytest-parallel) for parallel runs
# Usage:
- Install [cocotb](https://docs.cocotb.org/).
- Install simulator (for Icarus Verilog with conda, on widows use 10.3 or devel [steveicarus/iverilog#395](https://github.com/steveicarus/iverilog/issues/395) ):
```bash
conda install -c conda-forge iverilog==10.3
```
- Install the package via [pip](https://pip.pypa.io/en/stable/user_guide/):
```bash
pip install cocotb-test
```
 or development version
```bash
pip install -v https://github.com/themperek/cocotb-test/archive/master.zip
```
 or
```bash
git clone https://github.com/themperek/cocotb-test.git
pip install -v -e cocotb-test
```
- Create a `test_dff.py` file (check [test folder](https://github.com/themperek/cocotb-test/tree/master/tests) for more examples):
```python
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](https://docs.pytest.org/en/latest/contents.html) (need `dff.sv` and `dff_cocotb.py` in same directory where running `pytest`):
```bash
SIM=icarus pytest -o log_cli=True test_dff.py
```
- To clean (remove all `sim_build` folders):
```bash
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](https://docs.cocotb.org/en/stable/building.html?#envvar-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 `list`s 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 `list`s with the library name as key, if the simulator supports named libraries.
* `toplevel_lang`: see [TOPLEVEL_LANG](https://docs.cocotb.org/en/stable/building.html?#var-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](https://docs.cocotb.org/en/stable/building.html?#envvar-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](https://docs.cocotb.org/en/stable/building.html?#envvar-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:
```bash
pytest --collect-only
```
* Run only selected test:
```bash
pytest -k test_dff_verilog_param[3]
```
* Test parameterization (for more see: [test_parameters.py](https://github.com/themperek/cocotb-test/blob/master/tests/test_parameters.py) )
```python
@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](https://pypi.org/project/pytest-xdist/) )
```bash
pytest -n NUMCPUS
```
# Running (some) tests and examples from cocotb
For cocotb tests/examples install cocotb in editable mode
```bash
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](https://docs.pytest.org/en/stable/logging.html) - pytest logging documentation
- [pytest-xdist](https://pypi.org/project/pytest-xdist/) - test run parallelization (see [test_parallel](https://github.com/themperek/cocotb-test/blob/master/tests/test_parallel.py))
- [pytest-parallel](https://github.com/browsertron/pytest-parallel) - parallel and concurrent testing (see [test_parallel](https://github.com/themperek/cocotb-test/blob/master/tests/test_parallel.py))
- [pytest-html](https://github.com/pytest-dev/pytest-html) - generates a HTML report for the test results
- [pytest-sugar](https://github.com/Teemu/pytest-sugar/) - sugar
Raw data
{
"_id": null,
"home_page": "",
"name": "cocotb-test",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "",
"author": "Tomasz Hemperek",
"author_email": "hemperek@uni-bonn.de",
"download_url": "https://files.pythonhosted.org/packages/56/27/5d18c8cc3095615925c112d194bb5c98999cc5e9429d5350b833400fa82e/cocotb-test-0.2.5.tar.gz",
"platform": "any",
"description": "# cocotb-test\n[](https://dev.azure.com/themperek/themperek/_build/latest?definitionId=2&branchName=master)\n[](https://badge.fury.io/py/cocotb-test)\n\n``cocotb-test`` provides standard python unit testing capabilities for [cocotb](https://github.com/cocotb/cocotb)\n- allow the look and feel of Python unit testing\n- remove the need for Makefiles (includes Makefile compatibility mode)\n- allow easy customization of simulation flow\n- allow to use [pytest-xdist](https://pypi.org/project/pytest-xdist/) or [pytest-parallel](https://github.com/browsertron/pytest-parallel) for parallel runs\n\n# Usage:\n\n- Install [cocotb](https://docs.cocotb.org/).\n\n- Install simulator (for Icarus Verilog with conda, on widows use 10.3 or devel [steveicarus/iverilog#395](https://github.com/steveicarus/iverilog/issues/395) ):\n```bash\nconda install -c conda-forge iverilog==10.3\n```\n- Install the package via [pip](https://pip.pypa.io/en/stable/user_guide/):\n```bash\npip install cocotb-test\n```\n or development version\n```bash\npip install -v https://github.com/themperek/cocotb-test/archive/master.zip\n```\n or\n```bash\ngit clone https://github.com/themperek/cocotb-test.git\npip install -v -e cocotb-test\n```\n\n- Create a `test_dff.py` file (check [test folder](https://github.com/themperek/cocotb-test/tree/master/tests) for more examples):\n```python\nfrom cocotb_test.simulator import run\ndef test_dff():\n run(\n verilog_sources=[\"dff.sv\"], # sources\n toplevel=\"dff\", # top level HDL\n module=\"dff_cocotb\" # name of cocotb test module\n )\n```\n\n- Run [pytest](https://docs.pytest.org/en/latest/contents.html) (need `dff.sv` and `dff_cocotb.py` in same directory where running `pytest`):\n```bash\nSIM=icarus pytest -o log_cli=True test_dff.py\n```\n\n- To clean (remove all `sim_build` folders):\n```bash\ncocotb-clean -r\n```\n### Arguments for `simulator.run`:\n\n* `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.\n* `module`: The name of the module(s) to search for test functions (see [MODULE](https://docs.cocotb.org/en/stable/building.html?#envvar-MODULE) ).\n\n* `python_search` : List of additional directoreis to search for python/cocotb modules.\n* `verilog_sources`: Verilog source files to include. Can be specified as a `list` or as a `dict` of `list`s with the library name as key, if the simulator supports named libraries.\n* `vhdl_sources`: VHDL source files to include. Can be specified as a `list` or as a `dict` of `list`s with the library name as key, if the simulator supports named libraries.\n* `toplevel_lang`: see [TOPLEVEL_LANG](https://docs.cocotb.org/en/stable/building.html?#var-TOPLEVEL_LANG). (default: `verilog`)\n* `includes`: A list of directories to search for includes.\n* `defines`: A list of the defines.\n* `parameters`: A dictionary of top-level parameters/generics.\n* `compile_args`: Any arguments or flags to pass to the compile stage of the simulation.\n * `vhdl_compile_args`: Additional arguments or flags passed only when compiling VHDL sources.\n * `verilog_compile_args`: Additional arguments or flags passed only when compiling Verilog sources.\n* `sim_args`: Any arguments or flags to pass to the execution of the compiled simulation.\n* `extra_args`: Passed to both the compile and execute phases of simulators.\n* `plus_args`: plusargs arguments passed to simulator.\n* `force_compile`: Force compilation even if sources did not change. (default: `False`)\n* `compile_only`: Only compile sources. Do not run simulation. (default: `False`)\n* `testcase`: The name of the test function(s) to run (see [TESTCASE](https://docs.cocotb.org/en/stable/building.html?#envvar-TESTCASE) ).\n* `sim_build`: The directory used to compile the tests. (default: `sim_build`)\n* `work_dir`: The directory used to tun the tests. (default: same as `sim_build` argument)\n* `seed`: Seed the Python random module to recreate a previous test stimulus (see [RANDOM_SEED](https://docs.cocotb.org/en/stable/building.html?#envvar-RANDOM_SEED) ).\n* `extra_env`: A dictionary of extra environment variables set in simulator process.\n* `waves`: Enable wave dumps (not all simulators supported).\n* `timescale`: Set simulator time unit/precision (default: `None`)\n* `gui`: Starts in gui mode (not all simulators supported).\n* `make_args`: Arguments passed to make phase (`Verilator` only).\n\n\n### Environmental variables:\n\n* `SIM`: Selects which simulator to use. (default: `icarus`)\n* `WAVES`: Overwrite enable wave dumps argument. Example use `WAVES=1 pytest test_dff.py`.\n\n### pytest arguments\n\n* `cocotbxml`: Combines and saves junitxml reports from cocotb tests. Example use `pytest --cocotbxml=test-cocotb.xml`.\n\n### Tips and tricks:\n\n* List all available test:\n```bash\npytest --collect-only\n```\n\n* Run only selected test:\n```bash\npytest -k test_dff_verilog_param[3]\n```\n\n* Test parameterization (for more see: [test_parameters.py](https://github.com/themperek/cocotb-test/blob/master/tests/test_parameters.py) )\n\n```python\n@pytest.mark.parametrize(\"width\", [{\"WIDTH_IN\": \"8\"}, {\"WIDTH_IN\": \"16\"}])\ndef test_dff_verilog_testcase(width):\n run(\n ...\n parameters=width,\n sim_build=\"sim_build/\" + \"_\".join((\"{}={}\".format(*i) for i in width.items())),\n )\n```\n\n* Run test in parallel (after installing [pytest-xdist](https://pypi.org/project/pytest-xdist/) )\n```bash\npytest -n NUMCPUS\n```\n\n# Running (some) tests and examples from cocotb\nFor cocotb tests/examples install cocotb in editable mode\n```bash\ngit clone https://github.com/potentialventures/cocotb.git\npip install -e cocotb\nSIM=icarus pytest -o log_cli=True --junitxml=test-results.xml --cocotbxml=test-cocotb.xml tests\n```\n\n# Related resources\n- [pytest logging](https://docs.pytest.org/en/stable/logging.html) - pytest logging documentation\n- [pytest-xdist](https://pypi.org/project/pytest-xdist/) - test run parallelization (see [test_parallel](https://github.com/themperek/cocotb-test/blob/master/tests/test_parallel.py))\n- [pytest-parallel](https://github.com/browsertron/pytest-parallel) - parallel and concurrent testing (see [test_parallel](https://github.com/themperek/cocotb-test/blob/master/tests/test_parallel.py))\n- [pytest-html](https://github.com/pytest-dev/pytest-html) - generates a HTML report for the test results\n- [pytest-sugar](https://github.com/Teemu/pytest-sugar/) - sugar\n",
"bugtrack_url": null,
"license": "BSD",
"summary": "",
"version": "0.2.5",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "56275d18c8cc3095615925c112d194bb5c98999cc5e9429d5350b833400fa82e",
"md5": "e7da7d33475e6105ebde664dac3c224d",
"sha256": "0f19d9cfc1b7f64fe25394ff5a5d5f788f2d5b4f04b0a742f1330c4b6ebf1343"
},
"downloads": -1,
"filename": "cocotb-test-0.2.5.tar.gz",
"has_sig": false,
"md5_digest": "e7da7d33475e6105ebde664dac3c224d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 20560,
"upload_time": "2024-02-07T19:53:43",
"upload_time_iso_8601": "2024-02-07T19:53:43.732568Z",
"url": "https://files.pythonhosted.org/packages/56/27/5d18c8cc3095615925c112d194bb5c98999cc5e9429d5350b833400fa82e/cocotb-test-0.2.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-07 19:53:43",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "cocotb-test"
}
