Using Test Doubles

Introduction

The Function Double feature provides a means for intercepting C language functions on the target, and directing the call to a substitute function with identical parameters and return value. The use case is a unit test where the function under test uses a ("C") function during its execution, and this dependency is simulated by a substitute or double function during testing. The unit test is able to control the substitution of the dependency during run time, and thereby verify the behavior of the function under test. The following sample illustrates the relationship of the function under test and a dependency:

// depend.h
int depend(int x);

// depend.c
#include "depend.h"
 
int depend(int x)
{
    return x + x;
}

// test.h
int test(int x, int y);

// test.c
#include "test.h"
#include "depend.h"
 
int test(int x, int y)
{
    return depend(x) * y;
}

In the above sample, test() is the function under test and depend() is a dependency candidate for doubling.

The steps required to achieve doubling of a dependency function are as follows:

1. Configure the double parameters using SCL pragmas
2. Create the double intercepts in the IM
3. Switch to/from the double function during runtime

Configuring the Double Using SCL

The syntax of the scl_func and scl_function pragmas have been expanded to include new optional attributes that allow the specification of function interception parameters. If these options are omitted, then the function is not a candidate for doubling.

#pragma scl_function(function-name [,<intercept>])
#pragma scl_func(SUID, function-name [,<intercept>])

<intercept>     = <context>, <name_mangling>, <group_id>
<context>       = “REFERENCE” | “DEFINITION” (case insensitive)
<name_mangling> = “EXPLICIT” | “IMPLICIT” (case insensitive)
<group_id>      = [user defined identifier] (i.e. “^[A-Za-z_]\w*$”)

Context Option

The <context> option in the syntax guide above allows either the "REFERENCE" or "DEFINITION" strings. A "REFERENCE" context means the intercept is made at the function call, i.e., the intercept function is called instead of the dependency. A "DEFINITION" context means that the intercept is made at the function definition, i.e., the intercept function name is equivalent to the dependency name, and and is called in place of the dependency. These options are equivalent to the user and owner delegate options that are in place for generating delegates.

Mangling Option

The <name_mangling> option above allows either the "EXPLICIT" or "IMPLICIT" strings. These settings are used to solve name mangling conflicts within your target source. "EXPLICIT" mangling requires the use of the "imINTERCEPT(<function_name>)" macro, which explicitly mangles the name of "f()" to "__im_f()". This macro is defined in the generated Intercept Module delegate mangling header file (xxxIM.h). Explicit mangling requires Group ID(s) to be defined (#define MyGroupID) in the source file of the caller/callee of the routine to protect against the inclusion of unnecessary defined types. "IMPLICIT" mangling performs no mangling, and requires none of these steps.

Group ID Option

As described in the above mangling option section, a Group ID is required for EXPLICIT mangling. The <group_id> string is specified in the pragma as shown. The Group ID(s) must be defined your source before including the Intercept Module delegate mangling header file (xxxIM.h). Please refer to an example of when and how this is done here.

Dependency Interception

In the above sample, depend() needs to be SCL captured and enabled for interception in a matter to be doubled.

// depend_scl.h
#include "depend.h"

#pragma scl_function(depend, "DEFINITION", "IMPLICIT", "TEST_GROUP")

Creating Double Intercepts in the IM

If a function has been configured as a double candidate using SCL as outlined in the above step, then the next step is to compile and bind using STRIDE build tools and create the IM that contains the intercept for the double function. The options to s2sinstrument have been updated to support the function double feature as follows:

Option	Change	Notes
--default_mode=<mode>[#<group_id>]	Deprecated	Use the new format below.
--default_mode=<mode>	New	Optional. When present, sets the default generation mode. If not present the <mode> is assumed to be “I” for intercept-able functions and “S” for all others. The format of the <mode> is "SPI[T]", where: “S” – stub “P” – proxy “I” – intercept “T” – trace
--mode=<mode>[#<group_id>] (<interface>[,<interface>…])	Deprecated	Use the new format below.
--mode=<mode>(<interface>[,<interface>…])	New	Interface specific generation mode. The <mode> is the same as above. The <interface> is an interface name. This option could be repeated as many times as needed. It overrides any --default_mode option otherwise in effect.

Where the allowed mode combinations are:

S	P	I	T	Notes
X				Generate Stub
	X			Generate Proxy
		X		Generate Intercept for a Function Double (see Note below)
	X	X		Generate Intercept for Dynamic Delegate
		X	X	Generate Intercept for Trace Delegate
	X	X	X	Generate Intercept for a Dynamic Delegate with Tracing

Note: Currently the only option that supports Function Doubles is the "I" option by itself. Any other option combinations will not allow the double substitution at run-time as outlined in the next step. Also note that the absence of any options will default to the "I" option alone per interface.

Once the IM is successfully created alter the source file containing the depend() implementation by incluting the generated strideIM.h:

// depend.c
#include "depend.h"
/* include this */
#define TEST_GROUP
#include "strideIM.h"

int depend(int x)
{
    return x + x;
}

Switching the Double Function During Runtime

The test unit will have access to the following STRIDE runtime macros for substituting a stub function for a double candidate.

srDOUBLE_GET(fn, pfnDbl)
srDOUBLE_SET(fn, fnDbl)

Where:

• fn is the function qualified by scl_function or scl_func as a dependency candidate, as above.
• pfnFbl is a pointer to a object of type srFnDbl_t, declared to hold the current value of the active double function.
• fnDbl is a function that is to be the current active double. The function passed in should always match the signature of the dependency candidate specified by fn.

Note: the initial value of the current active double is always the dependency candidate function.

These macros are defined in the STRIDE runtime header file sr.h. The following example shows how they are used in a C++ test unit:

#include <srtest.h>

extern "C" int depend_dbl(int a) { return a * a; }

class Test: public stride::srTest
{ 
public:

    Test()
    {
        srDOUBLE_GET(depend, &m_depend_dbl);
        srDOUBLE_SET(depend, depend_dbl);
    }

    ~Test()
    {
        srDOUBLE_SET(depend, m_depend_dbl);
    }

    int test1(void) { return test(1, 2); }
    int test2(void) { return test(5, 6); }

private:
   srFnDbl_t m_depend_dbl;
};
 
#ifdef _SCL
#pragma scl_test_class(Test)
#endif