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
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<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="floating_point_comparison.html">Floating point comparison algorithms</A><BR>
<A href="custom_predicate_support.html">Output testing tool<BR>
Custom predicate support </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 component supply
a toolbox of instruments to ease a creation and a maintenance of test programs
and provide a uniform error reporting mechanism. The toolbox supplied in
most part 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 tools automatically supply an error location:
a file name and a line number. Boost Test Library's Test Tools are intended
for unit 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. For list of all supplied
Test Tools and usage examples see the <A href="reference/index.html">reference</A>.</P>
<H5>Test Tools flavours</H5>
<P class="first-line-indented">All the tools supplied (with one exclusion)
in three flavours(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 case
doesn't make sense if this assertions fails.</P>
<H5>Output testing tool </H5>
<P class="first-line-indented">In addition to the checking tools toolbox, the
Test Tools also contains class ostream_test_stream. This is a class designed
to significantly simplify correctness testing of the ostream based output
procedures. Detailed description of interface and example usage you
could see on the <A href="output_test_stream.html">ostream_test_stream</A> page.</P>
<H5>Logging tool arguments </H5>
<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<<(std::ostream&,ArgumentType const&) interface
you will get a compilation error. You could either implement above interface
or prohibit the Test Tools from logging argument values for specified type.
To do so use following statement on file level before first test case that
includes statement failing to compile:</P>
<P class="first-line-indented"><SPAN class="new-term">BOOST_TEST_DONT_PRINT_LOG_VALUE</SPAN>(
ArgumentType ).</P>
<H5>Logging floating point numbers</H5>
<P class="first-line-indented">It may appear that floating-point numbers are
displayed by Boost.Test with an excessive number of decimal digits. However
the number of digits shown is chosen to avoid apparently nonsensical displays
like [1.00000 != 1.00000] when comparing exactly unity against a value which
is increased by just one least significant binary digit using the default
precision for float of just 6 decimal digits, given by std::numeric_limits<float>::digits10.
The function used for the number of decimal digits displayed is that proposed
for a future C++ Standard, <A href="http://www2.open-std.org/JTC1/SC22/WG21/docs/papers/2005/n1822.pdf">A
Proposal to add a max significant decimal digits value</A>, to be called
numeric_limits::max_digits10();. For 32-bit floats, 9 decimal digits are
needed to ensure a single bit change produces a different decimal digit string.</P>
<P class="first-line-indented">So a much more helpful display using 9 decimal
digits is thus: [1.00000000 != 1.00000012] showing that the two values are
in fact different.</P>
<P class="first-line-indented">For IEEE754 32-bit float values - 9 decimal
digits are shown. For 64-bit IEEE754 double - 17 decimal digits.<BR>
For IEEE754 extended long double using 80-bit - 21 decimal digits. For
IEEE754 quadruple long double 128-bit, and Sparc extended long double 128-bit
- 36 decimal digits. For floating-point types, a convenient formula to calculate
max_digits10 is:<BR>
2 + std::numeric_limits<FPT>::digits * 3010/10000;</P>
<P class="first-line-indented">Note that a user defined floating point type
UDFPT must define numeric_limits<UDFPT>::is_specialized
= true and provide an appropriate value for std::numeric_limits<UDFPT>::digits,
the number of bits used for the significand or mantissa.
For example, for the Sparc extended long double 128, 113 bits are used
for the significand (one of which is implicit). </P>
<H5>Custom predicate support</H5>
<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 the
Test Tools implement <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 floating point comparison tools. 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>
<P class="first-line-indented">The Test Tools are implemented in namespace
boost::test_tools. But in majority of the cases you don't need to know about
that, since the tool are used through convinience macros that fully qualify
implementation functions access.</P>
<H2><A name="Examples">Examples and Tests</A></H2>
<P class="indented"><A href="../../tests/test_tools_test.html">test_tools_test</A><BR>
<A href="../../tests/output_test_stream_test.html">output_test_stream_test</A><BR>
<A href="../../tests/boost_check_equal_str.html">boost_check_equal_str</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%20at%20emailaccount%20dot%20com%20%28please%20unobscure%29">Gennadiy
Rozental</A> 2001-2006. <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 -->23 February, 2006<!-- #EndDate -->
</P>
</DIV>
</DIV>
</BODY>
</HTML>
|
