Choose Assessment Macro Variant in Polyspace Test xUnit API

The Polyspace® Test™ C/C++ xUnit API provides various kinds of test assessment macros to assess variable values after calling a function under test. Some of these macros are variants of each other, enabling the same assessment but with different functionalities.

For instance, to assess the return value of a function sum() that takes two integer arguments, you can invoke one of these macros:

  • PST_VERIFY(sum(1,1) == 2);

  • PST_VERIFY_EQ_INT(sum(1,1), 2);

  • PST_VERIFY_EQ_INT_MSG(sum(1,1), 2, "Sum of 1 and 1 should be 2.");

This topic helps you choose between similar kinds of assessment macros. For more information on assessment macros, see Assessment Macros in Polyspace Test API for C/C++ Code.

Choose Left/Right Value-Based Assessments over Predicate-Based Assessments

If you have to choose between a macro such as PST_VERIFY and PST_VERIFY_EQ, try to use PST_VERIFY_EQ when possible. Using PST_VERIFY_EQ allows easier diagnosis of test failures. Note that in C++, you can use the same macro PST_VERIFY_EQ to assess variables of all data types. In C, you have to use a typed version of the macro such as PST_VERIFY_EQ_INT and PST_VERIFY_EQ_UINT.

When you use the PST_VERIFY macro, you specify a condition expression, but when you use the PST_VERIFY_EQ macro and analogous macros such as PST_VERIFY_EQ_INT and PST_VERIFY_EQ_UINT, you specify the left side and right side of the condition expression as separate arguments.

During test execution, the PST_VERIFY_EQ macro and analogous macros provide more information on run-time values as compared to the PST_VERIFY macro. You typically need this information to diagnose test failures.

Consider these variations of the same assessment:

  • PST_VERIFY(actual_value == expected_value);

  • PST_VERIFY_EQ_INT(actual_value, expected_value);

When the first assessment fails, you see this message:

Expression 'actual_value == expected_value' evaluated to false

When the second assessment fails, you see this message:

Expression '(actual_value) == (expected_value)' evaluated to false
lhs="lhsValue" rhs="rhsValue"
In this message, lhsValue and rhsValue are the values of the variables actual_value and expected_value at run time.

Choose Assessments with Custom Messages When Needed

If you want to specify a custom message for an assessment failure in addition to the default message, you can use an assessment macro ending with _MSG.

All assessment macros in the Polyspace Test xUnit API have a variant with _MSG appended to the macro name. This variant allows you to specify a custom message in case the assessment fails.

Consider these variations of the same assessment:

  • PST_VERIFY(actual_value == expected_value);

  • PST_VERIFY_MSG(actual_value == expected_value, "Initialized failed.");

When the first assessment fails, you see this message:

Expression '(actual_value) == (expected_value)' evaluated to false

When the second assessment fails, you see this message:

Initialized failed.
Expression '(actual_value) == (expected_value)' evaluated to false

Use the _MSG variant when you need to see the additional message for more guidance on the test failure.

See Also

Topics