Python Interface

The Python interface of VUnit is exposed through the VUnit class that can be imported directly from the vunit module.

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, value, allow_empty=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, vhdl_standard=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 into this library, 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, vhdl_standard=None, allow_duplicate=False)

Add a library managed by VUnit.

Parameters
  • library_name – The name of the library

  • vhdl_standard – The VHDL standard used to compile files into this library, 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, library_name, preprocessors=None, include_dirs=None, defines=None, vhdl_standard=None, no_parse=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, preprocessors=None, include_dirs=None, defines=None, allow_empty=False, vhdl_standard=None, no_parse=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 these 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, vhdl_standard=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 file into this library, 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=True, vhdl_standard=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.

Returns

A VUnit object instance

classmethod from_argv(argv=None, compile_builtins=True, vhdl_standard=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.

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_source_file(file_name, library_name=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=None, allow_empty=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)

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, value, allow_empty=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, value, allow_empty=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.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 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, value, allow_empty=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, value, allow_empty=False, overwrite=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.flags", ["--no-vital-checks"])

Note

Only affects test benches added before the option is set.

class vunit.ui.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=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=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 these 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 an entity within the library

Parameters

name – The name of the entity

Returns

A TestBench object

Raises

KeyError

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.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.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

class vunit.ui.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.flags", ["--no-vital-checks"])
class vunit.ui.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.flags", ["--no-vital-checks"])
property vhdl_standard

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

class vunit.ui.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.flags", ["--no-vital-checks"])
test(name)

Get a test within this test bench

Parameters

name – The name of the test

Returns

A Test object

class vunit.ui.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.flags", ["--no-vital-checks"])
class vunit.ui.Results

Gives access to results after running tests.

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.

Compilation Options

Compilation options allow customization of compilation behavior. Since simulators have differing options available, generic options may be specified through this interface. The following compilation options are known.

ghdl.flags

Extra arguments passed to ghdl -a command during compilation. Must be a list of strings.

incisive.irun_vhdl_flags

Extra arguments passed to the Incisive irun command when compiling VHDL files. Must be a list of strings.

incisive.irun_verilog_flags

Extra arguments passed to the Incisive irun command when compiling Verilog files. Must be a list of strings.

modelsim.vcom_flags

Extra arguments passed to ModelSim vcom command. Must be a list of strings.

modelsim.vlog_flags

Extra arguments passed to ModelSim vlog command. Must be a list of strings.

rivierapro.vcom_flags

Extra arguments passed to Riviera PRO vcom command. Must be a list of strings.

rivierapro.vlog_flags

Extra arguments passed to Riviera PRO vlog command. Must be a list of strings.

activehdl.vcom_flags

Extra arguments passed to Active HDL vcom command. Must be a list of strings.

activehdl.vlog_flags

Extra arguments passed to Active HDL vcom command. Must be a list of strings.

Note

Only affects source files added before the option is set.

Simulation Options

Simulation options allow customization of simulation behavior. Since simulators have differing options available, generic options may be specified through this interface. The following simulation options are known.

vhdl_assert_stop_level

Will stop a VHDL simulation for asserts on the provided severity level or higher. Valid values are "warning", "error", and "failure". This option takes precedence over the fail_on_warning attribute.

disable_ieee_warnings

Disable ieee warnings. Must be a boolean value. Default is False.

enable_coverage

Enables code coverage collection during simulator for the run affected by the sim_option. Must be a boolean value. Default is False.

When coverage is enabled VUnit only takes the minimal steps required to make the simulator creates an unique coverage file for the simulation run. The VUnit users must still set sim and compile options to configure the simulator specific coverage options they want. The reason for this to allow the VUnit users maximum control of their coverage settings.

An example of a run.py file using coverage can be found here.

pli

A list of PLI file names.

ghdl.flags

Extra arguments passed to ghdl --elab-run command before executable specific flags. Must be a list of strings. Must be a list of strings.

incisive.irun_sim_flags

Extra arguments passed to the Incisive irun command when loading the design. Must be a list of strings.

modelsim.vsim_flags

Extra arguments passed to vsim when loading the design. Must be a list of strings.

modelsim.vsim_flags.gui

Extra arguments passed to vsim when loading the design in GUI mode where it takes precedence over modelsim.vsim_flags. Must be a list of strings.

modelsim.init_files.after_load

A list of user defined DO/TCL-files that is sourced after the design has been loaded. During script evaluation the vunit_tb_path variable is defined as the path of the folder containing the test bench. Must be a list of strings.

modelsim.init_file.gui

A user defined TCL-file that is sourced after the design has been loaded in the GUI. For example this can be used to configure the waveform viewer. During script evaluation the vunit_tb_path variable is defined as the path of the folder containing the test bench. Must be a string.

rivierapro.vsim_flags

Extra arguments passed to vsim when loading the design. Must be a list of strings.

rivierapro.vsim_flags.gui

Extra arguments passed to vsim when loading the design in GUI mode where it takes precedence over rivierapro.vsim_flags. Must be a list of strings.

rivierapro.init_files.after_load

A list of user defined DO/TCL-files that is sourced after the design has been loaded. During script evaluation the vunit_tb_path variable is defined as the path of the folder containing the test bench. Must be a list of strings.

rivierapro.init_file.gui

A user defined TCL-file that is sourced after the design has been loaded in the GUI. For example this can be used to configure the waveform viewer. During script evaluation the vunit_tb_path variable is defined as the path of the folder containing the test bench. Must be a string.

activehdl.vsim_flags

Extra arguments passed to vsim when loading the design. Must be a list of strings.

activehdl.vsim_flags.gui

Extra arguments passed to vsim when loading the design in GUI mode where it takes precedence over activehdl.vsim_flags. Must be a list of strings.

activehdl.init_file.gui

A user defined TCL-file that is sourced after the design has been loaded in the GUI. For example this can be used to configure the waveform viewer. Must be a string.

ghdl.elab_flags

Extra elaboration flags passed to ghdl --elab-run. Must be a list of strings.

ghdl.sim_flags

Extra simulation flags passed to ghdl --elab-run. Must be a list of strings.

ghdl.elab_e

With --elaborate, execute ghdl -e instead of ghdl --elab-run --no-run. Must be a boolean.

ghdl.gtkwave_script.gui

A user defined TCL-file that is sourced after the design has been loaded in the GUI. For example this can be used to configure the waveform viewer. Must be a string. There are currently limitations in the HEAD revision of GTKWave that prevent the user from sourcing a list of scripts directly. The following is the current work around to sourcing multiple user TCL-files: source <path/to/script.tcl>

Configurations

In VUnit Python API the name configuration is used to denote the user controllable configuration of one test run such as generic/parameter settings, simulation options as well as the pre_config and post_check callback functions. User attributes can also be added as a part of a configuration.

Configurations can either be unique for each test case or must be common for the entire test bench depending on the situation. For test benches without test such as tb_example in the User Guide the configuration is common for the entire test bench. For test benches containing tests such as tb_example_many the configuration is done for each test case. If the run_all_in_same_sim attribute has been used configuration is performed at the test bench level even if there are individual test within since they must run in the same simulation.

In a VUnit all test benches and test cases are created with an unnamed default configuration which is modified by different methods such as set_generic etc. In addition to the unnamed default configuration multiple named configurations can be derived from it by using the add_config method. The default configuration is only run if there are no named configurations.

Attributes

The user may set custom attributes on test cases via comments or via the set_attribute method. The attributes can for example be used to achieve requirements trace-ability. The attributes are exported in the JSON Export. All user defined attributes must start with a dot (.) as non-dot attributes are reserved for built-in attributes.

Attributes set via the python interface will effectively overwrite the value of a user attribute set via code comments.

Example

VHDL Example
if run("Test 1") then
    -- vunit: .requirement-117
end if;
SystemVerilog Example
`TEST_SUITE begin
    `TEST_CASE("Test 1") begin
        // vunit: .requirement-117
     end
 end
Python Example
my_test.set_attribute(".requirement-117", None)
JSON Export has attributes attached to each test. The attributes added via comments all have null value to be forward compatible in a future where user attributes can have values. Attributes set via python can have basic type values.
 {
    "attributes": {
         ".requirement-117": null
    }
 }

Pre and post simulation hooks

There are two hooks to run user defined Python code.

pre_config

A pre_config is called before simulation of the test case. The function may accept an output_path string which is the filesystem path to the directory where test outputs are stored. The function must return True or the test will fail immediately.

The use case is to automatically create input data files that is read by the test case during simulation. The test bench can access the test case unique output_path via a special generic/parameter.

post_check

A post_check is called after a passing simulation of the test case. The function may accept an output_path string which is the filesystem path to the directory where test outputs are stored. The function may accept an output string which full standard output from the test containing the simulator transcript. The function must return True or the test will fail.

The use case is to automatically check output data files that is written by the test case during simulation. The test bench can access the test case unique output_path via a special generic/parameter.

Note

The post_check function is only called after a passing test and skipped in case of failure.

Example

class DataChecker:
    """
    Provides input data to test bench and checks its output data
    """
    def __init__(self, data):
        self.input_data = data

    def pre_config(self, output_path):
        write_data(self.input_data, join(output_path, "input.csv"))
        return True

    def post_check(self, output_path):
        expected = compute_expected(self.input_data)
        got = read_data(join(output_path, "output.csv"))
        return check_equal(got, expected)

# Just change the original test
checker = DataChecker(data=create_random_data(seed=11))
my_test.set_pre_config(checker.pre_config)
my_test.set_post_check(checker.post_check)

# .. or create many configurations of the test
for seed in range(10, 20):
    checker = DataChecker(data=create_random_data(seed))
    my_test.add_config(name="seed%i" % seed,
                       pre_config=checker.pre_config,
                       post_check=checker.post_check)

Adding Custom Command Line Arguments

It is possible to add custom command line arguments to your run.py scripts using the VUnitCLI class.

class vunit.vunit_cli.VUnitCLI(description=None)

VUnit command line interface

parse_args(argv=None)

Parse command line arguments

Parameters

argv – Use explicit argv instead of actual command line argument

Returns

The parsed argument namespace object

A VUnitCLI object has a parser field which is an ArgumentParser object of the argparse library.

from vunit import VUnitCLI, VUnit

# Add custom command line argument to standard CLI
# Beware of conflicts with existing arguments
cli = VUnitCLI()
cli.parser.add_argument('--custom-arg', ...)
args = cli.parse_args()

# Create VUNit instance from custom arguments
vu = VUnit.from_args(args=args)

# Use args.custom_arg here ...
print(args.custom_arg)