Specify Test Assessments in Polyspace Platform User Interface

A C/C++ unit test typically calls a function with some inputs and compares the function outputs against expected values. This comparison is called a test assessment.

A test can have one or more assessments, each consisting of two parts:

  • The result that you want to check, for instance, a function return value.

  • The check itself, which consists of a value and a comparator. Typically, the comparator is ==, which means that you are checking if the result is equal to a value. For call count assessments, the default check is to verify that a function is called, in which case the comparator is > and the value is 0u.

Example Files

This tutorial uses the files in the folder polyspaceroot\polyspace\examples\doc_pstest\global_static_vars. Here, polyspaceroot is the Polyspace® installation folder, for instance, C:\Program Files\Polyspace\R2026a. To continue with this tutorial:

  1. Create a new Polyspace Platform project and add the folder to the project.

  2. Select Parse Code on the toolstrip to analyze the files in the folder.

Specifying Test Assessments

In this example, you write a test for the function addToOutliers() that returns a value and writes to a global variable numberOfOutliers:

bool addToOutliers(uint32_t val, uint32_t lim)
{
    if(val > lim)
        {
            numberOfOutliers++;
            return true;
        }
    else
        {
            return false;
        }
}

To write a test for addToOutliers() that assesses both the function return value and the global variable value after the function call:

  1. On the Projects pane, right-click addToOutliers and select Add Test Case.

  2. In the Inputs section of the test, add these values for the input variables:

    • val: 101u

    • lim: 100u

    • numberOfOutliers: 1u

    Inputs section of a test with Value column populated.

    With these input values, the function addToOutliers is expected to return a value true and update the global variable numberOfOutliers to 2u.

  3. In the Assessments section of the test, set the Value and Comparator columns for the assessment variables based on the above expectations:

    • pst_call_out: Set the comparator to == and value to true.

    • numberOfOutliers: Set the comparator to == and value to 2u.

    Assessments section of a test with Value and Comparator column populated.

    Note that if a test has multiple assessments, the failure of one assessment does not stop execution of the remaining test.

  4. Build and run the test to see passing test results.

    For more information on:

Types of Test Assessments

A graphical test in the Polyspace Platform user interface supports direct specification of assessment values for most common cases. The assessments that can be directly specified in the user interface fall into one of these categories:

  • Assessments on variables in the source code, which allow you to verify the expected behavior of a function.

  • Call count assessments, which allow you to verify whether or not a function is called, or compare the number of times a function is called to an expected value

Assessments on Variables with Simple Data Types

For variables with primitive data types, specify appropriate assessment values based on their data types. The data types are listed in the Type column.

  • For integer types such as int and long, specify a number.

  • For character types such as char, specify a single character.

  • For floating-point types such as float and double, specify a number in the Value column and a tolerance in the Tolerance column. If the comparator in your assessment involves an equality operation, the assessment does not check for exact equality but rather checks for equality within the specified tolerance (the default tolerance is 0).

Assessments on Variables with Complex Data Types

You can perform assessments on variables of complex data types such as:

  • Structures

    You can perform assessments on one or more data members of a structure. Specifying assessments on structured outputs is similar to specifying structured inputs. For more information on how to specify data of structured type, see Structures.

    Unlike inputs, you can perform partial assessments on structures. You can disable the assessments for all the structure members that you are not interested in, and assess the remaining members only.

  • Enumerations

    Specifying assessments on enum outputs is similar to specifying enum inputs. For more information on how to specify data of enum type, see Enumerations.

  • Unions

    You can perform assessments on a specific member of a union. Specifying assessments on union outputs is similar to specifying union inputs. For more information on how to specify data of union type, see Unions.

    Similar to inputs, if a union variable being assessed points to test data, you cannot change its member directly. Instead, you have to change the corresponding member of the test data that the variable points to.

  • Pointers

    You can perform assessments on both a pointer and the pointed value. Specifying assessments on pointer outputs is similar to specifying pointer inputs.

    • You can assess if a pointer has the value NULL.

    • You can specify if the pointer points to a buffer with specific values.

    For more details on how to specify pointer targets, see Specify Pointer Targets for C/C++ Test Authoring in Polyspace Platform User Interface.

  • Class objects (C++)

    You can perform assessments on variables of class object types. By default, an assessment is generated for a class object only if the class defines the equality operator operator== as a public member function with the parameter being a const l-value reference to an object of the class type. You can explicitly add an assessment on a class object by using buttons in the Assessments section of a test, but make sure that the comparison in the assessment can actually be performed.

    For more information on how to specify data of class type, see Class Objects (C++).

Function Call Count Assessments

Call count assessments allow you to verify whether or not a function is called, or compare the call count to an expected value. To add a call count assessment for a callee of the code under test in a tabular test step in the Polyspace Platform user interface:

  1. Open the test case in which you want to add a function call count assessment.

  2. Click the Add assessment button next to the Assessments table.

  3. In the Select Test Assessment(s) dialog box, callees of the code under test appear with a scope of fcn call and a type of call count. Select the function calls for which you want to add a call count assessment and click OK.

  4. The functions you select appear as new rows in the Assessments table. By default, the call count assessment verifies that the function is called (call count > 0u). Change the comparator and value as needed. For example:

    • To verify that a function is not called, set Comparator to == and Value to 0u.

    • To verify that a function is called at least five times, set Comparator to >= and Value to 5u.

Limitations.  To add a call count assessment for a function, the function must be supported for mocking. For more information see Limitations on Creating Mocks.

See Also

Topics