1 /* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
2 /*
3 * Copyright (c) 2009 University of Washington
4 *
5 * This program is free software; you can redistribute it and/or modify
6 * it under the terms of the GNU General Public License version 2 as
7 * published by the Free Software Foundation;
8 *
9 * This program is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 * GNU General Public License for more details.
13 *
14 * You should have received a copy of the GNU General Public License
15 * along with this program; if not, write to the Free Software
16 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
17 */
18
19 #ifndef NS3_TEST_H
20 #define NS3_TEST_H
21
22 #include <iostream>
23 #include <fstream>
24 #include <sstream>
25 #include <string>
26 #include <vector>
27 #include <list>
28 #include <limits>
29 #include <stdint.h>
30
31 #include "non-copyable.h"
32 #include "system-wall-clock-ms.h"
33
34 /**
35 * \file
36 * \ingroup testing
37 * \brief ns3::TestCase, ns3::TestSuite, ns3::TestRunner declarations,
38 * and \c NS_TEST_ASSERT macro definitions.
39 */
40
41 /**
42 * \ingroup core
43 * \defgroup testing Testing
44 * \brief Tools to define and execute unit tests.
45 *
46 * This module lists the normal Testing API. Most of these
47 * macros forward to the implementation macros in testingimpl.
48 * You should generally use these macros only.
49 */
50 /**
51 * \ingroup testing
52 * \defgroup testingimpl Testing Implementation
53 * \brief Internal implementation of the Testing system.
54 */
55
56 namespace ns3 {
57
58 /** Namespace for test files, TestCases and TestSuites. */
59 namespace tests {} // namespace tests
60
61 //
62 // Note on below macros:
63 //
64 // When multiple statements are used in a macro, they should be bound
65 // together in a loop syntactically, so the macro can appear safely
66 // inside if clauses or other places that expect a single statement or
67 // a statement block. The "strange" do while construct is a generally
68 // expected best practice for defining a robust macro.
69 //
70
71 /**
72 * \ingroup testing
73 * \brief Check if we should assert on errors, and do so
74 */
75 #define ASSERT_ON_FAILURE \
76 do { \
77 if (MustAssertOnFailure ()) \
78 { \
79 *(volatile int *)0 = 0; \
80 } \
81 } while (false)
82
83 /**
84 * \ingroup testing
85 * \brief If we shouldn't continue on errors, return
86 */
87 #define CONTINUE_ON_FAILURE \
88 do { \
89 if (!MustContinueOnFailure ()) \
90 { \
91 return; \
92 } \
93 } while (false)
94
95 /**
96 * \ingroup testing
97 * \brief If we shouldn't continue on errors, return test status
98 */
99 #define CONTINUE_ON_FAILURE_RETURNS_BOOL \
100 do { \
101 if (!MustContinueOnFailure ()) \
102 { \
103 return IsStatusFailure (); \
104 } \
105 } while (false)
106
107
108
109 // ===========================================================================
110 // Test for equality (generic version)
111 // ===========================================================================
112
113 /**
114 * \ingroup testingimpl
115 * \brief Test that an actual and expected (limit) value are equal and report
116 * and abort if not.
117 */
118 #define NS_TEST_ASSERT_MSG_EQ_INTERNAL(actual, limit, msg, file, line) \
119 do { \
120 if (!((actual) == (limit))) \
121 { \
122 ASSERT_ON_FAILURE; \
123 std::ostringstream msgStream; \
124 msgStream << msg; \
125 std::ostringstream actualStream; \
126 actualStream << actual; \
127 std::ostringstream limitStream; \
128 limitStream << limit; \
129 ReportTestFailure (std::string (#actual) + " (actual) == " + \
130 std::string (#limit) + " (limit)", \
131 actualStream.str (), limitStream.str (), \
132 msgStream.str (), file, line); \
133 CONTINUE_ON_FAILURE; \
134 } \
135 } while (false)
136
137 /**
138 * \ingroup testing
139 *
140 * \brief Test that an actual and expected (limit) value are equal and
141 * report and abort if not.
142 *
143 * Check to see if the expected (limit) value is equal to the actual
144 * value found in a test case. If the two values are equal nothing
145 * happens, but if the comparison fails, an error is reported in a
146 * consistent way and the execution of the current test case is
147 * aborted.
148 *
149 * The message is interpreted as a stream, for example:
150 *
151 * \code
152 * NS_TEST_ASSERT_MSG_EQ (result, true,
153 * "cannot open file " << filename << " in test");
154 * \endcode
155 *
156 * is legal.
157 *
158 * \param [in] actual Expression for the actual value found during the test.
159 * \param [in] limit Expression for the expected value of the test.
160 * \param [in] msg Message that is output if the test does not pass.
161 *
162 * \warning Do not use this macro if you are comparing floating point
163 * numbers (float or double) as it is unlikely to do what you expect.
164 * Use NS_TEST_ASSERT_MSG_EQ_TOL instead.
165 */
166 #define NS_TEST_ASSERT_MSG_EQ(actual, limit, msg) \
167 NS_TEST_ASSERT_MSG_EQ_INTERNAL (actual, limit, msg, __FILE__, __LINE__)
168
169 /**
170 * \ingroup testingimpl
171 * \brief Test that an actual and expected (limit) value are equal and report
172 * and abort if not.
173 */
174 #define NS_TEST_ASSERT_MSG_EQ_RETURNS_BOOL_INTERNAL(actual, limit, msg, file, line) \
175 do { \
176 if (!((actual) == (limit))) \
177 { \
178 ASSERT_ON_FAILURE; \
179 std::ostringstream msgStream; \
180 msgStream << msg; \
181 std::ostringstream actualStream; \
182 actualStream << actual; \
183 std::ostringstream limitStream; \
184 limitStream << limit; \
185 ReportTestFailure (std::string (#actual) + " (actual) == " + \
186 std::string (#limit) + " (limit)", \
187 actualStream.str (), limitStream.str (), \
188 msgStream.str (), file, line); \
189 CONTINUE_ON_FAILURE_RETURNS_BOOL; \
190 } \
191 } while (false)
192
193 /**
194 * \ingroup testing
195 *
196 * \brief Test that an actual and expected (limit) value are equal and
197 * report and abort if not.
198 *
199 * Check to see if the expected (limit) value is equal to the actual
200 * value found in a test case. If the two values are equal nothing
201 * happens, but if the comparison fails, an error is reported in a
202 * consistent way and the execution of the current test case is
203 * aborted.
204 *
205 * The message is interpreted as a stream, for example:
206 *
207 * \code
208 * NS_TEST_ASSERT_MSG_EQ_RETURNS_BOOL (result, true,
209 * "cannot open file " << filename << " in test");
210 * \endcode
211 *
212 * is legal.
213 *
214 * \param [in] actual Expression for the actual value found during the test.
215 * \param [in] limit Expression for the expected value of the test.
216 * \param [in] msg Message that is output if the test does not pass.
217 *
218 * \warning Do not use this macro if you are comparing floating point
219 * numbers (float or double) as it is unlikely to do what you expect.
220 * Use NS_TEST_ASSERT_MSG_EQ_RETURNS_BOOL_TOL instead.
221 *
222 * This function returns a Boolean value.
223 *
224 */
225 #define NS_TEST_ASSERT_MSG_EQ_RETURNS_BOOL(actual, limit, msg) \
226 NS_TEST_ASSERT_MSG_EQ_RETURNS_BOOL_INTERNAL (actual, limit, msg, __FILE__, __LINE__)
227
228 /**
229 * \ingroup testingimpl
230 * \brief Test that an actual and expected (limit) value are equal and
231 * report if not.
232 *
233 * Required to avoid use of return statement which allows use in
234 * methods (esp. callbacks) returning void.
235 */
236 #define NS_TEST_EXPECT_MSG_EQ_INTERNAL(actual, limit, msg, file, line) \
237 do { \
238 if (!((actual) == (limit))) \
239 { \
240 ASSERT_ON_FAILURE; \
241 std::ostringstream msgStream; \
242 msgStream << msg; \
243 std::ostringstream actualStream; \
244 actualStream << actual; \
245 std::ostringstream limitStream; \
246 limitStream << limit; \
247 ReportTestFailure (std::string (#actual) + " (actual) == " + \
248 std::string (#limit) + " (limit)", \
249 actualStream.str (), limitStream.str (), \
250 msgStream.str (), file, line); \
251 } \
252 } while (false)
253
254 /**
255 * \ingroup testing
256 *
257 * \brief Test that an actual and expected (limit) value are equal and
258 * report if not.
259 *
260 * Check to see if the expected (lmit) value is equal to the actual
261 * value found in a test case. If the two values are equal nothing
262 * happens, but if the comparison fails, an error is reported in a
263 * consistent way. EXPECT* macros do not return if an error is
264 * detected.
265 *
266 * The message is interpreted as a stream, for example:
267 *
268 * \code
269 * NS_TEST_EXPECT_MSG_EQUAL (result, true,
270 * "cannot open file " << filename << " in test");
271 * \endcode
272 *
273 * is legal.
274 *
275 * \param [in] actual Expression for the actual value found during the test.
276 * \param [in] limit Expression for the expected value of the test.
277 * \param [in] msg Message that is output if the test does not pass.
278 *
279 * \warning Do not use this macro if you are comparing floating point
280 * numbers (float or double) as it is unlikely to do what you expect.
281 * Use NS_TEST_EXPECT_MSG_EQ_TOL instead.
282 */
283 #define NS_TEST_EXPECT_MSG_EQ(actual, limit, msg) \
284 NS_TEST_EXPECT_MSG_EQ_INTERNAL (actual, limit, msg, __FILE__, __LINE__)
285
286 // ===========================================================================
287 // Test for equality with a provided tolerance (use for floating point
288 // comparisons -- both float and double)
289 // ===========================================================================
290
291 /**
292 * \ingroup testingimpl
293 * \brief Test that actual and expected (limit) values are equal to
294 * plus or minus some tolerance and report and abort if not.
295 */
296 #define NS_TEST_ASSERT_MSG_EQ_TOL_INTERNAL(actual, limit, tol, msg, file, line) \
297 do { \
298 if ((actual) > (limit) + (tol) || (actual) < (limit) - (tol)) \
299 { \
300 ASSERT_ON_FAILURE; \
301 std::ostringstream msgStream; \
302 msgStream << msg; \
303 std::ostringstream actualStream; \
304 actualStream << actual; \
305 std::ostringstream limitStream; \
306 limitStream << limit << " +- " << tol; \
307 std::ostringstream condStream; \
308 condStream << #actual << " (actual) < " << #limit \
309 << " (limit) + " << #tol << " (tol) && " \
310 << #actual << " (actual) > " << #limit \
311 << " (limit) - " << #tol << " (tol)"; \
312 ReportTestFailure (condStream.str (), actualStream.str (), \
313 limitStream.str (), msgStream.str (), \
314 file, line); \
315 CONTINUE_ON_FAILURE; \
316 } \
317 } while (false)
318
319 /**
320 * \ingroup testing
321 *
322 * \brief Test that actual and expected (limit) values are equal to
323 * plus or minus some tolerance and report and abort if not.
324 *
325 * Check to see if the expected (limit) value is equal to the actual
326 * value found in a test case to some tolerance. This is not the same
327 * thing as asking if two floating point are equal to within some
328 * epsilon, but is useful for that case. This assertion is geared
329 * toward more of a measurement problem. Consider measuring a
330 * physical rod of some kind that you have ordered. You need to
331 * determine if it is "good." You want to measure the rod to an
332 * arbitrary precision of sixteen significant figures, you will
333 * measure the rod to determine if its length is within the tolerances
334 * you provided. For example, 12.00 inches plus or minus .005 inch
335 * may be just fine.
336 *
337 * In ns-3, you might want to measure a signal to noise ratio and
338 * check to see if the answer is what you expect. If you naively
339 * measure (double)1128.93 and compare this number with a constant
340 * 1128.93 you are almost certainly going to have your test fail
341 * because of floating point rounding errors. We provide a floating
342 * point comparison function ns3::TestDoubleIsEqual() but you will
343 * probably quickly find that is not what you want either. It may
344 * turn out to be the case that when you measured an SNR that printed
345 * as 1128.93, what was actually measured was something more like
346 * 1128.9287653857625442 for example. Given that the double epsilon
347 * is on the order of 0.0000000000000009, you would need to provide
348 * sixteen significant figures of expected value for this kind of test
349 * to pass even with a typical test for floating point "approximate
350 * equality." That is clearly not required or desired. You really
351 * want to be able to provide 1128.93 along with a tolerance just like
352 * you provided 12 inches +- 0.005 inch above.
353 *
354 * This assertion is designed for real measurements by taking into
355 * account measurement tolerances. By doing so it also automatically
356 * compensates for floating point rounding errors. If you really want
357 * to check floating point equality down to the
358 * numeric_limits<double>::epsilon () range, consider using
359 * ns3::TestDoubleIsEqual().
360 *
361 * \note Mixing signed and unsigned types can lead to misleading
362 * results.
363 *
364 * The message is interpreted as a stream, for example:
365 *
366 * \code
367 * NS_TEST_ASSERT_MSG_EQ_TOL (snr, 1128.93, 0.005,
368 * "wrong snr (" << snr << ") in test");
369 * \endcode
370 *
371 * is legal.
372 *
373 * \param [in] actual Expression for the actual value found during the test.
374 * \param [in] limit Expression for the expected value of the test.
375 * \param [in] tol Tolerance of the test.
376 * \param [in] msg Message that is output if the test does not pass.
377 */
378 #define NS_TEST_ASSERT_MSG_EQ_TOL(actual, limit, tol, msg) \
379 NS_TEST_ASSERT_MSG_EQ_TOL_INTERNAL (actual, limit, tol, msg, __FILE__, __LINE__)
380
381 /**
382 * \ingroup testingimpl
383 * \brief Test that actual and expected (limit) values are equal to
384 * plus or minus some tolerance and report and abort if not.
385 */
386 #define NS_TEST_ASSERT_MSG_EQ_TOL_RETURNS_BOOL_INTERNAL(actual, limit, tol, msg, file, line) \
387 do { \
388 if ((actual) > (limit) + (tol) || (actual) < (limit) - (tol)) \
389 { \
390 ASSERT_ON_FAILURE; \
391 std::ostringstream msgStream; \
392 msgStream << msg; \
393 std::ostringstream actualStream; \
394 actualStream << actual; \
395 std::ostringstream limitStream; \
396 limitStream << limit << " +- " << tol; \
397 std::ostringstream condStream; \
398 condStream << #actual << " (actual) < " << #limit \
399 << " (limit) + " << #tol << " (tol) && " \
400 << #actual << " (actual) > " << #limit \
401 << " (limit) - " << #tol << " (tol)"; \
402 ReportTestFailure (condStream.str (), actualStream.str (), \
403 limitStream.str (), msgStream.str (), \
404 file, line); \
405 CONTINUE_ON_FAILURE_RETURNS_BOOL; \
406 } ` \
407 } while (false)
408
409 /**
410 * \ingroup testing
411 *
412 * \brief Test that actual and expected (limit) values are equal to
413 * plus or minus some tolerance and report and abort if not.
414 *
415 * Check to see if the expected (limit) value is equal to the actual
416 * value found in a test case to some tolerance. This is not the same
417 * thing as asking if two floating point are equal to within some
418 * epsilon, but is useful for that case. This assertion is geared
419 * toward more of a measurement problem. Consider measuring a
420 * physical rod of some kind that you have ordered. You need to
421 * determine if it is "good." You want to measure the rod to an
422 * arbitrary precision of sixteen significant figures, you will
423 * measure the rod to determine if its length is within the tolerances
424 * you provided. For example, 12.00 inches plus or minus .005 inch
425 * may be just fine.
426 *
427 * In ns-3, you might want to measure a signal to noise ratio and
428 * check to see if the answer is what you expect. If you naively
429 * measure (double)1128.93 and compare this number with a constant
430 * 1128.93 you are almost certainly going to have your test fail
431 * because of floating point rounding errors. We provide a floating
432 * point comparison function ns3::TestDoubleIsEqual() but you will
433 * probably quickly find that is not what you want either. It may
434 * turn out to be the case that when you measured an SNR that printed
435 * as 1128.93, what was actually measured was something more like
436 * 1128.9287653857625442 for example. Given that the double epsilon
437 * is on the order of 0.0000000000000009, you would need to provide
438 * sixteen significant figures of expected value for this kind of test
439 * to pass even with a typical test for floating point "approximate
440 * equality." That is clearly not required or desired. You really
441 * want to be able to provide 1128.93 along with a tolerance just like
442 * you provided 12 inches +- 0.005 inch above.
443 *
444 * This assertion is designed for real measurements by taking into
445 * account measurement tolerances. By doing so it also automatically
446 * compensates for floating point rounding errors. If you really want
447 * to check floating point equality down to the
448 * numeric_limits<double>::epsilon () range, consider using
449 * ns3::TestDoubleIsEqual().
450 *
451 * \note Mixing signed and unsigned types can lead to misleading
452 * results.
453 *
454 * The message is interpreted as a stream, for example:
455 *
456 * \code
457 * NS_TEST_ASSERT_MSG_EQ_TOL_RETURNS_BOOL (snr, 1128.93, 0.005,
458 * "wrong snr (" << snr << ") in test");
459 * \endcode
460 *
461 * is legal.
462 *
463 * \param [in] actual Expression for the actual value found during the test.
464 * \param [in] limit Expression for the expected value of the test.
465 * \param [in] tol Tolerance of the test.
466 * \param [in] msg Message that is output if the test does not pass.
467 *
468 * This function returns a Boolean value.
469 *
470 */
471 #define NS_TEST_ASSERT_MSG_EQ_TOL_RETURNS_BOOL(actual, limit, tol, msg) \
472 NS_TEST_ASSERT_MSG_EQ_TOL_RETURNS_BOOL_INTERNAL (actual, limit, tol, msg, __FILE__, __LINE__)
473
474 /**
475 * \ingroup testingimpl
476 * \brief Test that actual and expected (limit) values are equal to
477 * plus or minus some tolerance and report if not.
478 *
479 * Required to avoid use of return statement which allows use in
480 * methods (esp. callbacks) returning void.
481 */
482 #define NS_TEST_EXPECT_MSG_EQ_TOL_INTERNAL(actual, limit, tol, msg, file, line) \
483 do { \
484 if ((actual) > (limit) + (tol) || (actual) < (limit) - (tol)) \
485 { \
486 ASSERT_ON_FAILURE; \
487 std::ostringstream msgStream; \
488 msgStream << msg; \
489 std::ostringstream actualStream; \
490 actualStream << actual; \
491 std::ostringstream limitStream; \
492 limitStream << limit << " +- " << tol; \
493 std::ostringstream condStream; \
494 condStream << #actual << " (actual) < " << #limit \
495 << " (limit) + " << #tol << " (tol) && " \
496 << #actual << " (actual) > " << #limit \
497 << " (limit) - " << #tol << " (tol)"; \
498 ReportTestFailure (condStream.str (), actualStream.str (), \
499 limitStream.str (), msgStream.str (), \
500 file, line); \
501 } \
502 } while (false)
503
504 /**
505 * \ingroup testing
506 *
507 * \brief Test that actual and expected (limit) values are equal to
508 * plus or minus some tolerance and report if not.
509 *
510 * Check to see if the expected (limit) value is equal to the actual
511 * value found in a test case to some tolerance. This is not the same
512 * thing as asking if two floating point are equal to within some
513 * epsilon, but is useful for that case. This assertion is geared
514 * toward more of a measurement problem. Consider measuring a
515 * physical rod of some kind that you have ordered. You need to
516 * determine if it is "good." You want to measure the rod to an
517 * arbitrary precision of sixteen significant figures, you will
518 * measure the rod to determine if its length is within the tolerances
519 * you provided. For example, 12.00 inches plus or minus .005 inch
520 * may be just fine.
521 *
522 * In ns-3, you might want to measure a signal to noise ratio and
523 * check to see if the answer is what you expect. If you naively
524 * measure (double)1128.93 and compare this number with a constant
525 * 1128.93 you are almost certainly going to have your test fail
526 * because of floating point rounding errors. We provide a floating
527 * point comparison function ns3::TestDoubleIsEqual() but you will
528 * probably quickly find that is not what you want either. It may
529 * turn out to be the case that when you measured an SNR that printed
530 * as 1128.93, what was actually measured was something more like
531 * 1128.9287653857625442 for example. Given that the double epsilon
532 * is on the order of 0.0000000000000009, you would need to provide
533 * sixteen significant figures of expected value for this kind of test
534 * to pass even with a typical test for floating point "approximate
535 * equality." That is clearly not required or desired. You really
536 * want to be able to provide 1128.93 along with a tolerance just like
537 * you provided 12 inches +- 0.005 inch above.
538 *
539 * This assertion is designed for real measurements by taking into
540 * account measurement tolerances. By doing so it also automatically
541 * compensates for floating point rounding errors. If you really want
542 * to check floating point equality down to the
543 * numeric_limits<double>::epsilon () range, consider using
544 * ns3::TestDoubleIsEqual().
545 *
546 * \note Mixing signed and unsigned types can lead to misleading
547 * results.
548 *
549 * The message is interpreted as a stream, for example:
550 *
551 * \code
552 * NS_TEST_EXPECT_MSG_EQ_TOL (snr, 1128.93, 0.005,
553 * "wrong snr (" << snr << ") in test");
554 * \endcode
555 *
556 * is legal.
557 *
558 * \param [in] actual Expression for the actual value found during the test.
559 * \param [in] limit Expression for the expected value of the test.
560 * \param [in] tol Tolerance of the test.
561 * \param [in] msg Message that is output if the test does not pass.
562 */
563 #define NS_TEST_EXPECT_MSG_EQ_TOL(actual, limit, tol, msg) \
564 NS_TEST_EXPECT_MSG_EQ_TOL_INTERNAL (actual, limit, tol, msg, __FILE__, __LINE__)
565
566 // ===========================================================================
567 // Test for inequality
568 // ===========================================================================
569
570 /**
571 * \ingroup testingimpl
572 * \brief Test that an actual and expected (limit) value are not equal and
573 * report and abort if not.
574 */
575 #define NS_TEST_ASSERT_MSG_NE_INTERNAL(actual, limit, msg, file, line) \
576 do { \
577 if (!((actual) != (limit))) \
578 { \
579 ASSERT_ON_FAILURE; \
580 std::ostringstream msgStream; \
581 msgStream << msg; \
582 std::ostringstream actualStream; \
583 actualStream << actual; \
584 std::ostringstream limitStream; \
585 limitStream << limit; \
586 ReportTestFailure (std::string (#actual) + " (actual) != " + \
587 std::string (#limit) + " (limit)", \
588 actualStream.str (), limitStream.str (), \
589 msgStream.str (), file, line); \
590 CONTINUE_ON_FAILURE; \
591 } \
592 } while (false)
593
594 /**
595 * \ingroup testing
596 *
597 * \brief Test that an actual and expected (limit) value are not equal
598 * and report and abort if not.
599 *
600 * Check to see if the expected (limit) value is not equal to the
601 * actual value found in a test case. If the two values are not equal
602 * nothing happens, but if the comparison fails, an error is reported
603 * in a consistent way and the execution of the current test case is
604 * aborted.
605 *
606 * The message is interpreted as a stream, for example:
607 *
608 * \code
609 * NS_TEST_ASSERT_MSG_NE (result, false,
610 * "cannot open file " << filename << " in test");
611 * \endcode
612 *
613 * is legal.
614 *
615 * \param [in] actual Expression for the actual value found during the test.
616 * \param [in] limit Expression for the value that actual is tested against.
617 * \param [in] msg Message that is output if the test does not pass.
618 *
619 * \warning Do not use this macro if you are comparing floating point
620 * numbers (float or double). Use NS_TEST_ASSERT_MSG_FLNE instead.
621 */
622 #define NS_TEST_ASSERT_MSG_NE(actual, limit, msg) \
623 NS_TEST_ASSERT_MSG_NE_INTERNAL (actual, limit, msg, __FILE__, __LINE__)
624
625 /**
626 * \ingroup testingimpl
627 * \brief Test that an actual and expected (limit) value are not equal and
628 * report and abort if not.
629 */
630 #define NS_TEST_ASSERT_MSG_NE_RETURNS_BOOL_INTERNAL(actual, limit, msg, file, line) \
631 do { \
632 if (!((actual) != (limit))) \
633 { \
634 ASSERT_ON_FAILURE; \
635 std::ostringstream msgStream; \
636 msgStream << msg; \
637 std::ostringstream actualStream; \
638 actualStream << actual; \
639 std::ostringstream limitStream; \
640 limitStream << limit; \
641 ReportTestFailure (std::string (#actual) + " (actual) != " + \
642 std::string (#limit) + " (limit)", \
643 actualStream.str (), limitStream.str (), \
644 msgStream.str (), file, line); \
645 CONTINUE_ON_FAILURE_RETURNS_BOOL; \
646 } \
647 } while (false)
648
649 /**
650 * \ingroup testing
651 *
652 * \brief Test that an actual and expected (limit) value are not equal
653 * and report and abort if not.
654 *
655 * Check to see if the expected (limit) value is not equal to the
656 * actual value found in a test case. If the two values are equal
657 * nothing happens, but if the comparison fails, an error is reported
658 * in a consistent way and the execution of the current test case is
659 * aborted.
660 *
661 * The message is interpreted as a stream, for example:
662 *
663 * \code
664 * NS_TEST_ASSERT_MSG_NE_RETURNS_BOOL (result, false,
665 * "cannot open file " << filename << " in test");
666 * \endcode
667 *
668 * is legal.
669 *
670 * \param [in] actual Expression for the actual value found during the test.
671 * \param [in] limit Expression for the expected value of the test.
672 * \param [in] msg Message that is output if the test does not pass.
673 *
674 * \warning Do not use this macro if you are comparing floating point
675 * numbers (float or double). Use NS_TEST_ASSERT_MSG_FLNE instead.
676 *
677 * This function returns a Boolean value.
678 *
679 */
680 #define NS_TEST_ASSERT_MSG_NE_RETURNS_BOOL(actual, limit, msg) \
681 NS_TEST_ASSERT_MSG_NE_RETURNS_BOOL_INTERNAL (actual, limit, msg, __FILE__, __LINE__)
682
683 /**
684 * \ingroup testingimpl
685 * \brief Test that an actual and expected (limit) value are not equal and
686 * report if not.
687 *
688 * Required to avoid use of return statement which allows use in methods
689 * (callbacks) returning void.
690 */
691 #define NS_TEST_EXPECT_MSG_NE_INTERNAL(actual, limit, msg, file, line) \
692 do { \
693 if (!((actual) != (limit))) \
694 { \
695 ASSERT_ON_FAILURE; \
696 std::ostringstream msgStream; \
697 msgStream << msg; \
698 std::ostringstream actualStream; \
699 actualStream << actual; \
700 std::ostringstream limitStream; \
701 limitStream << limit; \
702 ReportTestFailure (std::string (#actual) + " (actual) != " + \
703 std::string (#limit) + " (limit)", \
704 actualStream.str (), limitStream.str (), \
705 msgStream.str (), file, line); \
706 } \
707 } while (false)
708
709 /**
710 * \ingroup testing
711 *
712 * \brief Test that an actual and expected (limit) value are not equal
713 * and report if not.
714 *
715 * Check to see if the expected (limit) value is not equal to the
716 * actual value found in a test case. If the two values are not equal
717 * nothing happens, but if the comparison fails, an error is reported
718 * in a consistent way. EXPECT* macros do not return if an error is
719 * detected.
720 *
721 * The message is interpreted as a stream, for example:
722 *
723 * \code
724 * NS_TEST_EXPECT_MSG_NE (result, false,
725 * "cannot open file " << filename << " in test");
726 * \endcode
727 *
728 * is legal.
729 *
730 * \param [in] actual Expression for the actual value found during the test.
731 * \param [in] limit Expression for the value that actual is tested against.
732 * \param [in] msg Message that is output if the test does not pass.
733 *
734 * \warning Do not use this macro if you are comparing floating point
735 * numbers (float or double). Use NS_TEST_EXPECT_MSG_FLNE instead.
736 */
737 #define NS_TEST_EXPECT_MSG_NE(actual, limit, msg) \
738 NS_TEST_EXPECT_MSG_NE_INTERNAL (actual, limit, msg, __FILE__, __LINE__)
739
740 // ===========================================================================
741 // Test for less than relation
742 // ===========================================================================
743
744 /**
745 * \ingroup testingimpl
746 * \brief Test that an actual value is less than a limit and report and abort
747 * if not.
748 */
749 #define NS_TEST_ASSERT_MSG_LT_INTERNAL(actual, limit, msg, file, line) \
750 do { \
751 if (!((actual) < (limit))) \
752 { \
753 ASSERT_ON_FAILURE; \
754 std::ostringstream msgStream; \
755 msgStream << msg; \
756 std::ostringstream actualStream; \
757 actualStream << actual; \
758 std::ostringstream limitStream; \
759 limitStream << limit; \
760 ReportTestFailure (std::string (#actual) + " (actual) < " + \
761 std::string (#limit) + " (limit)", \
762 actualStream.str (), limitStream.str (), \
763 msgStream.str (), file, line); \
764 CONTINUE_ON_FAILURE; \
765 } \
766 } while (false)
767
768 /**
769 * \ingroup testingimpl
770 * \brief Test that an actual value is less than or equal to a limit and report
771 * and abort if not.
772 */
773 #define NS_TEST_ASSERT_MSG_LT_OR_EQ_INTERNAL(actual, limit, msg, file, line) \
774 do { \
775 if (!((actual) <= (limit))) \
776 { \
777 ASSERT_ON_FAILURE; \
778 std::ostringstream msgStream; \
779 msgStream << msg; \
780 std::ostringstream actualStream; \
781 actualStream << actual; \
782 std::ostringstream limitStream; \
783 limitStream << limit; \
784 ReportTestFailure (std::string (#actual) + " (actual) < " + \
785 std::string (#limit) + " (limit)", \
786 actualStream.str (), limitStream.str (), \
787 msgStream.str (), file, line); \
788 CONTINUE_ON_FAILURE; \
789 } \
790 } while (false)
791
792 /**
793 * \ingroup testing
794 *
795 * \brief Test that an actual value is less than a limit and report
796 * and abort if not.
797 *
798 * Check to see if the actual value found in a test case is less than
799 * the limit value. If the actual value is lesser nothing happens,
800 * but if the check fails, an error is reported in a consistent way
801 * and the execution of the current test case is aborted.
802 *
803 * The message is interpreted as a stream.
804 *
805 * \param [in] actual Expression for the actual value found during the test.
806 * \param [in] limit Expression for the limit value of the test.
807 * \param [in] msg Message that is output if the test does not pass.
808 */
809 #define NS_TEST_ASSERT_MSG_LT(actual, limit, msg) \
810 NS_TEST_ASSERT_MSG_LT_INTERNAL (actual, limit, msg, __FILE__, __LINE__)
811
812 /**
813 * \ingroup testing
814 *
815 * \brief Test that an actual value is less than or equal to a limit
816 * and report and abort if not.
817 *
818 * Check to see if the actual value found in a test case is less than
819 * or equal to the limit value. If the actual value is lesser or
820 * equal nothing happens, but if the check fails, an error is reported
821 * in a consistent way and the execution of the current test case is
822 * aborted.
823 *
824 * The message is interpreted as a stream.
825 *
826 * \param [in] actual Expression for the actual value found during the test.
827 * \param [in] limit Expression for the limit value of the test.
828 * \param [in] msg Message that is output if the test does not pass.
829 */
830 #define NS_TEST_ASSERT_MSG_LT_OR_EQ(actual, limit, msg) \
831 NS_TEST_ASSERT_MSG_LT_OR_EQ_INTERNAL (actual, limit, msg, __FILE__, __LINE__)
832
833 /**
834 * \ingroup testingimpl
835 * \brief Test that an actual value is less than a limit and report if not.
836 *
837 * Required to avoid use of return statement which allows use in methods
838 * (callbacks) returning void.
839 */
840 #define NS_TEST_EXPECT_MSG_LT_INTERNAL(actual, limit, msg, file, line) \
841 do { \
842 if (!((actual) < (limit))) \
843 { \
844 ASSERT_ON_FAILURE; \
845 std::ostringstream msgStream; \
846 msgStream << msg; \
847 std::ostringstream actualStream; \
848 actualStream << actual; \
849 std::ostringstream limitStream; \
850 limitStream << limit; \
851 ReportTestFailure (std::string (#actual) + " (actual) < " + \
852 std::string (#limit) + " (limit)", \
853 actualStream.str (), limitStream.str (), \
854 msgStream.str (), file, line); \
855 } \
856 } while (false)
857
858 /**
859 * \ingroup testingimpl
860 * \brief Test that an actual value is less than or equal to a limit
861 * and report if not.
862 *
863 * Required to avoid use of return statement which allows use in
864 * methods (callbacks) returning void.
865 */
866 #define NS_TEST_EXPECT_MSG_LT_OR_EQ_INTERNAL(actual, limit, msg, file, line) \
867 do { \
868 if (!((actual) <= (limit))) \
869 { \
870 ASSERT_ON_FAILURE; \
871 std::ostringstream msgStream; \
872 msgStream << msg; \
873 std::ostringstream actualStream; \
874 actualStream << actual; \
875 std::ostringstream limitStream; \
876 limitStream << limit; \
877 ReportTestFailure (std::string (#actual) + " (actual) < " + \
878 std::string (#limit) + " (limit)", \
879 actualStream.str (), limitStream.str (), \
880 msgStream.str (), file, line); \
881 } \
882 } while (false)
883
884 /**
885 * \ingroup testing
886 *
887 * \brief Test that an actual value is less than a limit and report if
888 * not.
889 *
890 * Check to see if the actual value found in a test case is less than
891 * the limit value. If the actual value is lesser nothing happens,
892 * but if the check fails, an error is reported in a consistent way.
893 * EXPECT* macros do not return if an error is detected.
894 *
895 * The message is interpreted as a stream.
896 *
897 * \param [in] actual Expression for the actual value found during the test.
898 * \param [in] limit Expression for the limit value of the test.
899 * \param [in] msg Message that is output if the test does not pass.
900 */
901 #define NS_TEST_EXPECT_MSG_LT(actual, limit, msg) \
902 NS_TEST_EXPECT_MSG_LT_INTERNAL (actual, limit, msg, __FILE__, __LINE__)
903
904 /**
905 * \ingroup testing
906 *
907 * \brief Test that an actual value is less than or equal to a limit
908 * and report if not.
909 *
910 * Check to see if the actual value found in a test case is less than
911 * or equal to the limit value. If the actual value is lesser or
912 * equal nothing happens, but if the check fails, an error is reported
913 * in a consistent way. EXPECT* macros do not return if an error is
914 * detected.
915 *
916 * The message is interpreted as a stream.
917 *
918 * \param [in] actual Expression for the actual value found during the test.
919 * \param [in] limit Expression for the limit value of the test.
920 * \param [in] msg Message that is output if the test does not pass.
921 */
922 #define NS_TEST_EXPECT_MSG_LT_OR_EQ(actual, limit, msg) \
923 NS_TEST_EXPECT_MSG_LT_OR_EQ_INTERNAL (actual, limit, msg, __FILE__, __LINE__)
924
925 // ===========================================================================
926 // Test for greater than relation
927 // ===========================================================================
928
929 /**
930 * \ingroup testingimpl
931 * \brief Test that an actual value is greater than a limit and report and abort
932 * if not.
933 */
934 #define NS_TEST_ASSERT_MSG_GT_INTERNAL(actual, limit, msg, file, line) \
935 do { \
936 if (!((actual) > (limit))) \
937 { \
938 ASSERT_ON_FAILURE; \
939 std::ostringstream msgStream; \
940 msgStream << msg; \
941 std::ostringstream actualStream; \
942 actualStream << actual; \
943 std::ostringstream limitStream; \
944 limitStream << limit; \
945 ReportTestFailure (std::string (#actual) + " (actual) > " + \
946 std::string (#limit) + " (limit)", \
947 actualStream.str (), limitStream.str (), \
948 msgStream.str (), file, line); \
949 CONTINUE_ON_FAILURE; \
950 } \
951 } while (false)
952
953 /**
954 * \ingroup testingimpl
955 * \brief Test that an actual value is greater than or equal to a
956 * limit and report and abort if not.
957 */
958 #define NS_TEST_ASSERT_MSG_GT_OR_EQ_INTERNAL(actual, limit, msg, file, line) \
959 do { \
960 if (!((actual) >= (limit))) \
961 { \
962 ASSERT_ON_FAILURE; \
963 std::ostringstream msgStream; \
964 msgStream << msg; \
965 std::ostringstream actualStream; \
966 actualStream << actual; \
967 std::ostringstream limitStream; \
968 limitStream << limit; \
969 ReportTestFailure (std::string (#actual) + " (actual) > " + \
970 std::string (#limit) + " (limit)", \
971 actualStream.str (), limitStream.str (), \
972 msgStream.str (), file, line); \
973 CONTINUE_ON_FAILURE; \
974 } \
975 } while (false)
976
977 /**
978 * \ingroup testing
979 *
980 * \brief Test that an actual value is greater than a limit and report
981 * and abort if not.
982 *
983 * Check to see if the actual value found in a test case is greater
984 * than the limit value. If the actual value is greater nothing
985 * happens, but if the check fails, an error is reported in a
986 * consistent way and the execution of the current test case is
987 * aborted.
988 *
989 * The message is interpreted as a stream.
990 *
991 * \param [in] actual Expression for the actual value found during the test.
992 * \param [in] limit Expression for the limit value of the test.
993 * \param [in] msg Message that is output if the test does not pass.
994 */
995 #define NS_TEST_ASSERT_MSG_GT(actual, limit, msg) \
996 NS_TEST_ASSERT_MSG_GT_INTERNAL (actual, limit, msg, __FILE__, __LINE__)
997
998 /**
999 * \ingroup testing
1000 *
1001 * \brief Test that an actual value is greater than or equal to a
1002 * limit and report and abort if not.
1003 *
1004 * Check to see if the actual value found in a test case is greater
1005 * than or equal to the limit value. If the actual value is greater
1006 * nothing happens, but if the check fails, an error is reported in a
1007 * consistent way and the execution of the current test case is
1008 * aborted.
1009 *
1010 * The message is interpreted as a stream.
1011 *
1012 * \param [in] actual Expression for the actual value found during the test.
1013 * \param [in] limit Expression for the limit value of the test.
1014 * \param [in] msg Message that is output if the test does not pass.
1015 */
1016 #define NS_TEST_ASSERT_MSG_GT_OR_EQ(actual, limit, msg) \
1017 NS_TEST_ASSERT_MSG_GT_OR_EQ_INTERNAL (actual, limit, msg, __FILE__, __LINE__)
1018
1019 /**
1020 * \ingroup testingimpl
1021 * \brief Test that an actual value is greater than a limit and report if not.
1022 *
1023 * Required to avoid use of return statement which allows use in methods
1024 * (callbacks) returning void.
1025 */
1026 #define NS_TEST_EXPECT_MSG_GT_INTERNAL(actual, limit, msg, file, line) \
1027 do { \
1028 if (!((actual) > (limit))) \
1029 { \
1030 ASSERT_ON_FAILURE; \
1031 std::ostringstream msgStream; \
1032 msgStream << msg; \
1033 std::ostringstream actualStream; \
1034 actualStream << actual; \
1035 std::ostringstream limitStream; \
1036 limitStream << limit; \
1037 ReportTestFailure (std::string (#actual) + " (actual) > " + \
1038 std::string (#limit) + " (limit)", \
1039 actualStream.str (), limitStream.str (), \
1040 msgStream.str (), file, line); \
1041 } \
1042 } while (false)
1043
1044 /**
1045 * \ingroup testingimpl
1046 * \brief Test that an actual value is greater than or equal to limit
1047 * and report if not.
1048 *
1049 * Required to avoid use of return statement which allows use in
1050 * methods (callbacks) returning void.
1051 */
1052 #define NS_TEST_EXPECT_MSG_GT_OR_EQ_INTERNAL(actual, limit, msg, file, line) \
1053 do { \
1054 if (!((actual) >= (limit))) \
1055 { \
1056 ASSERT_ON_FAILURE; \
1057 std::ostringstream msgStream; \
1058 msgStream << msg; \
1059 std::ostringstream actualStream; \
1060 actualStream << actual; \
1061 std::ostringstream limitStream; \
1062 limitStream << limit; \
1063 ReportTestFailure (std::string (#actual) + " (actual) > " + \
1064 std::string (#limit) + " (limit)", \
1065 actualStream.str (), limitStream.str (), \
1066 msgStream.str (), file, line); \
1067 } \
1068 } while (false)
1069
1070 /**
1071 * \ingroup testing
1072 *
1073 * \brief Test that an actual value is greater than a limit and report
1074 * if not.
1075 *
1076 * Check to see if the actual value found in a test case is greater
1077 * than the limit value. If the actual value is greater nothing
1078 * happens, but if the check fails, an error is reported in a
1079 * consistent way. EXPECT* macros do not return if an error is
1080 * detected.
1081 *
1082 * The message is interpreted as a stream.
1083 *
1084 * \param [in] actual Expression for the actual value found during the test.
1085 * \param [in] limit Expression for the limit value of the test.
1086 * \param [in] msg Message that is output if the test does not pass.
1087 */
1088 #define NS_TEST_EXPECT_MSG_GT(actual, limit, msg) \
1089 NS_TEST_EXPECT_MSG_GT_INTERNAL (actual, limit, msg, __FILE__, __LINE__)
1090
1091 /**
1092 * \ingroup testing
1093 *
1094 * \brief Test that an actual value is greater than or equal to limit
1095 * and report if not.
1096 *
1097 * Check to see if the actual value found in a test case is greater
1098 * than or equal to the limit value. If the actual value is greater
1099 * nothing happens, but if the check fails, an error is reported in a
1100 * consistent way. EXPECT* macros do not return if an error is
1101 * detected.
1102 *
1103 * The message is interpreted as a stream.
1104 *
1105 * \param [in] actual Expression for the actual value found during the test.
1106 * \param [in] limit Expression for the limit value of the test.
1107 * \param [in] msg Message that is output if the test does not pass.
1108 */
1109 #define NS_TEST_EXPECT_MSG_GT_OR_EQ(actual, limit, msg) \
1110 NS_TEST_EXPECT_MSG_GT_OR_EQ_INTERNAL (actual, limit, msg, __FILE__, __LINE__)
1111
1112
1113 /**
1114 * \ingroup testing
1115 * \brief Compare two double precision floating point numbers and
1116 * declare them equal if they are within some epsilon of each other.
1117 *
1118 * Approximate comparison of floating point numbers near equality is
1119 * trickier than one may expect and is well-discussed in the
1120 * literature. Basic strategies revolve around a suggestion by Knuth
1121 * to compare the floating point numbers as binary integers, supplying
1122 * a maximum difference between them . This max difference is
1123 * specified in Units in the Last Place (ulps) or a floating point
1124 * epsilon.
1125 *
1126 * This routine is based on the GNU Scientific Library function
1127 * gsl_fcmp.
1128 *
1129 * \param [in] a The first of double precision floating point
1130 * numbers to compare
1131 * \param [in] b The second of double precision floating point
1132 * numbers to compare
1133 * \param [in] epsilon The tolerance to use in the comparison.
1134 * \returns Returns \c true if the doubles are equal to a precision
1135 * defined by epsilon
1136 */
1137 bool TestDoubleIsEqual (const double a, const double b,
1138 const double epsilon = std::numeric_limits<double>::epsilon ());
1139
1140 class TestRunnerImpl;
1141
1142 /**
1143 * \ingroup testing
1144 *
1145 * \brief encapsulates test code
1146 *
1147 * To allow a new test to be run within the ns-3 test framework, users
1148 * need to create subclasses of this base class, override the DoRun
1149 * method, and use the NS_TEST_* macros within DoRun.
1150 *
1151 * \see sample-test-suite.cc
1152 */
1153 class TestCase : private NonCopyable
1154 {
1155 public:
1156 /** \brief How long the test takes to execute. */
1157 enum TestDuration
1158 {
1159 QUICK = 1, //!< Fast test.
1160 EXTENSIVE = 2, //!< Medium length test.
1161 TAKES_FOREVER = 3 //!< Very long running test.
1162 };
1163
1164 /**
1165 * Destructor
1166 */
1167 virtual ~TestCase ();
1168
1169 /**
1170 * \return The name of this test
1171 */
1172 std::string GetName (void) const;
1173
1174 protected:
1175 /**
1176 * \brief Constructor.
1177 *
1178 * \param [in] name The name of the new TestCase created
1179 */
1180 TestCase (std::string name);
1181
1182 /**
1183 * \brief Add an individual child TestCase to this test suite.
1184 *
1185 * \param [in] testCase Pointer to the TestCase object to be added.
1186 * \param [in] duration Amount of time this test takes to execute
1187 * (defaults to QUICK).
1188 */
1189 void AddTestCase (TestCase *testCase, TestDuration duration = QUICK);
1190
1191 /**
1192 * \brief Set the data directory where reference trace files can be
1193 * found.
1194 *
1195 * \param [in] directory The directory where the test data is
1196 * located
1197 *
1198 * In general, this method is invoked as SetDataDir
1199 * (NS_TEST_SOURCEDIR); However, if a module contains a test
1200 * directory with subdirectories (e.g. src/mesh/test), and the test
1201 * data (e.g. pcap traces) is located in one of these
1202 * subdirectories, then the variable NS_TEST_SOURCEDIR may not work
1203 * and the user may want to explicitly pass in a directory string.
1204 *
1205 * Note that NS_TEST_SOURCEDIR is set in src/wscript for each module
1206 */
1207 void SetDataDir (std::string directory);
1208
1209 /**
1210 * \brief Check if any tests failed.
1211 *
1212 * \return \c true if any of the tests have failed, \c false otherwise.
1213 */
1214 bool IsStatusFailure (void) const;
1215 /**
1216 * \brief Check if all tests passed.
1217 *
1218 * \return \c true if the tests have succeeded, \c false otherwise.
1219 */
1220 bool IsStatusSuccess (void) const;
1221
1222 /**
1223 * \brief Get the parent of this TestCsse.
1224 *
1225 * \return A pointer to the parent of this test.
1226 */
1227 TestCase * GetParent () const;
1228
1229 /**
1230 * \name Internal Interface
1231 * These methods are the interface used by test macros and should not
1232 * be used directly by normal test code.
1233 * @{
1234 */
1235 /**
1236 * \brief Log the failure of this TestCase.
1237 *
1238 * \param [in] cond The test condition.
1239 * \param [in] actual Actual value of the test.
1240 * \param [in] limit Expected value of the test.
1241 * \param [in] message Message indicating the type of failure.
1242 * \param [in] file The file where the test failed.
1243 * \param [in] line The line number in \pname{file} where the test failed.
1244 */
1245 void ReportTestFailure (std::string cond, std::string actual,
1246 std::string limit, std::string message,
1247 std::string file, int32_t line);
1248 /**
1249 * \brief Check if this run should assert on failure.
1250 *
1251 * \return \c true if we should assert on failure.
1252 */
1253 bool MustAssertOnFailure (void) const;
1254 /**
1255 * \brief Check if this run should continue on failure.
1256 *
1257 * \return \c true if we should continue on failure.
1258 */
1259 bool MustContinueOnFailure (void) const;
1260 /**
1261 * \brief Construct the full path to a file in the data directory.
1262 *
1263 * The data directory is configured by SetDataDirectory().
1264 *
1265 * \param [in] filename The bare (no path) file name
1266 * \return The full path to \pname{filename} in the data directory
1267 */
1268 std::string CreateDataDirFilename (std::string filename);
1269 /**
1270 * \brief Construct the full path to a file in a temporary directory.
1271 *
1272 * If the TestRunner is invoked with "--update-data", this will be
1273 * the data directory instead.
1274 *
1275 * \param [in] filename The bare (no path) file name
1276 * \return The full path to \pname{filename} in the temporary directory.
1277 */
1278 std::string CreateTempDirFilename (std::string filename);
1279 /**@}*/
1280
1281 private:
1282
1283 /** Needs access to the TestCase data members. */
1284 friend class TestRunnerImpl;
1285
1286 /**
1287 * \brief Implementation to do any local setup required for this
1288 * TestCase.
1289 *
1290 * Subclasses should override this method to perform any costly
1291 * per-test setup before DoRun is invoked.
1292 */
1293 virtual void DoSetup (void);
1294
1295 /**
1296 * \brief Implementation to actually run this TestCase.
1297 *
1298 * Subclasses should override this method to conduct their tests.
1299 */
1300 virtual void DoRun (void) = 0;
1301
1302 /**
1303 * \brief Implementation to do any local setup required for this
1304 * TestCase.
1305 *
1306 * Subclasses should override this method to perform any costly
1307 * per-test teardown
1308 */
1309 virtual void DoTeardown (void);
1310
1311 // methods called by TestRunnerImpl
1312 /**
1313 * \brief Actually run this TestCase
1314 *
1315 * \param [in] runner The test runner implementation.
1316 */
1317 void Run (TestRunnerImpl *runner);
1318 /** \copydoc IsStatusFailure() */
1319 bool IsFailed (void) const;
1320
1321 /**
1322 * \ingroup testingimpl
1323 * \brief Container for results from a TestCase.
1324 */
1325 struct Result;
1326
1327 TestCase *m_parent; //!< Pointer to my parent TestCase
1328 std::vector<TestCase *> m_children; //!< Vector of my children
1329 std::string m_dataDir; //!< My data directory
1330 TestRunnerImpl *m_runner; //!< Pointer to the TestRunner
1331 struct Result *m_result; //!< Results data
1332 std::string m_name; //!< TestCase name
1333 enum TestDuration m_duration; //!< TestCase duration
1334 };
1335
1336 /**
1337 * \ingroup testing
1338 *
1339 * \brief A suite of tests to run.
1340 *
1341 * \see sample-test-suite.cc
1342 */
1343 class TestSuite : public TestCase
1344 {
1345 public:
1346 /**
1347 * \enum Type
1348 * \brief Type of test.
1349 */
1350 enum Type
1351 {
1352 ALL = 0, //!<
1353 UNIT, //!< This test suite implements a Unit Test
1354 SYSTEM, //!< This test suite implements a System Test
1355 EXAMPLE, //!< This test suite implements an Example Test
1356 PERFORMANCE //!< This test suite implements a Performance Test
1357 };
1358
1359 /**
1360 * \brief Construct a new test suite.
1361 *
1362 * \param [in] name The name of the test suite.
1363 * \param [in] type The TestType of the test suite (defaults to UNIT test).
1364 */
1365 TestSuite (std::string name, Type type = UNIT);
1366
1367 /**
1368 * \brief get the kind of test this test suite implements
1369 *
1370 * \returns The Type of the suite.
1371 */
1372 TestSuite::Type GetTestType (void);
1373
1374 private:
1375 // Inherited
1376 virtual void DoRun (void);
1377
1378 TestSuite::Type m_type; //!< Type of this TestSuite
1379 };
1380
1381 /**
1382 * \ingroup testingimpl
1383 *
1384 * \brief A runner to execute tests.
1385 */
1386 class TestRunner
1387 {
1388 public:
1389 /**
1390 * Run the requested suite of tests,
1391 * according to the given command line arguments.
1392 *
1393 * \param [in] argc The number of elements in \pname{argv}
1394 * \param [in] argv The vector of command line arguments
1395 * \returns Success status
1396 */
1397 static int Run (int argc, char *argv[]);
1398 };
1399
1400 /**
1401 * \ingroup testing
1402 *
1403 * \brief A simple way to store test vectors (for stimulus or from responses)
1404 */
1405 template <typename T>
1406 class TestVectors : private NonCopyable
1407 {
1408 public:
1409 /**
1410 * Constructor
1411 */
1412 TestVectors ();
1413 /**
1414 * Virtual destructor
1415 */
1416 virtual ~TestVectors ();
1417
1418 /**
1419 * \brief Set the expected length of this vector.
1420 *
1421 * \param [in] reserve The number of entries to reserve
1422 */
1423 void Reserve (uint32_t reserve);
1424
1425 /**
1426 * \param [in] vector The test vector to add
1427 *
1428 * \returns The new test vector index
1429 */
1430 std::size_t Add (T vector);
1431
1432 /**
1433 * \brief Get the total number of test vectors.
1434 * \return The number of test vectors
1435 */
1436 std::size_t GetN (void) const;
1437 /**
1438 * \brief Get the i'th test vector
1439 * \param [in] i The requested vector index
1440 * \return The requested vector
1441 */
1442 T Get (std::size_t i) const;
1443
1444 private:
1445 typedef std::vector<T> TestVector; //!< Container type
1446 TestVector m_vectors; //!< The list of test vectors
1447 };
1448
1449 template <typename T>
TestVectors()1450 TestVectors<T>::TestVectors ()
1451 : m_vectors ()
1452 {}
1453
1454 template <typename T>
1455 void
Reserve(uint32_t reserve)1456 TestVectors<T>::Reserve (uint32_t reserve)
1457 {
1458 m_vectors.reserve (reserve);
1459 }
1460
1461 template <typename T>
~TestVectors()1462 TestVectors<T>::~TestVectors ()
1463 {}
1464
1465 template <typename T>
1466 std::size_t
Add(T vector)1467 TestVectors<T>::Add (T vector)
1468 {
1469 std::size_t index = m_vectors.size ();
1470 m_vectors.push_back (vector);
1471 return index;
1472 }
1473
1474 template <typename T>
1475 std::size_t
GetN(void)1476 TestVectors<T>::GetN (void) const
1477 {
1478 return m_vectors.size ();
1479 }
1480
1481 template <typename T>
1482 T
Get(std::size_t i)1483 TestVectors<T>::Get (std::size_t i) const
1484 {
1485 NS_ABORT_MSG_UNLESS (m_vectors.size () > i, "TestVectors::Get(): Bad index");
1486 return m_vectors[i];
1487 }
1488
1489 } // namespace ns3
1490
1491 #endif /* NS3_TEST_H */
1492