Plugin reference

CLI options

All options belong to the cocotb option group.

Flag	Default	Description
--simulator	$SIM or verilator	Simulator name
--hdl-toplevel	$HDL_TOPLEVEL	HDL top-level module name
--hdl-library	top	HDL library name
--sources	[]	HDL source files (repeatable)
--filelist	None	Path to .f filelist; resolved to absolute and passed as -f <path> to the simulator
--includes	[]	Include directories (repeatable)
--defines NAME VALUE	[]	Preprocessor defines as name/value pairs (repeatable)
--build-args	[]	Extra build arguments, shlex-split (repeatable)
--parameters NAME VALUE	[]	HDL parameters as name/value pairs (repeatable); passed to runner.build(parameters={...})
--waves	False	Enable waveform capture
--clean	False	Force clean rebuild
--sim-build	sim_build	Base output directory
--regress	False	Create a timestamped subdirectory for this run (useful for regression tracking)
--modules	[]	Environment modules to load before simulation (repeatable; see HPC support)

Fixtures

testrun_uid (session)

Timestamp string (YYYYMMDD_HHMMSS) identifying this pytest invocation.

sim_build_dir (session)

Path to the base output directory for this run. When --regress is passed this is <sim-build>/<testrun_uid>/; otherwise it is simply <sim-build>/.

build_dir (session)

Path to the compiled HDL directory. Defaults to <sim_build_dir>/build/. When --waves is enabled a separate build_waves/ directory is used instead, so that wave-enabled and non-wave builds do not clobber each other.

runner (session)

The cocotb runner instance. Compiles the HDL design once per session using cocotb_tools.runner.get_runner(). When pytest output capture is active, build output is redirected to build_dir/build.log.

test_session (function)

A TestSession bound to a unique per-test directory.

TestSession API

@dataclass
class TestSession:
    runner: object
    directory: Path
    hdl_toplevel: str
    test_module: str
    waves: bool = False
    log_file: Path | None = None

run(**kwargs) -> Path

Delegates to runner.test() with sensible defaults derived from the dataclass fields. Any keyword argument accepted by runner.test() can be passed to override the defaults (e.g. test_module, waves).

run() may only be called once per TestSession instance; a second call raises RuntimeError.

When pytest output capture is active (the default), the log_file field is automatically set to <test_dir>/sim.log so that simulator output is captured to a file instead of being printed to stdout.

class pytest_cocotb.session.TestSession(runner: object, directory: pathlib.Path, hdl_toplevel: str, test_module: str, waves: bool = False, log_file: pathlib.Path | None = None, hdl_toplevel_lang: str | None = None, verbose: bool = False, gui: bool = False, test_args: list[str] = <factory>, plusargs: list[str] = <factory>, extra_env: dict[str, str] = <factory>, seed: str | int | None = None, testcase: str | None = None, test_filter: str | None = None, results_xml: str | None = None, _has_run: bool = False)

run(**kwargs) → Path

Run cocotb test(s) in the simulator. Delegates to runner.test().

Build behaviour

• The runner fixture compiles HDL once at session scope.

• Subsequent tests reuse the compiled build in build_dir.

• When --waves is enabled the build is placed in build_waves/ instead of build/, so you can switch between wave and non-wave runs without forcing a rebuild.

• Pass --clean to force a full rebuild.

Output directory layout

Without ``–regress`` (default):

sim_build/
├── build/                                      # compiled HDL (build_dir)
├── test_counter__test_counter_basic/
│   ├── sim.log                                  # simulator stdout
│   └── ...                                      # simulator output
└── ...

With ``–regress``:

sim_build/
└── 20250101_120000/                             # testrun_uid
    ├── build/                                    # compiled HDL (build_dir)
    ├── test_counter__test_counter_basic/
    │   ├── sim.log
    │   └── ...
    └── ...