source: trunk/contrib/cppunit-1.12.2/include/cppunit/Asserter.h @ 876

Last change on this file since 876 was 876, checked in by sam, 9 years ago

contrib: add a precompiled Win32 version of CppUnit and update build system
accordingly.

File size: 6.0 KB
Line 
1#ifndef CPPUNIT_ASSERTER_H
2#define CPPUNIT_ASSERTER_H
3
4#include <cppunit/AdditionalMessage.h>
5#include <cppunit/SourceLine.h>
6#include <string>
7
8CPPUNIT_NS_BEGIN
9
10
11class Message;
12
13
14/*! \brief A set of functions to help writing assertion macros.
15 * \ingroup CreatingNewAssertions
16 *
17 * Here is an example of assertion, a simplified version of the
18 * actual assertion implemented in examples/cppunittest/XmlUniformiser.h:
19 * \code
20 * #include <cppunit/SourceLine.h>
21 * #include <cppunit/TestAssert.h>
22 *
23 * void
24 * checkXmlEqual( std::string expectedXml,
25 *                std::string actualXml,
26 *                CppUnit::SourceLine sourceLine )
27 * {
28 *   std::string expected = XmlUniformiser( expectedXml ).stripped();
29 *   std::string actual = XmlUniformiser( actualXml ).stripped();
30 *
31 *   if ( expected == actual )
32 *     return;
33 *
34 *   ::CppUnit::Asserter::failNotEqual( expected,
35 *                                      actual,
36 *                                      sourceLine );
37 * }
38 *
39 * /// Asserts that two XML strings are equivalent.
40 * #define CPPUNITTEST_ASSERT_XML_EQUAL( expected, actual ) \
41 *     checkXmlEqual( expected, actual,                     \
42 *                    CPPUNIT_SOURCELINE() )
43 * \endcode
44 */
45struct Asserter
46{
47  /*! \brief Throws a Exception with the specified message and location.
48   */
49  static void CPPUNIT_API fail( const Message &message,
50                                const SourceLine &sourceLine = SourceLine() );
51
52  /*! \brief Throws a Exception with the specified message and location.
53   * \deprecated Use fail( Message, SourceLine ) instead.
54   */
55  static void CPPUNIT_API fail( std::string message,
56                                const SourceLine &sourceLine = SourceLine() );
57
58  /*! \brief Throws a Exception with the specified message and location.
59   * \param shouldFail if \c true then the exception is thrown. Otherwise
60   *                   nothing happen.
61   * \param message Message explaining the assertion failiure.
62   * \param sourceLine Location of the assertion.
63   */
64  static void CPPUNIT_API failIf( bool shouldFail,
65                                  const Message &message,
66                                  const SourceLine &sourceLine = SourceLine() );
67
68  /*! \brief Throws a Exception with the specified message and location.
69   * \deprecated Use failIf( bool, Message, SourceLine ) instead.
70   * \param shouldFail if \c true then the exception is thrown. Otherwise
71   *                   nothing happen.
72   * \param message Message explaining the assertion failiure.
73   * \param sourceLine Location of the assertion.
74   */
75  static void CPPUNIT_API failIf( bool shouldFail,
76                                  std::string message,
77                                  const SourceLine &sourceLine = SourceLine() );
78
79  /*! \brief Returns a expected value string for a message.
80   * Typically used to create 'not equal' message, or to check that a message
81   * contains the expected content when writing unit tests for your custom
82   * assertions.
83   *
84   * \param expectedValue String that represents the expected value.
85   * \return \a expectedValue prefixed with "Expected: ".
86   * \see makeActual().
87   */
88  static std::string CPPUNIT_API makeExpected( const std::string &expectedValue );
89
90  /*! \brief Returns an actual value string for a message.
91   * Typically used to create 'not equal' message, or to check that a message
92   * contains the expected content when writing unit tests for your custom
93   * assertions.
94   *
95   * \param actualValue String that represents the actual value.
96   * \return \a actualValue prefixed with "Actual  : ".
97   * \see makeExpected().
98   */
99  static std::string CPPUNIT_API makeActual( const std::string &actualValue );
100
101  static Message CPPUNIT_API makeNotEqualMessage( const std::string &expectedValue,
102                                                  const std::string &actualValue,
103                                                  const AdditionalMessage &additionalMessage = AdditionalMessage(),
104                                                  const std::string &shortDescription = "equality assertion failed");
105
106  /*! \brief Throws an Exception with the specified message and location.
107   * \param expected Text describing the expected value.
108   * \param actual Text describing the actual value.
109   * \param sourceLine Location of the assertion.
110   * \param additionalMessage Additional message. Usually used to report
111   *                          what are the differences between the expected and actual value.
112   * \param shortDescription Short description for the failure message.
113   */
114  static void CPPUNIT_API failNotEqual( std::string expected,
115                                        std::string actual,
116                                        const SourceLine &sourceLine,
117                                        const AdditionalMessage &additionalMessage = AdditionalMessage(),
118                                        std::string shortDescription = "equality assertion failed" );
119
120  /*! \brief Throws an Exception with the specified message and location.
121   * \param shouldFail if \c true then the exception is thrown. Otherwise
122   *                   nothing happen.
123   * \param expected Text describing the expected value.
124   * \param actual Text describing the actual value.
125   * \param sourceLine Location of the assertion.
126   * \param additionalMessage Additional message. Usually used to report
127   *                          where the "difference" is located.
128   * \param shortDescription Short description for the failure message.
129   */
130  static void CPPUNIT_API failNotEqualIf( bool shouldFail,
131                                          std::string expected,
132                                          std::string actual,
133                                          const SourceLine &sourceLine,
134                                          const AdditionalMessage &additionalMessage = AdditionalMessage(),
135                                          std::string shortDescription = "equality assertion failed" );
136
137};
138
139
140CPPUNIT_NS_END
141
142
143#endif  // CPPUNIT_ASSERTER_H
Note: See TracBrowser for help on using the repository browser.