VectorCAST User Code

2020-09-16
Support Note SN-ACT-1-002

Author(s) Yue, Jeanne

Restrictions Public Document

Table of Contents
1 Overview .....................................................................................................................................2
2 What is User Code? ....................................................................................................................2
3 Why is User Code needed? .........................................................................................................2
4 Types of User Code.....................................................................................................................2
4.1 Test case and parameter User Code ....................................................................................3
4.1.1 User Code tags ..........................................................................................................3
4.1.2 I/O Chaining example .................................................................................................3
4.2 Environment User Code .......................................................................................................4
4.2.1 Unit prefix and unit appendix ......................................................................................4
4.2.2 Function pointers ........................................................................................................5
4.2.3 Undefining and redefining pointers to hardware register structures .............................5
5 Contacts ......................................................................................................................................6
 VectorCAST User Code

1 Overview
This Support Note is meant to provide a high level overview of VectorCAST User Code and some real
world examples. If you are looking for help implementing User Code in your environment please refer
to the VectorCAST/C++ User’s Guide. The VectorCAST/C++ User’s Guide provides a detailed section
on User Code that describes what User Code is, the different types of User Code, and how to
implement User Code in a VectorCAST unit test environment.

2 What is User Code?

User Code is a powerful tool that can be used in a VectorCAST unit test environment as an avenue to
customizing the test harness. Practically any part of the test harness can be customized with User
Code. The test engineer can use User Code to read data from a file, initialize arrays, call routines,
dynamically assign and verify data objects and much more. The possibilities are endless.

User Code is written in the language native to the unit under test. Therefore, anything that is legal to
the native language can be implemented in User Code.

3 Why is User Code needed?

VectorCAST automates the creation of a complete unit test framework. This includes setting up global
variables, creating stubs for external dependencies, evaluating expected values against the actual
values, and providing pass/fail status. In most cases a test engineer just needs to set input and
expected values and execute the test. But there are times when customization of the test harness is
necessary to create valid unit tests for the code under test. VectorCAST allows this customization
through User Code. There are many places in the test harness where User Code can be inserted:

> in the test harness (environment User Code),

> in stubs,
> in each test case, and
> for each parameter in a test case.

One example where User Code is needed is for void* pointers. A void* pointer has no data type
associated with it. Void* pointers can hold the address to a data item and be type casted to any data
type. Therefore, in the scope of the unit under test, VectorCAST cannot determine what data type
should be accessed by the void* pointer. For example, let’s say a void* pointer is passed as a
parameter to a function under test. And the function under test is equipped to accept two different C
type structures and a char* via the void* pointer. Additionally, the two different C type structures are
declared in a header file external to the unit under test. VectorCAST has no way of knowing which
data type should be passed to the function under test. In this case User Code can be used to declare
the data types to be used by the void* pointer as global data. The test engineer can then easily assign
the correct data type from a drop-down list.

Another example would be dynamically setting a global data item based on the return of a function.
User Code can be used to call the function in an executable expression.

4 Types of User Code

Basically, there are three types of User Code:

1. Test case
2. Parameter
3. Environment

Copyright © 2020 – Vector Informatik GmbH 2

Contact Information: www.vector.com or +49-711-80 670-0
 VectorCAST User Code

4.1 Test case and parameter User Code

Test case User Code can be used to set or compare on any data item available to the function under
test and only applies to simple test cases. A simple test case calls the function under test once with
input values and evaluates expected values when the test case completes. This is opposed to a
compound test case where one or more simple test cases are executed sequentially.

There are two separate areas where test case User Code can be utilized. The first area is prior to
calling the function under test and the second area is after the function has returned from execution.
The test case User Code that is executed prior to calling the function under test is used to set up
inputs for the test case. The test case User Code that is executed upon completion of the test case is
used to compare data and report a pass/fail status.

Parameter User Code applies to a specific data item within a simple test case. The data items can be
global variables, input parameters to a function or the return of a function. One example of parameter
User Code would be implementing a stub hit counter. Let’s say a function repeatedly calls a stubbed
function in a for loop. Parameter User Code can be used on the return value of the stubbed function.
Every time the stub is called the counter is incremented by 1. When the counter hits a specified value,
the User Code can assign a value to the return of the stub.

4.1.1 User Code tags

Every time an environment is rebuilt a new test harness is generated. During this process VectorCAST
creates a global variable for each parameter of each subprogram in each unit that is either under test
or stubbed. When developers make changes to the testable source code the test harness will need to
be regenerated. When the test harness is regenerated the names of the global variables that
VectorCAST assigns to each parameter can change. To provide access to these global variables
VectorCAST implements what is known as User Code tags. These User Code tags use a special
syntax that is based on the unit name, subprogram name and parameter name and is incased by
angle brackets. The following is one example of a User Code tag:

<<unitname.subprogram.parameter>>

The syntax is slightly different for structures, classes, arrays, etc. But the test engineer does not have
to worry about getting the syntax correct. The User Code tag for a particular data item can be
accessed by clicking on the User Code tag button from any of the User Code dialogs or from the
VectorCAST toolbar. This will bring up a listing of all User Code tags available to the VectorCAST
environment. The test engineer can select the User Code tag from the list and copy and paste it into
their User Code. Alternatively, the test engineer can copy the User Code tag by right clicking on a
particular data item in the test case editor and selecting Copy User Code Tag.

The User Code tags can be used to assign a value to parameters and global objects in the native
language to the unit under test.

<<myUnit.mySubprogram.myGlobal>> = foo(a) + 5;
if( <<myUnit.mySubprogram.myGlobal>> == 10) { // Do something }

The test engineer can also compare values of a User Code tag and display the results in the execution
report by using double curly braces wrapped around the conditional statement.

{{ <<myUnit.mySubprogram.myGlobal>> >= 200 }}

One thing to remember is that any expression contained in expected User Code between {{ }} the curly
braces must evaluate to a Boolean value. During execution of the test case the Boolean expression is
evaluated and is reported in the execution report. The result of the Boolean expression will also be
used to determine the pass/fail status of the test case. As in input User Code, the Boolean expression
of expected User Code can be combined with the native language for more complex evaluations.

4.1.2 I/O Chaining example

Compound test cases can be used in conjunction with parameter User Code in a VectorCAST

Copyright © 2020 – Vector Informatik GmbH 3

Contact Information: www.vector.com or +49-711-80 670-0
 VectorCAST User Code

methodology that we call I/O Chaining. When a simple test case is executed as a stand-alone
execution the function under test is called and executed based on the inputs set by the test engineer.
When the function under test returns, the expected values are evaluated and a pass/fail status is
reported. The data that is used in one simple test case cannot be used in another simple test case
when executed as stand-alone test cases.

As previously mentioned compound test cases call a set of linked simple test cases sequentially. But
the unique thing about compound test cases is that the data can persist throughout the execution of
the simple test cases. That means that any data from any of the simple test cases can be used
throughout the execution of a compound test case. Hence the term chaining.

In this example we are going to test some wrapper functions that will open a file, write to the opened
file and close the file when complete. These wrapper functions are contained within the unit
io_wrapper.c. Therefore, all of the wrapper functions will be dependent on a file pointer to a file.
Three simple test cases placed in a compound test case will be needed to completely test the
functionality of opening the file, writing to the file and then closing the file.

The OpenFile() function opens a stream for use via the standard C routine fopen() and links the file to
that stream. The OpenFile() function can also name the file and set the read and write mode for the file
that is being pointed to. When file processing is complete the OpenFile() function returns the file
pointer to the newly opened file. The User Code tag for the return of OpenFile() will be used to store
the file pointer to be used throughout the compound test case execution. The following is an example
of the User Code tag for the return parameter of OpenFile():

<<io_wrapper.OpenFile.return>>

The WriteString() function accepts a file pointer as an input parameter (fp) to the function. A test case
for WriteString() can be developed with parameter User Code to set the input parameter “fp” to the
return from OpenFile().

<<io_wrapper.WriteString.fp>> = <<io_wrapper.OpenFile.return>>;

The Closefile() function accepts a file pointer as an input parameter (fp) as well. And, in a similar
fashion, the return of OpenFile() will be used in a simple test case to access the file pointer.

<<io_wrapper.CloseFile.fp>> = <<io_wrapper.OpenFile.return>>;

4.2 Environment User Code

There are many different types of environment User Codes. But there is one thing that all types of
environment User Codes have in common. Environment User Code is executed for every test case in
a unit test environment. This is opposed to test case and parameter User Code, where these are test
case specific. Environment User Code also gives the test engineer the most access to test harness
components to customize.

Whenever environment User Code is used, the environment must be rebuilt to insert the environment
User Code into the test harness. However, when using test case or parameter User Code there is no
need to rebuild the entire environment. In this case an incremental build is completed prior to test case
execution.

The following are some examples of environment User Codes.

4.2.1 Unit prefix and unit appendix

Unit prefix and unit appendix environment User Code gives the test engineer the ability to add codes
to either the beginning or the end of the unit under test. Unit prefix User Code is prepended to the
beginning of the unit under test and unit appendix User Code is appended to the end of the unit under
test. This code then becomes part of the specified unit under test and added to the test harness. Any
global variables created in unit prefix or unit appendix User Code will be present in the unit’s Globals

Copyright © 2020 – Vector Informatik GmbH 4

Contact Information: www.vector.com or +49-711-80 670-0
 VectorCAST User Code

section of the test case editor. Any functions created in unit prefix or unit appendix User Code can
optionally be testable.

4.2.2 Function pointers

One common use case for unit appendix User Code is for functions calling function pointers. The C
programming language will allow function prototypes to be placed anywhere in source code. The test
engineer can use appendix User Code to add a function prototype with the same return type and input
parameter list that the function pointer is expecting. Normally VectorCAST would not stub this function
because it is not called by the unit under test. But VectorCAST can be forced to stub the prototype
thus giving the ability to control what is passed in to the function pointer and what it returns.

4.2.3 Undefining and redefining pointers to hardware register structures

Hardware registers are usually instantiated as volatile data types. These data types can change their
value at any time without any action being taken by the code. In a unit testing scenario it is very
difficult, if not impossible, to control the values of hardware registers and validate the unit under test
behaves as expected.

A set of hardware registers can be instantiated within a structure with each element of the structure
being a hardware register. In this case each hardware register is a 32 bit register.

typedef volatile struct regs_Base

{
uint32 GCR0; /**< 0x0000 Global Control Register 0 */
uint32 GCR1; /**< 0x0004 Global Control Register 1 */
…
uint32 IODFTCTRL; /**< 0x0090 I/O Error Enable Register */
} regs_BASE_t;

Then a macro is defined to point the structure regs_BASE_t to a hardware address.

#define HW_REGS ((regs_BASE_t *)0xFFF7E000U)

Unit prefix User Code can be used to undefine the macro pointing to the hardware address and
redefine it to another structure that can be set as an input and also check expected values in the test
case editor.

#include "regs.h" /* Include header defineing struct and macro

*/
regs_BASE_t* ptr_Regs; /* Struct to test against.
*/
#undef HW_REGS /* Undefine macro pointing to hw address
*/
#define HW_REGS ptr_Regs /* Redefine to struct to test against
*/

Remember that any User Code that is placed in unit prefix User Code is placed at the beginning of the
unit under test. Therefore, the code entered here becomes part of the unit. The variable ptr_Regs
will now be listed in the Globals section of the test case editor. The test engineer can then set input
values and check expected values just as any other global without the need of the hardware registers.

As you can see User Code gives the test engineer a lot of flexibility during unit testing by allowing
customization of the test harness. The VectorCAST User Guide contains many more examples of
User Code. Other interactive examples can also be accessed via the help menu (Help | Example
Environments)

Copyright © 2020 – Vector Informatik GmbH 5

Contact Information: www.vector.com or +49-711-80 670-0
 VectorCAST User Code

5 Contacts
For support related questions please address to the support contact for your country
https://www.vector.com/int/en/company/contacts/support-contact/.

Copyright © 2020 – Vector Informatik GmbH 6

Contact Information: www.vector.com or +49-711-80 670-0