Script Utilities

Writing tests that use the script utilities

For tests written in Python or sh/bash, there are script utilities (useful functions) available from the vvtest area. These utilities can be imported (or sourced) from the test script. Having functions available within your tests makes performing common actions easier and reduces the size of each test.

Every test will have the scripts vvtest_util.py (for Python) and vvtest_util.sh (for bash/sh) written to the test execution directory, and should be imported/sourced at the beginning of the test. These scripts contain the settings for the test and any command line options. For example, if this is the start of the test script mytest.vvt

#VVT: parameterize : MODEL = 1 2

and is run with the command

$ vvtest -o dbg

then the TestResults.*.ON=dbg/mytest.MODEL=1/vvtest_util.py file will include the lines like

NAME = "mytest"
TESTID = "mytest.MODEL=1"
PLATFORM = "iDarwin"
COMPILER = ""
OPTIONS = ['dbg']
OPTIONS_OFF = []
SRCDIR = "/Users/rrdrake/Projects/scidev/example"
TIMEOUT = 3600

PARAM_DICT = {'MODEL': '1'}
MODEL = '1'

There are a number of useful variables and flags defined in this file; take a look to see what is available. Of note is that the parameter names are defined in a dictionary and as simple variables. In this case MODEL is a parameter in the test, so it forms a variable whose value is the value of the parameter for that test. In nearly every case, these parameters are used in the test script to set up or apply a variation before the core test is performed.

An effect of importing the vvtest_util.py file is to add the config directories to the Python import path. This then allows the import of the script_util module, which contains a bunch of Python utilities. For example,

#VVT: parameterize : MODEL = 1 2

import vvtest_util as vvt
import script_util as util

# replace the word MODEL in the simulation input file with the value in this test
util.sedfile( 'input.txt', 'MODEL', vvt.MODEL )

# ... (run the simulation)

if len( util.grepfile( 'DIFFERENCES', 'outputfile' ) ) > 0:
    util.exit_diff()

The script utility functions

The best way to become familiar with the functions available in the script_util module is to look in the directory <vvtest_install>/config/script_util/*. However, we list some of the functions here:

• platform_expr: evaluates an expression involving platform names, such as "Linux or Darwin"
• parameter_expr: evaluates an expression against the parameters defined in the test, such as "dt<0.01 and dh=0.1"
• option_expr: evaluates an expression against the options given on the command line
• set_have_diff: sets the variable "have_diff" to True
• exit_diff: exits the test with a diff status
• if_diff_exit_diff: checks the variable "have_diff" and if True, then exits with a diff status
• analyze_only: returns True if the -a or --analyze option was given on the command line
• set_python_trace: engages or disengages python statement tracing to help debugging
• print3: a Python 2.x and 3.x compatible print function
• which: returns the full path of the given program name
• sedfile: applies regex pattern replacements to a file
• unixdiff: compares two files and if there are differences, then sets the "have_diff" variable
• runcmd: executes a shell command; can return the output; can redirect to a file
• catfile: reads a file and writes its output to the stdout
• grepfile: searches lines of a file for a regex pattern

These functions have more explanation in the source files themselves. Note that the runcmd function is very helpful when using Python for your test script.

The project specific script utility functions

Note that a project can provide additional script utilities by using the --config option, described here.