In this section:
In this section:
A test suite is a container for test cases and must be created before test cases can be added:
All test suite data (including test cases) is stored in a test suite file located under the C++test Project directory. This file and other C++test-generated test artifacts should be managed within a Software Configuration Management system.
The updated test suite is ready to be executed.
The new test case will appear in the Test Case Explorer tree and can be executed. See Executing Test Cases, for instructions on running test cases.
The default test case represents a standard test case for a given function. It contains the following steps that will be executed in the order described below when you run the test case:
You can also customize the structure of your test cases. See Working with Steps.
Only test cases created with Test Case Editor (see Creating Test Cases) can be edited with the editor. Automatically generated test cases (see Generating Test Cases), test cases created in the Code Editor, or test cases created with the Test Case Wizard (see Adding Test Suites and Test Cases with the Graphical Test Case Wizard) are not editable with the Test Case Editor.
In the Test Case Editor, each test case is represented by a sequence of steps. During runtime, the steps are executed in order from top to bottom as defined in the Editor. Various steps are available in the Editor that implement a particular functionality:
See Test Case Steps Reference for more details on available Steps.
The default test case uses only a subset of available steps (see Default Test Case). If needed, you can customize a test case to implement a specific scenario by defining the test case flow with various steps configured in the desired order. For example, additional Stubs configuration can be performed prior to executing a sequence of function Calls. Additionally, specific input/output values can be reported.
In the Test Case Editor, click (-) button next to a step. The step will be removed from the test case.
In the Test Case Editor, click on a step handle (four-way arrow) to drag and drop steps into order.
In the Test Case Editor, click on a step handle (four-way arrow) to drag and drop a step while pressing the CTRL key.
You may need to configure stub behavior to implement certain testing scenarios and to ensure a consistent runtime environment. Using the Dynamic Stub Configuration feature, you can place stub configurations directly into the test case definition, so each test case may have its own unique stub configuration. The Test Case Editor provides a dedicated step for stub configuration. You can configure stubs for setting up a desired return value of the stub, switch between stub and original, and more.
If multiple SET RETURN VALUE actions are specified, they will be processed from top to bottom. The last action that meets the condition will take effect.
If the CALL ORIGINAL action is also specified for a given function and condition, it will override the SET RETURN VALUE action and the original function will be called.
For modifying complex type return values, use the CUSTOM ACTION with the approach described in Basic Approach to Working with Complex Types.
Specify stub parameters in the Parameters column using <stub parameter name>=<value> syntax. A semicolon-separated list is also supported. Examples:
paramA=100; paramB=localVar; paramC=ByRef(globalVar) arrayParamD[3]=10 |
If multiple SET PARAMETERS actions are specified for the same parameter, they will be processed from top to bottom. The last action that meets the condition will take effect.
If the CALL ORIGINAL action is also specified for a given function and condition, the original function will be called with modified parameters.
For modifying complex type parameters, use the CUSTOM ACTION with the approach described in the Basic Approach to Working with Complex Types.
(Optional) Specify a condition for custom action execution (Condition column)
Custom action will be represented in C / C++ code using Stubs API as:
CPPTEST_ON_CALL("<Function>")->[If()-><Condition>->]<Parameters> |
This action can be used to manipulate complex type values - as described in the Basic Approach to Working with Complex Types.
When entering values into the Stubs step, C++test will automatically detect the type for constant values, as well as the Parameters API. For other values (variables, expressions), the type of value must be explicitly specified using the Stubs API, e.g., Int(<value>), Float(<value>). This is not required for C++ test cases.
Use the following syntax to define conditions (i.e., SET RETURN VALUE, CALL ORIGINAL, USE CUSTOM ACTION).
<name of stub parameter> <operator> <value> |
Examples:
paramA == 10 (condition will be met if "paramA" stub parameter equals 10) paramB > 100 (condition will be met if "paramB" stub parameter is greater than 100) |
PPTEST_NCALLS <operator> <number of calls> |
Examples:
CPPTEST_NCALLS == 10 (condition will be met for 10th call to stub function) CPPTEST_NCALLS < 5 (condition will be met during the first 4 calls to stub function) |
If().Arg("param1").Greater().Value(10)Simplified and Extended syntax cannot be mixed in a single condition. 
You can use the Parameters step when the testing scenario requires the execution of the same test with a different set of pre- and post-condition values. You can define an arbitrary set of variables in a parameters table. Each variable has its own column with a unique user-assigned name. Parameterized test cases will be executed independently for each row of values.
Variables defined in Parameters can be used in various steps, for example:
Variables from the Parameters table can be accessed using the following Parameters API. These access functions define the parameter type:
CPPTEST_DS_GET_BOOL("<column name with bool values>")CPPTEST_DS_GET_C_STR("<column name with string values>")CPPTEST_DS_GET_FLOAT("<column name with float values>")CPPTEST_DS_GET_INTEGER("<column name with integer values>")Press CTRL+SPACE in the target to access the Parameters API step.
processValue(int,int): input values, expected output, stub return value, number of calls
Use the Reports step to report values from a test case. This step provides a set of reporting functions that will print values of a given type (e.g., CPPTEST_REPORT_INTEGER(), CPPTEST_REPORT_FLOAT(), etc.). The functions are available in the Type drop-down list. After the reporting function is selected, the required parameters appear in the P1-P3 columns.
Alternatively, you can use the Message step to print a simple text message during runtime. This step can be used for outputting traceability identifiers or for debugging purposes.
The output of Reports and Message steps will be printed to the console and can also be included in Unit Testing Reports.
You can add complex logic to a test case using the Code step, which implements a custom C or C++ code snippet. The code snippet can be placed anywhere in the test case definition, but the location of the step is important due to top-to-bottom execution order. The code snippet may use variables defined with preceding Variables steps. Variables introduced by the Code may be reused by subsequent steps.
The Test Case Editor will not validate correctness of the custom code entered into Code step. Syntax errors will be reported during test case execution.
The Test Case Editor provides the following Steps, which can be used as basic building blocks when defining a test case.
Assertions verify the actual values against expected values. They are usually used for checking output values (post-conditions).
Available assertion types can be selected from the drop-down list. For complete list of supported assertion types see Test Case Validation Macros.
The available parameters depend on the assertion type. Press CTRL+SPACE with a parameter field selected for a list of known variables.
<Type>([<P1>, <P2>, <P3>, <P4>]);
The Call step allows you to call a tested function. Multiple Call steps can be used in a single test case to define a sequence of calls. The Test Case Editor will not validate the correctness of call parameters entered.
The Return field is a variable for storing the return value. Leave empty if a return value is not needed. Press CTRL+SPACE for a list of known types.
The Name field is the function name. For a member function, the Name field should also contain an object variable (object.mFunction or object->mFunction). Press CTRL+SPACE for a list of known variables.
You can enter a comma-separated list of parameters in this field. Any valid C / C++ parameter is accepted (constant, variable, expression, etc.). Press CTRL+SPACE for a list of known variables.
<Return> =] <Name>(<Parameters>);
The code field allows you to enter a custom C / C++ code snippet to be executed when running a test case. The code can use symbols already defined in preceding steps. Subsequent steps can use symbols introduced by the Code step. The Test Case Editor will not validate the syntax of entered code.
<Code>
Globals are variable definitions, initializations, and assignments specific to the test suite. Global variables can be used in later test cases. Globals are only available in the Test Suite Editor.
Enter the type of global variable in the Type field (required). Press CTRL+SPACE for a list of known types.
Enter the name of the global variable in the Name field (required). A warning will be reported if multiple variables with the same name are defined.
Enter the initialized value you want assigned to the variable in the Value field. Any valid C / C++ initializer is accepted (constant, expression, etc.). Press CTRL+SPACE for a list of known variables.
<Type> <Name> [= <Value>];
Enter a simple text message into the Message step and it will be printed out during test execution using CPPTEST_REPORT(). The Message step is useful for traceability or debugging purposes. The text will be printed as-is (no variables or expressions allowed) with all quotation marks escaped. 
CPPTEST_REPORT(“<Message>”);
Use the Parameters step to set test parameters. Test cases will be executed for each row in the step independently. Only one Parameters step is allowed in a single test case. Values from the Parameters step can be accessed using the Parameters API. The Parameters step has two modes: Built-in (table) mode and Data Source mode.
Enable the Built-in (table) option to enter values directly in the Parameters editor:
In this mode, each column (A, B, C, etc.) represents a variable, and each row represents a vector of data that will be used during test case execution.
Enable the Data source option and enter the name of an existing data source. Holding down the Control key while pressing the Space key shows the names of available data sources:
After entering the name of data source, the following actions are available:
This mode uses existing data sources that have already been defined, including rows and column names. You can click the Update column names button to display the column names of the existing data sources. Only column names can be displayed when clicking the Update column names button; rows from existing data sources are not displayed in this mode.
N/A
You can set messages in the Reports step that print with runtime values during test execution. This step may be used for printing input / output values or for debugging purposes.
Choose a type of report from the available types in the Type the drop-down-list. For complete list of supported assertion types, see Test Case Validation Macros.
The available parameters depend on the report type. Press CTRL+SPACE for a list of known variables.
<Type>([<P1>, <P2>, <P3>]);
The Stubs step sets the configuration for current test case. This step should be placed before the Call step for which the configuration is intended. See also Configuring Stub Behavior.
The Action field specifies the stub behavior or expectations. Available actions appear in the drop-down list. The following Actions are supported:
Specify the function-identifier for the stub function that the configuration should be applied to in the Function field. Enter a comma-separated sequence of function identifier calls for the EXPECT CALL SEQUENCE action.
Function identifiers are strings used to identify the stub. By default, stubs generated by C++test use identifiers in the following pattern: [parent::]<function_name>. The parent:: prefix is added only if the function/method is a class or namespace member. Only a direct parent is added. In the case of template class methods, template parameters are omitted in the parent name.
C++test uses the same function-identifier for all overloaded versions of the function. If necessary, you may introduce unique function-identifiers for each overloaded stub function by modifying stub definitions. This will allow you to distinguish stubs for overloaded functions/methods.
The available parameters depend on the action type. Press CTRL+SPACE for a list of known variables, Parameters API and Stubs API.
You can specify optional conditions in the Condition field. The available conditions depend on the type of action. Press CTRL+SPACE for a list of known variables, Parameters API, and Stubs API.
/* SET RETURN VALUE */
CPPTEST_ON_CALL("<Function>")[-><Condition>]->Arg("__return")->Assign()-><Parameters>;
/* SET PARAMETERS */
CPPTEST_ON_CALL("<Function>")[-><Condition>]->Arg("<param1>")->Assign()-><value
representation>->Arg("<param2">)->Assign()-><value representation>...
/* CALL ORIGINAL */
CPPTEST_ON_CALL("<Function>")[-><Condition>]->Arg("__callOrig")->Assign()->Int(1);
/* USE CUSTOM ACTION */
CPPTEST_ON_CALL("<Function>")[-><Condition>]-><Parameters>;
/* EXPECT NUMBER OF CALLS */
CPPTEST_EXPECT_NCALLS("<Function>", <Parameters>);
/* EXPECT NUMBER OF CALLS MORE THAN */
CPPTEST_EXPECT_NCALLS_MORE_THAN("<Function>", <Parameters>);
/* EXPECT NUMBER OF CALLS LESS THAN */
CPPTEST_EXPECT_NCALLS_LESS_THAN("<Function>", <Parameters>);
/* EXPECT NUMBER OF CALLS IN RANGE */
CPPTEST_EXPECT_NCALLS_IN_RANGE("<Function>", <Parameters>);
/* EXPECT CALL SEQUENCE */
CPPTEST_EXPECT_CALL_SEQUENCE()->Add("<Function>")->Add("<Function>")... ; |
Use the Variables step to specify variable definitions, initializations, and assignments. Both local and global variables can be added to this step. Variables are usually used to set up input values (preconditions).
The Type field specifies the type of a variable. Leave the field empty to set a global variable. Press CTRL+SPACE for a list of known types.
Enter a name for the variable in the Name field. Names are required. For member variables, the name should also contain the object variable (object.mVariable or object->mVariable). A warning will be reported if multiple variables with the same name are defined. Press CTRL+SPACE for a list of known variables.
Enter a value in the Value field to initialize and assign the value to the variable. Any valid C / C++ initializer is accepted (constant, expression, function call, etc.). Press CTRL+SPACE for a list of known variables.
[<Type>] <Name> [= <Value>];