mirror of
https://github.com/boostorg/test.git
synced 2026-02-14 13:12:10 +00:00
171 lines
11 KiB
HTML
171 lines
11 KiB
HTML
<!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>
|