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"
lhsValuerhsValueactual_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.
