Test Directives#

Before running a test, canary reads the test file looking for “test directives”. Test directives are instructions for how to setup and allocate resources needed by the test. The .pyt and .vvt file types use different directive styles. In the .pyt file type, directives are python commands contained in the canary.directives namespace. In the .vvt file type, text directives are preceded with #VVT: and canary will stop processing further #VVT: directives once the first non-comment non-whitespace line has been reached in the test script.

The general format for a directive is

.pyt:

import canary
canary.directives.directive_name(*args, **kwargs)

.vvt:

#VVT: directive_name [<option spec>] [: <args>]

where the optional option spec takes the form:

(name=value[, ...])

.vvt directives can be continued on subsequent lines by starting them with #VVT:::

#VVT: directive_name : args
#VVT:: ...
#VVT:: ...

Which is equivalent to

#VVT: directive_name : args ... ...

Conditional directive activation

Most directives take the optional keyword argument when, which is an expression that limits when the directive is activated. For example, to restrict a directive to be activated only on linux platforms, add the following:

import canary
canary.directives.directive_name(*args, when='platforms=linux')

or, to restrict processing to linux platforms and when the user has defined the opt option (by passing -o opt on the command line), add the following:

import canary
canary.directives.directive_name(*args, when='platforms=linux options=opt')

when also accepts a dict, so the previous example can be expressed equivalently as

import canary
canary.directives.directive_name(*args, when={"platforms": "linux", "options": "opt"})

The when expression recognizes the following conditions:

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

Directives: