elasticai.creator.testing.cocotb_pytest

Module Contents

Classes

CocotbTestFixture

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

Functions

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

API

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 (both need to live in the same module). 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 to be available 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 .set_top_module_name() and .set_srcs(). The default 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.

  The fixture assumes the test resolves package resources itself (e.g. via get_file_from_package). It will keep open the files whose paths are passed to set_srcs()/add_srcs() while run executes, but you must keep a surrounding with in the test so the package helper holds the resource alive during the simulation.

• If you need to generate hdl sources prior to running testbenches and want to store them with the rest of the testing artifacts, you can retrieve the automatically determined folder via the .get_artifact_dir() method. This allows you to store the sources there and pass the resulting paths to the fixture using eg. .add_srcs.

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

Initialization

setup()

teardown()

get_artifact_dir() → pathlib.Path

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.

For more information see the documentation of CocotbTestFixture

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