Info |
---|
Stub API require the Enable Stub API option to be enabled in the Stubs view (see Configuring Stub Options in the Stubs View) or directly in your test configuration (see Execution Tab Settings - Defining How Tests are Executed) before the stub is created. |
You can dynamically configure stub behavior for specific requirements associated with the Stub behavior can be dynamically configured to specific requirements for a test case. Stub configuration is defined in source code using the dedicated API. You can specify a stub configuration at test suite setup/teardown, test case setup/teardown, and inside the test case. A stub configuration created inside a test case is removed immediately after test case execution. Similarly, with a stub configuration specified inside test case and test suite setup()
functions, it is removed just after executing respective teardown()
functions.
User definition of the -defined stub behavior is internally represented by “trigger objects.” When you define a trigger object, it accumulates your specified set of operations, values, and arguments references. Triggers perform defined operations when they are executed. The execution of trigger objects is supplemented with real values for the arguments referenced by name at the time of trigger object definition. The following table presents macros used to specify and execute stub behavior definition (trigger objects).
Macro | Definition |
---|---|
CPPTEST_ON_CALL(func-id)[definition]<definition> | Defines stub behavior (creates trigger object). Typically specified in the test case body. |
CPPTEST_AFTER_CALL(func-id)[definition]<definition> | Defines additional (optional) stub behavior executed only after the original function/method call was made from the stub (creates trigger objects). Typically specified in the test case body. |
CPPTEST_ACTUAL_CALL(func-id)[args]<args> | Executes defined behavior for the stub. Always located inside the stub. |
CPPTEST_ACTUAL_AFTER_CALL(func-id)[args]<args> | Executes defined behavior for the original function/method call post-processing. Always located inside the stub. |
definition
: Sequence of calls to the Stubs API that define expected stub behaviorargs
: Sequence of arguments passed to stub behavior executionfunc-id
: String used to identify the stub. By default, stubs generated by C++test use identifi-ers identifiers according to the following patterpattern:[parent <parent::]<function><function_name>.
Theparent::
prefix is added only if the function/method is a class or namespace member. Only the direct the parent is added. In the case of template class methods, template parameters are omitted in the parent name.
C++test uses the same stub function-identifier for all overloaded versions of the function. If needed, you may introduce unique stub function-identifiers for each overloaded stub function by modifying stub definitions. This will allow you to distinguish stubs for overloaded functions/methods.
...
In this example, the stub for function foo()
performs the following behaviors:
- Test Tests the value of
param1
against0
and report reports a problem message ifparasm1
is equal to0
. - Assign Assigns an integer value of
3
to the__return
trigger argument, which represents a variable returned from the stub.
...
- Operators used to invoke chains of methods/functions when defining stub behavior are different for C and C++. The C++ version of the API uses the dot operator (.), while the C version uses the arrow operator (→)
- When specifying a value in stub behavior definition, the C version requires the use of type-dedicated methods for passing values, while the C++ version allow allows for the use of a single overloaded method.
...
API method | Description |
---|---|
Arg(const char *argName) | Argument is determined by its The argument name provided as character string. The name used in Example: [ |
ArgByExpr() | Argument The argument is determined by evaluating the subsequent expression, which should have a const char * type. Example:
It is assumed that {
|
Stubs generated by C++test use the following naming convention for default arguments:
- Parameters of the stub Stub parameters (reflecting parameters of stubbed function/method) are available by the names name as specified in the original function/method declaration
- Variable Variables used for returning value values from the stub is are available under the name
__return
- Variable Variables used as a condition conditions to redirect the call calls to original symbol definition is definitions are available by the name
__callOrig
...
Values for the operations in the stub behavior definition can be provided “by value” or “by reference”. Functionally, this is reference,” which is functionally the same concept as in C/C++. When an lvalue behavior is expected, the value that is passed value must be wrapped with a call to the ByRef()
function. It is not necessary to wrap a value with ByRef()
in situations where an rvalue semantic is expected.
It is typically preferable to pass variables by reference if an assignment is expected or if the evaluation of real value should be deferred until the time stub is executed. See example below:
Code Block | ||
---|---|---|
| ||
extern int global; |
...
[By Value] CPPTEST_ON_CALL("foo").Arg("param1").Assign(global); |
...
[By Reference] CPPTEST_ON_CALL("foo").Arg("param1").Assign(ByRef(global)); |
In the first example, the value assigned to param1
will be copied when the CPPTEST_ON_CALL
definition is processed. Any further changes to the real value of the global variable will not be reflected when performing an assignment.
...
There is an important difference when specifying the values for stub behavior definition in C and in C++ mode. In C mode, the value specification must always be wrapped with a type-specific function. For example:
Code Block | ||
---|---|---|
| ||
CPPTEST_ON_CALL("foo")->Arg("param2") |
...
->Assign() |
...
->Float(1.5); |
...
CPPTEST_ON_CALL("foo")->Arg("param3")->Assign() |
...
->VoidPtr(ptr); |
Wrapping functions are provided for all simple types. For a full list, refer to ? Stubs API Reference. In C++ mode, values can be provided without wrapping functions. In all the situations where value specification is required, you can use a generic “Value” function, which is overloaded for all simple types. For simpler notation, overloaded versions of “operator-methods” accept the value directly. This is shown in the examples below:
Code Block | ||
---|---|---|
| ||
CPPTEST_ON_CALL("foo").Arg("param1").Assign().Value(1); |
...
CPPTEST_ON_CALL("foo").Arg("param1").Assign().Value(1.77); |
...
CPPTEST_ON_CALL("foo").If().Arg("p1").Greater().Value(1.77).Arg("p2").Assign(0); |
Simpler notation using overloaded “operator” methods:
Code Block | ||
---|---|---|
| ||
CPPTEST_ON_CALL("foo").Arg("param1").Assign(1); |
...
CPPTEST_ON_CALL("foo").Arg("param1").Assign(1.77); |
...
CPPTEST_ON_CALL("foo"().Arg("p1").Greater(1.77).Arg("p2").Assign(0); |
The following section discusses typical use cases or the Stubs API.
...
int foo(int param1, int param2);
Enable the call to original function:
Code Block [C++] CPPTEST_ON_CALL("foo").Arg("__callOrig").Assign(1);
→Assign[C] CPPTEST_ON_CALL("foo")->Arg("__callOrig")
→Int->Assign()
->Int(1);
You can also enable calls to the original function depending on the parameter value. If a stub will be called with parameter
param1
set equal to0
, then the original function will be called. In all other cases the original function will not be called:Code Block [C++] CPPTEST_ON_CALL("foo").If().Arg("param1").Equal(0).
Arg("__callOrig").Assign(1);
→[C] CPPTEST_ON_CALL("foo")->If()->Arg("param1")->Equal()->Int(0)
Arg
→Assign->Arg("__callOrig")
->Assign()→Int(1);
Example 2: Modifying Stub Return Value
...
int foo(int param1, int param2);
You can enforce the returning integer value 5 for all calls to the stub.
Code Block [C++] CPPTEST_ON_CALL("foo").Arg("__return").Assign(5);
→Int[C] CPPTEST_ON_CALL("foo")->Arg("__return").Assign()
->Int(5);
You can enforce the return value depending on the stub parameter value. In the following example, the returning integer value
for5
for the calls to the stub where parameter
param1
is equal to the integer value0
is enforced. For all other cases, the default value is returned (0
for numerical types).Code Block [C++] CPPTEST_ON_CALL("foo").If().Arg("param1").Equal(0).
Arg("__return").Assign(5);
→Int[C] CPPTEST_ON_CALL("foo")->If()->Arg("param1")->Equal()
→->Int(0)
Arg
→Int->Arg("__return")->Assign()
->Int(5);
You can call the original function and modify return values. In the following example, the original function is called and the return value is modified to the integer value of 5.
Code Block [C++] CPPTEST_ON_CALL("foo").Arg("__callOrig").Assign(1).
Arg("__return").Assign(5);
→[C] CPPTEST_ON_CALL("foo")->Arg("__callOrig")->Assign()->Int(1)
Arg->Arg("__return")->Assign()->Int(5);
Example 3: Checking Stub Call Parameters’ Values
...
int foo(int param1, int param2);
Test to determine if the stub call parameter param1
is equal to 0
. If not, the test fails with the provided message.
Code Block |
---|
[C++] CPPTEST_ON_CALL("foo").If().Arg("param1").NotEqual(0). |
...
Fail("Incorrect param value"); |
...
[C] CPPTEST_ON_CALL("foo")->If()->Arg("param1") |
...
->NotEqual() |
...
->Int(0) |
...
->Fail("Incorrect param value"); |
Example 4: Modifying Stub Call Paramters’ Values
As in the previous example, you can assign values for the stub call parameters. Typically, this scenario is used when a call to the original function/method is requested.
...
int foo(int param1, int param2);
You can assign a value to the stub call parameter. In this example, the integer value
is1
is assigned to the stub call parameter
param1
Code Block [C++] CPPTEST_ON_CALL("foo").Arg("param1").Assign(1);
→Int[C] CPPTEST_ON_CALL("foo")->Arg("param1")->Assign()
->Int(1);
You can assign a value to the parameter depending on another parameter. In this example, the integer value
is1
is assigned to
ifparam2
if the value of
isparam1
is equal integer value
0
.Code Block [C++] CPPTEST_ON_CALL("foo").If().Arg("param1").Equal(0).
Arg("param2").Assign(1);
→[C] CPPTEST_ON_CALL("foo")->If()->Arg("param1")->Equal()->Int(0)
Arg
→Int->Arg("param2")->Assign()
->Int(1);