-pstunit-test

Option to specify a test the input of which is used for static analysis

Syntax

-pstunit-test <myTest>


Description

-pstunit-test <myTest> specifies that Polyspace^® must use the input of the test myTest when running static analysis on C/C++ tests and functions under test.

When authoring tests, you write a test that calls one or more function under test, build the test to create an executable, and finally run the executable to obtain test results for specific inputs. If your function under test or any of the tests contain a run-time error, the test results are unreliable and you can have sporadic test failures. You can check if the test inputs cause any run-time errors by running Polyspace Code Prover™ and Polyspace Bug Finder™ on your test and the functions called by the test. If you have multiple tests, Polyspace considers the inputs of all tests when running the static analysis. To run the static analysis using the inputs of a specific test, use this option to specify the test.

In the user interface (Polyspace desktop products only), on the Configuration pane, enter this option in the Other field. See Other.

Examples

Run Static Analysis Using Inputs from Single Test in Test Suite

The function times_two accepts an integer and returns the doubled value of the input. A test suite tests this function using three different inputs INT_MAX, 10, and 1.

• Code under test:

  int times_two(int x) {
      return 2*x;
  }

• Tests written using the Polyspace xUnit API:

  #include <limits.h>
  #include <pstunit.h>
  
  extern int times_two(int); 
  
  PST_SUITE(mySuite);
  
  PST_TEST(mySuite, test1) {
      int input = INT_MAX;
      PST_VERIFY_EQ_INT(times_two(input)-input, input);
  }
  
  PST_TEST(mySuite, test2) {
      int input = 10;
      PST_VERIFY_EQ_INT(times_two(input)-input, input);
  }
  
  PST_TEST(mySuite, test3) {
      int input = 1;
      PST_VERIFY_EQ_INT(times_two(input)-input, input);
  }

For the input INT_MAX, the multiplication overflows and the function returns an undefined value. Even if the test passes initially, a sporadic failure can occur later because of the overflow. To detect such issues, run a Code Prover analysis on the function and tests.

Copy the function times_two() in example.c and the tests in test.c. At the command line, run a Code Prover verification by using the input of the test muSuite/test1:

polyspace-code-prover -sources example.c,test.c -library pstunit -I "<polyspaceroot>\polyspace\pstest\pstunit\include" -pstunit-test "mySuite/test1"

The analysis checks the functions under test in the file example.c using the input INT_MAX. Here, <polyspaceroot> is the Polyspace installation folder, for instance, C:\Program Files\Polyspace\R2025a.

Once the verification finishes, Polyspace reports a red runtime error that is caused by the input of the test mySuit/test1. To avoid run-time errors, modify the function times_two() so that the multiplication operation does not result in an overflow.