Pytest Plugin Reference

Pytest Plugin Reference#

Warning

The pytest plugin is under active development and the API will change in breaking ways over the next release or two.

You can still use pytest with the Python runners for building designs and running simulations, and you can also still use pytest features in cocotb tests, such pytest.raises(), pytest.skip(), or pytest’s assertion rewriting.

Fixtures#

fixture cocotb_tools._pytest.plugin.dut[source]#

Scope: session

A cocotb fixture that is providing a simulation handle to DUT.

Provided simulation handle is the same as cocotb.top.

Example usage:

async def test_dut_feature_1(dut) -> None:
    dut.rst.value = 0
    dut.clk.value = 0

    # Testing DUT feature
    ...

Returns:: Simulation handle to DUT (equivalent to cocotb.top).

fixture cocotb_tools._pytest.plugin.hdl_session[source]#

Scope: session

A cocotb fixture that is providing a helper instance to define own HDL design and to build it.

Note

This fixture is scoped to global session scope. It can be useful to build the whole HDL project with different HDL modules at once not per test.

It contains own instance of Runner that can be accessed directly from runner member.

Defined HDL design can be build by invoking the build() method from non-async test functions. This method will invoke build step from runner member.

Requested fixture will pass various plugin options to own instance of Runner. Like setting a desired verbosity level for cocotb runner.

Please refer to available public members of HDL that can be used to define own HDL design.

Example usage:

import pytest
from cocotb_tools._pytest.hdl import HDL


@pytest.fixture(scope="session")
def my_hdl_project(hdl_session: HDL) -> HDL:
    # Build whole HDL design with all HDL modules at once
    hdl_session.sources = (
        # Add more HDL source files here
        # ...
        DIR / "my_hdl_module_1.sv",
        DIR / "my_hdl_module_2.sv",
    )

    hdl_session.build()

    return hdl_session


@pytest.fixture(name="my_hdl_module_1")
def my_hdl_module_1_fixture(hdl: HDL, my_hdl_project: HDL) -> HDL:
    # Define HDL module 1
    hdl.build_dir = my_hdl_project.build_dir
    hdl.toplevel = "my_hdl_module_1"

    return hdl


@pytest.fixture(name="my_hdl_module_2")
def my_hdl_module_2_fixture(hdl: HDL, my_hdl_project: HDL) -> HDL:
    # Define HDL module 2
    hdl.build_dir = my_hdl_project.build_dir
    hdl.toplevel = "my_hdl_module_2"

    return hdl


@pytest.mark.cocotb_runner
def test_dut_1(my_hdl_module_1: HDL) -> None:
    # Run HDL simulator with cocotb tests
    my_hdl_module_1.test()


@pytest.mark.cocotb_runner
def test_dut_2(my_hdl_module_2: HDL) -> None:
    # Run HDL simulator with cocotb tests
    my_hdl_module_2.test()

Parameters:: request – The pytest fixture request that is providing plugin options to this fixture. These options will be used to configure own instance of Runner.
Returns:: Instance that allows to build and test HDL design.

fixture cocotb_tools._pytest.plugin.hdl[source]#

Scope: function

A cocotb fixture that is providing a helper instance to define own HDL design, to build it and run set of cocotb tests from test modules (testbenches) against selected top level design.

Note

This fixture is scoped to default function scope. It can help to build HDL module per test and run tests for defined HDL top level.

It contains own instance of Runner that can be accessed directly from runner member.

Defined HDL design can be build by invoking the build() method and test by invoking the test() method from non-async test functions. These methods will invoke build and test steps from runner member.

Requested fixture will pass various plugin options to own instance of Runner. Like setting a desired verbosity level for cocotb runner.

Please refer to available public members of HDL that can be used to define own HDL design.

Example usage:

import pytest
from cocotb_tools._pytest.hdl import HDL


@pytest.fixture(name="my_hdl_module")
def my_hdl_module_fixture(hdl: HDL) -> HDL:
    # Build HDL module per test
    hdl.toplevel = "my_hdl_module"

    hdl.sources = (
        # Add more HDL source files here
        # ...
        DIR / "my_hdl_module.sv",
    )

    hdl.build()

    return hdl


@pytest.mark.cocotb_runner
def test_dut(my_hdl_module: HDL) -> None:
    # Run HDL simulator with cocotb tests
    my_hdl_module.test()

Parameters:

request – The pytest fixture request that is providing plugin options to this fixture. These options will be used to configure own instance of Runner.
hdl_session – HDL design defined at global session scope level.

Returns:

Instance that allows to build and test HDL design.

Markers#

@cocotb_tools._pytest.mark.cocotb_runner( test_module: str = '', *extra_test_module: str, ) → MarkDecorator[source]#

Mark test function as cocotb runner.

Example usage:

import pytest
from cocotb_tools._pytest.hdl import HDL

@pytest.fixture(name="sample_module")
def sample_module_fixture(hdl: HDL) -> HDL:
    # Define HDL design and build it
    hdl.toplevel = "sample_module"
    hdl.sources = (DESIGNS / "sample_module.sv",)
    hdl.build()

    return hdl

@pytest.mark.cocotb_runner
def test_dut(sample_module: HDL) -> None:
    # Run HDL simulator with cocotb tests
    sample_module.test()

Parameters:: test_module – Name of Python module with cocotb tests to be loaded by cocotb runner.
Returns:: Decorated test function as cocotb runner.

@cocotb_tools._pytest.mark.cocotb_test[source]#

Mark coroutine function as cocotb test.

Example usage:

# NOTE: decorator is not needed if coroutine function starts with the test_ prefix and it uses dut fixture
async def test_dut_feature(dut) -> None:
    # Test DUT feature
    ...

@pytest.mark.cocotb_test
async def non_canonical_test_name(dut) -> None:
    # Test DUT feature but from a test function that doesn't follow with the pytest naming convention
    ...

Returns:: Decorated coroutine function as cocotb test.

@cocotb_tools._pytest.mark.cocotb_timeout( duration: float, unit: 'step' | 'fs' | 'ps' | 'ns' | 'us' | 'ms' | 'sec', ) → MarkDecorator[source]#

Mark coroutine function with simulation time duration before the test is forced to fail.

Example usage:

@pytest.mark.cocotb_timeout(duration=200, unit="ns")
async def test_dut_feature_with_timeout(dut) -> None:
    # Test DUT feature with timeout configured from cocotb marker
    ...

Parameters:

duration – Simulation time duration before the test is forced to fail.
unit – Simulation time unit that accepts any unit that Timer does.

Raises:

SimTimeoutError – Test function timeouted.

Returns:

Decorated coroutine function with simulation time duration before the test is forced to fail.

@cocotb_tools._pytest.mark.cocotb_library[source]#: Set the library name to compile into.

@cocotb_tools._pytest.mark.cocotb_sources[source]#: Add language-agnostic list of source files to build.

@cocotb_tools._pytest.mark.cocotb_defines[source]#: Set defines.

@cocotb_tools._pytest.mark.cocotb_includes[source]#: Add Verilog includes.

@cocotb_tools._pytest.mark.cocotb_parameters[source]#: Set Verilog/SystemVerilog parameters and VHDL generics.

@cocotb_tools._pytest.mark.cocotb_plusargs[source]#: Add plus arguments for the simulator.

@cocotb_tools._pytest.mark.cocotb_env[source]#: Set environment variables.

@cocotb_tools._pytest.mark.cocotb_seed[source]#: A specific random seed to use.

@cocotb_tools._pytest.mark.cocotb_timescale( unit: str, precision: str | None = None, ) → MarkDecorator[source]#: Set time unit and time precision for simulation.

@cocotb_tools._pytest.mark.cocotb_always[source]#: Always run the build step.

@cocotb_tools._pytest.mark.cocotb_clean[source]#: Delete build_dir before building.

@cocotb_tools._pytest.mark.cocotb_waves[source]#: Record signal traces.

@cocotb_tools._pytest.mark.cocotb_build_args[source]#: Add extra build arguments for the simulator.

@cocotb_tools._pytest.mark.cocotb_elab_args[source]#: Add extra elaboration arguments to the simulator.

@cocotb_tools._pytest.mark.cocotb_test_args[source]#: Add extra runtime arguments to the simulator.

@cocotb_tools._pytest.mark.cocotb_pre_cmd[source]#: Add extra commands to run before simulation begins. Typically Tcl commands for simulators that support them..

HDL Fixture Request#

class cocotb_tools._pytest.hdl.HDL(request: FixtureRequest)[source]#

Build HDL design and run test against specific HDL top level.

Expand for references to cocotb_tools._pytest.hdl.HDL

Pytest Plugin Reference / Markers

Pytest Plugin Reference / Fixtures

Pytest Plugin / Integration / By Hooks

Pytest Plugin / Building and Testing / Fixtures / cocotb_tools._pytest.plugin.hdl

Pytest Plugin / Building and Testing / Markers / @pytest.mark.cocotb_runner

Pytest Plugin / Building and Testing / Markers / @pytest.mark.cocotb_test

always: bool#: Always run the build step.

Build HDL design.

Parameters:

library – The library name to compile into.
sources – Language-agnostic list of source files to build.
includes – Verilog include directories.
defines – Defines to set.
parameters – Verilog parameters or VHDL generics.
build_args – Extra build arguments for the simulator.
toplevel – Name of the HDL toplevel module.
always – Always run the build step.
clean – Delete build_dir before building.
verbose – Enable verbose messages.
timescale – Tuple containing time unit and time precision for simulation.
waves – Record signal traces.
build_dir – Directory to run the build step in.
cwd – Directory to execute the build command(s) in.

Expand for references to cocotb_tools._pytest.hdl.HDL.build

Pytest Plugin Reference / Markers

Pytest Plugin Reference / Fixtures

Pytest Plugin / Building and Testing / Fixtures / cocotb_tools._pytest.plugin.hdl

Pytest Plugin / Building and Testing / Markers / @pytest.mark.cocotb_runner

Pytest Plugin / Building and Testing / Markers / @pytest.mark.cocotb_test

build_args: MutableSequence[str | VHDL | Verilog]#: Extra build arguments for the simulator.

build_dir: PathLike[str] | str#: Directory to run the build step in.

clean: bool#: Delete build_dir before building.

cwd: PathLike[str] | str#: Directory to execute the build command(s) in.

defines: MutableMapping[str, object]#: Defines to set.

elab_args: MutableSequence[str]#: A list of elaboration arguments for the simulator.

env: MutableMapping[str, str]#: Extra environment variables to set.

gpi_interfaces: list[str]#: List of GPI interfaces to use, with the first one being the entry point.

gui: bool#: Run with simulator GUI.

includes: MutableSequence[PathLike[str] | str]#: Verilog include directories.

library: str#: The library name to compile into.

parameters: MutableMapping[str, object]#: Verilog parameters or VHDL generics.

plusargs: MutableSequence[str]#: ‘plusargs’ to set for the simulator.

pre_cmd: list[str]#: Commands to run before simulation begins. Typically Tcl commands for simulators that support them.

runner: Runner#: Instance that allows to build HDL and run cocotb tests.

seed: str | int | None#: A specific random seed to use.

property simulator: str#: Name of HDL simulator.

sources: MutableSequence[PathLike[str] | str | VHDL | Verilog | VerilatorControlFile]#: Language-agnostic list of source files to build.

Test HDL design.

Parameters:

test_module – Name(s) of the Python module(s) containing the tests to run.
toplevel – Name of the HDL toplevel module.
toplevel_library – The library name for HDL toplevel module.
toplevel_lang – Language of the HDL toplevel module.
gpi_interfaces – List of GPI interfaces to use, with the first one being the entry point.
parameters – Verilog parameters or VHDL generics.
seed – A specific random seed to use.
elab_args – A list of elaboration arguments for the simulator.
test_args – A list of extra arguments for the simulator.
plusargs – ‘plusargs’ to set for the simulator.
env – Extra environment variables to set.
gui – Run with simulator GUI.
waves – Record signal traces.
verbose – Enable verbose messages.
pre_cmd – Commands to run before simulation begins. Typically Tcl commands for simulators that support them.
timescale – Tuple containing time unit and time precision for simulation.
build_dir – Directory to run the build step in.
test_dir – Directory to run the tests in.

Returns:

Path to created results file with cocotb tests in JUnit XML format.

Expand for references to cocotb_tools._pytest.hdl.HDL.test

Pytest Plugin Reference / Markers

Pytest Plugin Reference / Fixtures

Pytest Plugin / Building and Testing / Markers / @pytest.mark.cocotb_runner

test_args: MutableSequence[str]#: A list of extra arguments for the simulator.

test_dir: PathLike[str] | str#: Directory to run the tests in.

test_module: str | Sequence[str]#: Name(s) of the Python module(s) containing the tests to run.

timescale: tuple[str, str] | None#: Tuple containing time unit and time precision for simulation.

toplevel: str | None#: Name of the HDL toplevel module.

toplevel_lang: str | None#: Language of the HDL toplevel module.

toplevel_library: str#: The library name for HDL toplevel module.

verbose: bool#: Enable verbose messages.

waves: bool#: Record signal traces.

Hook Specifications#

cocotb_tools._pytest.hookspecs.pytest_cocotb_make_hdl( request: FixtureRequest, ) → HDL | None[source]#

Create new instance of cocotb_tools._pytest.hdl.HDL.

Note

Any conftest file can implement this hook. Stops at first non-None result.

Parameters:: request – The pytest fixture request object.
Returns:: New instance of HDL.

cocotb_tools._pytest.hookspecs.pytest_cocotb_make_runner( simulator_name: str, ) → Runner | None[source]#

Create new instance of cocotb_tools.runner.Runner.

Note

Any conftest file can implement this hook. Stops at first non-None result.

Parameters:: simulator_name – Name of HDL simulator.
Returns:: New instance of runner.

Pytest Plugin Reference

Contents

Pytest Plugin Reference#

Fixtures#

Markers#

HDL Fixture Request#

Hook Specifications#