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 
8 CPPUNIT_NS_BEGIN
9 
10 
11 class 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  */
45 
46 #if defined __GNUC__
47 #   define NORETURN __attribute__((noreturn))
48 #else
49 #   define NORETURN
50 #endif
51 
52 struct Asserter
53 {
54   /*! \brief Throws a Exception with the specified message and location.
55    */
56   NORETURN static void CPPUNIT_API fail( const Message &message,
57                                 const SourceLine &sourceLine = SourceLine() );
58 
59   /*! \brief Throws a Exception with the specified message and location.
60    * \deprecated Use fail( Message, SourceLine ) instead.
61    */
62   NORETURN static void CPPUNIT_API fail( std::string message,
63                                 const SourceLine &sourceLine = SourceLine() );
64 
65   /*! \brief Throws a Exception with the specified message and location.
66    * \param shouldFail if \c true then the exception is thrown. Otherwise
67    *                   nothing happen.
68    * \param message Message explaining the assertion failiure.
69    * \param sourceLine Location of the assertion.
70    */
71   static void CPPUNIT_API failIf( bool shouldFail,
72                                   const Message &message,
73                                   const SourceLine &sourceLine = SourceLine() );
74 
75   /*! \brief Throws a Exception with the specified message and location.
76    * \deprecated Use failIf( bool, Message, SourceLine ) instead.
77    * \param shouldFail if \c true then the exception is thrown. Otherwise
78    *                   nothing happen.
79    * \param message Message explaining the assertion failiure.
80    * \param sourceLine Location of the assertion.
81    */
82   static void CPPUNIT_API failIf( bool shouldFail,
83                                   std::string message,
84                                   const SourceLine &sourceLine = SourceLine() );
85 
86   /*! \brief Returns a expected value string for a message, case equal than
87    * Typically used to create 'not equal' message, or to check that a message
88    * contains the expected content when writing unit tests for your custom
89    * assertions.
90    *
91    * \param expectedValue String that represents the expected value.
92    * \return \a expectedValue prefixed with "Expected: ".
93    * \deprecated Use makeExpectedEqual instead
94    * \see makeActual().
95    */
96   static std::string CPPUNIT_API makeExpected( const std::string &expectedValue );
97   /*! \brief Returns a expected value string for a message, case equal than
98    * Typically used to create 'not equal' message, or to check that a message
99    * contains the expected content when writing unit tests for your custom
100    * assertions.
101    *
102    * \param expectedValue String that represents the expected value.
103    * \return \a expectedValue prefixed with "Expected: ".
104    * \see makeActual().
105    */
106   static std::string CPPUNIT_API makeExpectedEqual( const std::string &expectedValue );
107   /*! \brief Returns a expected value string for a message, case less than.
108    *
109    * \param expectedValue String that represents the expected value.
110    * \return \a expectedValue prefixed with "Expected less than: ".
111    * \see makeExpectedEqual().
112    */
113   static std::string CPPUNIT_API makeExpectedLess( const std::string &expectedValue );
114   /*! \brief Returns a expected value string for a message, case less or equal than.
115    *
116    * \param expectedValue String that represents the expected value.
117    * \return \a expectedValue prefixed with "Expected: ".
118    * \see makeExpectedEqual().
119    */
120   static std::string CPPUNIT_API makeExpectedLessEqual( const std::string &expectedValue );
121   /*! \brief Returns a expected value string for a message, case greater than.
122    *
123    * \param expectedValue String that represents the expected value.
124    * \return \a expectedValue prefixed with "Expected: ".
125    * \see makeExpectedEqual().
126    */
127   static std::string CPPUNIT_API makeExpectedGreater( const std::string &expectedValue );
128   /*! \brief Returns a expected value string for a message, greater or equal than.
129    *
130    * \param expectedValue String that represents the expected value.
131    * \return \a expectedValue prefixed with "Expected: ".
132    * \see makeExpectedEqual().
133    */
134   static std::string CPPUNIT_API makeExpectedGreaterEqual( const std::string &expectedValue );
135 
136   /*! \brief Returns an actual value string for a message.
137    * Typically used to create 'not equal' message, or to check that a message
138    * contains the expected content when writing unit tests for your custom
139    * assertions.
140    *
141    * \param actualValue String that represents the actual value.
142    * \return \a actualValue prefixed with "Actual  : ".
143    * \see makeExpected().
144    */
145   static std::string CPPUNIT_API makeActual( const std::string &actualValue );
146 
147   /*!
148    * \deprecated Use makeMessage instead
149    */
150   static Message CPPUNIT_API makeNotEqualMessage( const std::string &expectedValue,
151                                                   const std::string &actualValue,
152                                                   const AdditionalMessage &additionalMessage = AdditionalMessage(),
153                                                   const std::string &shortDescription = "equality assertion failed");
154 
155   static Message CPPUNIT_API makeMessage( const std::string &expectedValue,
156                                                   const std::string &actualValue,
157                                                   const std::string &shortDescription,
158                                                   const AdditionalMessage &additionalMessage = AdditionalMessage());
159 
160   /*! \brief Throws an Exception with the specified message and location.
161    * \param expected Text describing the expected value.
162    * \param actual Text describing the actual value.
163    * \param sourceLine Location of the assertion.
164    * \param additionalMessage Additional message. Usually used to report
165    *                          what are the differences between the expected and actual value.
166    * \param shortDescription Short description for the failure message.
167    */
168   NORETURN static void CPPUNIT_API failNotEqual( std::string expected,
169                                         std::string actual,
170                                         const SourceLine &sourceLine,
171                                         const AdditionalMessage &additionalMessage = AdditionalMessage(),
172                                         std::string shortDescription = "equality assertion failed" );
173 
174   /*! \brief Throws an Exception with the specified message and location.
175    * \param expected Text describing the expected value.
176    * \param actual Text describing the actual value.
177    * \param sourceLine Location of the assertion.
178    * \param additionalMessage Additional message. Usually used to report
179    *                          what are the differences between the expected and actual value.
180    * \param shortDescription Short description for the failure message.
181    */
182   static void CPPUNIT_API failNotLess( std::string expected,
183                                         std::string actual,
184                                         const SourceLine &sourceLine,
185                                         const AdditionalMessage &additionalMessage = AdditionalMessage(),
186                                         std::string shortDescription = "less assertion failed" );
187 
188   /*! \brief Throws an Exception with the specified message and location.
189    * \param expected Text describing the expected value.
190    * \param actual Text describing the actual value.
191    * \param sourceLine Location of the assertion.
192    * \param additionalMessage Additional message. Usually used to report
193    *                          what are the differences between the expected and actual value.
194    * \param shortDescription Short description for the failure message.
195    */
196   static void CPPUNIT_API failNotGreater( std::string expected,
197                                         std::string actual,
198                                         const SourceLine &sourceLine,
199                                         const AdditionalMessage &additionalMessage = AdditionalMessage(),
200                                         std::string shortDescription = "greater assertion failed" );
201 
202   /*! \brief Throws an Exception with the specified message and location.
203    * \param expected Text describing the expected value.
204    * \param actual Text describing the actual value.
205    * \param sourceLine Location of the assertion.
206    * \param additionalMessage Additional message. Usually used to report
207    *                          what are the differences between the expected and actual value.
208    * \param shortDescription Short description for the failure message.
209    */
210   static void CPPUNIT_API failNotLessEqual( std::string expected,
211                                         std::string actual,
212                                         const SourceLine &sourceLine,
213                                         const AdditionalMessage &additionalMessage = AdditionalMessage(),
214                                         std::string shortDescription = "less equal assertion failed" );
215 
216   /*! \brief Throws an Exception with the specified message and location.
217    * \param expected Text describing the expected value.
218    * \param actual Text describing the actual value.
219    * \param sourceLine Location of the assertion.
220    * \param additionalMessage Additional message. Usually used to report
221    *                          what are the differences between the expected and actual value.
222    * \param shortDescription Short description for the failure message.
223    */
224   static void CPPUNIT_API failNotGreaterEqual( std::string expected,
225                                         std::string actual,
226                                         const SourceLine &sourceLine,
227                                         const AdditionalMessage &additionalMessage = AdditionalMessage(),
228                                         std::string shortDescription = "greater equal assertion failed" );  /*! \brief Throws an Exception with the specified message and location.
229 
230    * \param shouldFail if \c true then the exception is thrown. Otherwise
231    *                   nothing happen.
232    * \param expected Text describing the expected value.
233    * \param actual Text describing the actual value.
234    * \param sourceLine Location of the assertion.
235    * \param additionalMessage Additional message. Usually used to report
236    *                          where the "difference" is located.
237    * \param shortDescription Short description for the failure message.
238    */
239   static void CPPUNIT_API failNotEqualIf( bool shouldFail,
240                                           std::string expected,
241                                           std::string actual,
242                                           const SourceLine &sourceLine,
243                                           const AdditionalMessage &additionalMessage = AdditionalMessage(),
244                                           std::string shortDescription = "equality assertion failed" );
245 
246 };
247 
248 
249 CPPUNIT_NS_END
250 
251 
252 #endif  // CPPUNIT_ASSERTER_H
253