libs/core/doc/lightweight_test.qbk

   1 [/
   2   Copyright 2010, 2011 Beman Dawes
   3   Copyright 2013 Ion Gaztanaga
   4   Copyright 2014 Peter Dimov
   5
   6   Distributed under the Boost Software License, Version 1.0.
   7
   8   See accompanying file LICENSE_1_0.txt
   9   or copy at http://boost.org/LICENSE_1_0.txt
  10 ]
  11
  12 [section:lightweight_test lightweight_test]
  13
  14 [simplesect Authors]
  15
  16 * Peter Dimov
  17 * Beman Dawes
  18
  19 [endsimplesect]
  20
  21 [section Header <boost/core/lightweight_test.hpp>]
  22
  23 The header `<boost/core/lightweight_test.hpp>` is a
  24 lightweight test framework. It's useful for writing
  25 Boost regression tests for components that are dependencies
  26 of Boost.Test.
  27
  28 When using `lightweight_test.hpp`, *do not forget* to
  29 `return boost::report_errors()` from `main`.
  30
  31 [section Synopsis]
  32
  33 ``
  34 #define BOOST_TEST(expression) /*unspecified*/
  35 #define BOOST_TEST_NOT(expression) /*unspecified*/
  36 #define BOOST_ERROR(message) /*unspecified*/
  37 #define BOOST_TEST_EQ(expr1, expr2) /*unspecified*/
  38 #define BOOST_TEST_NE(expr1, expr2) /*unspecified*/
  39 #define BOOST_TEST_CSTR_EQ(expr1, expr2) /*unspecified*/
  40 #define BOOST_TEST_CSTR_NE(expr1, expr2) /*unspecified*/
  41 #define BOOST_TEST_ALL_EQ(begin1, end1, begin2, end2) /* unspecified */
  42 #define BOOST_TEST_ALL_WITH(begin1, end1, begin2, end2, predicate) /* unspecified */
  43 #define BOOST_TEST_THROWS(expr, excep) /*unspecified*/
  44
  45 namespace boost
  46 {
  47     int report_errors();
  48 }
  49 ``
  50
  51 [endsect]
  52
  53 [section BOOST_TEST]
  54
  55 ``
  56 BOOST_TEST(expression)
  57 ``
  58
  59 If expression is false increases the error count and outputs a
  60 message containing `expression`.
  61
  62 [endsect]
  63
  64 [section BOOST_TEST_NOT]
  65
  66 ``
  67 BOOST_TEST_NOT(expression)
  68 ``
  69
  70 If expression is true increases the error count and outputs a
  71 message containing `!(expression)`.
  72
  73 [endsect]
  74
  75 [section BOOST_ERROR]
  76
  77 ``
  78 BOOST_ERROR(message)
  79 ``
  80
  81 Increases error count and outputs a message containing
  82 `message`.
  83
  84 [endsect]
  85
  86 [section BOOST_TEST_EQ]
  87
  88 ``
  89 BOOST_TEST_EQ(expr1, expr2)
  90 ``
  91
  92 If `expr1 != expr2` increases the error count and outputs a
  93 message containing both expressions.
  94
  95 [endsect]
  96
  97 [section BOOST_TEST_NE]
  98
  99 ``
 100 BOOST_TEST_NE(expr1, expr2)
 101 ``
 102
 103 If `expr1 == expr2` increases the error count and outputs a
 104 message containing both expressions.
 105
 106 [endsect]
 107
 108 [section BOOST_TEST_CSTR_EQ]
 109
 110 ``
 111 BOOST_TEST_CSTR_EQ(expr1, expr2)
 112 ``
 113
 114 Specialization of BOOST_TEST_EQ which interprets expr1 and expr2 as pointers to null-terminated byte strings (C strings). If `std::strcmp(expr1, expr2) != 0`, increase the error count and output a message containing both expressions.
 115
 116 [endsect]
 117
 118 [section BOOST_TEST_CSTR_NE]
 119
 120 ``
 121 BOOST_TEST_CSTR_NE(expr1, expr2)
 122 ``
 123
 124 Specialization of BOOST_TEST_NE which interprets expr1 and expr2 as pointers to null-terminated byte strings (C strings). If `std::strcmp(expr1, expr2) == 0`, increase the error count and output a message containing both expressions.
 125
 126 [endsect]
 127
 128 [section BOOST_TEST_ALL_EQ]
 129
 130 ``
 131 BOOST_TEST_ALL_EQ(begin1, end1, begin2, end2)
 132 ``
 133
 134 Compares the content of two sequences. If they have different sizes, or if any pairwise element differs, increases the error count and outputs a message containing at most 8 differing elements.
 135
 136 [endsect]
 137
 138 [section BOOST_TEST_ALL_WITH]
 139
 140 ``
 141 BOOST_TEST_ALL_WITH(begin1, end1, begin2, end2, predicate)
 142 ``
 143
 144 Compares the content of two sequences. If they have different sizes, or if any pairwise element do not fulfill the binary predicate, increases the error count and outputs a message containing at most 8 differing elements.
 145
 146 [endsect]
 147
 148 [section BOOST_TEST_THROWS]
 149
 150 ``
 151 BOOST_TEST_THROWS(expr, excep)
 152 ``
 153
 154 If `BOOST_NO_EXCEPTIONS` is *not* defined and if `expr` does not
 155 throw an exception of type `excep`, increases the error count
 156 and outputs a message containing the expression.
 157
 158 If `BOOST_NO_EXCEPTIONS` is defined, this macro expands to
 159 nothing and `expr` is not evaluated.
 160
 161 [endsect]
 162
 163 [section report_errors]
 164
 165 ``
 166 int boost::report_errors()
 167 ``
 168
 169 Return the error count from `main`.
 170
 171 [endsect]
 172
 173 [section Example]
 174
 175 ``
 176 #include <boost/core/lightweight_test.hpp>
 177
 178 int sqr( int x )
 179 {
 180     return x * x;
 181 }
 182
 183 int main()
 184 {
 185     BOOST_TEST( sqr(2) == 4 );
 186     BOOST_TEST_EQ( sqr(-3), 9 );
 187
 188     return boost::report_errors();
 189 }
 190 ``
 191
 192 [endsect]
 193
 194 [endsect]
 195
 196 [section Header <boost/core/lightweight_test_trait.hpp>]
 197
 198 The header `<boost/core/lightweight_test_trait.hpp>` defines
 199 a couple of extra macros for testing compile-time traits that
 200 return a boolean value.
 201
 202 [section Synopsis]
 203
 204 ``
 205 #define BOOST_TEST_TRAIT_TRUE((Trait)) /*unspecified*/
 206 #define BOOST_TEST_TRAIT_FALSE((Trait)) /*unspecified*/
 207 ``
 208
 209 [endsect]
 210
 211 [section BOOST_TEST_TRAIT_TRUE]
 212
 213 ``
 214 BOOST_TEST_TRAIT_TRUE((Trait))
 215 ``
 216
 217 If `Trait::value != true` increases the error count and outputs a
 218 message containing `Trait`. Note the double set of parentheses; these
 219 enable `Trait` to contain a comma, which is common for templates.
 220
 221 [endsect]
 222
 223 [section BOOST_TEST_TRAIT_FALSE]
 224
 225 ``
 226 BOOST_TEST_TRAIT_FALSE((Trait))
 227 ``
 228
 229 If `Trait::value != false` increases the error count and outputs a
 230 message containing `Trait`. Note the double set of parentheses.
 231
 232 [endsect]
 233
 234 [section Example]
 235
 236 ``
 237 #include <boost/core/lightweight_test_trait.hpp>
 238 #include <boost/core/is_same.hpp>
 239
 240 template<class T, class U> struct X
 241 {
 242     typedef T type;
 243 };
 244
 245 using boost::core::is_same;
 246
 247 int main()
 248 {
 249     BOOST_TEST_TRAIT_TRUE(( is_same<X<int, long>::type, int> ));
 250
 251     return boost::report_errors();
 252 }
 253 ``
 254
 255 [endsect]
 256
 257 [endsect]
 258
 259 [endsect]