Page History

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). 

• definition: Sequence of calls to the Stubs API that define expected stub behavior
• args: Sequence of arguments passed to stub behavior execution
• func-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>. The parent:: 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 against 0 and report reports a problem message if parasm1 is equal to 0.
• 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.

...

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:

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:

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:

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:

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);

1. Enable the call to original function:

   Code Block
   [C++] CPPTEST_ON_CALL("foo").Arg("__callOrig").Assign(1);

   
   

   [C] CPPTEST_ON_CALL("foo")->Arg("__callOrig")

   →Assign

   ->Assign()

   →Int

   ->Int(1);

2. 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 to 0, 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

   ->Arg("__callOrig")

   →Assign

   ->Assign()→Int(1);

Example 2: Modifying Stub Return Value

...

int foo(int param1, int param2);

1. 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);

   
   

   [C] CPPTEST_ON_CALL("foo")->Arg("__return").Assign()

   →Int

   ->Int(5);

   
   

2. You can enforce the return value depending on the stub parameter value. In the following example, the returning integer value 5

   for

    for the calls to the stub where parameter param1 is equal to the integer value 0 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);

   
   

   [C] CPPTEST_ON_CALL("foo")->If()->Arg("param1")->Equal()

   →Int

   ->Int(0)

   →
   Arg

   ->Arg("__return")->Assign()

   →Int

   ->Int(5);

3. 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.

[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);

1. You can assign a value to the stub call parameter. In this example, the integer value 1

   is

    is assigned to the stub call parameter param1

   Code Block
   [C++] CPPTEST_ON_CALL("foo").Arg("param1").Assign(1);

   
   

   [C] CPPTEST_ON_CALL("foo")->Arg("param1")->Assign()

   →Int

   ->Int(1);

2. You can assign a value to the parameter depending on another parameter. In this example, the integer value 1

   is

    is assigned to param2

   if

    if the value of param1

   is

    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

   ->Arg("param2")->Assign()

   →Int

   ->Int(1);