CppUnit源码解读(5) ---断言

从这里开始，将要讲述core中，与断言相关的部分。

[Asserter] [TestAssert]  

相关文件：Asserter.h，Asserter.cpp

Asserter并非类名，而是一个name space，它内嵌于CppUnit name space之中。该域中一共有四个函数，用来帮助编写和断言有关的宏，它们分别是：fail，failIf，failNotEqual，failNotEqualIf。

函数fail仅抛出一个Exception对象，里面包含了和产生的错误相关的信息：

void fail( std::string message, SourceLine sourceLine )
{
  throw Exception( message, sourceLine );
}

函数failIf加上了条件控制，仅当shouldFail为true时才抛异常（调用fail函数）：

void failIf( bool shouldFail, std::string message, SourceLine location )
{
  if ( shouldFail )
    fail( message, location );
}

类似的，函数failNotEqual抛出NotEqualException对象，表明expected字串和actual字串不相等，NotEqualException对象包含了和产生的错误相关的信息：

void failNotEqual( std::string expected, std::string actual, 
        SourceLine sourceLine, std::string additionalMessage )
{
  throw NotEqualException( expected, actual, sourceLine, additionalMessage );
}

而函数failNotEqualIf则加上了条件控制：

void failNotEqualIf( bool shouldFail, std::string expected, std::string actual, 
        SourceLine sourceLine, std::string additionalMessage )
{
  if ( shouldFail )
    failNotEqual( expected, actual, sourceLine, additionalMessage );
}

下面的例子演示了如何使用上面提供的函数编写与断言相关的宏，这个例子选自随CppUnit源码所附的范例中：

#include <cppunit/SourceLine.h>
#include <cppunit/TestAssert.h>

// 检查XML字串是否与预期值相等
void  checkXmlEqual( std::string expectedXml, 
        std::string actualXml, 
        CppUnit::SourceLine sourceLine )
{
  // 预期之XML字串
  std::string expected = XmlUniformiser( expectedXml ).stripped();
  // 实际之XML字串
  std::string actual = XmlUniformiser( actualXml ).stripped();

  if ( expected == actual )    // 实际值和预期值相符，则相安无事
    return;

  // 不符，则报之以异常
  ::CppUnit::Asserter::failNotEqual( expected, actual, sourceLine );
}

/// 断言：两个XML字串相等
#define CPPUNITTEST_ASSERT_XML_EQUAL( expected, actual ) / 
        checkXmlEqual( expected, actual, CPPUNIT_SOURCELINE() )

 

相关文件：TestAssert.h，TestAssert.cpp

TestAssert并非类名，而是一个name space，它内嵌于CppUnit name space之中。该域中也有CPPUNIT_ENABLE_SOURCELINE_DEPRECATED的痕迹，去除与之相关的代码，剩下两个函数：assertEquals和assertDoubleEquals，其余均是宏。

assertEauals为模板函数，其大致功能类似前面的checkXmlEqual函数，若实际值和预期值不相符，则调用Asserter::failNotEqual，来看一下代码：

template <class T>
void assertEquals( const T& expected, const T& actual, 
        SourceLine sourceLine, const std::string &message ="" )
{
  if ( !assertion_traits<T>::equal(expected,actual) )
  {
    // 在需要时才调用toString，此之谓“lazy toString conversion”
    Asserter::failNotEqual( assertion_traits<T>::toString(expected), 
            assertion_traits<T>::toString(actual), 
            sourceLine, 
            message );
  }
}

之所以采用模板是为了使之支持多种类型，但是assertion_traits<T>::equal又是何方神圣呢。看到这个traits，想必大家一定会想到在泛型编程中大名鼎鼎的特性萃取技法。不错，这就是traits技法在此处的一个小小的应用。assertion_traits的定义和TestAssert同在一个文件中：

template <class T>
struct assertion_traits
{
  static bool equal( const T& x, const T& y )
  {
    return x == y;
  }

  static std::string toString( const T& x )
  {
    OStringStream ost;
    ost << x;
    return ost.str();
  }
};

assertion_traits的功能就是从T中萃取与断言相关的两个特征：equal和toString，上面提供的是泛化版本，根据需要你还可以定义特化版本，比如专门为std::string定制的代码如下：

template<>
struct assertion_traits<std::string>
{
  static bool equal( const std::string& x, const std::string& y )
  {
    return x == y;
  }

  static std::string toString( const std::string& x )
  {
    std::string text = '"' + x + '"';    // 两边加上引号以留空
    OStringStream ost;
    ost << text;
    return ost.str();
  }
};

assertEquals中利用assertion_traits<T>::equal判断expected与actual是否相等，若不等则调用Asserter::failNotEqual函数。到此，对于NotEqualException中仅对字串作比较的疑问，相信读者已经明白缘由了。有了assertion_traits<T>::toString，不管什么类型，一个string版的NotEqualException足以应对。

理解了assertEquals之后，再来看assertDoubleEquals函数就十分简单了，该函数用于作模糊相等判断，针对的是double类型的数据：

void TestAssert::assertDoubleEquals( double expected,
        double actual,
        double delta,
        SourceLine sourceLine )
{
  Asserter::failNotEqualIf( fabs( expected - actual ) > delta,
    assertion_traits<double>::toString(expected),
    assertion_traits<double>::toString(actual),
    sourceLine );
}

当expected和actual的差值的绝对值大于限值delta，则调用Asserter::failNotEqualIf，此处再次使用了assertion_traits<T>::toString，T以double代之。

好了，现在万事俱备，有了这些工具，就可以编写与断言相关的宏了，正如前面的checkXmlEqual函数。用这些宏，我们可以得到错误发生的文件物理位置和行号：

#if CPPUNIT_HAVE_CPP_SOURCE_ANNOTATION
// 断言条件condition为真
#define CPPUNIT_ASSERT(condition)                          / 
  ( ::CppUnit::Asserter::failIf( !(condition),             / 
        (#condition),             / 
        CPPUNIT_SOURCELINE() ) )
#else
#define CPPUNIT_ASSERT(condition)                          / 
  ( ::CppUnit::Asserter::failIf( !(condition),             / 
        "",                       / 
        CPPUNIT_SOURCELINE() ) )
#endif

// 断言条件condition为真，若为假，message中指明了诊断信息
#define CPPUNIT_ASSERT_MESSAGE(message,condition)          / 
  ( ::CppUnit::Asserter::failIf( !(condition),             / 
        (message),                / 
        CPPUNIT_SOURCELINE() ) )

// 表示失败，message中指明了诊断信息
#define CPPUNIT_FAIL( message )                            / 
  ( ::CppUnit::Asserter::fail( message,                    / 
        CPPUNIT_SOURCELINE() ) )

// 断言两个值相等，若不相等，则会打印诊断信息
#define CPPUNIT_ASSERT_EQUAL(expected,actual)                     / 
  ( ::CppUnit::TestAssert::assertEquals( (expected),              / 
        (actual),                / 
        CPPUNIT_SOURCELINE() ) )

// 断言两个值相等，message中指明了附加的诊断信息
#define CPPUNIT_ASSERT_EQUAL_MESSAGE(message,expected,actual)     / 
  ( ::CppUnit::TestAssert::assertEquals( (expected),              / 
        (actual),                / 
        CPPUNIT_SOURCELINE(),    / 
        (message) ) )

// 断言两个值不精确相等
#define CPPUNIT_ASSERT_DOUBLES_EQUAL(expected,actual,delta)       / 
  ( ::CppUnit::TestAssert::assertDoubleEquals( (expected),        / 
        (actual),          / 
        (delta),           / 
        CPPUNIT_SOURCELINE() ) )

关于CPPUNIT_ASSERT_EQUAL还有一点要说明，该宏对于expected和actual是有要求的，也就是所谓的Requirement：

• 具有相同的类型（比如都是std::string）
• 可以使用<<序列化到std::strstream（assertion_traits<T>::toString中指明）
• 能用==作比较（assertion_traits<T>::equal中指明）

不过，后两条可以通过为assertion_traits定制特化版本去除掉。

最后，TestAssert还定义了与上述宏功能相当的另一组宏，依据ChangeLog的描述，这又是“历史遗留”问题：为了与早先版本兼容，即早先使用的是如下这组宏。若你仍需使用这些宏，只要在所有CppUnit包含文件之前将宏CPPUNIT_ENABLE_NAKED_ASSERT定义为1即可：

#if CPPUNIT_ENABLE_NAKED_ASSERT

#undef assert
#define assert(c)                 CPPUNIT_ASSERT(c)
#define assertEqual(e,a)          CPPUNIT_ASSERT_EQUAL(e,a)
#define assertDoublesEqual(e,a,d) CPPUNIT_ASSERT_DOUBLES_EQUAL(e,a,d)
#define assertLongsEqual(e,a)     CPPUNIT_ASSERT_EQUAL(e,a)

#endif