Using Test Doubles: Difference between revisions
(New page: =Function Double= 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 param...) |
|||
(53 intermediate revisions by 4 users not shown) | |||
Line 1: | Line 1: | ||
__NOTOC__ | |||
The '' | The ''Test Double'' feature provides a means for intercepting C/C++ language '''global 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 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: | The following sample illustrates the relationship of the function under test and a dependency: | ||
Line 6: | Line 6: | ||
// depend.h | // depend.h | ||
int depend(int x); | int depend(int x); | ||
</source> | |||
<source lang="c"> | |||
// depend.c | // depend.c | ||
#include "depend.h" | #include "depend.h" | ||
Line 14: | Line 17: | ||
return x + x; | return x + x; | ||
} | } | ||
</source> | |||
<source lang="c"> | |||
// test.h | // test.h | ||
int test(int x, int y); | int test(int x, int y); | ||
</source> | |||
<source lang="c"> | |||
// test.c | // test.c | ||
#include "test.h" | #include "test.h" | ||
Line 28: | Line 37: | ||
</source> | </source> | ||
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: | The steps required to achieve doubling of a dependency function are as follows: | ||
#[[# | #[[#Configuring the Double Using Function Pragma | Configuring the Double Using Function Pragma]] | ||
#[[#Creating_Double_Intercepts_in_the_IM|Create | #[[#Creating_Double_Intercepts_in_the_IM|Create Double Intercepts in the IM]] | ||
#[[#Switching_the_Double_Function_During_Runtime|Switch | #[[#Switching_the_Double_Function_During_Runtime|Switch Double Function During Runtime]] | ||
The syntax of the | ==Configuring the Double Using Function Pragma== | ||
The syntax of the [[Scl_function|function pragma]] supports a set of '''''optional''''' attributes that allow the specification of function interception parameters. When captured for the purpose of interception ('''intercept-able''') the optional arguments are '''required'''. | |||
#pragma scl_function(function-name [,context, name-mangling, group-id]) | |||
Refer to the actual [[Scl_function | function pragma]] definition for an explanation of | |||
* '''context''' - set to ''DEFINITION'' or ''REFERENCE'' | |||
* '''name-mangling''' - set to ''EXPLICIT'' or ''IMPLICIT''. Note if set to explicit requires usage of the ''srTEST_INTERCEPT'' macro | |||
* '''group-id''' - user defined to enable or disable interception | |||
In the above sample, ''depend()'' needs to be captured via the pragma and enabled for interception in the following manner. | |||
<source lang="c"> | |||
// depend_scl.h | |||
#include "depend.h" | |||
#pragma scl_function(depend, "DEFINITION", "IMPLICIT", "TEST_GROUP") | |||
</source> | |||
==Creating Double Intercepts in the IM== | ==Creating Double Intercepts in the IM== | ||
If a function has been configured as a double candidate using | If a function has been configured as a double candidate using the function pragma as outlined in the above step, the [[Build_Tools|Stride Build Tools]] will automatically create the [[Intercept Module]], aka IM, that contains the intercept for the double function. This all happens automatically during the build process. | ||
But to enable the interception the source file containing the <tt>depend()</tt> implementation '''must be altered''' to [[Name_Mangling|mangle the function's name]] by defining the Group ID and including the generated Intercept Module header file (xxxIM.h): | |||
| | |||
<source lang="c"> | |||
// depend.c | |||
#include "depend.h" | |||
/* define the Group ID before including the IM header */ | |||
#define TEST_GROUP | |||
#include "strideIM.h" | |||
int depend(int x) | |||
{ | |||
return x + x; | |||
} | |||
</source> | |||
==Switching the Double Function During Runtime== | ==Switching the Double Function During Runtime== | ||
In the context of the test unit code the following STRIDE runtime macros, defined in the STRIDE runtime header file '''srtest.h''', could be used for substituting a stub function for a double candidate. | |||
<source lang="c"> | <source lang="c"> | ||
srDOUBLE_SET(fn, fnDbl) | srDOUBLE_SET(fn, fnDbl) | ||
srDOUBLE_RESET(fn) | |||
srDOUBLE_GET(fn, pfnDbl) // used for more advanced scenarios | |||
</source> | </source> | ||
Where: | Where: | ||
*'''fn''' is the function qualified by scl_function or scl_func as a dependency candidate, as above. | *'''fn''' is the function qualified by <tt>scl_function</tt> or <tt>scl_func</tt> as a dependency candidate, as above. | ||
*''' | *'''pfnDbl''' is a pointer to a object of type <tt>srFunctionDouble_t</tt>, 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'''.'' | *'''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. | '''''Note:''''' the initial value of the current active double is always the dependency candidate function. | ||
=== Example 1 === | |||
The following example shows how to double a routine for the lifetime of a C++ Test Unit: | |||
<source lang="cpp"> | <source lang="cpp"> | ||
#include <srtest.h> | #include <srtest.h> | ||
#include "depend.h" | |||
extern "C" int | extern "C" int depend_dbl(int a) { return a * a; } | ||
class Test: public stride::srTest | class Test: public stride::srTest | ||
Line 162: | Line 118: | ||
Test() | Test() | ||
{ | { | ||
srDOUBLE_SET(depend, depend_dbl); | |||
srDOUBLE_SET(depend, | |||
} | } | ||
~Test() | ~Test() | ||
{ | { | ||
srDOUBLE_RESET(depend); | |||
} | } | ||
int test1(void) { return test(1, 2); } | int test1(void) { return test(1, 2); } | ||
int test2(void) { return test(5, 6); } | int test2(void) { return test(5, 6); } | ||
}; | }; | ||
#ifdef _SCL | #ifdef _SCL | ||
#pragma scl_test_class(Test) | #pragma scl_test_class(Test) | ||
#pragma scl_function(depend, "DEFINITION", "IMPLICIT", "TEST_GROUP") | |||
#endif | #endif | ||
</source> | </source> | ||
=== Example 2 === | |||
The following example shows how to make a call to the original routine in the context of a double by safely handling any nested doubling: | |||
<source lang="c"> | |||
#include <srtest.h> | |||
#include "depend.h" | |||
extern "C" int depend_dbl(int a) | |||
{ | |||
int ret; | |||
srFunctionDouble_t fn; | |||
srDOUBLE_GET(depend, &fn); | |||
srDOUBLE_RESET(depend); | |||
ret = depend(a); | |||
srDOUBLE_SET(depend, fn); | |||
return ret; | |||
} | |||
</source> |
Latest revision as of 20:08, 6 July 2015
The Test Double feature provides a means for intercepting C/C++ language global 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 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:
- Configuring the Double Using Function Pragma
- Create Double Intercepts in the IM
- Switch Double Function During Runtime
Configuring the Double Using Function Pragma
The syntax of the function pragma supports a set of optional attributes that allow the specification of function interception parameters. When captured for the purpose of interception (intercept-able) the optional arguments are required.
#pragma scl_function(function-name [,context, name-mangling, group-id])
Refer to the actual function pragma definition for an explanation of
- context - set to DEFINITION or REFERENCE
- name-mangling - set to EXPLICIT or IMPLICIT. Note if set to explicit requires usage of the srTEST_INTERCEPT macro
- group-id - user defined to enable or disable interception
In the above sample, depend() needs to be captured via the pragma and enabled for interception in the following manner.
// 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 the function pragma as outlined in the above step, the Stride Build Tools will automatically create the Intercept Module, aka IM, that contains the intercept for the double function. This all happens automatically during the build process.
But to enable the interception the source file containing the depend() implementation must be altered to mangle the function's name by defining the Group ID and including the generated Intercept Module header file (xxxIM.h):
// depend.c
#include "depend.h"
/* define the Group ID before including the IM header */
#define TEST_GROUP
#include "strideIM.h"
int depend(int x)
{
return x + x;
}
Switching the Double Function During Runtime
In the context of the test unit code the following STRIDE runtime macros, defined in the STRIDE runtime header file srtest.h, could be used for substituting a stub function for a double candidate.
srDOUBLE_SET(fn, fnDbl)
srDOUBLE_RESET(fn)
srDOUBLE_GET(fn, pfnDbl) // used for more advanced scenarios
Where:
- fn is the function qualified by scl_function or scl_func as a dependency candidate, as above.
- pfnDbl is a pointer to a object of type srFunctionDouble_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.
Example 1
The following example shows how to double a routine for the lifetime of a C++ Test Unit:
#include <srtest.h>
#include "depend.h"
extern "C" int depend_dbl(int a) { return a * a; }
class Test: public stride::srTest
{
public:
Test()
{
srDOUBLE_SET(depend, depend_dbl);
}
~Test()
{
srDOUBLE_RESET(depend);
}
int test1(void) { return test(1, 2); }
int test2(void) { return test(5, 6); }
};
#ifdef _SCL
#pragma scl_test_class(Test)
#pragma scl_function(depend, "DEFINITION", "IMPLICIT", "TEST_GROUP")
#endif
Example 2
The following example shows how to make a call to the original routine in the context of a double by safely handling any nested doubling:
#include <srtest.h>
#include "depend.h"
extern "C" int depend_dbl(int a)
{
int ret;
srFunctionDouble_t fn;
srDOUBLE_GET(depend, &fn);
srDOUBLE_RESET(depend);
ret = depend(a);
srDOUBLE_SET(depend, fn);
return ret;
}