Test Multi-Input C/C++ Functions Using Multiple Parameters and Parameter Combination Strategies

When to Define Single Test Parameter Versus Multiple Parameters

When authoring a parameterized test for a multi-input function, consider one of these approaches:

This example shows the latter approach to authoring parameterized tests for multi-input functions. You parameterize the function inputs separately, drawing parameter values from separate test data arrays. This approach is simpler than defining a single test parameter combining all inputs because:

However, you cannot always write a multi-parameter test for multi-input functions. For example, if you explicitly enumerate the expected values from a function in your tests, defining a single parameter with all inputs and the expected output is a better strategy. Multi-parameter tests are more useful when you do not need to explicitly enumerate the expected values, for example, when testing the equivalence of two functions.

How to Define Multiple Test Parameters

To author a parameterized test with multiple parameters:

Example Files

Find the files for this tutorial in the folder polyspaceroot\polyspace\examples\doc_pstest\multi_parameter_tests. Copy these files to a writable location and continue the tutorial. Here, polyspaceroot is the Polyspace installation folder, for example, C:\Program Files\Polyspace\R2026a.

Inspect Function Under Test and Requirements

The functions times_n_multi and times_n_add both return the product of their two inputs, which is subject to a saturation at UINT_MAX.

#include <limits.h> 

unsigned times_n_multi (unsigned input, unsigned n) {
    if(n > 10)
        return -1; //Return error for large multipliers
    if(UINT_MAX/n < input)
        return UINT_MAX;
    else
        return input * n;
}

unsigned times_n_add (unsigned input, unsigned n) {
    int i, sum = 0;
    if(n > 10)
        return -1; //Return error for large multipliers
    for (i = 1; i <= n; i++) {
        if(input > UINT_MAX - input) {
            sum = UINT_MAX;
            break;
        }
        else {
            sum += input;
        }
    }
    return sum;
}

Save this function in a file example.c.

Suppose you have to test that the functions times_n_multi and times_n_add are indeed functionally equivalent, that is, they return the same value for the same inputs. You have to perform this test for these values of the function inputs:

You can combine corresponding values of input and n (sequential testing) or combine each value of input with all values of n (exhaustive testing).

Write Test

This test defines two test parameters for the two function inputs, input and n, and combines corresponding values of input and n when testing. In other words, the testing follows a sequential parameter combination approach:

#include <pstunit.h>
#include <limits.h>

unsigned times_n_multi (unsigned input, unsigned n);
unsigned times_n_add (unsigned input, unsigned n);

int input_data_sequential[] = {(UINT_MAX - 1),  (UINT_MAX/2 - 1), 
   (UINT_MAX/3 - 1), (UINT_MAX/4 - 1)};
int n_data_sequential[] = {1, 2, 3, 4};

PST_PARAM_WITH_VALUES(input_param, unsigned, pst_format_param_uint, input_data_sequential, 4);
PST_PARAM_WITH_VALUES(n_param, unsigned, pst_format_param_uint, n_data_sequential, 4);

PST_SIMPLE_TEST_CONFIG(test_multi_add_equivalence) {
    PST_ADD_PARAM(input_param);
    PST_ADD_PARAM(n_param);
    PST_PARAM_COMBINATION_SEQUENTIAL();
}

PST_SIMPLE_TEST_BODY(test_multi_add_equivalence) {
    PST_VERIFY_EQ_UINT(
              times_n_multi(*PST_PARAM_PTR(input_param),*PST_PARAM_PTR(n_param))
              ,
              times_n_add(*PST_PARAM_PTR(input_param),*PST_PARAM_PTR(n_param))
              );
}

PST_REGFCN(myRegFcn) {
    PST_ADD_SIMPLE_TEST(test_multi_add_equivalence);
}

#ifndef PSTEST_BUILD
int main(int argc, char *argv[]) {
    PST_REGFCN_CALL(myRegFcn);
    return PST_MAIN(argc, argv);
}
#endif

Save this code in a file test_sequential.c.

The test consists of these macros from the Polyspace Test xUnit API:

The remaining macros, PST_REGFCN, PST_ADD_SIMPLE_TEST, and PST_REGFCN_CALL, register the test.

Execute Test and Inspect Results

Compile the files example.c and test_sequential.c along with files shipped with Polyspace Test, as usual:

gcc example.c test_sequential.c <PSTUNIT_SOURCE> -I <PSTUNIT_INCLUDE> -o testrunner

Run the test executable:

testrunner.exe

Since the test data contains four values, you see the results of four tests. Since the functions under test are functionally equivalent, you see that all tests pass.

|        |  Total | Passed | Failed | Incomplete
|--------|--------|--------|--------|------------
| Suites |      1 |      1 |      0 |          0
|  Tests |      4 |      4 |      0 |          0

Further Exploration: Exhaustive Parameter Combination

Instead of combining corresponding values of test parameters input_param and n_param, you can follow an exhaustive parameter combination approach by combining each value of input_param with all values of n_param.

In this example, replace PST_PARAM_COMBINATION_SEQUENTIAL() with PST_PARAM_COMBINATION_EXHAUSTIVE(). When you run the test, you execute 16 test cases. The macro combines each value of input_param with all four values of n_param.