This topic explains how to use Stub Callbacks for dynamic stubs configuration.
In this section:
Stub Callbacks provide a powerful mechanism for programming test case-specific stub logic. For each test case, you can define specific stub behavior to be performed each time the stub is called during test case execution. C++test automatically generates code that runs the test case-specific stub logic, so you do not need to modify the main stub definition.
You can configure Stub Callbacks in one of the following ways:
Quick Start with Stub Callbacks
Before you create a stub, ensure that the Enable Stub Callbacks option is enabled in the Stubs view (see Configuring Stub Options in the Stubs View) or in your test configuration (see Execution Tab Settings - Defining How Tests are Executed).
Configuring Stub Behavior in the Test Case Editor
- Create a stub for the function you want to configure with the Generate Auto Stub or Create User Stub option (see Adding and Modifying Stubs).
- Open test case in the Test Case Editor.
- Add a new Stub Configuration step and specify the Function you want to configure.
- Define the stub logic using the available Actions and input/output parameters.
- Execute your test cases. When the test case is run, the custom stub logic defined in your Stub Configuration step will be executed when the stub is called.
See Adding Test Suites and Test Cases with the Test Case Editor - Configuring Stub Behavior for more details about configuring stub behavior using the Test Case Editor.
Configuring Stub Behavior in Source Code
Create a stub for the function you want to configure with the Generate Auto Stub or Create User Stub option (see Adding and Modifying Stubs).
- Open test suite file in the Code Editor.
Add a Stub Callback function to the test suite file.
Define the stub logic in the Stub Callback function, using the available input/output parameters.
Navigate to the test case definition and register the Stub Callback using the following macro:
Ensure that the Callback is registered before the function under test is called.
- Execute your test case. When the test case is executed, the stub logic you configured will be executed when the stub is called.
See Stub Callback Details for more information about Stub Callback Function and Stub Callback Registration.
Stub Callback Details
The Stub Callbacks framework consists of the following components:
- Stub Callback Function: a user-defined function that implements the custom stub logic for individual stubs.
- Stub Callback Registration: a mechanism that activates Stub Callback Function, which is typically placed inside a test case.
- Stub Callback Execution: an invocation of Stub Callback Function, which is built into the C++test's stub definition.
Stub Callback Function
The Stub Callback Function is a user-defined C/C++ function that contains logic to be executed when the related stub is called. It has a unique signature derived from the signature of the stub/stubbed function:
The interface of the Stub Callback Function includes all the input/output parameters of the stubbed function (
<STUB_IN_OUT_PARAMETERS>), as well as additional helper parameters (
stubCallInfo). You can also customize the name of the Stub Callback Function (
The following example demonstrates how the Stub Callback Function may be customized for a
int processValues(int i, int j); function:
We recommend that you keep the Stub Callback Function together with the related test case definition in the same test suite file.
You can define the Stub Callback Function as a global function or as a static member function (C++ only) of the test suite class. This allows the Stub Callback Function to access private class members of the code under test when the "Access to private members code" instrumentation feature is enabled.
The custom stub logic can be expressed with any valid C or C++ code using the following Stub Callback interface:
- stubbed function parameters – available as parameters of the Stub Callback Function
- stubbed function return value – available as the "
__return" pointer to the return value holder
- stubbed function class object – available as the "
__this" pointer to the class object
- the current call number of the Stub Callback Function – available as the "
int stubCallInfo->callNo" variable
In addition, you can use a global variable or global function in the Stub Callback Function, including the C++test Unit Testing API (e.g.,
CPPTEST_REPORT). If the original definition of the stubbed function is available, it can also be executed from the Stub Callback Function.
You can define multiple Stub Callback Functions in a Test Suite file — they can correspond to the same stub or a number of different stubs.
One Stub Callback Function can be used in a single test case or shared across a number of different test cases.
A stub can have only one Stub Callback Function active at a time (see Stub Callback Registration).
Stub Callback Registration
For a Stub Callback Function to be active, it must be registered. The function is typically registered inside a related test case before the first call to the stubbed function. In most scenarios, registration should be placed before the call to the function under test.
Use the following API call to register a Stub Callback Function:
<STUB_ID>is the unique stub identifier (see Stub Callback Execution)
<STUB_CALLBACK_NAME>is the name of the user-defined Stub Callback Function
You can register the same Stub Callback Function in mulitple test cases so that each of them will use the same custom logic for a given stub. Also, it is possible to register different Stub Callback Functions (for different stubs) in a single test case. This enables the test case to provide custom behavior for multiple stubs. At any given time, there can be only one Stub Callback Function active for given stub.
The lifetime of a Stub Callback Function:
- activation: registration with
- deactivation: end of a test case or registration of another Stub Callback Function for the same stub (same
Stub Callback Execution
If the Stub Callback Function is defined and registered, it will be executed each time corresponding stub is called. The Callback Function is invoked by calling
, which is automatically added into a stub definition if the "Enable Stub Callbacks" option is enabled when the stub is created (this option is enabled by default).
The Stub Callback invocation section that is automatically added to stub definition contains a default signature of the Stub Callback Function and the exemplary Stub Callback Registration line that can be copied into test suite file when you configure Stub Callbacks manually.
Stub identifiers that are used for Stub Callback Registration and Stub Callback Execution must be unique to identify individual stubs. By default, stubs generated by C++test use identifiers according to the following pattern:
<parent::> prefix is added only if the stubbed function is a class or namespace member. Only the direct parent is added. In the case of template class methods, template parameters are omitted in the parent name.
Using Stub Callbacks for Overloaded Functions
C/C++test uses the same stub identifier for all overloaded versions of the function (see Stub Identifier). Before using Stub Callbacks for overloaded functions, update identifiers used for Stub Callback Execution code (
CPPTEST_STUB_CALLED()) and Stub Callback Registration to ensure they are unique. This will allow you to distinguish stubs for overloaded functions/methods.
The default identifier used for all overloaded versions of foo():
The updated identifier for foo(int):
Creating Stubs that Call the Original Function
C/C++test allows you to generate stubs that call the original function if no test-case specific Stub Callback Function is registered in the test case. To achieve this, enable following options in the Stubs view (see Configuring Stub Options in the Stubs View) or in your test configuration (see Execution Tab Settings - Defining How Tests are Executed):
- Enable Stub Callbacks
- Insert call to original function
With these options enabled, C/C++test will apply the following stubbing strategy:
- If a test case-specific Stub Callback is registered for the currently executed test, the Stub Callback Function will be used to stub the original function.
- If no test case-specific Stub Callback is registered for the currently executed test, the stub will call the original function. As a result, the original function will be called during the test case execution, with the stub acting as a "proxy".
- If no test case-specific Stub Callback is registered for the currently executed test and the the original function is not available, C/C++test will use the custom logic you can specify in the stub definition.
Calling original functions is not supported for the following:
- functions with ellipsis
- pure virtual functions
- functions with internal linkage
- functions that have a deduced return type and are not visible from any header