Test Macros

From STRIDE Wiki
Revision as of 16:09, 17 November 2009 by Mikee (talk | contribs)
Jump to: navigation, search

Pass/Fail Macros

The STRIDE Test Unit implementation also provides a set of Test Macros (declared in srtest.h) available for use within test methods. The macros are optional - you are not required to use them in your test units. They provide shortcuts for testing assertions and automatic report annotation in the case of failures.

The macros can be used in C++ and C test unit code (Note that there is no C version of exceptions test).

General Guidelines for Pass/Fail Macros

There are three types of pass/fail macros: EXPECT, ASSERT, and EXIT macros. They have slight but important differences in their behavior.

srEXPECT_xx(condition)

  • If the condition does match the expectation, this macro:
    • sets the current test case status to PASS
  • If the condition does not match the expectation, this macro:
    • sets the current test case status to FAIL
    • adds a comment to the current test case's results report which includes the condition as well as file and line number
    • does not alter code execution

srASSERT_xx(condition)

  • If the condition does match the assertion, this macro:
    • sets the current test case status to PASS
  • If the condition does not match the expectation, this macro:
    • adds a comment to the current test case's results report which includes the condition as well as file and line number
    • immediately returns from the current test function. The return specifies no value, therefore a function or method that uses srASSERT_xx should be declared to return void.

srEXIT_xx(condition)

  • The behavior and restrictions of the exit macros are identical to the ASSERT macros. EXIT macros differ only in that they cause the test unit to cease execution. That is, no subsequent test methods are executed once an EXIT macro has failed in its assertion.

Macros

The following sections document the several types of testing macros that are provided by the STRIDE Framework. For simplicity, we refer to all the macros using a prefix tag - when using the macros in test code, the prefix should be replaced by one of the following: srEXPECT, srASSERT, or srEXIT, depending on how the test writer wants failures to be handled.

Boolean Macros

The boolean macros take a single condition expression, cond, that evaluates to an integral type or bool.

The condition will be evaluated once. When a failure is detected, the report will be annotated.

Boolean
EXPECT macro Pass if
prefix_TRUE(cond); cond is non-zero
prefix_FALSE(cond); cond is zero

Example

int a = 5; 
int b = 5; 
srEXPECT_TRUE(a == b); 

srEXPECT_FALSE(2 < 1);

srEXPECT_FALSE(a != b);
srEXPECT_TRUE(1 < 2); 
srEXPECT_TRUE(1);

Comparison Macros

Comparison macros take two operands and compare them using the indicated operator.

The comparison macros will work for scalar types as well as C++ objects that have the corresponding comparison operator implemented.

Comparison
EXPECT macro ASSERT macro Pass if
srEXPECT_EQ(val1, val2); srASSERT_EQ(val1, val2); val1 == val2
srEXPECT_NE(val1, val2); srASSERT_NE(val1, val2); val1 != val2
srEXPECT_LT(val1, val2); srASSERT_LT(val1, val2); val1 < val2
srEXPECT_LE(val1, val2); srASSERT_LE(val1, val2); val1 <= val2
srEXPECT_GT(val1, val2); srASSERT_GT(val1, val2); val1 > val2
srEXPECT_GE(val1, val2); srASSERT_GE(val1, val2); val1 >= val2

Example

int a = 5; 
int b = 5; 

srEXPECT_EQ( 4, 4 ); 
srEXPECT_NE( 6, 7 );
srEXPECT_EQ( a, b ); 
srEXPECT_GT( 2 , 1 );
srEXPECT_GE( 2 , 1 );

C String Comparison Macros

C String Comparison Macros are intended only for use with C-style null terminated strings. The strings can be char or wchar_t based.

Don't use these macros to compare C++ objects representing strings since such classes typically have overloaded comparison operators. The standard comparison macros should be used instead.

  • An empty string will appear in error message output as “”. A null string will appear as NULL with no surrounding quotes. Otherwise all output strings are quoted.
  • The type of str1 and str2 must be compatible with const char* or const wchar_t*.
C-string comparison
EXPECT macro ASSERT macro Pass if
srEXPECT_STREQ(str1, str2); srASSERT_STREQ(str1, str2); str1 and str2 have the same content
srEXPECT_STRNE(str1, str2); srASSERT_STRNE(str1, str2); str1 and str2 have different content
srEXPECT_STRCASEEQ(str1, str2); srASSERT_STRCASEEQ(str1, str2); str1 and str2 have the same content, ignoring case.
srEXPECT_STRCASENE(str1, str2); srASSERT_STRCASENE(str1, str2); str1 and str2 have different content, ignoring case.

Example

const char* s1 = "This String is unique"; 
const char* s2 = "This String has an equivalent"; 
const char* s2Twin = "This String has an equivalent"; 
const char* s2TwinNoCase = "this string has an equivalent"; 

srEXPECT_STREQ( s2, s2Twin); 
srEXPECT_STREQ( s2, "This String has an equivalent"); 
srEXPECT_STRCASEEQ(s2, s2TwinNoCase); 

srEXPECT_STRNE(s1, s2);  
srEXPECT_STRNE(s2, s2TwinNoCase); 
srEXPECT_STRCASENE(s1, s2);


Predicate Macros

Predicate macros allow user control over the pass/fail decision making.

A predicate is a function returning bool that is implemented by the user that is the macro. Up to four arguments can also passed to the predicate through the macro.

Predicates
EXPECT macro ASSERT macro Pass if
srEXPECT_PRED1(pred, val1) srASSERT_PRED1(pred, val1) pred(val1) returns true
srEXPECT_PRED2(pred, val1, val2) srASSERT_PRED2(pred, val1, val2) pred(val1, val2) returns true
…(up to arity of 4)

Example

static int alwaysTrueOneArg(int i)
{
    return 1; 
}

static int alwaysTrueTwoArgs(int i, int j)
{
    return 1;
}

static void Pass()
{
    // examples of passing expectations using predicates.

    srEXPECT_PRED1(alwaysTrueOneArg, 25); 
    srEXPECT_PRED2(alwaysTrueTwoArgs, 100, 33); 
}

Floating Point Comparison Macros

Floating point macros are for comparing equivalence (or near equivalence) of floating point numbers.

These macros are are very useful for dealing with floating point round-off effects.

Floating Point comparison
EXPECT macro ASSERT macro Pass if
srEXPECT_NEAR(val1, val2, epsilon); srASSERT_NEAR(val1, val2, epsilon); The absolute value of the difference between val1 and val2 is less than or equal to epsilon.

Example

float x =           2.00005f;
float nearX =       2.00006f; 
float nearXEpsilon = .000019f;

double y =           1.2345; 
double nearY =       1.23456; 
double nearYEpsilon = .00019;
    
srEXPECT_NEAR(x, nearX, nearXEpsilon); 
srEXPECT_NEAR(y, nearY, nearYEpsilon);

C++ Only Features

Exception Macros

Exception macros are used to ensure that expected exceptions are thrown.

These macros require exception support from the target compiler. If the target compiler does not have exception support the macros cannot be used.

Exceptions
EXPECT macro ASSERT macro Pass if
srEXPECT_THROW(statement, ex_type); srASSERT_THROW(statement, ex_type); statement throws an exception of type ex_type
srEXPECT_THROW_ANY(statement); srASSERT_THROW_ANY(statement); statement throws an exception (type not important)
srEXPECT_NO_THROW(statement); srASSERT_NO_THROW(statement); statement does not throw an exception
Example
srEXPECT_THROW(throwStdException(), std::exception); 
srEXPECT_THROW(throwInt(), int);

srEXPECT_THROW_ANY(throwStdException()); 
srEXPECT_THROW_ANY(throwInt()); 

srEXPECT_NO_THROW(doesntThrow());

Use Operator << to Augment Report Annotation

In C++ test code all pass/fail macros support adding to a test's annotations using the << operator. For example: 

srEXPECT_TRUE(a != b) << "My custom message";

As delivered, the macros will support stream input annotations for:

  • all numeric types,
  • C string (char* or wchar_t*), and
  • types allowing implicit cast to numeric type or "C" string.

You can also overload the << operator in order to annotate reports using your own custom type. An example is below.

The following will compile and execute successfully given that the << operator is overloaded as shown: 

#include <srtest.h>

// MyCustomClass implementation
class MyCustomClass
{
public:
   MyCustomClass(int i) : m_int(i) {}

private: 
   int m_int; 
   friend stride::Message& operator<<(stride::Message& ss, const MyCustomClass& obj);
}; 

stride::Message& operator<<(stride::Message& ss, const MyCustomClass& obj)
{
   ss << obj.m_int;
   return ss;
}

void test()
{
    MyCustomClass custom(34); 

    srEXPECT_FALSE(true) << custom;
}

Dynamic Test Case Macros

The macros presented so far assume that their actions are directed at the currenly in-scope test case. However, test cases can be created dynamically using STRIDE's [Runtime Test Services].

In order to handle dynamic test cases, each of the macros requires another parameter which specifies the test case to report against. Other than this, these macros provide exactly equivalent functionality to the non-dynamic peer. The dynamic macros are listed below. All require a test case, value of type srTestCaseHandle_t from srtest.h, to be passed as the first parameter).

Nonfatal Assertion Fatal Assertion
Boolean
srEXPECT_TRUE_DYN(tc, cond); srASSERT_TRUE_DYN(tc, cond);
srEXPECT_FALSE_DYN(tc, cond); srASSERT_FALSE_DYN(tc, cond);
Comparison
srEXPECT_EQ_DYN(tc, val1, val2); srASSERT_EQ_DYN(tc, expect, val);
srEXPECT_NE_DYN(tc, val1, val2); srASSERT_NE_DYN(tc, val1, val2);
srEXPECT_LT_DYN(tc, val1, val2); srASSERT_LT_DYN(tc, val1, val2);
srEXPECT_LE_DYN(tc, val1, val2); srASSERT_LE_DYN(tc, val1, val2);
srEXPECT_GT_DYN(tc, val1, val2); srASSERT_GT_DYN(tc, val1, val2);
srEXPECT_GE_DYN(tc, val1, val2); srASSERT_GE_DYN(tc, val1, val2);
C-string comparison
srEXPECT_STREQ_DYN(tc, str1, str2); srASSERT_STREQ_DYN(tc, str1, str2);
srEXPECT_STRNE_DYN(tc, str1, str2); srASSERT_STRNE_DYN(tc, str1, str2);
srEXPECT_STRCASEEQ_DYN(tc, str1, str2); srASSERT_STRCASEEQ_DYN(tc, str1, str2);
srEXPECT_STRCASENE_DYN(tc, str1, str2); srASSERT_STRCASENE_DYN(tc, str1, str2);
Exceptions
srEXPECT_THROW_DYN(statement, ex_type); srASSERT_THROW_DYN(tc, statement, ex_type);
srEXPECT_THROW_ANY_DYN(tc, statement); srASSERT_THROW_ANY_DYN(tc, statement);
srEXPECT_NO_THROW_DYN(tc, statement); srASSERT_NO_THROW_DYN(tc, statement);
Predicates
srEXPECT_PRED1_DYN(tc, pred, val1); srASSERT_PRED1_DYN(tc, pred, val1);
srEXPECT_PRED2_DYN(tc, pred, vall, val2); srASSERT_PRED2_DYN(tc, pred, vall, val2);
…(up to arity of 4)
Floating Point
srEXPECT_NEAR_DYN(tc, val1, val2, epsilon); srASSERT_NEAR_DYN(tc, val1, val2, epsilon);
Retrieved from "https://www.stridewiki.com/index.php?title=Test_Macros&oldid=11690"