This topic explains how to add user-defined stubs to replace calls to resources that you cannot (or do not want to) access during testing, as well as how to modify automatically-generated stubs. See Stubs for background information about stubs and how they help you test software during the development. 

Sections include:

About Stubs

...

Viewing Stubs in the Stubs View

The Stubs view provides details on the stub configuration based on the most recent run of a unit testing Test Configuration. It allows you to modify the configuration by adding user-defined stubs or automatically generating stubs for missing symbols.

Accessing the Stubs View

To Choose Parasoft> Show View> Stubs to access the Stubs view:

...

.

Understanding the Stubs View

...

• Symbol: Function or global variable name.
• Definition: The current definition/stub type:
  • User: User provided definition/stub will be is used.
  • Safe: C++test's safe definition/stub will be is used.
  • Original: Original definition will be is used.
  • Auto: C++test's auto definition/stub will be is used.
  • N/A (not required): Definition is not available, not needed by the linker.
  • N/A: Definition is not available, but is needed by the linker (in most cases, this will result in a linker error when building the test executable).
• Location: Location of the current definition (source file, library, N/A if not found).

Updating

The content in the Stubs view updates its contents is updated based on data collected during unit testing , and in response to specific actions available from the Stubs view (i.e., Create User Stub, Generate Auto Stub). Note that it does not update its contents contents won't be updated in response to external actions that you perform (, such as manually adding/removing stubs, etc.).

Unused Definitions

The Stubs view presents information about the most-recently used stub configuration, as well as other available (but not used) definitions. For instance, it shows information about the existing original definitions for functions with that have user-defined stubs defined. Such definitions display For these types of definitions, (not used) is displayed in the 'Definition' column—for column, for example: Original (not used). To hide such definitions in the Stubs view, click the Filter button in  in the Stubs view tool bar , then check and enable the Hide unused definitions option.

Multiple Definitions

If a single function has more than one stub definition (for example, if there are two user stub definitions for a particular function), then the Stubs view will show both of them, but place an stubs. An error mark will appear on the stub icon and display (conflict) in the    the 'Definition' column—for column, for example: User (conflict).

Collecting/Refreshing Symbols Data

Anchor
Collecting/Refreshing Symbols Data Collecting/Refreshing Symbols Data

...

1. In the project tree, select the files to be tested.
2. Run a Test Configuration that will build the test executable (for example, the "Collect Stub Information" or "Build Test Executable" Test Configuration).

Anchor
Configuring Stub Options in the Stubs View Configuring Stub Options in the Stubs View

Configuring Stub Options in the Stubs View

The Stubs view allows you to specify the location where auto-generated stubs will be saved, as well as enable or disable a desired mode of dynamic stub configuration (see Dynamic Stubs Configuration):

1. Go to the Stubs View menu and select Stub settings.... to open the configuration dialog.
   Image Added
2. Specify the location where auto-generated stubs will be saved in the Auto-generated stubs output location field.
   Image Added
   
   
3. Enable or disable the following modes of dynamic stubs configuration:
   • Enable Stub Callbacks - if enabled, the Stub Callbacks mechanism will be used for dynamic stubs configuration; enabled by default (see Using Stub Callbacks for details)
   • Enable Stub API (deprecated) - if enabled the stub API will be used for dynamic stubs configuration (see Dynamic Stubs Configuration for details)

Tips for Using the Stubs View

...

To add user-defined stubs by creating and then editing a wizard-generated stub file:

1. If you have not already done so, create a new directory for your stubs.

   • The stubs directory can be located anywhere within the project. By default, C++test expects stubs to be stored in a subdirectory of the project’s stubs directory. However, you can use a different location as long as you modify the Test Configuration’s Use extra symbols from files found in setting (in the Execution> Symbols tab) accordingly.

     Tip

     If you do not want to store your stubs within the project directory, you can add a folder that links to files stored elsewhere in your file system. To do this:           a. Choose File> New> Folder (if this is not available, choose File> New> Other, select General> Folder, then click Next).           b. Click the Advanced button.           c. Enable the Link to folder in file system option.           d. Enter or browse to the location of your source files.           e. Click Finish.

2. Open the Stub Wizard in one of the following ways:
   • In the Stubs view, right-click the function for which you want to create a stub , then choose and choose Create User Stub.

   • Select your stubs directory in the project tree ,rightand right-click the selection, then choose New> Other from the shortcut menu. A wizard will open. Select C++test> User stub, then click Next.Then, in In that wizard’s functions table, select the function for which you want to create a stub , and click click Next.

   Note
   title Note
   The "Symbols data not collected" warning indicates that the required symbols data was not yet collected. See Collecting/Refreshing Symbols Data for details on how to collect/update symbols data. The "No symbols to create stubs for" warning indicates that there are no known functions for which user-defined stubs can be created.

...

1. Enter a name and location for the new stub file in the User Stub File dialog. 
2. Click Finish. The user-defined stub file will

...

1. be created

...

1. and opened in the code editor. C++test will

...

1. automatically add the appropriate definition and the

...

1. required #include

...

1.  directives.

     4. Click Finish. The stub file will be automatically opened in the editor.

...

1. Examine/modify the stub definition and/or #include

...

1.  directives as needed.

...

1. Save the modified file.

...

Additional Information About User-defined

...

Stubs

• Can be created for multiple functions at once. To do this, select multiple functions in the table, then right-click the selection and choose Create User Stub from the shortcut menu. All user stubs will be added to the same stub file.
• Can be created for any function.
• Have the highest priority. A user-defined stub will be used even if the original definition is available.
• Cannot be created for global variables. Auto Stubs should be used instead.

Adding User-Defined Stubs to an Empty Stub File

...

1. Open the Stub Wizard in one of the following ways:
   • In the Stubs view, right-click the function for which you want to create a stub, then choose Create User Stub.

   • Select your stubs directory in the project tree,right-click the selection, then choose New> Other from the shortcut menu. A wizard will open. Select C++test> User stub, then click Next.  Then, in that wizard’s functions table, select the function for which you want to create a stub, and click Next.

2. Do not make any selection in the functions table (in order to create an empty stub file).
3. Click Next.
4. Enter the stub file name/location.
5. Click Finish. The stub file will be automatically opened in the editor.

6. Create a stub template by typing stub, placing your cursor immediately after the "b" in "stub", pressing Ctrl+ Space, then choosing the appropriate template (either a standard stub template for a C or C++ function, or a constructor/destructor stub template).
   
   
   
   

7. Insert the appropriate values for the  ret_type, scope, and name, parameters.
   • Note that C++test’s stubs (except for constructor stubs) take the same values as the original functions.
     
     

  8. Enter the stub body/definition.

...

 9. Save the modified file.

    void example(Base* ptr)     
    {
	// ...
	ptr->doSth();  // (*) 
	// ...
   }

...

Generating Stubs for Symbols with Missing Definitions

To generate an Auto Stub file for a symbol with missing definitions:

...

Right-click the function in the table

...

and choose Generate Auto Stub

...

 from the shortcut menu

...

to generate an Auto Stub file for a symbol with missing definitions. An Auto Stub file will be created and opened in the editor. C++test will automatically add the appropriate definition and required #include directives.

...

Auto Stubs...

...

You can also create Auto Stubs for multiple symbols at

...

the same time:

1. Select multiple functions in the table

...

1. and right-click the selection

...

2. Choose Generate Auto Stub from the shortcut menu. All Auto Stubs will be added to the same stub file.

...

You can also create Auto Stubs for symbols without available definitions. For other symbols, use User Stubs instead. 

...

Auto Stubs have the lowest priority. An Auto Stub will not be used if any other definition is available.

Understanding and Customizing Automatically-Generated Stubs

Anchor
Understanding and Customizing Automatically-Generated Stubs Understanding and Customizing Automatically-Generated Stubs

...

You can readily configure automatically-generated stubs either through the dynamic stubs configuration API (see Dynamic Stubs Configuration) or by using the Test Case Editor Stubs step (see Working with Steps).

...

1. Open the related stub file, which is saved in the location indicated in the Test Configuration’s Auto-generated stubs output location (in the Execution> Symbols tab).
2. Modify the ret_type, scope, name, and parameters as needed.

   • Note that C++test’s stubs (except for constructor stubs) take the same values as the original functions. 

     • You can use the Tab key to move between ret_type, scope, name, and parameters.

...

1. Modify the stub body/definition as needed.

1. User-defined stubs can interact with C++test API functions as described in C++test API Functions for User-Defined Stubs.

...

1. Save the modified file

...

1. and rerun the analysis.

Disabling Automatically-Generated Safe Stubs

...

This function allows you to query the currently executed test case. It will return true if the specified id equals the name of the currently executed test case, otherwise it will return false. This feature is useful for functions that use conditional statements based on the external function calls. See Functions for Stubs Driven by Test Cases for an example.

bool CPPTEST_DS_HAS_COLUMN(const char* name) 

...

These functions get the name of the currently-executed test case and test suite. Using these functions, you can write a stub that applies to a specific test case from a specific test suite.

See Functions for Stubs Driven by Test Cases for  for an example.

Using Data Sources in Stubs

Anchor
Using Data Sources in Stubs Using Data Sources in Stubs

...

See Using Different Tests and/or Stubs for Different Contexts.

Using Dynamic Stubs Configuration

See Dynamic Stubs Configuration.

Using Stubs Driven By Test Cases

Anchor
Using Stubs Driven By Test Cases Using Stubs Driven By Test Cases

...