vunit.ui

class vunit.ui.VUnit

The public interface of VUnit

Example

from vunit import VUnit
add_array_util()

Add array util

add_com()

Add communication package

add_compile_option(name: str, value: str, allow_empty: Optional[bool] = False)

Add compile option to all files

Parameters
  • name – The name of the compile option (See Compilation options)

  • value – The value of the compile option

  • allow_empty – To disable an error when no source files were found

Note

Only affects files added before the option is set.

add_external_library(library_name, path: Union[str, pathlib.Path], vhdl_standard: Optional[str] = None)

Add an externally compiled library as a black-box

Parameters
  • library_name – The name of the external library

  • path – The path to the external library directory

  • vhdl_standard – The VHDL standard used to compile files, if None the VUNIT_VHDL_STANDARD environment variable is used

Returns

The created Library object

Example

prj.add_external_library("unisim", "path/to/unisim/")
add_json4vhdl()

Add JSON-for-VHDL library

add_library(library_name: str, vhdl_standard: Optional[str] = None, allow_duplicate: Optional[bool] = False)

Add a library managed by VUnit.

Parameters
  • library_name – The name of the library

  • vhdl_standard – The VHDL standard used to compile files, if None the VUNIT_VHDL_STANDARD environment variable is used

  • allow_duplicate – Set to True to allow the same library to be added multiple times. Subsequent additions will just return the previously created library.

Returns

The created Library object

Example

library = prj.add_library("lib")
add_osvvm()

Add osvvm library

add_random()

Add random

add_source_file(file_name: Union[str, pathlib.Path], library_name: str, preprocessors=None, include_dirs=None, defines=None, vhdl_standard: Optional[str] = None, no_parse: Optional[bool] = False, file_type=None)

Add source file to library

Parameters
  • file_name – The name of the file

  • library_name – The name of the library to add the file into

  • include_dirs – A list of include directories

  • defines – A dictionary containing Verilog defines to be set

  • vhdl_standard – The VHDL standard used to compile this file, if None VUNIT_VHDL_STANDARD environment variable is used

  • no_parse – Do not parse file for dependency or test scanning purposes

  • file_type – The type of the file; "vhdl", "verilog" or "systemverilog". Auto-detected by default when set to None.

Returns

The SourceFile which was added

Example

prj.add_source_file("file.vhd", "lib")
add_source_files(pattern, library_name: str, preprocessors=None, include_dirs=None, defines=None, allow_empty: Optional[bool] = False, vhdl_standard: Optional[str] = None, no_parse: Optional[bool] = False, file_type=None)

Add source files matching wildcard pattern to library

Parameters
  • pattern – A wildcard pattern matching the files to add or a list of files

  • library_name – The name of the library to add files into

  • include_dirs – A list of include directories

  • defines – A dictionary containing Verilog defines to be set

  • allow_empty – To disable an error if no files matched the pattern

  • vhdl_standard – The VHDL standard used to compile files, if None VUNIT_VHDL_STANDARD environment variable is used

  • no_parse – Do not parse file(s) for dependency or test scanning purposes

  • file_type – The type of the file; "vhdl", "verilog" or "systemverilog". Auto-detected by default when set to None.

Returns

A list of files (SourceFileList) which were added

Example

prj.add_source_files("*.vhd", "lib")
add_source_files_from_csv(project_csv_path: Union[str, pathlib.Path], vhdl_standard: Optional[str] = None)

Add a project configuration, mapping all the libraries and files

Parameters
  • project_csv_path – path to csv project specification, each line contains the name of the library and the path to one file ‘lib_name,filename’ note that all filenames are relative to the parent folder of the csv file

  • vhdl_standard – The VHDL standard used to compile files, if None, the VUNIT_VHDL_STANDARD environment variable is used

Returns

A list of files (:class .SourceFileList) that were added

add_verification_components()

Add verification component library

enable_check_preprocessing()

Inserts error context information into VUnit check_relation calls

enable_location_preprocessing(additional_subprograms=None, exclude_subprograms=None)

Inserts file name and line number information into VUnit check and log subprograms calls. Custom subprograms can also be added. Must be called before adding any files.

Parameters
  • additional_subprograms – List of custom subprograms to add the line_num and file_name parameters to.

  • exclude_subprograms – List of VUnit subprograms to exclude from location preprocessing. Used to avoid location preprocessing of other functions sharing name with a VUnit log or check subprogram.

Example

prj.enable_location_preprocessing(additional_subprograms=['my_check'],
                                  exclude_subprograms=['log'])
classmethod from_args(args, compile_builtins: Optional[bool] = True, vhdl_standard: Optional[str] = None)

Create VUnit instance from args namespace. Intended for users who adds custom command line options. See vunit.vunit_cli.VUnitCLI class to learn about adding custom command line options.

Parameters
  • args – The parsed argument namespace object

  • compile_builtins – Do not compile builtins. Used for VUnit internal testing.

  • vhdl_standard – The VHDL standard used to compile files, if None the VUNIT_VHDL_STANDARD environment variable is used

Returns

A VUnit object instance

classmethod from_argv(argv=None, compile_builtins: Optional[bool] = True, vhdl_standard: Optional[str] = None)

Create VUnit instance from command line arguments.

Parameters
  • argv – Use explicit argv instead of actual command line argument

  • compile_builtins – Do not compile builtins. Used for VUnit internal testing.

  • vhdl_standard – The VHDL standard used to compile files, if None the VUNIT_VHDL_STANDARD environment variable is used

Returns

A VUnit object instance

Example

from vunit import VUnit
prj = VUnit.from_argv()
get_compile_order(source_files=None)

Get the compile order of all or specific source files and their dependencies.

A dependency of file A in terms of compile order is any file B which must be successfully compiled before A can be successfully compiled.

This is not the same as all files required to successfully elaborate A. For example using component instantiation in VHDL there is no compile order dependency but the component instance will not elaborate if there is no binding component.

Parameters

source_files – A list of SourceFile objects or None meaing all

Returns

A list of SourceFile objects in compile order.

get_implementation_subset(source_files)

Get the subset of files which are required to successfully elaborate the list of input files without any missing dependencies.

Parameters

source_files – A list of SourceFile objects

Returns

A list of SourceFile objects which is the implementation subset.

get_simulator_name()

Get the name of the simulator used.

Will return None if no simulator was found.

get_source_file(file_name: Union[str, pathlib.Path], library_name: Optional[str] = None)

Get a source file

Parameters
  • file_name – The name of the file as a relative or absolute path

  • library_name – The name of a specific library to search if not all libraries

Returns

A SourceFile object

get_source_files(pattern='*', library_name: Optional[str] = None, allow_empty: Optional[bool] = False)

Get a list of source files

Parameters
  • pattern – A wildcard pattern matching either an absolute or relative path

  • library_name – The name of a specific library to search if not all libraries

  • allow_empty – To disable an error if no files matched the pattern

Returns

A SourceFileList object

library(library_name: str)

Get a library

Parameters

library_name – The name of the library

Returns

A Library object

main(post_run=None)

Run vunit main function and exit

Parameters

post_run – A callback function which is called after running tests. The function must accept a single results argument which is an instance of Results

set_attribute(name: str, value: str, allow_empty: Optional[bool] = False)

Set a value of attribute in all configurations

Parameters
  • name – The name of the attribute

  • value – The value of the attribute

  • allow_empty – To disable an error when no test benches were found

Example

prj.set_attribute(".foo", "bar")

Note

Only affects test benches added before the attribute is set.

set_compile_option(name: str, value: str, allow_empty: Optional[bool] = False)

Set compile option of all files

Parameters
  • name – The name of the compile option (See Compilation options)

  • value – The value of the compile option

  • allow_empty – To disable an error when no source files were found

Example

prj.set_compile_option("ghdl.a_flags", ["--no-vital-checks"])

Note

Only affects files added before the option is set.

set_generic(name: str, value: str, allow_empty: Optional[bool] = False)

Set a value of generic in all configurations

Parameters
  • name – The name of the generic

  • value – The value of the generic

  • allow_empty – To disable an error when no test benches were found

Example

prj.set_generic("data_width", 16)

Note

Only affects test benches added before the generic is set.

set_parameter(name: str, value: str, allow_empty: Optional[bool] = False)

Set value of parameter in all configurations

Parameters
  • name – The name of the parameter

  • value – The value of the parameter

  • allow_empty – To disable an error when no test benches were found

Example

prj.set_parameter("data_width", 16)

Note

Only affects test benches added before the parameter is set.

set_sim_option(name: str, value: str, allow_empty: Optional[bool] = False, overwrite: Optional[bool] = True)

Set simulation option in all configurations

Parameters
  • name – The name of the simulation option (See Simulation options)

  • value – The value of the simulation option

  • allow_empty – To disable an error when no test benches were found

  • overwrite – To overwrite the option or append to the existing value

Example

prj.set_sim_option("ghdl.a_flags", ["--no-vital-checks"])

Note

Only affects test benches added before the option is set.

simulator_supports_coverage()

Returns True when the simulator supports coverage

Will return None if no simulator was found.

Library

class vunit.ui.library.Library

User interface of a library

add_compile_option(name, value, allow_empty=False)

Add compile option to all files within the library

Parameters
  • name – The name of the compile option (See Compilation options)

  • value – The value of the compile option

  • allow_empty – To disable an error when no source files were found

Note

Only affects files added before the option is set.

add_source_file(file_name, preprocessors=None, include_dirs=None, defines=None, vhdl_standard: Optional[str] = None, no_parse=False, file_type=None)

Add source file to library

Parameters
  • file_name – The name of the file

  • include_dirs – A list of include directories

  • defines – A dictionary containing Verilog defines to be set

  • vhdl_standard – The VHDL standard used to compile this file, if None library default is used

  • no_parse – Do not parse file for dependency or test scanning purposes

  • file_type – The type of the file; "vhdl", "verilog" or "systemverilog". Auto-detected by default when set to None.

Returns

The SourceFile which was added

Example

library.add_source_file("file.vhd")
add_source_files(pattern, preprocessors=None, include_dirs=None, defines=None, allow_empty=False, vhdl_standard: Optional[str] = None, no_parse=False, file_type=None)

Add source files matching wildcard pattern to library

Parameters
  • pattern – A wildcard pattern match the files to add

  • include_dirs – A list of include directories

  • defines – A dictionary containing Verilog defines to be set

  • allow_empty – To disable an error if no files matched the pattern

  • vhdl_standard – The VHDL standard used to compile files, if None library default is used

  • no_parse – Do not parse file(s) for dependency or test scanning purposes

  • file_type – The type of the file; "vhdl", "verilog" or "systemverilog". Auto-detected by default when set to None.

Returns

A list of files (SourceFileList) which were added

Example

library.add_source_files("*.vhd")
entity(name)

Get a test bench within this library

Parameters

name – The name of the test bench entity

Returns

A TestBench object

Raises

KeyError

get_entity(name)

Get an entity within the library

get_source_file(file_name)

Get a source file within this library

Parameters

file_name – The name of the file as a relative or absolute path

Returns

A SourceFile object

get_source_files(pattern='*', allow_empty=False)

Get a list of source files within this libary

Parameters
  • pattern – A wildcard pattern matching either an absolute or relative path

  • allow_empty – To disable an error if no files matched the pattern

Returns

A SourceFileList object

get_test_benches(pattern='*', allow_empty=False)

Get a list of test benches

Parameters
  • pattern – A wildcard pattern matching the test_bench name

  • allow_empty – To disable an error when no test benches were found

Returns

A list of TestBench objects

module(name)

Get a module within the library

Parameters

name – The name of the module

Returns

A TestBench object

Raises

KeyError

property name

The name of the library

set_compile_option(name, value, allow_empty=False)

Set compile option for all files within the library

Parameters
  • name – The name of the compile option (See Compilation options)

  • value – The value of the compile option

  • allow_empty – To disable an error when no source files were found

Example

lib.set_compile_option("ghdl.a_flags", ["--no-vital-checks"])

Note

Only affects files added before the option is set.

set_generic(name, value, allow_empty=False)

Set a value of generic within all configurations of test benches and tests this library

Parameters
  • name – The name of the generic

  • value – The value of the generic

  • allow_empty – To disable an error when no test benches were found

Example

lib.set_generic("data_width", 16)

Note

Only affects test benches added before the generic is set.

set_parameter(name, value, allow_empty=False)

Set a value of parameter within all configurations of test benches and tests this library

Parameters
  • name – The name of the parameter

  • value – The value of the parameter

  • allow_empty – To disable an error when no test benches were found

Example

lib.set_parameter("data_width", 16)

Note

Only affects test benches added before the parameter is set.

set_sim_option(name, value, allow_empty=False, overwrite=True)

Set simulation option within all configurations of test benches and tests this library

Parameters
  • name – The name of the simulation option (See Simulation options)

  • value – The value of the simulation option

  • allow_empty – To disable an error when no test benches were found

  • overwrite – To overwrite the option or append to the existing value

Example

lib.set_sim_option("ghdl.a_flags", ["--no-vital-checks"])

Note

Only affects test benches added before the option is set.

test_bench(name)

Get a test bench within this library

Parameters

name – The name of the test bench

Returns

A TestBench object

Raises

KeyError

SourceFileList

class vunit.ui.source.SourceFileList

A list of SourceFile

add_compile_option(name, value)

Add compile option to all files in the list

Parameters
  • name – The name of the compile option (See Compilation options)

  • value – The value of the compile option

add_dependency_on(source_file)

Add manual dependency of these files on other file(s)

Parameters

source_file – The file(s) which this file depends on

Example

other_file = lib.get_source_file("other_file.vhd")
files.add_dependency_on(other_file)
set_compile_option(name, value)

Set compile option for all files in the list

Parameters
  • name – The name of the compile option (See Compilation options)

  • value – The value of the compile option

Example

files.set_compile_option("ghdl.a_flags", ["--no-vital-checks"])

SourceFile

class vunit.ui.source.SourceFile

A single file

add_compile_option(name, value)

Add compile option to this file

Parameters
  • name – The name of the compile option (See Compilation options)

  • value – The value of the compile option

add_dependency_on(source_file)

Add manual dependency of this file other file(s)

Parameters

source_file – The file(s) which this file depends on

Example

other_files = lib.get_source_files("*.vhd")
my_file.add_dependency_on(other_files)
get_compile_option(name)

Return compile option of this file

Parameters

name – The name of the compile option (See Compilation options)

property library

The library of the source file

property name

The name of the SourceFile

set_compile_option(name, value)

Set compile option for this file

Parameters
  • name – The name of the compile option (See Compilation options)

  • value – The value of the compile option

Example

my_file.set_compile_option("ghdl.a_flags", ["--no-vital-checks"])
property vhdl_standard

The VHDL standard applicable to the file, None if not a VHDL file

TestBench

class vunit.ui.testbench.TestBench

User interface of a test bench. A test bench consists of one or more Test cases. Setting options for a test bench will apply that option all test cases belonging to that test bench.

add_config(name, generics=None, parameters=None, pre_config=None, post_check=None, sim_options=None, attributes=None)

Add a configuration of this test bench or to all test cases within it by copying the default configuration.

Multiple configuration may be added one after another. If no configurations are added the default configuration is used.

Parameters
  • name – The name of the configuration. Will be added as a suffix on the test name

  • generics – A dict containing the generics to be set in addition to the default configuration

  • parameters – A dict containing the parameters to be set in addition to the default configuration

  • pre_config – A callback function to be called before test execution.

  • post_check – A callback function to be called after test execution.

  • sim_options – A dict containing the sim_options to be set in addition to the default configuration

  • attributes – A dict containing the attributes to be set in addition to the default configuration

Example

Given a test bench that by default gives rise to the test lib.test_bench and the following add_config calls:

for data_width in range(14, 15+1):
    for sign in [False, True]:
        test_bench.add_config(
            name="data_width=%s,sign=%s" % (data_width, sign),
            generics=dict(data_width=data_width, sign=sign))

The following tests will be created:

  • lib.test_bench.data_width=14,sign=False

  • lib.test_bench.data_width=14,sign=True

  • lib.test_bench.data_width=15,sign=False

  • lib.test_bench.data_width=15,sign=True

get_tests(pattern='*')

Get a list of tests

Parameters

pattern – A wildcard pattern matching the test name

Returns

A list of Test objects

property library
Returns

The library that contains this test bench

property name
Returns

The entity or module name of the test bench

scan_tests_from_file(file_name)

Scan tests from another file than the one containg the test bench. Useful for when the top level test bench does not contain the tests.

Such a structure is not the preferred way of doing things in VUnit but this method exists to accommodate legacy needs.

Parameters

file_name – The name of another file to scan for tests

Warning

The nested module containing the tests needs to be given the runner_cfg parameter or generic by the instantiating top level test bench. The nested module should not call its parameter or generic runner_cfg but rather nested_runner_cfg to avoid the VUnit test scanner detecting and running it as a test bench. In SystemVerilog the NESTED_TEST_SUITE macro should be used instead of the TEST_SUITE macro.

set_attribute(name, value)

Set a value of attribute within all configurations of this test bench or test cases within it

Parameters
  • name – The name of the attribute

  • value – The value of the atrribute

Example

test_bench.set_attribute(".foo", "bar")
set_generic(name, value)

Set a value of generic within all configurations of this test bench or test cases within it

Parameters
  • name – The name of the generic

  • value – The value of the generic

Example

test_bench.set_generic("data_width", 16)
set_parameter(name, value)

Set a value of parameter within all configurations of this test bench or test cases within it

Parameters
  • name – The name of the parameter

  • value – The value of the parameter

Example

test_bench.set_parameter("data_width", 16)
set_post_check(value)

Set post_check function of all configurations of this test bench or test cases within it

Parameters

value – The post_check function

set_pre_config(value)

Set pre_config function of all configurations of this test bench or test cases within it

Parameters

value – The pre_config function

set_sim_option(name, value, overwrite=True)

Set simulation option within all configurations of this test bench or test cases within it

Parameters
  • name – The name of the simulation option (See Simulation options)

  • value – The value of the simulation option

  • overwrite – To overwrite the option or append to the existing value

Example

test_bench.set_sim_option("ghdl.a_flags", ["--no-vital-checks"])
test(name)

Get a test within this test bench

Parameters

name – The name of the test

Returns

A Test object

Test

class vunit.ui.test.Test

User interface of a single test case

add_config(name, generics=None, parameters=None, pre_config=None, post_check=None, sim_options=None, attributes=None)

Add a configuration to this test copying the default configuration.

Multiple configuration may be added one after another. If no configurations are added the default configuration is used.

Parameters
  • name – The name of the configuration. Will be added as a suffix on the test name

  • generics – A dict containing the generics to be set in addition to the default configuration.

  • parameters – A dict containing the parameters to be set in addition to the default configuration.

  • pre_config – A callback function to be called before test execution.

  • post_check – A callback function to be called after test execution.

  • sim_options – A dict containing the sim_options to be set in addition to the default configuration.

  • attributes – A dict containing the attributes to be set in addition to the default configuration.

Example

Given the lib.test_bench.test test and the following add_config calls:

for data_width in range(14, 15+1):
    for sign in [False, True]:
        test.add_config(
            name="data_width=%s,sign=%s" % (data_width, sign),
            generics=dict(data_width=data_width, sign=sign))

The following tests will be created:

  • lib.test_bench.data_width=14,sign=False.test

  • lib.test_bench.data_width=14,sign=True.test

  • lib.test_bench.data_width=15,sign=False.test

  • lib.test_bench.data_width=15,sign=True.test

property name
Returns

the entity or module name of the test bench

set_attribute(name, value)

Set a value of attribute within all configurations of this test

Parameters
  • name – The name of the attribute

  • value – The value of the attribute

Example

test.set_attribute(".foo", "bar")
set_generic(name, value)

Set a value of generic within all configurations of this test

Parameters
  • name – The name of the generic

  • value – The value of the generic

Example

test.set_generic("data_width", 16)
set_parameter(name, value)

Set a value of parameter within all configurations of this test

Parameters
  • name – The name of the parameter

  • value – The value of the parameter

Example

test.set_parameter("data_width", 16)
set_post_check(value)

Set post_check function of all configurations of this test

Parameters

value – The post_check function

set_pre_config(value)

Set pre_config function of all configurations of this test

Parameters

value – The pre_config function

set_sim_option(name, value, overwrite=True)

Set simulation option within all configurations of this test

Parameters
  • name – The name of the simulation option (See Simulation options)

  • value – The value of the simulation option

  • overwrite – To overwrite the option or append to the existing value

Example

test.set_sim_option("ghdl.a_flags", ["--no-vital-checks"])

Results

class vunit.ui.results.Results

Gives access to results after running tests

get_report()

Get a report (dictionary) of tests: status, time and output path

Returns

A Report object

merge_coverage(file_name, args=None)

Create a merged coverage report from the individual coverage files

Parameters
  • file_name – The resulting coverage file name.

  • args – The tool arguments for the merge command. Should be a list of strings.

class vunit.ui.results.Report

Gives access to test results and paths after running tests

Data output_path

Absolute path to the output path (see Command Line Interface)

Data tests

Dictionary of TestResult objects

class vunit.ui.results.TestResult

Gives access to a subset of the results of a test

Data status

Result status (passed, failed or skipped)

Data time

Simulation time

Data path

Absolute path of the test output

Example

def post_func(results):
    report = results.get_report()
    print(report.output_path)
    for key, test in report.tests.items():
        print(key)
        print(test.status)
        print(test.time)
        print(test.path)
        print(test.relpath)

vu.main(post_run=post_func)
property relpath

If the path is a subdir to the default TEST_OUTPUT_PATH, return the subdir only