1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
|
<HTML>
<HEAD>
<TITLE>The Test Tools</TITLE>
<LINK rel="stylesheet" type="text/css" href="../../style/btl.css" media="screen">
<LINK rel="stylesheet" type="text/css" href="../../style/btl-print.css" media="print">
<META http-equiv="Content-Language" content="en-us">
<META http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
</HEAD>
<BODY>
<DIV class="header"> <A href="../../index.html">Boost.Test</A> > <A href="../index.html">Components</A> > <SPAN class="current_article">The
Test Tools</SPAN> </DIV>
<DIV class="body"> <IMG src='../../btl1.gif' width='252' height='43' alt="Boost Test logo">
<H1>Boost Test Library: The Test Tools</H1>
<P class="page-toc"> <A href="#Introduction">Introduction</A><BR>
<A href="reference/index.html">Reference</A><BR>
<A href="#Implementation">Implementation</A><BR>
<A href="#Examples">Examples and tests</A><BR>
</P>
<H2><A name="Introduction">Introduction</A></H2>
<P class="first-line-indented"> Boost Test Library's Test Tools supply a toolbox
to ease a creation and a maintenance of test programs and provide a uniform
error reporting mechanism. The toolbox supplied in a form of macro and function
declarations. While the functions can be called directly, the usual way to
use Test Tools is via convenience macros. All macros arguments are calculated
once, so it's safe to pass complex expressions in their place. All macros
provide an error location: a file name and a line number. Boost Test Library's
Test Tools are intended for test code rather than library or production code,
where throwing exceptions, using assert(), <A href="../../../../../libs/concept_check/index.html">boost::concept_check</A> or
<A href="../../../../../libs/static_assert/static_assert.htm">BOOST_STATIC_ASSERT</A>()
may be more suitable ways to detect and report errors. To use the Test Tools
you need to link with either the <A href="../test_exec_monitor/index.html">Test
Execution Monitor</A> or the <A href="../utf/index.html">Unit Test Framework</A>.
For list of all supplied Test Tools and usage examples see the <A href="reference/index.html">reference</A>.</P>
<P class="first-line-indented">Most of the tools supplied comes in three variations(levels):
WARN, CHECK and REQUIRE ( for example BOOST_WARN_EQUAL, BOOST_CHECK_EQUAL,
BOOST_REQUIRE_EQUAL). If an assertion designated by the tool passes, confirmation
message could be printed in log output (note:
to manage what messages appear in the test log stream set the proper log
level). If an assertion designated by the tool failed, depending on the level
following will happened (in some cases log message could be slightly different
to reflect failed tool specifics):</P>
<TABLE border="0" cellpadding="10" cellspacing="0">
<TR>
<TH style="border-bottom: solid 2px black; border-right: solid 1px black;">Level</TH>
<TH style="border-bottom: solid 2px black; border-right: solid 1px black;">Output log content </TH>
<TH style="border-bottom: solid 2px black; border-right: solid 1px black;">Errors counter </TH>
<TH style="border-bottom: solid 2px black">Test execution </TH>
</TR>
<TR>
<TD style="border-right: solid 1px black;">WARN</TD>
<TD style="border-right: solid 1px black;">warning in <test case
name>:
condition <assertion description> is not satisfied</TD>
<TD style="border-right: solid 1px black;">not affected</TD>
<TD>continues</TD>
</TR>
<TR>
<TD style="border-right: solid 1px black;">CHECK</TD>
<TD style="border-right: solid 1px black;">error in <test case name>:
test <assertion description> failed</TD>
<TD style="border-right: solid 1px black;">increased</TD>
<TD>continues</TD>
</TR>
<TR>
<TD style="border-right: solid 1px black;">REQUIRE</TD>
<TD style="border-right: solid 1px black;">fatal error in <test case
name>: critical test <assertion description> failed</TD>
<TD style="border-right: solid 1px black;">increased</TD>
<TD>aborts</TD>
</TR>
</TABLE>
<P class="first-line-indented">Regularly you should use CHECK level tools to
implement your assertions.You could use WARN level tools to validate aspects
less important then correctness: performance, portability, usability etc.
You should use REQUIRE level tools only if continuation of the test doesn't
make sense if this assertions fails.</P>
<P class="first-line-indented">Among many tools in supplied toolbox, there
are the BOOST_<level>_CLOSE
tools that perform floating point comparison of values. See <A href="floating_point_comparison.html">floating
point comparison</A> page
for detailed description of used algorithms.</P>
<P class="first-line-indented">In addition to toolbox, the Test Tools also
contains separate ostream_test_stream tool. This is class designed to significantly
simplify correctness testing of the ostream based output procedures. For
detailed description of it's interface and usage see the <A href="output_test_stream.html">ostream_test_stream</A> page.</P>
<P class="first-line-indented">Most of test tools direct values of their arguments
to the output stream in some form of log statement. If arguments type does
not support operator<<(...) interface you will get a compilation error.
You could either implement above interface or prohibit Test tools from logging
argument values for specified type. To do so use following statement on file
level before first test case including statements failing to comply:</P>
<P class="first-line-indented"><SPAN class="new-term">BOOST_TEST_DONT_PRINT_LOG_VALUE</SPAN>(
ArgumentType ).</P>
<P class="first-line-indented">Even though supplied test tools cover wide range
of possible checks and provide detailed report on cause of error in some
cases you may want to implement and use custom predicate that perform complex
check and produce intelligent report on failure. To satisfy this need test
tools implements <A href="custom_predicate_support.html">custom predicate
support</A>.</P>
<H2><A name="Implementation">Implementation</A></H2>
<P class="first-line-indented">The Test Tools are implemented in three modules:
two header files and one source file. </P>
<H4><A href="../../../../../boost/test/test_tools.hpp">boost/test/test_tools.hpp</A>:</H4>
<P class="first-line-indented">contains definition for the convenience macros,
some template based Test Tools implementation functions and class ostream_test_stream.</P>
<H4><A href="../../../../../boost/test/floating_point_comparison.hpp">Boost/test/floating_point_comparison.hpp</A>:</H4>
<P class="first-line-indented">contains implementation for the floating point
comparison algorithms, used by BOOST_CHECK_CLOSE tool. They also could be
used directly.</P>
<H4><A href="../../../src/test_tools.cpp">libs/test/test_tools.cpp</A>:</H4>
<P class="first-line-indented">contains definition for the most Test Tools
implementation functions and class ostream_test_stream implementation.</P>
<P class="first-line-indented">Since this component is not intended to be used
standalone, there are no special compilation instruction for it.</P>
<H2><A name="Examples">Examples and Tests</A></H2>
<P class="indented"><A href="../../examples/test_exec_monitor_example.html">test_exec_example</A><BR>
<A href="../../tests/test_exec_fail2.html">test_exec_fail2</A><BR>
<A href="../../tests/test_exec_fail3.html">test_exec_fail3</A><BR>
<A href="../../tests/test_tools_test.html">test_tools_test</A><BR>
<A href="../../tests/test_fp_comparisons.html">test_fp_comparisons</A> </P>
</DIV>
<DIV class="footer">
<DIV class="footer-body">
<P> © <A name="Copyright">Copyright</A> <A href='mailto:boost-test at emailaccount dot com (please unobscure)'>Gennadiy
Rozental</A> 2001-2005. <BR>
Distributed under the Boost Software License, Version 1.0. (See accompanying
file <A href="../../../../../LICENSE_1_0.txt">LICENSE_1_0.txt</A> or copy
at <A href="http://www.boost.org/LICENSE_1_0.txt">www.boost.org/LICENSE_1_0.txt</A>)</P>
<P>Revised:
<!-- #BeginDate format:Sw1 -->11 July, 2005<!-- #EndDate -->
</P>
</DIV>
</DIV>
</BODY>
</HTML>
|
