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:
What if the test case-specific stub logic is not defined?
Each C++test's stub has its default logic built into the stub definition – typically, a stub only returns simple/default return values. If a stub does not have a Stub Callback Function defined, C++test will use the default logic when the stub is called. If a Stub Callback Function is configured, it will have precedence over the default logic (for example, it will overwrite return values and modify the in-out parameters).
Quick Start with Stub Callbacks
Stub Callbacks require the Enable Stub Callbacks 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.
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.
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
CPPTEST_CALL_STUB_CALLBACK(), 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 the full 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++test uses the same stub identifier for all overloaded versions of the function. Before using Stub Callbacks for overloaded functions, update identifiers used for Stub Callback Execution code (
CPPTEST_CALL_STUB_CALLBACK()) 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):