keywords

keywords(*args: str, when: str | dict[str, str] | None = None) → None

Mark a test with keywords. The main use of test keywords is to filter a set of tests, such as selecting which tests to run.

Usage

.pyt:

import canary
canary.directives.keywords(*args, when=...)

.vvt:

#VVT: keywords (parameters=..., testname=...) : args...

Parameters

• args: list of keywords

• when: Restrict processing of the directive to this condition

The when expression is limited to the following conditions:

• testname: Restrict processing of the directive to this test name

• parameters: Restrict processing of the directive to certain parameter names and values

Implicit keywords

The following implicit keywords are defined:

• The test name

• The test file basename (regardless of testname settings)

• The names of parameters, e.g.

  import canary
  canary.directives.parameterize("meshsize", (0.1, 0.01, 0.001))
  

  would have “meshsize” as a keyword.

• The results of running the test are added as keywords. The result strings are

  • ready: the test is ready to be run

  • pass : the test ran and completed successfully

  • diff : the test ran and completed with a numerical difference

  • fail : the test ran but crashed for some reason (exited with a non-zero exit status)

  • timeout : the test ran out of time and was killed. A test that times out is also considered to have failed.

Examples

import canary
canary.directives.keywords("3D", "mhd", "circuit")

#VVT: keywords : 3D mhd circuit

---

import canary
canary.directives.keywords("3D", "mhd", when="testname=spam parameters='cpus>1'")

#VVT: keywords (testname=spam, parameters="np>1") : 3D mhd