cocotb 2.1.dev49+r621cba2c (2026-06-15)

Features

• Support null-ranged arrays (including std_logic_vector and string) in VHDL. (#4519)

• Added @cocotb.xfail to mark a test as expected to fail with an optional reason and expected exception type. (#5007)

• Added @cocotb.skipif to mark a test as conditionally skipped, with an optional reason string. (#5007)

• Made @cocotb.test and @cocotb.parametrize stackable. Applying the decorator multiple times to the same test will combine the values of each decoration into a single test generation. (#5007)

• Add support for Python 3.14. (#5057)

• Added cwd argument to Runner.build(). (#5076)

• Added the Pytest Plugin that enables using pytest as the regression manager for running cocotb tests. (#5090)

• Added COCOTB_RANDOM_TEST_ORDER environment variables to enable randomized ordering of cocotb tests within each stage. (#5106)

• Added support for SAIF tracing when using Verilator>=5.042 as the simulator. This is enabled by adding --trace-saif to EXTRA_ARGS (when using Makefiles) or to build_args (when using the runner). (#5114)

• Added GPI_DEBUG and PYGPI_DEBUG environment variables to enable additional debug features, including TRACE log messages. (#5131)

• Added cocotb.triggers.TaskManager for managing multiple concurrent tasks with automatic cleanup on completion or error. (#5163)

• Added cocotb.triggers.gather() to wait for multiple awaitables concurrently and collect all results. (#5165)

• Added cocotb.triggers.wait() for waiting on multiple awaitables concurrently with a configurable return condition. (#5165)

• Added cocotb.triggers.select() to wait for multiple awaitables concurrently and return the first one to complete. (#5165)

• LogicArrayObject now supports indexing single elements. (#5179)

• Add support for pre_cmd argument to Runner.test() for Aldec Riviera-Pro. (#5181)

• Add support for gui argument to Runner.test() for Aldec Riviera-Pro. (#5182)

• with_timeout() now supports being passed any awaitable. (#5205)

• Added the COCOTB_RESULTS_ATTACHMENTS environment variable that allows to attach files as attachments in generated reports like JUnit Test Report. (#5219)

• Added the COCOTB_RESULTS_RELATIVE_TO environment variable as a hint for JUnit Test Report how to convert absolute paths to relative ones. (#5219)

• Generated log and waveform files from simulators will be attached in created JUnit XML tests results file. (#5219)

• Added support for using underscores (_) as visual separators in str values used to set the value of LogicArrayObject to enhance readability of long bitstrings, e.g. dut.signal.value = "1010_1101". (#5220)

• Added visual separator support to LogicArray string construction. This allows underscores (_) to be used to improve readability of long bitstrings, e.g. "1010_1101". (#5220)

• Added the on_overflow parameter to LogicArray.from_unsigned() and LogicArray.from_signed() to allow the user to decide how to handle values which are too large to fit in range. (#5222)

• Added support for constructing LogicArray from a negative integer. This assumes two’s complement representation. (#5293)

• Added support for comparing LogicArray with negative integers. This assumes two’s complement representation. (#5293)

• Added support for terminating a regression early when the number of test failures reaches COCOTB_MAX_FAILURES. (#5309)

• Added support for pytest.RaisesExc and pytest.RaisesGroup as raises argument to cocotb.xfail(). (#5357)

• Added COCOTB_LIST_TESTS environment variable to list tests without running them. (#5366)

• Added support for pytest.skip() and pytest.xfail() for ending the test early. (#5380)

• Added cocotb.end_test() to end the test immediately from any Task without forcing a pass. (#5392)

• Added public variable cocotb_tools.runner.SUPPORTED_RUNNERS, allowing external libraries to register additional simulators for the get_runner() function. (#5415)

• Add ability to specify a particular architecture for a toplevel entity when using NVC. (#5450)

• Added support for RisingEdge and FallingEdge for instances of LogicArrayObject with only one bit. (#5483)

• Add support for SIM_CMD_PREFIX and SIM_CMD_SUFFIX environment variables to the Python Runners. (#5506)

• Added the as_vhdl_literal() and as_sv_literal() functions to explicitly convert Python values to VHDL or SystemVerilog literal strings. (#5534)

Bugfixes

• Improve VsimSA simulator support (adds Active-HDL support and updates Riviera-Pro support). (#5041)

• Generated JUnit XML tests results file is now compatible with Jenkins xUnit schema version 2. (#5219)

• cocotb.logging.default_config() no longer overwrites root handlers, but configures formatting on whatever handlers are already registered. (#5248)

• Fixed bug where COCOTB_RESOLVE_X when set "random" would resolve all non-0/1 values in a vector to the same value. (#5306)

• Fixed use-after-free in VpiSignalObjHdl::register_value_change_callback error handling code which caused VCS to segfault. (#5439)

• Fixed a segmentation fault on Icarus Verilog when VPI callbacks fired after the Python interpreter was finalized during simulator shutdown. (#5440)

• Fixed memory leak of one-shot callback on VCS/Xcelium. (#5447)

• Fixed LogicArray equality against list and tuple values containing unsupported object types. (#5596)

• Fixed a performance regression where the time to remove a completed Task scaled linearly with the number of concurrently running tasks. (#5603)

Deprecations and Removals

• Dropped support for MacOS 13 (Ventura). (#4986)

• Removed Windows and Linux 32-bit release builds. (#4986)

• Support for Python 3.6, 3.7, and 3.8 was removed. (#4987)

• Deprecated passing Tasks to First and Combine in favor of passing coroutines directly to select() and gather(), respectively. (#5206)

• Removed support for undocumented COCOTB_RESULT_TESTPACKAGE environment variable. The XML attribute package is invalid in JUnit XML. (#5219)

• Removed support for undocumented COCOTB_RESULT_TESTSUITE environment variable. Name of test suite will be based on name of the cocotb test module. (#5219)

• Deprecated cocotb.pass_test(). Instead, use cocotb.skip() to skip a test or use cocotb.end_test() to end a test while respecting expected failures. (#5395)

• Removed the cocotb_tools.config.lib_name() function. (#5516)

• Removed the --lib-name option from the cocotb-config script. (#5516)

Changes

• Reimplemented the scheduler. Exact scheduling order may have changed. (#4717)

• Changed Task.cancel() to throw RuntimeError if attempting to cancel the currently running task. (#5162)

• The LIBPYTHON_LOC environment variable was removed from the GPI. Instead, libpython should be included in GPI_USERS. Support remains in Makefiles (LIBPYTHON_LOC) and Python Runner (LIBPYTHON_LOC) for backwards-compatibility. In this case the value of LIBPYTHON_LOC is included in the generated GPI_USERS if and only if GPI_USERS is not already defined. (#5207)

• Tests reported in generated JUnit XML tests results file will be grouped into test suites by cocotb test module. (#5219)

• Added environment variable type information to all documented environment variables. (#5232)

• Entry points listed in PYGPI_USERS are no longer passed the argv object. If you need access to command-line arguments, use cocotb.simulator.get_simulator_args() instead. (#5258)

• Changed input value checking on IntegerObject and EnumObject to reflect the size and signedness of the underlying HDL type. Previously, both classes would accept negative values even if the underlying type was unsigned, and had a hardcoded and incorrect limit on the size of the value size that didn’t reflect the size of the underlying HDL type. (#5263)

• Split the random number generator (RNG) for the COCOTB_RESOLVE_X "random" mode from the global Python RNG, so that switching from one COCOTB_RESOLVE_X mode to another would not affect the random number sequence of the rest of the testbench. (#5306)

• pytest is no longer an optional dependency, but is required. (#5363)

• The Makefile target sim no longer recursively calls make. This makes it possible to use += with Make variables without the right hand side being added twice. (#5382)

• Changed the extension on the Icarus GPI implementation library from .vpl to the normal extension for shared libraries on the platform (e.g. .so or .dll). (#5516)

• Removed implicit conversion of defines in Runner.build to literals. If users need to convert Python objects to literals for use in defines or parameters, they must explicitly call the new as_vhdl_literal() or as_sv_literal() functions. (#5534)

• Makefile simulator recipes now use a shared COCOTB_ENV variable defined in Makefile.inc. (#5565)