<TARGETS> section contains the list of what is tested in this test scenario (<BLOCK>): functions, properties, etc.

At least one test target should be defined for each test scenario (<BLOCK>).

The targets are listed one per line. They may contain spaces and tab characters. Leading and trailing spaces and tab characters are ignored. In the following example, <TARGETS> section contains the names of three functions tested in this <BLOCK> section:

<TARGETS>
    g_array_set_size
    g_array_new
    g_array_sized_new
</TARGETS>

Many test scenarios have often only one test target. Indeed, if, for example, two target functions can be checked separately, they should better be checked in separate <BLOCK> sections which results in the tests that are usually easier to understand and maintain. However, there can be tightly coupled groups of test targets like getter/setter or open/close functions in which the targets are difficult to test separately. In such cases, several targets can and should be listed for the test scenario.

T2C file generator defines a (possibly multivalued) parameter named target which values are the test targets listed in this section. The parameter can be used by the templates from test_case template group (as <$target$>). In the following example, the list of test targets is placed in the comments before the test function and in TRACE0 call that will output it to the log when the test is executed:

////////////////////////////////////////
// This is the test #<%abs_test_index%>
//
// Target(s):
//    <$target : join(,\n//    )$>
////////////////////////////////////////
int
test_<%abs_test_index%>()
{
    ...
    // Output the list of test targets
    TRACE0("Test target(s):\n    <$target : join(\\n    )$>\n");
    // The rest of the test
    ...
}

The resulting fragment of the test source file generated using this template may look like this:

////////////////////////////////////////
// This is the test #12
//
// Target(s):
//    g_module_open,
//    g_module_close
////////////////////////////////////////
int
test_12()
{
    ...
    // Output the list of test targets
    TRACE0("Test target(s):\n    g_module_open\n    g_module_close\n");
    // The rest of the test
    ...
}

Note that it is allowed to use <%…%>-parameters not only in <DEFINE>, <CODE> and <FINALLY> subsections but also in <TARGETS> subsection. For example, assume that the value of parameter <%0%> of the tests may be char or wchar_t. Sometimes it can be convenient to define the test targets the following way to take advantage of parameter substitution:

<TARGETS>
basic_string<<%0%>>::basic_string(const allocator<<%0%>>&)
</TARGETS>

If the first value (#0) specified in the <VALUES> section is char, the fragment above evaluates to the following:

<TARGETS>
basic_string<char>::basic_string(const allocator<char>&)
</TARGETS>

On the other hand, if the value of <%0%> is wchar_t, the result will be different:

<TARGETS>
basic_string<wchar_t>::basic_string(const allocator<wchar_t>&)
</TARGETS>

That is, even the set of targets of a <BLOCK> can be controlled by the parameters of the tests from this <BLOCK>.

<DEFINE> section is commonly used to provide symbolic names (aliases) for test parameters which are often easier to understand in the test scenario than the references to <%…%>-parameters themselves.

However, <DEFINE> section can serve other purposes as well. In general, its entries just allow to define (name, value) pairs that can be interpreted in a way specific to the chosen T2C file generation target (it is described below in more detail).

Each entry in the section should occupy a single line. The syntax of an entry is as follows:

#define <name> <value>

Space and tab characters are ignored before and after “#define” and also after “<name>” and “<value>”.

<%…%>-parameters can be used both in the names and the values in <DEFINE> section.

As it has been said, <DEFINE> section is commonly used to provide human-readable names for test parameters, especially for numbered test parameters coming from <VALUES> (<PURPOSE>) sections.

Consider the following fragment of a test scenario:

int total = <%0%> * <%1%>;

The meaning of that fragment would be easier to understand if we defined symbolic aliases for these numbered parameters:

<DEFINE>
#define QUANTITY <%0%>
#define PRICE    <%1%>
</DEFINE>

Now that fragment of the test scenario could be rewritten as follows:

int total = QUANTITY * PRICE;

The meaning of the statement in the fragment above is probably clearer now. So this fragment would be easier to develop and maintain.

For historical and compatibility reasons, the syntax of an entry in a <DEFINE> section resembles #define C preprocessor directive. The entries, however, can be interpreted in a variety of ways depending on the templates used. They can be used even if the target programming language does not have #define directives.

What the file generator does, is to define two (possibly multivalued) parameters named define_name and define_value, respectively, that can be used by the templates from test_case template group (as <$define_name$> and <$define_value$>). Each entry in <DEFINE> section provides corresponding values of these parameters.

Consider the following example of <DEFINE> section:

<DEFINE>
#define AAA  <%0%>
#define BBB  val-<%1%>-<%2%>
#define CCC  some constant value
</DEFINE>

Assume the numbered parameters <%0%>, <%1%> and <%2%> have values (without the quotes) “XX”, “YY” and “ZZ”, respectively, in this particular test.

The main template from test_case template group that deals with defines may look like this:

void
test_<%abs_test_index%>()
{
<$define : join(\n)$>
    ...
    // The body of the test
    ...
<$undef : join(\n)$>
    ...
} 

First, we can define define and undef subtemplates (referred to by the template above) in define.tpl and undef.tpl files as follows:

define.tpl:

#define <$define_name$> <$define_value$>

undef.tpl:

#undef <$define_name$>

When the source code of this particular test will be generated, the result will be as follows:

void
test_1()
{
#define AAA XX
#define BBB val-YY-ZZ
#define CCC some constant value
    ...
    // The body of the test
    ...
#undef AAA
#undef BBB
#undef CCC
    ...
}

In the above example, ordinary C preprocessor directives (#define and #undef) were generated. But let us now define define and undef subtemplates differently:

define.tpl:

CObject* obj_<$define_name$> = 
    CObjectFactory::create_object("<$define_value$>");

undef.tpl:

CObjectFactory::destroy_object(obj_<$define_name$>);

This time the resulting source code of the test will be completely different:

void
test_1()
{
CObject* obj_AAA = 
    CObjectFactory::create_object("XX");
CObject* obj_BBB = 
    CObjectFactory::create_object("val-YY-ZZ");
CObject* obj_CCC = 
    CObjectFactory::create_object("some constant value");
    ...
    // The body of the test
    ...
CObjectFactory::destroy_object(obj_AAA);
CObjectFactory::destroy_object(obj_BBB);
CObjectFactory::destroy_object(obj_CCC);
    ...
}

These examples once again demonstrate that the interpretation of the data provided in a .t2c file depends on the templates. Processing the same .t2c file with different sets of templates allows to produce source files that differ very much from each other.

As it is also shown in the above examples, it is not required to use <%…%>-parameters in the entries of <DEFINE> section, neither it is mandatory to use just one such parameter in each entry.

<CODE> section contains the main part of the parameterized test scenario, perhaps except for cleanup (resource deallocation) instructions that are usually placed in <FINALLY> section. The contents of <CODE> and <FINALLY> sections are written in target programming language but they can refer to <%…%>-parameters and often use to what <DEFINE> section evaluates: symbolic names of test parameters or the like.

T2C targets may provide special API that can be used in <CODE> and <FINALLY> sections, for example, to link each check with the requirements that are checked there, to conveniently handle error reporting and other message output, etc. C API provided by several T2C targets is described in Section 4, “T2C File Generation Targets”. It is not required of a target to provide exactly the same or similar API or any API at all.

The code in <FINALLY> should be called both if the test passes and if it fails (probably with the exception of abnormal termination of test application). For example, in c_standalone, c_minimal and some other targets, the instructions in <FINALLY> are called not only when the test passes but also if a violation of a requirement is detected or when the test situation cannot be prepared (“precondition failure”), etc.

It is up to T2C target, how to implement support for <FINALLY>. It may use exception handling, unconditional jumps (goto) or whatever else is suitable. The templates and may be API provided by this target are responsible for this.

T2C file generator sets the contents of <CODE> and <FINALLY> sections as the values of the parameters named code and finally, respectively, that can be used by the templates from test_case template group (as <$code$> and <$finally$>).

<VALUES> sections are used to define the values of test parameters. For compatibility with T2C 1.x, <PURPOSE> sections can also be used with the same meaning and syntax as <VALUES> sections. What is stated below concerning <VALUES> sections, also holds for <PURPOSE> sections.

The value for each parameter should be on a separate line. Blank lines are ignored. Leading and trailing space and tab characters in the entries are ignored too.

More than one value can be specified for a parameter at once, in a single <VALUES> section. See Section 2.7.7, “Specifying sets of values for test parameters (SET and RES constructs)” for details.

Examples:

<VALUES>
## ZERO
    FALSE
    
## CLEAR
    TRUE
    
## TYPE
    struct CMyStruct
</VALUES>

<VALUES>
## ZERO
    SET(TRUE; FALSE)
    
## CLEAR
    SET(TRUE; FALSE)
    
## TYPE
    SET(int; char)
</VALUES>  

The entries in <VALUES> section correspond to the numbered parameters of the test. The file generator defines parameter <%0%> for the first entry, <%1%> - for the second one, <%2%> - for the third one, etc. The number of such parameters is limited only by the amount of memory available to the file generator. In practice, the number of such parameters should be kept reasonably small. For example, if a test scenario has 20 or more parameters, it can be difficult to see what is going on in there.

If a test refers to a numbered <%…%>-parameter which is not defined in the corresponding <VALUES> sections (that is, 0-based number of the parameter is greater than or equal to the number of entries in each of these sections), the parameter is considered to have an empty value.

The number of entries in different <VALUES> sections of the same <BLOCK> section should be the same. T2C file generator will report an error if this is not the case. Even if some individual tests do not use a particular parameter which the other tests from this <BLOCK> use, they should still provide some value for it. The value will not affect the test and can be something like “Not used” string to point out that this parameter is not used in this test.

<VALUES> section can be left empty. It indicates that no numbered parameter is defined for the tests from this <BLOCK>.

If no <VALUES> and <PURPOSE> sections are present in a <BLOCK>, it is the same as if one empty <VALUES> section was in this <BLOCK>.

Long entries in <VALUES> section can be written in more than one line: they can be broken into smaller parts with a backslash character ( \ ). A backslash affects the next meaningful line in the section (that is, a line that is not blank and is not a T2C-style comment). Note that leading whitespace characters (spaces and tabs) in that line are ignored but the spaces and tabs before the backslash at the previous line are not.

## The following sections are equivalent:
<VALUES>
    "prefix" "body" \ 
        "suffix"
    1\
    2\
    3
</VALUES>

<VALUES>
    "prefix" "body" "suffix"
    123
</VALUES>

<VALUES>
    "prefix" "body" \ 
        "suffix"
    1\
## one 
    2\
## two 
    3
</VALUES>

A backslash after the last entry in the section is ignored, so the following example sections are equivalent:

<VALUES>
    TRUE
    TRUE
    int \
</VALUES>

<VALUES>
    TRUE
    TRUE
    int
</VALUES>

If one or more backslashes are the last characters of the value rather than line-breaking markers, the last one of them should be escaped (again with a backslash). Example:

## Here the following values are defined:
##   "string\\"
##   "TRUE"
## rather than "string\\TRUE"
<VALUES>
    string\\\
    TRUE
</VALUES>

For each set of values of test parameters, the file generator defines additional <%…%>-parameter named param. It has the same number of values as there are entries in the corresponding <VALUES> section, the values being the values of the respective numbered parameters of the test. The order is the same as the order of entries in the <VALUES> section: the first value of param is that of <%0%> parameter, the second one is the value of <%1%>, etc.

This parameter can be used by the templates from test_case template group to create the list of parameter values for each particular test (usually in the description of the test in the comments) or other similar list-like structures. Consider, for example, the following fragment of the main template from test_case group (the template of a comment block before the test):

///////////////////////////////////////////////////////////////////
// This is the test #<%abs_test_index%>
//
// Target(s):
//    <$target : join(,\n//    )$>
//
// Parameters:
//    <%if concat(param)%><%param : join(,\n//    )%><%else%>none<%endif%>
///////////////////////////////////////////////////////////////////

The resulting fragment of the source file may look like this:

///////////////////////////////////////////////////////////////////
// This is the test #2
//
// Target(s):
//    g_module_open,
//    g_module_close
//
// Parameters:
//    GET_PATH("open-symbol-close/module/test.so"),
//    G_MODULE_BIND_LAZY,
//    "test"
///////////////////////////////////////////////////////////////////

In the above fragment, the values of parameters <%0%>, <%1%> and <%2%> are listed after the line “// Parameters:”, on a separate line each, separated by commas.

If there are no entries in the corresponding <VALUES> section, the resulting fragment of the source file may look like this:

///////////////////////////////////////////////////////////////////
// This is the test #30
//
// Target(s):
//    g_module_supported
//
// Parameters:
//    none
///////////////////////////////////////////////////////////////////

A <BLOCK> section can have user-defined attributes that can be used in the tests generated from that section.

Example:

<BLOCK  name = "My Super Test" 
        depth = "medium" 
        min_ver="2.0.1" 
        max_ver="3.9.99"
>

In this example, four attributes are defined (the format is <name>="<value>", the quotation marks are not included in the value).

A name of an attribute may containg latin letters, digits, dots, underscores, hyphens, etc. It must not begin with a dot or a parenthesis. The names are case-sensitive. In fact, it must be valid as a name of T2C template or parameter (see Section 5, “Templates, Template Groups and File Generation with T2C”), the rules are the same here.

The attributes can be used in the same way as the numbered parameters of the tests (<%0%>, <%1%>): <%name%>, <%depth%>, etc.

Example:

<CODE>
    ...
    printf("<%name%>: some message\n");
    printf("<%name%>: par0 = %s\n", "<%0%>");
    ...
</CODE>

As with any other parameters in the T2C templates, if an attribute is not specified but is used in a <BLOCK>, its value is assumed to be an empty string.

The attributes can be used both in the parameterized test scenarios and in the templates (“test case” group) from which individual tests are generated. Often these attributes are more useful in the templates rather than in test scenarios themselves.

For example, assume that the tests from each <BLOCK> may have restrictions on the version of the system under test they are applicable for. The minimum and/or maximum acceptable version could be specified in the attributes of these <BLOCK> sections, say, “min_ver” and “max_ver”, respectively. If one or both of these attributes are not specified or have an empty value, this means there are no restrictions on the respective version.

A template of an individual test (main template from “test case” group) could contain the following to automatically check if the test is applicable to a current version of the system (imagine that check_version() function is provided to check that):

void
test_function()
{
    ...
    if (check_version("<%min_ver%>", "<%max_ver%>") != VERSION_SUPPORTED)
    {
        return; // Do not run the test.
    }
    ...
    //the code from <CODE> and <FINALLY> goes here
    ...
    return;
}

So, in this case, the test developer only needs to specify these attributes in the <BLOCK> sections and the code dealing with version checking will appear in the tests automatically.