Python Interface¶
The Python interface of VUnit is exposed through the VUnit
class
that can be imported directly. See the
User Guide for a quick introduction. The
following list provides detailed references of the Python API and
about how to set compilation and simulation options.
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¶
if run("Test 1") then
-- vunit: .requirement-117
end if;
`TEST_SUITE begin
`TEST_CASE("Test 1") begin
// vunit: .requirement-117
end
end
my_test.set_attribute(".requirement-117", None)
{
"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 anoutput_path
string which is the filesystem path to the directory where test outputs are stored. The function must returnTrue
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 anoutput_path
string which is the filesystem path to the directory where test outputs are stored. The function may accept anoutput
string which full standard output from the test containing the simulator transcript. The function must returnTrue
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. 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)
- 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
- vunit.vunit_cli.positive_int(val)¶
ArgumentParse positive int check