What is VUnit?¶

VUnit is an open source unit testing framework for VHDL/SystemVerilog released under the terms of Mozilla Public License, v. 2.0. It features the functionality needed to realize continuous and automated testing of your HDL code. VUnit doesn’t replace but rather complements traditional testing methodologies by supporting a “test early and often” approach through automation.

VUnit reduces the overhead of testing by supporting automatic discovery of test benches and compilation order as well as including libraries for common verification tasks. It improves the speed of development by supporting incremental compilation and by enabling large test benches to be split up into smaller independent tests. It increases the quality of projects by enabling large regression suites to be run on a continuous integration server.

VUnit does not impose any specific verification methodology on its users. The benefits of VUnit can be enjoyed when writing tests first or last, when writing long running top level tests or short running unit tests, when using directed or constrained random testing. Often projects adopt mix of approaches for different testing needs. VUnit has been used in production environments where thousands of tests take several hours to run on powerful multi-core machines as well as in small open source projects where only a small package is tested in a few seconds.

Main Features¶

Scriptable API as well as command line support.
- Has --gui switch to launch test cases in the simulator GUI when debugging is necessary.
Automatic scanning of files for tests, file dependencies, and file changes enable automatic (incremental) (re)compilation and execution of test suites.
Python test suite runner that enables powerful test administration:
- Can continue testing after fatal run-time errors (e.g. division by zero).
- Ensures test case independence.
- Can run test cases in parallel to take advantage of multi-core machines.
- Support for running test benches with multiple generic/parameter settings.
- Requirements trace-ability through JSON Export and test attributes.
- Outputs JUnit report files for better Jenkins integration.
- Builds on the commonly used xUnit architecture.
Built-in HDL utility libraries:
- Run library providing functionality for declaring multiple test cases within HDL testbenches.
- Assertion checker library that extends VHDL built-in support (assert).
- Logging framework supporting display and file output, different log levels, visibility settings of levels and design hierarchy, output formatting and multiple loggers. Supports machine readable output formats that for example can be read by a spreadsheet.
  - For simulartors without VHDL 2019 call path support, an optional location preprocessor traces log and check calls back to file and line number.
- Convenient Data Types to deal with queues and/or dynamic arrays of integers in up to three dimensions.
- Communication library providing a high-level communication mechanism based on the actor model.
- Verification Components library providing verification components (VCs) for interfaces such as AXI, Avalon or Wishbone, along with utilities for writing your own self-checking VCs.
- Third-party submodules:
  - OSVVM
  - JSON-for-VHDL

Overview¶

The core of VUnit is the Python plumbing composed by the library and testbench API, the simulator interfaces and the runner for interacting with HDL testbenches. Sibling run HDL libraries allow specifying tests within testbenches.

Moreover, VUnit includes multiple optional HDL libraries, along with third-party resources such as OSVVM and JSON-for-VHDL. Those are made available through the built-ins API, which is based on the library and testbench API.

Both the core and builtins are available in the public Python Interface of VUnit. Details about how to execute a project are explained in Command Line Interface. Further info about the optional libraries is found in HDL Libraries.

Experimental co-simulation through GHDL’s VHPIDIRECT is supported in VUnit/cosim.

Getting Started¶

There are a number of ways to get started.

VUnit User Guide will guide users on how to start using the basic features of VUnit but also provides information about more specific and advanced usage.
Run Library User Guide presents the run packages.
Check Library User Guide presents the check packages.
Logging Library User Guide presents the log packages.
There are also various presentations of VUnit on YouTube. For example an introduction to unit testing (6 min) and a short introduction to VUnit (12 min).

Support¶

Any bug reports, feature requests or questions about the usage of VUnit can be made by creating a new issue.

Credits and License¶

Substantial contributors are shown in the table below, but many others contributed with minor patches. Find a list at github.com/VUnit/vunit/graphs/contributors.

With apologies to anyone who ought to be either on this table or in the GitHub contributor list, but isn’t. Thanks also to all those who have reported bugs and support issues, and often patches and testcases.

Contributor [1]	Role
Asplund, Lars [@LarsAsplund] [2]	Founder and main author of VUnit as a whole
Kraigher, Olof [@kraigher]	Founder and main author of VUnit until v4
Marquardt, Colin [@cmarqu]	Cadence Incisive support
Martinez-Corral, Unai [@umarcor] [2]	Continuous Integration (CI), Co-simulation with GHDL’s VHPIDIRECT interface (VUnit/cosim, based on ghdl/ghdl-cosim)
Siluk, Sławomir [@slaweksiluk]	Verification Components (such as Avalon and Wishbone)

The following libraries are redistributed with VUnit for convenience:

JSON-for-VHDL (vunit/vhdl/JSON-for-VHDL): these files are licensed under the terms of Apache License, v 2.0, © 2015 - 2022 Patrick Lehmann.

The font used in VUnit’s logo and illustrations is ‘Tratex’, the traffic sign typeface used on swedish road signs: