Set Global and Static Variables in Polyspace Platform User Interface

A C/C++ function can interact with the remainder of the program by reading or modifying function parameters, by returning a value, or by reading or modifying global variables. Of these, global variables can be the trickiest to handle when testing the function. To avoid unexpected test results, it is recommended that you start from a known state of global variables and after the test, reset to this state.

This tutorial shows various ways of setting global variables to a known state when authoring tests in the Polyspace^® Platform user interface.

Example Files

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

Create a new Polyspace Platform project and add the folder to the project.
Select Parse Code on the toolstrip to analyze the files in the folder.

Set Global Variables

You can set global variables before a test in one of two ways:

Set global variables as inputs in the Polyspace Platform user interface.
Set global variables in a function and call this function in a dedicated initialized step at the beginning of each test (and optionally again in a final step at the end of each test).

Setting global variables in the Polyspace Platform user interface is simpler but requires having to perform this step for each test. On the other hand, if you set global variables in a function once, you can simply call this function from each test.

Set Global Variables in Polyspace Platform User Interface

Consider the function addToOutliers():

uint32_t numberOfOutliers;

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

Write a test that initializes the global variable numberOfOutliers to a known value in a test step:

On the Projects pane, right-click addToOutliers and select Add Test Case.
In the Inputs section of the test, note that the Value column for the global variable numberOfOutliers shows <<default>>. This indicates that the global variable is initialized to a default value. The default value in the first test step is based on C initialization rules: 0 for int, 0.0 for double, and so on. In a later step, the value of the global variable is the one retained from previous step. If you set the global variable in the setup section of a test, the default value is the value specified during test setup. For more information on test setup, see Set Global Variables in Initialization Step.
Other possible entries in this column are:
- <<undefined>>: This means that the global variable is not defined in the code. To assign a default value to the global variable, select Code Explorer on the Polyspace Platform toolstrip. On the Code pane, locate the variable under the Undefined Symbols node and right-click the variable to generate a stub with a default value. For more information about stubs, see Test Functions with Undefined Callees in Polyspace Platform User Interface.
- <<default stub>>: This means that the global variable is not defined in the code but in a stub.
In the Inputs section of the first test step, enter the following values:
- val: 11u
- lim: 10u
- numberOfOutliers: 2u
In the Assessments section of the first test step, enter the following values (leaving the comparator to ==):
- pst_call_out: true
- numberOfOutliers: 3u

You can now build and run the test, and see passing test results. For more information, see Build and Run Tests in Polyspace Platform User Interface.

Set Global Variables in Initialization Step

Instead of entering the initial values of global variables individually in each test, you can set these initial values in a dedicated initialization function. You can reuse an initialization function already present in your source code or author an initialization function in your code editor or IDE (and save the file containing the function separately from your sources since this file will be used only for testing).

Write a test that uses a dedicated initialization function to set/reset the global variable numberOfOutliers:

Add a folder containing a file with an initialization function as a test artifact to the project:
1. On the Projects pane, right-click the Test Artifacts node of the project and select Add Stub Source Folder.
  This section of a project is typically used for adding folders that contain files with function stubs. However, you can use it for adding definitions of helper functions for testing.
2. Add the folder polyspaceroot\polyspace\examples\doc_pstest\global_static_vars\test_helpers.
  This folder contains a file init_helpers.c containing a function set_globals(), which sets the global variable numberOfOutliers to a known value 2u.
```
#include "../src/decls.h"
#include "init_helpers_decls.h"

extern uint32_t numberOfOutliers;

void set_globals(void) {
    numberOfOutliers = 2u;
}
```
Open the project configuration. On the Projects tab, add the path polyspaceroot\polyspace\examples\doc_pstest\global_static_vars\test_helpers to the Include paths option.
This folder contains a header init_helpers_decls.h that contains a declaration of the set_globals() function.
Write a test for the addToOutliers() function and initialize the global variable using the set_globals() function added earlier:
1. On the Projects pane, right-click addToOutliers and select Add Test Case.
2. Expand the Preambles, Setup, Teardown section and enter the following:
  - Preamble:
    #include "init_helpers_decls.h"
  - Setup:
    set_globals();
  - Teardown:
    set_globals();
  In general, if you use a symbol in the Setup or Teardown section, you must declare it in the Preamble section of the test.
3. In the Inputs section of the first test step, enter the following values:
  - val: 11u
  - lim: 10u
  - numberOfOutliers: Leave the value to <<default>>. In this case, the global variable has the value 2u based on the value specified in the initialization function set_globals().
4. In the Assessments section of the first test step, enter the following values (leaving the comparator to ==):
  - pst_call_out: true
  - numberOfOutliers: 3u

You can now build and run the test, and see passing test results. For more information, see Build and Run Tests in Polyspace Platform User Interface. The setup and teardown ensures that the initialization function is invoked before test execution to initialize the global variables and after test execution to reset the values.

Set File-Scope Static Variables

A file-scope static variable is similar to a global variable but it can be accessed only in the file in which it is declared. Such variables are declared with the static keyword. When authoring tests for a function that reads or updates a file-scope static variable, you can leave the static variable out of the test or explicitly set its value.

Consider the increment() function:

static uint32_t var = 1;

uint32_t increment(int32_t arg) {
    if (arg > 0) {
         var++;
    }
    return var;
}

Write a test that verifies that the static variable is updated correctly after the function call:

On the Projects pane, right-click increment and select Add Test Case.
By default, the static variable var does not appear in the test. This means:
- The value of var is set to 1 before the function increment() is called.
  In the more general case, the value depends on previous functions called in the test or other functions in the source file that update the static variable. It is not guaranteed to be set to the value at initialization.
- There is no assessment on the value of var after the function call.
To add the static variable in the Inputs or Assessments section, click the button in the section header. Then select the variable var@global_static_vars.c (since multiple static variables with the same name can occur in different files, each static variable is identified in the list by its file name).
In the Inputs section of the first test step, enter the following values:
- arg: 2
- var@global_static_vars.c: 2u
In the Assessments section of the first test step, enter the following values:
- pst_call_out: 3u
- var@global_static_vars.c: 3u