elasticai.creator.testing.cocotb_pytest

Module Contents

Classes

CocotbTestFixture

Run cocotb via pytest, inject parameters before and during test execution.

Functions

create_name_for_build_test_subdir
eai_testbench	Intended usage:
cocotb_test_fixture	Yields the setup CocotbTestFixture and performs necessary clean up after the test run.

API

elasticai.creator.testing.cocotb_pytest.create_name_for_build_test_subdir(fn: collections.abc.Callable, *args: Any, **kwargs: Any) → str

elasticai.creator.testing.cocotb_pytest.eai_testbench(fn)

Intended usage:

@cocotb.test()
@eai_testbench
async def my_testbench_for_input_buffer(dut, x, input_data):
  dut.d_in = x

and

@pytest.mark.parametrize("x", [1, 2, 3])
def test_input_buffer(cocotb_test_fixture, x):
  cocotb_test_fixture.write({"input_data": "hello world"})
  cocotb_test_fixture.run()

The example will assume your toplevel module is "input_buffer" and it’s source file lives in a sibling folder of the test folder that contains the pytest test function. It will create a unique subdirectory under build_test that matches the path to the module containing the testbench definition and pytest test function (those need to be the same). This prevents test A overriding the artifacts of test B. The name of the subdirectory will be derived from the parameters passed via the parametrize pytest marker and the top module name. In this example this results in folders: input_buffer_test_input_buffer_x_1, input_buffer_test_input_buffer_x_2, input_buffer_test_input_buffer_x_3.

class elasticai.creator.testing.cocotb_pytest.CocotbTestFixture(test_fn: collections.abc.Callable, *args: float | int | str, **kwargs: float | int | str)

Run cocotb via pytest, inject parameters before and during test execution.

The fixture will inspect the requesting test function to assume some default values and perform a little bit of setup. Namely this is

• Use the test function name to determine the dut top module name and the name of its containing source file. These can be overriden inside the test function using CocotbTestFixture.set_top_module_name() and CocotbTestFixture.set_srcs(). The name will be derived by stripping the test_ prefix from the test function name. The implementation will try to find a vhdl or verilog file under ../{vhdl, verilog}/<name>.{vhd, v}. Vhdl will take precedence. If no file is found, the initial srcs list will be left empty without raising an exception.

• It will create a folder to contain test artifacts including waveforms, xml result, testdata json and compiled simulation object files. To avoid collisions, the name of the folder will be derived from the fully qualified test function name (replacing . by /) and the parameter list provided via pytest parametrization.

This is not intended to be used directly. Request cocotb_test_fixture as a pytest fixture instead.

Initialization

setup()

teardown()

write(data: dict[str, Any]) → None

set_top_module_name(top_module_name: str) → None

set_srcs(srcs: collections.abc.Iterable[str | pathlib.Path])

add_srcs(*srcs: str | pathlib.Path) → None

set_timescale(scale: tuple[str, str]) → None

run(params, defines)

elasticai.creator.testing.cocotb_pytest.cocotb_test_fixture(request) → collections.abc.Iterator[elasticai.creator.testing.cocotb_pytest.CocotbTestFixture]

Yields the setup CocotbTestFixture and performs necessary clean up after the test run.

To use the fixture either place add the line

pytest_plugins = "elasticai.creator.testing.cocotb_pytest"

to either a conftest.py in the test directory tree or in the test module.