mirror of
https://github.com/boostorg/test.git
synced 2026-01-24 18:32:30 +00:00
144 lines
9.0 KiB
HTML
144 lines
9.0 KiB
HTML
<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 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
|
|
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">All of the tools supplied (with one exclusion)
|
|
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 case
|
|
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 and BOOST_<level>_CLOSE_FRACTION
|
|
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 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 it's interface and usage you could see
|
|
on 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<<(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>
|
|
<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 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>
|
|
<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="../../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/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 -->31 January, 2006<!-- #EndDate -->
|
|
</P>
|
|
</DIV>
|
|
</DIV>
|
|
</BODY>
|
|
</HTML>
|