Pytest Plugin

Pytest Plugin#

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.

cocotb_tools._pytest.plugin provides full pytest integration with cocotb. Including:

fixtures to cleanly set up and tear down cocotb tests and designs under test.
plugins that can extend cocotb testing capabilities.
configuration facilities to configure the cocotb testing environment using command line arguments --cocotb-*, configuration files like pyproject.toml or fixture arguments for fine control per test, class, module or session.
listing all available cocotb tests and their relationship with cocotb_tools.runner.
marks to easily set metadata on cocotb test functions.
filtering cocotb tests with pytest -k '<expression>' and -m '<markers>' options.
reporting all executed cocotb tests.
parallel execution of cocotb runners by using the pytest-xdist plugin

Enabling the Plugin#

cocotb_tools._pytest.plugin can be enabled in various ways.

In a Python project#

When using the pyproject.toml file (recommended way):

[project.entry-points.pytest11]
cocotb = "cocotb_tools._pytest.plugin"

When using the pytest.ini file:

[pytest]
addopts = -p cocotb_tools._pytest.plugin

When using the setup.cfg file:

[options.entry_points]
pytest11 =
  cocotb = cocotb_tools._pytest.plugin

When using the setup.py file:

from setuptools import setup

setup(
    # ...,
    entry_points={
        "pytest11": [
            "cocotb = cocotb_tools._pytest.plugin",
        ],
    },
)

In a non-Python project#

By defining the global variable pytest_plugins when using a conftest.py file (which must be located in the root of the project):

pytest_plugins = ("cocotb_tools._pytest.plugin",)

By defining the PYTEST_PLUGINS environment variable:

export PYTEST_PLUGINS="cocotb_tools._pytest.plugin"

By using the -p <plugin> option when invoking the pytest command line interface:

pytest -p cocotb_tools._pytest.plugin ...

Building and Testing#

cocotb_tools._pytest.hdl.HDL interfaces with the Python runners to build designs and run simulations. The Runner is fully configurable by using --cocotb-* command line arguments, configuration files like pyproject.toml or fixture arguments.

Fixtures#

`cocotb_tools._pytest.plugin.hdl`#

The plugin provides an hdl fixture that will create a new instance of HDL that can be customized and then used in tests.

An example is provided below, located in a project conftest.py file:

import pytest
from cocotb_tools._pytest.hdl import HDL


@pytest.fixture(name="sample_module")
def sample_module_fixture(hdl: HDL) -> HDL:
    """Define HDL design by adding HDL source files to it.

    Args:
        hdl: Fixture created by the cocotb pytest plugin, representing a HDL design.

    Returns:
        Representation of HDL design with added HDL source files.
    """
    hdl.sources = (
        # List HDL source files,
        "sample_module.sv",
    )

    # Build HDL design
    hdl.build()

    return hdl

Markers#

`@pytest.mark.cocotb_runner`#

The plugin provides the marker @pytest.mark.cocotb_runner that will mark test function as cocotb runner.

import pytest
from cocotb_tools._pytest.hdl import HDL


@pytest.fixture(name="sample_module")
def sample_module_fixture(hdl: HDL) -> HDL:
    """Define new HDL design by adding HDL source files to it."""
    hdl.toplevel = "sample_module"
    hdl.sources = (DESIGNS / "sample_module.sv",)
    hdl.build()

    return hdl


# Request for defined HDL design by using fixture
@pytest.mark.cocotb_runner  # needed to mark this test function as cocotb runner
def hdl_runner_1(sample_module: HDL) -> None:
    """Run HDL simulator that will execute cocotb tests."""
    sample_module.test()


@pytest.mark.cocotb_runner
@pytest.mark.cocotb_timescale(unit="1ns", precision="1ps")
def test_dut_using_different_timescale(sample_module: HDL) -> None:
    """Test DUT using different timescale."""
    sample_module.test()

If no positional arguments were provided to @pytest.mark.cocotb_runner, plugin will load current Python module where @pytest.mark.cocotb_runner was used as cocotb testbench (Python file with cocotb tests).

@pytest.mark.cocotb_runner
def test_dut_using_default_testbench(sample_module: HDL) -> None:
    """Test DUT with cocotb tests defined in the same Python file as this test function."""
    sample_module.test()


async def test_dut_feature_1(dut) -> None:
    """Test DUT feature 1."""
    ...


async def test_dut_feature_2(dut) -> None:
    """Test DUT feature 2."""
    ...

Additionally, positional arguments of @pytest.mark.cocotb_runner marker are equivalent to test_module argument from Runner.test().

@pytest.mark.cocotb_runner("test_dut_tb_1")
def test_dut_using_different_testbench(sample_module: HDL) -> None:
    """Load ``test_dut_tb_1`` Python module and run cocotb tests from there to test DUT."""
    sample_module.test()


@pytest.mark.cocotb_runner("test_dut_tb_2", "test_dut_tb_3")
def test_dut_using_different_testbenches(sample_module: HDL) -> None:
    """Load ``test_dut_tb_2`` and ``test_dut_tb_3`` Python modules and run cocotb tests from there to test DUT."""
    sample_module.test()

If toplevel argument is empty/non-set, plugin will use name of first test module but without test_* prefix or *_test suffix. For example, if test module was test_design then name of HDL top level design will be design.

# test_design.py

@pytest.mark.cocotb_runner
def test_dut_using_default_toplevel(sample_module: HDL) -> None:
    """Test DUT with default top level associated with name of test file as this test function."""
    assert hdl.toplevel == "design"
    sample_module.test()

`@pytest.mark.cocotb_test`#

The plugin provides the marker @pytest.mark.cocotb_test which allows to mark any coroutine test function as cocotb test.

@pytest.mark.cocotb_test
async def my_test_function(dut) -> None:
    """Function to test DUT feature."""
    ...

Using the @pytest.mark.cocotb_test marker is optional for test functions if they meet the following criteria:

start with test_
is a coroutine function (async def)
has a positional argument dut to use the dut fixture

async def test_dut_feature(dut) -> None:
    """Function to test DUT feature."""
    ...

Non-async functions marked with @pytest.mark.cocotb_test are control functions run by pytest. They can run simulations by invoking cocotb_tools._pytest.hdl.HDL.test() or cocotb_tools.runner.Runner.test().

import pytest
from cocotb_tools._pytest.hdl import HDL


# First, define new HDL design, add HDL source files to it and build it
@pytest.fixture(name="sample_module")
def sample_module_fixture(hdl: HDL) -> HDL:
    """Define new HDL design by adding HDL source files to it."""
    hdl.toplevel = "sample_module"
    hdl.sources = (DESIGNS / "sample_module.sv",)
    hdl.build()

    return hdl


# Request for defined HDL design by using fixture
@pytest.mark.cocotb_runner  # needed to mark this test function as cocotb runner
def hdl_runner(sample_module: HDL) -> None:
    """Run HDL simulator that will execute cocotb tests."""
    hdl.test()


async def test_something(dut) -> None:
    """Function that is picked up by pytest discovery does not need a decorator."""


@pytest.mark.cocotb_test
async def name_without_test_prefix(dut) -> None:
    """Function that is not picked up by pytest discovery needs a decorator to count as a test."""

`@pytest.mark.cocotb_timeout`#

The plugin provides the marker @pytest.mark.cocotb_timeout which allows to mark coroutine function with simulation time duration before the test is forced to fail.

@pytest.mark.cocotb_timeout(duration=200, unit="ns")
async def test_dut_feature(dut) -> None:
    """Test DUT feature that must finish before 200 nanoseconds."""
    ...

Test Discovery#

Markers can also help the plugin identify and bind cocotb tests to cocotb runners. This is done based on positional arguments supplied to the @pytest.mark.cocotb_runner decorator. Users can filter tests when invoking pytest with -k '<expression>' or -m '<markers>' options.

List tree hierarchy of cocotb tests related to cocotb runners and cocotb testbenches:

pytest --collect-only

Example output:

<Dir tests>
  <Module test_sample_module.py>
    <Function test_sample_module>
    <Runner test_sample_module>
      <Testbench test_sample_module>
        <Function test_dut_feature_1>
        <Function test_dut_feature_2>

Note

Functions which build HDL designs and run tests using the cocotb Runner are treated by the plugin as test functions. Unfortunately, pytest <Function> items cannot have other sub-items like cocotb test functions or cocotb test modules. So the plugin uses the <Runner> node to visualize relationship between the cocotb Runner (<Function>), cocotb test modules (<Testbench>) and cocotb tests (<Function>).

Run specific test(s) based on output from pytest --collect-only:

pytest -k 'test_sample_module and test_dut_feature_2'

User Fixtures#

pytest fixtures can provide useful test functionality, and can use the fixtures provided by the cocotb plugin.

Some examples include:

Automatically generate a clock.
Automatically set up (reset, configure) and tear down DUT per each test

Example clock generation for all tests using the conftest.py file:

from collections.abc import AsyncGenerator

import pytest
from cocotb.clock import Clock


@pytest.fixture(scope="session", autouse=True)
async def clock_generation(dut) -> AsyncGenerator[None, None]:
    """Generate clock for all tests using session scope."""
    # Test setup (executed before test), create and start clock generation
    dut.clk.value = 0

    Clock(dut.clk, 10, unit="ns").start(start_high=False)

    yield  # Calling test, yield is needed to keep clock generation alive

    # Test teardown (executed after test), clock generation will be finished here

Example set up and tear down fixture:

from collections.abc import AsyncGenerator

import pytest
from cocotb.triggers import FallingEdge


@pytest.fixture(autouse=True)
async def setup_sample_module(dut) -> AsyncGenerator[None, None]:
    """Set up and tear down sample module."""
    # Test setup (executed before test)
    dut.rst.value = 1
    dut.stream_in_valid.value = 0
    dut.stream_in_data.value = 0
    dut.stream_out_ready.value = 0

    for _ in range(2):
        await FallingEdge(dut.clk)

    dut.rst.value = 0

    yield  # Calling test

    # Test teardown (executed after test)
    dut.stream_in_valid.value = 0
    dut.stream_in_data.value = 0
    dut.stream_out_ready.value = 0

    await FallingEdge(dut.clk)


async def test_dut_feature_1(dut) -> None:
    """Test DUT feature 1. DUT will be always correctly reset and configured."""


async def test_dut_feature_2(dut) -> None:
    """Test DUT feature 2. DUT will be always correctly reset and configured."""

Integration#

First, you should follow the chapter about Extending Existing Build Flows to learn how to integrate cocotb into your existing build flow.

Direct Usage#

The most straightforward usage with the plugin is to directly invoke build system from a test function. Example with a custom Makefile that is defining the sample_module make recipe:

import pytest
import subprocess

@pytest.mark.cocotb_runner
def test_sample_module() -> None:
    """Build and run HDL design."""
    subprocess.run(["make", "sample_module"], check=True)

You may also consider to use command line arguments from pytest to configure build system:

import pytest
import subprocess

@pytest.mark.cocotb_runner
def test_sample_module(request: pytest.FixtureRequest) -> None:
    args: list[str] = ["make", "sample_module"]

    # Add additional arguments based on request.config.option.cocotb_* options or
    # from fixtures request.node.iter_markers() like "cocotb" marker
    if request.config.option.cocotb_verbose:
        args.append("VERBOSE=1")

    subprocess.run(args, check=True)

As Fixture#

And make it reusable for other projects/teams by packaging is as a new plugin for pytest:

import pytest
import subprocess

class MyBuildSystem:
    def __init__(self, request: pytest.FixtureRequest) -> None:
        # Handle request.config.option.cocotb_* options and fixtures request.node.iter_markers() like "cocotb" marker
        self.args: list[str] = ["make"]

    def build_and_run(self) -> None:
        # Compile HDL design and run simulator
        subprocess.run(args, check=True)


@pytest.fixture
def my_build_system(request: pytest.FixtureRequest) -> MyBuildSystem:
    return MyBuildSystem(request)

So others can use it in their projects:

import pytest
from pytest_cocotb_my_build_system import MyBuildSystem

@pytest.mark.cocotb_runner
def test_sample_module(my_build_system: MyBuildSystem) -> None:
    my_build_system.build_and_run()

By Hooks#

The most recommended way to integrate custom build flow with plugin is to implement cocotb pytest hooks defined in cocotb_tools._pytest.hookspecs.

from pathlib import Path
from cocotb_tools._pytest.hdl import HDL
from cocotb_tools.runner import Runner
from pytest import FixtureRequest, hookimpl


class MyHDL(HDL):
    def __init__(self, request: FixtureRequest) -> None:
        # Add new attributes, load HDL source files from build system, ...
        ...


class MyRunner(Runner):
    def build(self, *args, **kwargs) -> None:
        # Build HDL design by invoking existing build system
        ...

    def test(self, *args, **kwargs) -> Path:
        # Run HDL simulator by invoking existing build system
        ...


@hookimpl(tryfirst=True)
def pytest_cocotb_make_hdl(request: FixtureRequest) -> HDL:
    return MyHDL(request)


@hookimpl(tryfirst=True)
def pytest_cocotb_make_runner(simulator_name: str) -> Runner:
    return MyRunner()

Implemented hooks can be distributed as new Python package published to PyPI registry.

Consider to name published Python package with the pytest-cocotb- prefix. This will allow to automatically list your integration in the list of available pytest plugins.

Configuration#

Thanks to cocotb_tools._pytest.plugin, cocotb can be configured in many ways.

Precedence order of configuring cocotb from the highest to the lowest priority:

cocotb_tools._pytest.hdl.HDL() attributes set at fixture or test function level
@pytest.mark.cocotb_runner marker used with test functions.
--cocotb-* command line arguments when invoking them with pytest command line interface.
COCOTB_* environment variables.
cocotb_* entries defined in various configuration files like pyproject.toml file.
Default values.

All available command line arguments, configuration entries and environment variables that can be used to configure cocotb testing environment, can be listed by invoking pytest help:

pytest --help

JUnit XML Reporting#

cocotb generates a JUnit XML test report file for every regression. See JUnit Test Report for the general behavior of this file and JUnit Tests Report Reference for its schema. The notes below cover the plugin-specific knobs for controlling its output.

Output file#

Use pytest’s --junit-xml command line option to specify the output file name:

pytest --junit-xml=junit.xml

Attachments#

Setting the junit_logging pytest INI config option to system-out or all is required for attachments to be added when using the plugin.

pytest --override-ini=junit_logging=system-out --junit-xml=junit.xml ...

Relative paths#

The path hint used to convert absolute paths to relative ones (see Outputting Relative Paths) is determined from where the pytest command was invoked. Use the COCOTB_RESULTS_RELATIVE_TO environment variable when invoking pytest to override that.

COCOTB_RESULTS_RELATIVE_TO=$(pwd)/cocotb_subproject pytest --junit-xml=junit.xml ...

Under the Hood#

The cocotb_tools._pytest.plugin is split into two independent parts that complement each other.

The first part is performed when invoking the pytest from command line. This is the main process that is running in non-simulation environment. It will:

Identify and mark test function as cocotb runner or cocotb test.
Collect all tests, including cocotb runners and cocotb tests, when invoking pytest with the --collect-only option. This will allow to properly visualize relationship between cocotb runner, test module (testbench) and cocotb test in the pytest summary report about collected tests (items).
Collect all non-cocotb tests, including cocotb runners, when invoking pytest without the --collect-only option. This will allow to execute cocotb runners as test functions that will build HDL design and run simulation with cocotb tests.
Collect serialized test reports sent by cocotb tests via IPC (Inter-Process Communication) from running simulation process.

Note

Cocotb runners are treated by the plugin as test functions and they will be reported in pytest collect and test summary info. This will allow to report compilation/elaboration of HDL design and simulation runtimes.

The second part of the cocotb_tools._pytest.plugin is performed within the simulator process. It will:

Identify and mark test function as cocotb test.
Collect only cocotb tests.
Handle coroutines (asynchronous functions) for requested fixtures, test setup, test call and test teardown.
Serialize test reports and send them via IPC to the main process (non-simulation environment).

Options#

Plugin options

usage: pytest [-h] [--cocotb-summary]
              [--cocotb-sim-time-unit {step,fs,ps,ns,us,ms,sec}]
              [--cocotb-gui] [--cocotb-waves] [--cocotb-waveform-viewer NAME]
              [--cocotb-seed INTEGER] [--cocotb-attach SECONDS]
              [--cocotb-plusargs [PLUSARG ...]]
              [--cocotb-resolve-x {error,weak,zeros,ones,random}]
              [--cocotb-scheduler-debug] [--cocotb-simulator NAME]
              [--cocotb-trust-inertial-writes] [--cocotb-pytest-args ARGS]
              [--cocotb-pytest-dir PATH] [--cocotb-build-dir PATH]
              [--cocotb-defines [NAME[=VALUE] ...]]
              [--cocotb-includes [PATH ...]]
              [--cocotb-parameters [NAME[=VALUE] ...]] [--cocotb-library NAME]
              [--cocotb-always] [--cocotb-clean] [--cocotb-verbose]
              [--cocotb-timescale UNIT[/PRECISION]]
              [--cocotb-env [NAME[=VALUE] ...]]
              [--cocotb-toplevel-library NAME]
              [--cocotb-toplevel-lang {auto,verilog,vhdl}]
              [--cocotb-gpi-interfaces [NAME ...]] [--cocotb-build-args ARGS]
              [--cocotb-elab-args ARGS] [--cocotb-test-args ARGS]
              [--cocotb-pre-cmd ARGS]
              [--cocotb-log-level {trace,debug,info,warning,error,critical}]
              [--gpi-log-level {trace,debug,info,warning,error,critical}]
              [--pygpi-users [MODULE:FUNCTION ...]]

Named Arguments#

--cocotb-summary

Show cocotb test summary info.

Configuration option: cocotb_summary

Environment variable: COCOTB_SUMMARY

Default: False

--cocotb-sim-time-unit

Possible choices: step, fs, ps, ns, us, ms, sec

Simulation time unit that will be used during tests reporting.

Configuration option: cocotb_sim_time_unit

Environment variable: COCOTB_SIM_TIME_UNIT

Default: 'ns'

--cocotb-gui

Enable the GUI mode in the simulator (if supported).

Configuration option: cocotb_gui

Environment variable: COCOTB_GUI

Default: False

--cocotb-waves

Enable wave traces dump for simulator (if supported).

Configuration option: cocotb_waves

Environment variable: COCOTB_WAVES

Default: False

--cocotb-waveform-viewer

The name of the waveform viewer executable to use (like surfer) when GUI mode is enabled for simulators that do not have a built-in waveform viewer (like Verilator) The executable name will be called with the name of the waveform file as the argument.

Configuration option: cocotb_waveform_viewer

Environment variable: COCOTB_WAVEFORM_VIEWER

Default: 'surfer'

--cocotb-seed

Seed the Python random module to recreate a previous test stimulus.

Configuration option: cocotb_seed

Environment variable: COCOTB_RANDOM_SEED

Default: current epoch time in seconds

--cocotb-attach

Pause time value in seconds before the simulator start. If set to non-zero value, cocotb will print the process ID (PID) to attach to and wait the specified time in seconds before actually letting the simulator run.

Configuration option: cocotb_attach

Environment variable: COCOTB_ATTACH

Default: 0

--cocotb-plusargs

Plusargs are options that are starting with a plus (+) sign. They are passed to the simulator and are also available within cocotb as cocotb.plusargs. In the simulator, they can be read by the Verilog/SystemVerilog system functions $test$plusargs and $value$plusargs.

Configuration option: cocotb_plusargs

Environment variable: COCOTB_PLUSARGS

Default: []

--cocotb-resolve-x

Possible choices: error, weak, zeros, ones, random

Defines how to resolve bits with a value of X, Z, U, W, or - when being converted to integer. Valid settings are:

error: Resolves nothing.
weak: Resolves L to 0 and H to 1.
zeros: Like weak, but resolves all other non-0/1 values to 0.
ones: Like weak, but resolves all other non-0/1 values to 1.
random: Like weak, but resolves all other non-0/1 values randomly to either 0 or 1.

There is also a slight difference in behavior of bool(logic). When this is set, bool(logic) treats all non-0/1 values as equivalent to 0. When this is not set, bool(logic) will fail on non-0/1 values. Warning: Using this feature is not recommended.

Configuration option: cocotb_resolve_x

Environment variable: COCOTB_RESOLVE_X

--cocotb-scheduler-debug

Enable additional log output of the coroutine scheduler. This will default the value of debug, which can later be modified.

Configuration option: cocotb_scheduler_debug

Environment variable: COCOTB_SCHEDULER_DEBUG

Default: False

--cocotb-simulator

Possible choices: auto, verilator, nvc, ghdl, icarus, xcelium, vcs, questa, riviera

Select HDL simulator for cocotb. The auto option will automatically pick one of available HDL simulators where precedence order is based on available choices for this argument, from the highest priority (most left) to the lowest priority (most right).

Configuration option: cocotb_simulator

Environment variable: COCOTB_SIMULATOR

Default: 'auto'

--cocotb-trust-inertial-writes

It enables a mode which allows cocotb to trust that VPI/VHPI/FLI inertial writes are applied properly according to the respective standards. This mode can lead to noticeable performance improvements, and also includes some behavioral difference that are considered by the cocotb maintainers to be “better”. Not all simulators handle inertial writes properly, so use with caution. This is achieved by not scheduling writes to occur at the beginning of the ReadWrite mode, but instead trusting that the simulator’s inertial write mechanism is correct. This allows cocotb to avoid a VPI callback into Python to apply writes.

Configuration option: cocotb_trust_inertial_writes

Environment variable: COCOTB_TRUST_INERTIAL_WRITES

Default: False

--cocotb-pytest-args

By default, instance of pytest that is running from HDL simulator as regression manager for cocotb tests, will be called with the same command line arguments as pytest invoked by user from command line that is starting cocotb runners (HDL simulators). This option allows user to override it and pass own arguments to pytest instance that is running from HDL simulator process. For example, it can be used to set different verbosity levels or capture modes between them. Example: pytest -v --capture=no --cocotb-pytest-args='-vv --capture=fd'

Configuration option: cocotb_pytest_args

Environment variable: COCOTB_PYTEST_ARGS

Default: []

--cocotb-pytest-dir

Override path from where pytest was invoked.

Configuration option: cocotb_pytest_dir

Environment variable: COCOTB_PYTEST_DIR

Default: current working directory

--cocotb-build-dir

Directory to run the build step in.

Configuration option: cocotb_build_dir

Environment variable: COCOTB_BUILD_DIR

Default: sim_build

--cocotb-defines

Extra defines to set.

Configuration option: cocotb_defines

Environment variable: COCOTB_DEFINES

Default: []

--cocotb-includes

Extra Verilog include directories.

Configuration option: cocotb_includes

Environment variable: COCOTB_INCLUDES

Default: []

--cocotb-parameters

Extra Verilog parameters or VHDL generics.

Configuration option: cocotb_parameters

Environment variable: COCOTB_PARAMETERS

Default: []

--cocotb-library

The library name to compile into.

Configuration option: cocotb_library

Environment variable: COCOTB_LIBRARY

Default: 'top'

--cocotb-always

Always run the build step.

Configuration option: cocotb_always

Environment variable: COCOTB_ALWAYS

Default: False

--cocotb-clean

Delete build directory before building.

Configuration option: cocotb_clean

Environment variable: COCOTB_CLEAN

Default: False

--cocotb-verbose

Enable verbose messages.

Configuration option: cocotb_verbose

Environment variable: COCOTB_VERBOSE

Default: False

--cocotb-timescale

Timescale containing time unit and time precision for simulation.

Configuration option: cocotb_timescale

Environment variable: COCOTB_TIMESCALE

--cocotb-env

Extra environment variables to set.

Configuration option: cocotb_env

Environment variable: COCOTB_ENV

Default: []

--cocotb-toplevel-library

The library name for HDL toplevel module.

Configuration option: cocotb_toplevel_library

Environment variable: COCOTB_TOPLEVEL_LIBRARY

Default: 'top'

--cocotb-toplevel-lang

Possible choices: auto, verilog, vhdl

Language of the HDL toplevel module. Can be set to notify tests about preferred language in multi-language HDL design. This is also used by simulators that support more than one interface (VPI, VHPI, or FLI) to select the appropriate interface to start cocotb. When set to auto, value will be automatically evaluated based on selected HDL simulator or list of HDL source files provided during build stage in cocotb_tools._pytest.hdl.HDL.build() or cocotb_tools.runner.Runner.build() methods.

Configuration option: cocotb_toplevel_lang

Environment variable: COCOTB_TOPLEVEL_LANG

Default: 'auto'

--cocotb-gpi-interfaces

List of GPI interfaces to use, with the first one being the entry point.

Configuration option: cocotb_gpi_interfaces

Environment variable: COCOTB_GPI_INTERFACES

Default: []

--cocotb-build-args

Extra build arguments for the simulator.

Configuration option: cocotb_build_args

Environment variable: COCOTB_BUILD_ARGS

Default: []

--cocotb-elab-args

Extra elaboration arguments for the simulator.

Configuration option: cocotb_elab_args

Environment variable: COCOTB_ELAB_ARGS

Default: []

--cocotb-test-args

Extra arguments for the simulator.

Configuration option: cocotb_test_args

Environment variable: COCOTB_TEST_ARGS

Default: []

--cocotb-pre-cmd

Extra commands to run before simulation begins.

Configuration option: cocotb_pre_cmd

Environment variable: COCOTB_PRE_CMD

Default: []

--cocotb-log-level

Possible choices: trace, debug, info, warning, error, critical

The default log level of all “cocotb” Python loggers. The default is unset, which means that the log level is inherited from the root logger. This behaves similarly to logging.NOTSET.

Configuration option: cocotb_log_level

Environment variable: COCOTB_LOG_LEVEL

--gpi-log-level

Possible choices: trace, debug, info, warning, error, critical

The default log level of all “gpi” (the low-level simulator interface) loggers, including both Python and the native GPI logger. The default is unset, which means that the log level is inherited from the root logger. This behaves similarly to logging.NOTSET.

Configuration option: gpi_log_level

Environment variable: GPI_LOG_LEVEL

--pygpi-users

The Python module and callable that starts up the Python cosimulation environment. User overloads can be used to enter alternative Python frameworks or to hook existing cocotb functionality. It is formatted as path.to.entry.module:entry_point.function,other_module:other_func. The string before the colon is the Python module to import and the string following the colon is the object to call as the entry function. The entry function must be a callable matching this form: entry_function(argv: List[str]) -> None

Configuration option: pygpi_users

Environment variable: PYGPI_USERS

Default: ('cocotb_tools._coverage:start_cocotb_library_coverage,cocotb.logging:_configure,cocotb._init:init_package_from_simulation,cocotb_tools._pytest._init:run_regression',)

Pytest Plugin

Contents

Pytest Plugin#

Enabling the Plugin#

In a Python project#

In a non-Python project#

Building and Testing#

Fixtures#

cocotb_tools._pytest.plugin.hdl#

Markers#

@pytest.mark.cocotb_runner#

@pytest.mark.cocotb_test#

@pytest.mark.cocotb_timeout#

Test Discovery#

User Fixtures#

Integration#

Direct Usage#

As Fixture#

By Hooks#

Configuration#

JUnit XML Reporting#

Output file#

Attachments#

Relative paths#

Under the Hood#

Options#

Named Arguments#

`cocotb_tools._pytest.plugin.hdl`#

`@pytest.mark.cocotb_runner`#

`@pytest.mark.cocotb_test`#

`@pytest.mark.cocotb_timeout`#