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.
In the Additional Test Suite Code editor, configure predefined insertable code sections that can be added to your test suite code.
By default, the following code section can be configured:
- Additional Includes - additional include files
- TestSuiteSetUp - the definition (body) of the test suite setUp() function
- TestSuiteTearDown - the definition (body) of the test suite tearDown() function
- TestCaseSetUp - the definition (body) of the test case setUp() function
- TestCaseTearDown - the definition (body) of the test case tearDown() function
You can add other code sections by following begin/end markers to your test suite:
/* CPPTEST_TEST_SUITE_CODE_BEGIN CodeSectionIdentifier *//* CPPTEST_TEST_SUITE_CODE_END CodeSectionIdentifier */
Ensure that the names (identifiers) of the code sections you configure are unique. |
For example, if you add the following markers to a test suite:
/* CPPTEST_TEST_SUITE_CODE_BEGIN NewIncludes2 */ //This is a user-configured code section. /* CPPTEST_TEST_SUITE_CODE_END NewIncludes2 */ |
the new Code section will appear in the drop-down menu:
The updated test suite is ready to be executed.
)- creates a new test case for the selected function
)- creates a new parameterized test case for the selected function; you can parameterize the test case with values obtained form a data source table built into the test case or from an external data source (see Using Data Sources to Parameterize Test Cases).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.
Test cases created in the Test Case Editor should not be modified outside of it. If a test case has been modified manually, you can restore the code generated in the Test Case Editor.
This option is also available from the test suite and project level.
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. You can manually modify test case source code using the Stub Callbacks framework (see Using Stub Callbacks for details) or use the interface of the Test Case Editor. The Test Case Editor provides dedicated steps for stub configuration – Stub Configuration and Stub Expectations – for setting up a desired return value of the stub, switch between stub and original, and more.
The steps defined in the Test Case Editor are executed from top to bottom. For this reason, it is essential to ensure that the steps are configured in the desired order:
The information about configuring the deprecated Stubs step is available in the Deprecated Stubs Step Configuration Actions section. |
The Stub Configuration step allows you to configure stub behavior using the Stub Callbacks framework.
Stub Callbacks require the Enable Stub Callbacks option to be enabled in the Subs 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. |
Table – (default) opens the configuration table specifying parameters
Code – opens the code editor for scripting stub behavior
The Table mode allows you to define actions that will be performed during test case execution. The actions are configured in separate table rows and executed from top to bottom.
Complete the Action column by selecting the action type form the drop-down menu.
Then complete the P1-P4 columns with the required parameters. You can follow the suggestions that are automatically displayed when the action type is selected.
The following action types are available:
(*__return), global variables and the members of the class the stubbed function belongs to.(__this), global variables, and the members of the class the stubbed function belongs to.You can specify stub behavior for individual calls of the same stub by defining call-specific parameters. Call-specific parameters must be provided as a comma-separated list of parameters in curly brackets:
You can configure an action to be performed for any number of stub calls by adding an ellipsis (…) as the last parameter in the sequence. As a result, the last value explicitly specified in the sequence will be used for all the following stub calls.
In the following example the values 2 and 37 will be used in the first and second stub call respectively, while 14 will be used for the third call, as well as for any number the following calls to the stub:
If a stub action is parameterized with more than one set of call-specific parameters, both sets must have the identical number of values. In the following example, both call-specific sets contain two values:
The parameter value can be any value that is appropriate in the given context, for example:
The Code mode allows you to provide snippets of code that configure stub behavior.
You can use all functions of the C++test API, including Assertions, for configuring stub behavior in code.
You can specify stub behavior for individual calls by using stubCallInfo->callNo and providing call-specific values. The example below shows a stub configured in the following way:
The Stub Expectations step allows you to configure the following expectations for the stub function calls:
To configure the Stub Expectations Step:
The Expect Call Sequence action helps you ensure that the specified stub functions are in the desired order.
If multiple SET VALUE actions are specified, they will be processed from top to bottom. It they are specified for the same parameter, the last action will take effect. |
(__this), global variables, parent class membersParameterization allows you to execute the same test with a different set of pre- and post-condition values. You can define an arbitrary set of variables in a built-in table or in an external data source, such as a CSV file. Each variable has its own column with a unique user-assigned name. Parameterized test cases will be executed independently for each row of values.
You can add test case parametrization in one of the following ways:
The variables you define in the Parameters step can be used in other steps, for example, as initializers of pre-condition variables (Variables step), as expected post-condition values (Assertions step), as stub configuration parameters (Stubs step). The other steps can access the variables by using the Parameters API. The following data source macros are available:
CPPTEST_DS_GET_BOOL("<column name with bool values>")CPPTEST_DS_GET_CSTR("<column name with string values>")CPPTEST_DS_GET_FLOAT("<column name with float values>")CPPTEST_DS_GET_INTEGER("<column name with integer values>")CPPTEST_DS_GET_CHAR ("<column name with char values>")
CPPTEST_DS_GET_UINTEGER("<column name with unsigned integer values>")
CPPTEST_DS_GET_MEM_BUFFER ("<column name with buffer data>", "<size of data>")
CPPTEST_DS_GET_ENUM ("<enum type name>", "<column name with enum values>")
Press CTRL+SPACE in the target to access the Parameters API step.
Only simple type values are supported by the Parameters Step.
The following example shows a parameterized test case for processValue(int). The values specified in the built-in table are applied in the Variables, Stub Configuration, and Assertions steps using a data source macro and the column name.
The following options are available to configure the Parameters step:
To parameterize the test case with values specified in the data source you've added:
CPPTEST_DS_GET_INTEGERCPPTEST_DS_GET_FLOATCPPTEST_DS_GET_CSTRCPPTEST_DS_GET_CHARCPPTEST_DS_GET_BOOLCPPTEST_DS_GET_UINTEGERCPPTEST_DS_GET_MEM_BUFFERCPPTEST_DS_GET_ENUM The default is {CONTEXT}#{TYPE}#{VARIABLE} (see Example).
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 a complete list of supported assertion types see Test Case Validation Macros. All supported assertion types can be added manually in the Code section; see Code.
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 report types, see Test Case Report Macros.
The available parameters depend on the report type. Press CTRL+SPACE for a list of known variables.
<Type>([<P1>, <P2>, <P3>]);
The Stub Configuration step allows you to configure stub behavior for the 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 action type that configures stub behavior. The available actions appear in the drop-down list. The following Actions are supported:
The P1, P2, P3 and P4 fields allow you to specify the parameters for selected action types. Parameters depend on the action type. You can follow the suggestions that are automatically displayed when the action type is selected. Press CTRL+SPACE for a list of known variables.
The Table and Mode radio buttons enable a desired edit mode for defining stub behavior:
The Stub Expectations step allows you to configure the expected number and sequence of stub calls. This step should be placed before the Call step for which it is configured. See also Configuring Stub Behavior.
The Action field specifies the expectation type. The available types 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 Parameters fields allow you to specify the parameters for selected action types. Parameters depend on the action type. You can follow the suggestions that are automatically displayed when the action type is selected.
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>];
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.
