Header directive format

Test header directives are just special comment lines at the top of the test file. They are how the test describes itself to the test harness, such as its resource needs, filtering keywords, parameter name/values, test input files, and dependencies.

Directive lines must appear at the top of the test file and start with "#VVT:". For example,

# this comment ignored by the test harness

#VVT: parameterize : np = 1 4
#VVT: keywords : fast 2D fracture
#VVT: link : $NAME.inp $NAME.gen $NAME.base.exo $NAME.exodiff
#VVT: timeout (platform=ATS*) : 300

# start the test scripting...

The directives must come before any script content (the first non-comment, non-empty line stops the directive processing). However, a Python string comment can appear at the top, such as

"""
This is a Python comment
section, and will be ignored by
the test harness.
"""

#VVT: parameterize : np = 1 4

...

The general format for a directive line is

#VVT: directive name (attrname=attrvalue, ...) : directive value

The attributes in parenthesis are optional, and multiple attribute name=value are separated by commas. While not necessary, the attribute value can be surrounded by double quotes.

If there is no directive value, then the colon can be omitted. Also, an equals sign can be used instead of a colon. For example,

#VVT: testname = mytest
#VVT: enable (platform=not Linux, option="dbg or debug")

To comment out a directive line, prepend with another comment character. For example, this line will be ignored:

# #VVT: enable = false

Line continuation

If a "#VVT:" directive is followed immediately by a line starting with "#VVT::", then that line's content is effectively appended to the previous line. Note the double colon. For example,

#VVT: parameterize : paramA, paramB = name1, value1
#VVT::                                name2, value2
#VVT::                                name3, value3

These three lines would be interpreted the same as

#VVT: parameterize : paramA, paramB = name1, value1 name2, value2 name3, value3

White space between the two colons is allowed, and comments can be placed between the continuation lines. For example,

#VVT: parameterize : paramA, paramB = name1, value1
#  helpful comment
#VVT:                               : name2, value2
#  another comment
#VVT:                               : name3, value3

Directive attributes

The known and allowable attribute names and values depend on the directive name, and are generally documented in the same section as the directive. However, there are some common attributes worth describing here:

• testname: Restrict processing of the directive to a test name
• platform: Restrict processing of the directive to certain platform or platforms
• parameter: Restrict processing of the directive to certain parameter names and values
• option: Restrict processing of the directive to command line -o options

Note that the plural can be used for "platform", "parameter", and "option" (such as platforms=Linux).

The values for these attributes are word expressions, such as

#VVT: link (platforms=Linux or Darwin) : baseline.exo

In this case, the baseline.exo file will only be soft linked for the Linux or Darwin platform names.

In general for these attributes, if the word expression is satisfied, the directive applies to the test. If it is not satisfied, then the directive is ignored for the test. If multiple attributes are given for a single directive, then each must be satisfied for the directive to apply.

Some example expressions

expression	notes
(platforms=Linux or Darwin)
(platforms="Linux or Darwin")	quotes are generally optional
(platforms=Linux, options=not debug)	attributes are separated by commas
(testname=foobar)
(parameters="np>4")	applies to tests that define parameter np and it is greater than 4
(parameters="np<=4 or np>=8")
(options=debug or cuda)
(platforms=Linux/Darwin)	shorthand for "Linux or Darwin"

The word expression syntax is generally the same for all four of these attributes.