This section describes how to specify test step in YAML format (version 1.1). YAML is language used for structured data representation, which is human readable and machine parseable. It is easier to read than XML, and much easier to write. More information is available at Wikipedia and The Official YAML Web Site.

Conventions

Bold and underlined - used for mandatory tags and default values

Code - used for examples and code

Italics - used for emphasis

Operators '*', '&', and [] in C/C++ and YAML

YAML uses characters '&' and '' to define anchors and references. This conflicts with operators in C, so we must quote all strings, which start with '&' or '', when specifying C operators.

Examples:

- ax == &g    # OK, because YAML list item is scalar 'ax == &g',
              # which does not start with '&'
              
ptr1: '&g'    # must be quoted, because mapping pair is composed of
              # scalars 'ptr1' and '&g'. Scalar '&g' starts with '&',
              # so quoting is needed.
              
'*ptr1': 10   # must be quoted, because mapping key '*ptr1' starts with '*'

Another issue are square brackets '[' and ']', which are used for lists in YAML flow style, and for array indices in C/C++. They have to be quoted always when they are the first char in string, or when they are used in YAML flow style lists, even if they do not start the string. To be on the safe side, use single quotes for all strings which contain square brackets.

Quotes in test specifications

Since both C and YAML use single and double quotes, it is important to understand quoting in YAML and C and how it is used in isystem.test.

YAML understands three types of strings. The string type is determined by the first character. If it is single quote, it is single quoted string, if it is double quote, it is double quoted string, and it is plain string in all other cases. If the first character is not quote (single or double), it is a plain string, even if quotes appear inside of the string. Detailed descriptions follow:

plain strings are strings, which are not surrounded with quotes and do not support escaping. Characters with special meaning in YAML are not allowed in plain strings. These are: & * , : # { } [ ] In isystem.test plain strings are used for single word items, like tags, function names, parameter names, and variable names. Examples:

locals:

myVar: int

desc: This is test description.

If quotes appear inside plain string, they are treated as any other character, for example:

expect:

- retVal == 'a'

The plain string here is ‘retVal == 'a’`. Quotes have no special meaning for YAML parser.
single quoted strings in YAML support no escaping, except single quote itself, which is written as two single quotes. In isystem.test single quotes are used for specifying character constants, and when '&', '*' or '[]' are used as C operators. Example:

locals:

myvar: char

singleQuote: char

init:

myVar: 's'

singleQuote: '\''' # backslash is required for C evaluator, which gets: '\''

function: [myFunction, ['&myvar', 'a[0]'], retVal]

expect:

- retVal == '\''

Note the last line in example, where the single quote is not escaped, because this line contains a plain string ‘retVal == ’\''`, not quoted string.
double quoted strings in YAML support escaping with \. In isystem.test the double quoted strings are used for specifying string literals, which can be used for initialization of character arrays, for example:

locals:

array: char [15]

init:

array: "Hello!"

func: [f, [array]]

Backslash '\' character in strings must be escaped as in C, for example:

"\\home\\test\n" # string ends with newline character

Example of complete test specification:

locals:
  a: char[10]
  b: char[15]
  c: char[5]
  d: char[20]
  pd: 'char *'
init:
  a: "elephant"
  b: "horse"
  c: ""   
  pd: '&d'
  d: "monitor"
func: [funcTestCharArray2, [a, b, c], charRetVal]
expect:
- a[0] == 'f'
- a == "flephant"
- b[1] == 'g'
- c[0] == 0
- c[2] == 'h'
- pd == "monitor"
- pd == &d
- charRetVal[2] == 'h'

More details about quotes in YAML can be found at The Official YAML Web Site.

Host variables

Test specifications may use also variables, which are defined on host only. These variables should be prefixed with $ and surrounded with {}:

${<varName>}

for example:

${expectedValue}

These variables do not have to be declared, and they always contain strings. Inside test specification they are simply replaced with their value. To use them, we simply assign value to them in Variables* section, and then use them in expressions.

Reserved host variables

Host variables must start with a letter. They may contain also numbers and underscores in their name, but not as the first character. Names starting with underscore are reserved, and will be defined by iSYSTEM.

Predefined host variables

Predefined host variables are created automatically by isystem.test and can be used in expressions. The following host variables are predefined:

${_rv} - function return value
${_p<n>} - value of function parameter, where n is parameter index, for example {_p1} refers to first function parameter.
(empty entry)

Global host variables

User defined host variable with prefix g_ are global variables, which means they will be available in all succeeding test cases. Their value can be changed, but once defined they can not be deleted.

winIDEA SDK

Contents

Conventions

Operators '*', '&', and [] in C/C++ and YAML

Quotes in test specifications

Host variables