Generating Test Suites

A test suite is a container for test cases and must be created before test cases can be added:

1. Choose Parasoft> Show View> Test Case Explorer to open the Test Case Explorer view.
2. Choose a project in the Test Case Explorer tree.
3. Choose Parasoft> Test Using> Builtin> Unit Testing> Generate Test Suites to generate empty test suites for the project.
   You can also add an empty test suite manually by right-clicking on a project or folder in the Test Case Explorer and choosing Add New> Test Suite.

Test Suite Data Storage

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.

Editing Test Suites

1. Double-click a test suite in the Test Case Explorer tree to open the Test Suite Editor.
2. Click in a field of the Globals editor to configure global variables for the test suite (see Test Case Steps Reference, for more details). These variables be used in test cases later.

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

4. Choose File> Save to save test suite after changes

The updated test suite is ready to be executed.

Creating Test Cases

1. Open the Test Case Explorer and right-click on a test suite
2. Choose Add New> Test Case using Editor…
   
   
   
   
   
3. When prompted, enter test case name and click OK; an empty Test Case Editor opens
4. Choose a function from the Create test case for drop-down list.
5. Click one of the (+) buttons to open a default test case for the selected function:
   Create new test case ()- creates a new test case for the selected function
   Create new parameterized test case ()- 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).
6. Review and modify input values (Variables) and expected output values (Assertions); see Default Test Case, for more information on the structure of the default test case
7. Save the test case to add it to the test suite

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.

Default Test Case

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:

1. Variables: All required input values (pre-conditions) will be set. Input values include global variables, local variables (parameters to tested function), and test object (when testing member functions). By default, standard values for a given type (0, null, default constructor, etc.) will be used as input values to be reviewed/modified by the test case author.
2. Call: The tested function will be called using pre-condition values set in the Variables step.
3. Assertions: The actual output values will be compared against expected values (post-conditions). Output values include function return value, global variables, and member variables (when testing member functions). By default, standard values for a given type (0, null etc.) will be used as expected values to be reviewed/modified by the test case author.

You can also customize the structure of your test cases. See Working with Steps.

Editing Test Cases with the Test Case Editor

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.

1. Open the Test Case Explorer view and double-click a test case.
2. Modify the test case structure or specific parameters (see Working with Steps).
3. Choose File> Save to save your changes to the test case.

Restoring the Test Case Code

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.

1. Open the Test Case Explorer view, and right-click a test case.
2. Select the Update test case code option.

This option is also available from the test suite and project level.

Working with Steps

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:

• Assertions: verify post-condition values
• Call: call tested function
• Code: insert custom code snippet
• Message: specify messages to be printed out during test execution
• Parameters: enable test case parameterization
• Reports: report test case values
• Stub Configuration: configure stubs
• Stub Expectations: configure sequence or expected number calls
• Stubs (Deprecated): configure stubs
• Variables: set-up input values

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.

Adding a New Step

1. In the Test Case Editor, choose a step from the Add new drop-down menu
   
   
   
2. Click (+) button; the new step will be appended to the test case
3. Click and drag steps to reorder them as needed

Removing an Existing Step

In the Test Case Editor, click (-) button next to a step. The step will be removed from the test case.

Reordering Steps

In the Test Case Editor, click on a step handle (four-way arrow) to drag and drop steps into order.

Duplicating Steps

In the Test Case Editor, click on a step handle (four-way arrow) to drag and drop a step while pressing the CTRL key.

Copying Steps from Another Test Case

1. Open two Test Case Editor windows and place them side-by-side.
2. Click on a step handle (four-way arrow) and drag the step from one editor to the other.

Configuring Stub Behavior

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 configuration specified in a Stub Configuration step affects only stub calls whose execution is configured in the test case steps that follow. Stub calls that result from steps preceding the Stub Configuration step do not perform the configured actions.
• If more than one Stub Configuration step is added for the same stub, the stub call will use the configuration specified in the Stub Configuration step directly preceding the stub.
• The Stub Expectations step should precede all the test case steps for which the expectations are defined. This ensures that all the calls are counted.
• If more than one Stub Expectations step is added to the test case, expectations configured in each of the steps will apply.

Additional Details about Stub Behavior Configuration

• The stub function must be auto-generated or manually created using C++test 10.3 or later to configure stub behavior.
• Available stub functions are presented in the Stubs view (Parasoft> Show View> Stubs).
• Stub functions that are not configured in a test case (with Stub Configuration and Stub Expectations steps) will behave according to the stub definition (auto-generated stub will return default value: 0, false, null).
• Stub Configuration steps must be placed before the Call step that the stub configuration is intended to use.

Configuring the Stub Configuration Step

The Stub Configuration step allows you to configure stub behavior using the Stub Callbacks framework.

1. Complete the Function field with the stub function name or press Ctrl + Space to display the list of available stubs and select the stub you want to configure. C++test will automatically display the stub function interface next to the Function field.
   
   
   
2. Enable an edit mode for defining stub behavior:
   

   Table – (default) opens the configuration table specifying parameters

   Code – opens the code editor for scripting stub behavior

   
   If stub behavior is defined in both edit modes, the currently selected mode will be used during test case execution.

Configuring Stub Behavior in the Table

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.

Action Types

The following action types are available:

• Setting a value. Select the SET VALUE type and specify a variable name in P1 and a value in P2. You can define this action for stub parameters, return values (*__return), global variables and the members of the class the stubbed function belongs to.
• Function calls. Select the CALL FUNCTION type and specify the variable name in P1, the function name in P2 and the function parameters in P3.
• Assertions. Specify the assertion parameters required for the selected assertion type (suggestions are displayed for each assertion type). The assertion types that can be selected from the drop-down menu are identical with the assertions that are configurable in the Assertions step (see the C++test User Guide for the list of available assertions).  All supported assertion types can be added manually in the Stub Configuration Code mode; see Configuring Stub Behavior in Code. You can define this action to check value of stub parameters, parent object (__this), global variables, and the members of the class the stubbed function belongs to.

Call-specific Parameters

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:

• The position of a parameter in the sequence corresponds to the stub call number during execution. In the above example, the values 2, 37, and 14 will be used in the first, second and third stub call respectively.
• If an action is configured with call-specific parameters, it will be performed only for the corresponding number of stub calls, unless the last parameter is an ellipsis (see below). In the above example, the action will only be performed for the first, second and third stub call, even if the overall numbers of calls to the stub is higher.

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:

• {3, 5, 7} – a sequence of 3 integer parameters
• {56.3, 5.22, 7.99, 0.77} – a sequence of 4 floating point parameters
• {foo(1), goo(2), boo(3,45)} – a sequence of 3 function call parameters

Configuring Stub Behavior in Code

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 first stub call verifies if the a and b parameters equal 0, and the stub returns the value 123
• all other stub calls verify if the a and b parameters equal 1, and the stub returns the value 10

Configuring the Stub Expectations Step

The Stub Expectations step allows you to configure the following expectations for the stub function calls:

• Expect exact number of function calls
• Expect number of calls to be more than specified vale
• Expect number of calls to be less than specified value
• Expect number of calls to be in a specified range
• Expect sequence of stub calls

To configure the Stub Expectations Step:

1. Complete the Action column by selecting the action type form the drop-down menu.
   
2. Complete the Function column with the function name.
3. Complete the Parameters column with the parameters. You can follow the suggestions that are automatically displayed when the action type is selected.
   

The Expect Call Sequence Action

The Expect Call Sequence action helps you ensure that the specified stub functions are in the desired order.

• It monitors only the stubs that are provided in the Function column and ignores any other functions. For example, the Expect Call Sequence in the following example will match the runtime sequence [foo1, foo4, foo5, foo2, foo7, foo3], as the foo4, foo5 and foo7 functions are ignored.
  
• The specified sequence can be encountered more than once. For example, no errors will be reported for the runtime sequence [foo1, foo2, foo2, foo1, foo2, foo3].
• If at least one occurrence of the specified sequence is incomplete, errors will be reported. For example, the following sequence will report errors, because the second occurrence of the sequence is unfinished: [foo1, foo2, foo2, foo1, foo2].

Supported Stub Behavior Configuration Actions

Modifying value of stub parameters, return value, global variables, parent class members

1. Add the Stub Configuration step for given function (or select existing one).
2. Select SET VALUE from the drop-down list in the Action column.
3. Complete the P1 column with the variable name that will be assigned with the value. Use *__return to modify the return value.
4. Specify the value in the P2 column.

Checking value of stub parameters, the parent object (__this), global variables, parent class members

1. Add the Stub Configuration step for given function (or select existing one).
2. Select CPPTEST_ASSERT from the drop-down list in the Action column.
3. Specify the expected value in the P1 column.
4. Specify the actual value (variable name) in the P2 column.
5. Specify additional values in P3 or P4 column if needed.

Calling original function (for functions with original definition available)

1.  Add the Stub Configuration step for given function (or select existing one).
2. Select CALL FUNCTION from the drop-down list in the Action column.
3. Complete the P1 column with the *__return variable that will be assigned with the value.
4. Complete the P2 column with the function name.
5. Complete the P3 column with the original function parameters.

Configuring expected number of calls

1. Add the Stub Expectations step.
2. Select EXPECT NUMBER OF CALLS from the Action drop-down list
3. Specify a function name in the Function column - be sure stub function exists
4. Specify the expected number of calls in the Parameters column

Configuring expected call sequence

1. Add the Stub Expectations step.
2. Select EXPECT CALL SEQUENCE from the Action drop-down list
3. Specify a sequence of function names (comma separated) in the Function column - be sure stub functions exist

Defining custom action on stub call

1. Add the Stub Configuration step for given function (or select existing step).
2. Enable the Code edit mode.
3. In the Code editor, provide code that modifies stub behavior.

Adding Test Case Parameterization

Parameterization 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:

• by creating a new test case using the Create new parameterized test case option (see Using Data Sources to Parameterize Test Cases); this will add the Parameters step to the test case and automatically update the test case with the default values,
• by manually adding a Parameters step to an already existing test case.

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.

Example

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.

Configuring the Parameters Step

The following options are available to configure the Parameters step:

• Built-in (table) radio button - adds a table for specifying parametrization values to your test case
• Data source radio button - defines an external data source for specifying parametrization values
• Create new data source icon- creates a new external data source
• Edit data source icon - opens the data source
• Open data source file icon - opens an existing data source file
• Update column names icon - displays the column names
• Parameterize test case... icon - opens the dialog that allows you to:
  - customize the column naming pattern for the data source
  - automatically update the test case with the values from the columns that match the pattern (see Parameterizing the Test Case)

Parameterizing the Test Case

To parameterize the test case with values specified in the data source you've added:

1. Click the Parameterize test case... icon to open the Test Case Editor dialog.
   
   
   
2. Specify the column naming pattern. The pattern must include the following:
   - {CONTEXT} - the context where the value obtained from the column will be used. The following contexts are available:
         V indicates the Variables step
         A indicates the Assertions step
         SV indicates the SET VALUE action type in the Stub Configuration step
         SA indicates an assertion in the Stub Configuration step
   - {TYPE} - the data source macro that will be used to obtain the value. The following data types are available:
         I indicates CPPTEST_DS_GET_INTEGER
         F indicates CPPTEST_DS_GET_FLOAT
         S indicates CPPTEST_DS_GET_CSTR
         C indicates CPPTEST_DS_GET_CHAR
         B indicates CPPTEST_DS_GET_BOOL
         U indicates CPPTEST_DS_GET_UINTEGER
         M(<size>) indicates CPPTEST_DS_GET_MEM_BUFFER
         E(<type>) indicates CPPTEST_DS_GET_ENUM
   - {VARIABLE} - the name of the variable
     
   The default is {CONTEXT}#{TYPE}#{VARIABLE} (see Example).
   
   
       
3. Click OK. The test case will be updated with values specified in the data source columns that match the pattern.

Reporting Values and Messages

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.

Inserting Custom Code Snippets

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.

Test Case Steps Reference

The Test Case Editor provides the following Steps, which can be used as basic building blocks when defining a test case.

Assertions

Assertions verify the actual values against expected values. They are usually used for checking output values (post-conditions). 

Type

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.

P1, P2, P3, P4 (Additional Parameters)

The available parameters depend on the assertion type. Press CTRL+SPACE with a parameter field selected for a list of known variables.

Corresponding C / C++ Code

<Type>([<P1>, <P2>, <P3>, <P4>]);

Call

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. 

Return

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.

Name

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.

Parameters

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.

Corresponding C / C++

<Return> =] <Name>(<Parameters>);

Code

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.  

Corresponding C/C++ Code

<Code>

Globals

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.

Type

Enter the type of global variable in the Type field (required). Press CTRL+SPACE for a list of known types.

Name

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.

Value

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.

Corresponding C / C++ Code

<Type> <Name> [= <Value>];

Message

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.  

Corresponding C / C++ Code

CPPTEST_REPORT(“<Message>”); 

Parameters

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.

Built-in (table) 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.

Data Source Mode

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:

• Update column names: loads column names of specified data source. Loaded column names will be listed in a Parameters step.
• Create new data source: if the name entered does not match an existing data source, a new data source will be created with the name
• Edit data source: opens the data source editor for the specified data source
• Open data source file: opens data source file for specified CSV or Excel data source

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.

Corresponding C / C++ Code

N/A

Reports

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. 

Type

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.

P1, P2, P3 (Additional Parameters)

The available parameters depend on the report type. Press CTRL+SPACE for a list of known variables.

Corresponding C / C++ Code

<Type>([<P1>, <P2>, <P3>]);

Stub Configuration

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.

Action

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:

• SET VALUE: modifying the value; this action can be defined for stub parameters, return values, global variables and the members of the class the stubbed function belongs to.
• CALL FUNCTION: specifying the function called.
• CPPTEST_ASSERT: (assertions): verifying actual output values against expected values; the specific assertion type can be selected from the drop-down menu (the available assertions are identical with the assertions that are configurable in the Assertions step; see Test Case Validation Macros for the list of available assertions).

P1, P2, P3 (Additional Parameters)

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.

Table/Code Mode

The Table and Mode radio buttons enable a desired edit mode for defining stub behavior:

• Table – (default) opens the configuration table specifying parameters
• Code – opens the code editor for scripting stub behavior

Stub Expectations

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.

Action

The Action field specifies the expectation type. The available types appear in the drop-down list. The following Actions are supported:

• EXPECT NUMBER OF CALLS: configuring expected number of calls
• EXPECT NUMBER OF CALLS MORE THAN: configuring expected number of calls
• EXPECT NUMBER OF CALLS LESS THAN: configuring expected number of calls
• EXPECT NUMBER OF CALLS IN RANGE: configuring expected number of calls
• EXPECT CALL SEQUENCE: configuring expected call sequence

Functions

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.

Parameters

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.

Stubs (Deprecated)

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.

Action

The Action field specifies the stub behavior or expectations. Available actions appear in the drop-down list. The following Actions are supported:

• SET RETURN VALUE: modifying return value (for simple types only)
• SET PARAMETERS: modifying stub parameters
• CALL ORIGINAL: calling original functions
• USE CUSTOM ACTION: performing custom action on stub call
• EXPECT NUMBER OF CALLS: configuring expected number of calls
• EXPECT NUMBER OF CALLS MORE THAN: configuring expected number of calls
• EXPECT NUMBER OF CALLS LESS THAN: configuring expected number of calls
• EXPECT NUMBER OF CALLS IN RANGE: configuring expected number of calls
• EXPECT CALL SEQUENCE: configuring expected call sequence

Function

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.

Parameters

The available parameters depend on the action type. Press CTRL+SPACE for a list of known variables, Parameters API and Stubs API.

Condition

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.

Corresponding C / C++ Code

/* 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>")... ;

Variables

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

Type

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.

Name

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.

Value

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.

Corresponding C / C++ Code

[<Type>] <Name> [= <Value>];

Deprecated Stubs Step Configuration Actions

Modifying Return Value for Functions Returning Simple Type Values

1. Select SET RETURN VALUE from the Action drop-down list
2. Specify a function name in the Function column - be sure that the stub function exists
3. Specify the return value in the Parameters column
4. (Optional) Specify condition for when the value should be returned (Condition column)

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.

Modifying Stub Parameters for Simple Type Values

1. Select SET PARAMETERS from the Action drop-down list
2. Specify a function name in the Function column - be sure that the stub function exists

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

4. (Optional) Specify condition for when the parameters should be modified (Condition column)

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.

Calling Original Function for Functions with Original Definition Available

1. Select CALL ORIGINAL from the Action drop-down list
2. Specify a function name in the Function column - be sure stub function exists
3. (Optional) Specify a condition for when the original function should be called (Condition column)

Configuring Expected Number of Calls

1. Select EXPECT NUMBER OF CALLS from the Action drop-down list
2. Specify a function name in the Function column - be sure stub function exists
3. Specify the expected number of calls in the Parameters column

Configuring Expected Call Sequence

1. Select EXPECT CALL SEQUENCE from the Action drop-down list
2. Specify a sequence of function names (comma separated) in the Function column - be sure stub functions exist

Defining Custom Action on Stub Call

1. Select USE CUSTOM ACTION from the Action drop-down list
2. Specify function name in the Function column - be sure stub function exists
3. Specify custom actions in the Parameters column - the action is defined with the Stubs API -for more details, see Using Stubs API (deprecated).

4. (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.

About C Test Cases

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.

Syntax for Defining Conditions

Use the following syntax to define conditions (i.e., SET RETURN VALUE, CALL ORIGINAL, USE CUSTOM ACTION).

Simplified Syntax

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

Extended Syntax

• Stubs API can be used to build complex conditions; see Using Stubs API (deprecated).
  Example:
  If().Arg("param1").Greater().Value(10)

Simplified and Extended syntax cannot be mixed in a single condition.