boost/test
2
0
Fork 0
mirror of https://github.com/boostorg/test.git synced 2026-02-15 01:22:08 +00:00
Code Issues Projects Releases Wiki Activity
Files
2e7d65bbd3da83df17008a9614677ed7fb0cd0c2
test/doc/html/utf/user-guide/test-output/test-log.html
Gennadiy Rozental bd6850ccc3 some cleanup 
[SVN r81191]
2012-11-05 06:03:48 +00:00

216 lines
11 KiB
HTML
Executable File
Raw Blame History

<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Test log output</title>
<link rel="stylesheet" href="../../../../style/style.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
<link rel="home" href="../../../index.html" title="Boost Test Library">
<link rel="up" href="../test-output.html" title="Test Output &#8230; or let's see what you got for your money">
<link rel="prev" href="../test-output.html" title="Test Output &#8230; or let's see what you got for your money">
<link rel="next" href="BOOST_TEST_MESSAGE.html" title="BOOST_TEST_MESSAGE">
<script language="JavaScript1.2" src="../../../../js/boost-test.js"></script>
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table width="100%"><tr>
<td width="10%"><a href="../../../index.html"><img alt="Home" width="229" height="61" border="0" src="../../../../../../../libs/test/doc/img/boost.test.logo.png"></a></td>
<td valign="middle" align="left"> &gt; <a href="../../../utf.html">The Unit Test Framework</a><a href="../../../execution-monitor.html">
&gt;
</a><a href="../../user-guide.html">User's guide</a><a href="../../usage-recommendations.html">
&gt;
</a><a href="../test-output.html">Test Output </a><a href="../runtime-config.html">
&gt;
</a><b>Test log</b><a href="results-report.html">
&gt;
</a>
</td>
<td><div class="spirit-nav">
<a href="../test-output.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a href="BOOST_TEST_MESSAGE.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
</div></td>
</tr></table>
<hr>
<div class="section">
<div class="titlepage"><div><div><h5 class="title">
<a name="utf.user-guide.test-output.log"></a>Test log output</h5></div></div></div>
<p class="first-line-indented">
The test log is produced during the test execution. All entries in the test log are assigned a particular log
level. Only the entries with level that exceeds the <em class="firstterm">active log level threshold</em> actually
appear in the test log output. Log levels are arranged by the "importance" of the log entries. Here is
the list of all levels in order of increasing "importance":
</p>
<div class="itemizedlist"><ul type="disc">
<li class="listitem">
<p class="simpara">Success information messages</p>
<p class="simpara">
This category includes messages that provide information on successfully passed assertions
</p>
</li>
<li class="listitem">
<p class="simpara">Test tree traversal notifications</p>
<p class="simpara">
This category includes messages that are produced by the <acronym class="acronym">UTF</acronym> core and indicate which test suites/cases are
currently being executed or skipped
</p>
</li>
<li class="listitem">
<p class="simpara">General information messages</p>
<p class="simpara">
This category includes general information massages produced in most cases by a test module author using the
macro <code class="computeroutput"><a class="link" href="BOOST_TEST_MESSAGE.html#BOOST_TEST_MESSAGE">BOOST_TEST_MESSAGE</a></code>.
</p>
</li>
<li class="listitem">
<p class="simpara">Warning messages</p>
<p class="simpara">
This category includes messages produced by failed warning level assertions.
</p>
</li>
<li class="listitem">
<p class="simpara">Non fatal error messages</p>
<p class="simpara">
This category includes messages produced by failed check level assertions
</p>
</li>
<li class="listitem">
<p class="simpara">Uncaught C++ exceptions notifications</p>
<p class="simpara">
This category includes messages that are produced by the <acronym class="acronym">UTF</acronym> and provide detailed information on the C++
exceptions uncaught by the test case body.
</p>
</li>
<li class="listitem">
<p class="simpara">Non-fatal system error</p>
<p class="simpara">
This category includes messages that are produced by the <acronym class="acronym">UTF</acronym> itself and provides information about caught
non-fatal system error. For example it includes messages produced in the case of test case timeout or if
floating point values calculation errors are caught.
</p>
</li>
<li class="listitem">
<p class="simpara">Fatal system error</p>
<p class="simpara">
This category includes messages produced by failed require level assertions and by the <acronym class="acronym">UTF</acronym> itself in case of
abnormal test case termination.
</p>
</li>
</ul></div>
<div class="note"><table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../../doc/src/images/note.png"></td>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top"><p>
The active log level works namely as threshold, not as selector. For the given active log level threshold, all
test log entries with "importance" higher than threshold are enabled and all test log entries with
"importance" below threshold are disabled.
</p></td></tr>
</table></div>
<p class="first-line-indented">
In addition to the levels described above the test log defines two special log levels. The current log level can
be set to:
</p>
<div class="itemizedlist"><ul type="disc">
<li class="listitem">
<p class="simpara">All messages</p>
<p class="simpara">
If active log level threshold is set to this value, all test log entries appear in the output. In practice
this is equivalent to setting the active log level threshold to "success information messages"
</p>
</li>
<li class="listitem">
<p class="simpara">Nothing</p>
<p class="simpara">
If the active log level threshold is set to this value, none of test log entries appear in the output. This log level
is used to execute a "silent" test that doesn't produce any test log and only generates a result code indicating whether test failed or passed.
</p>
</li>
</ul></div>
<p class="first-line-indented">
By default the active log level threshold is set to "non fatal error messages" and the test log output
is generated in the human readable format. The active log level threshold and the output format can be configured
at runtime during a test module invocation and at compile time from within a test module using the test log
public interfaces. For example, for automated test module output processing it might be more convenient to use
the XML based format.
</p>
<p class="first-line-indented">
In most cases The <acronym class="acronym">UTF</acronym> can't provide an exact location, where system error occurs or uncaught C++ exception
is thrown from. To be able to pinpoint it as close as possible the <acronym class="acronym">UTF</acronym> keeps track of checkpoints - the
location a test module passed through. A test case entrance and exit points, a test tool invocation point the
<acronym class="acronym">UTF</acronym> tracks automatically. Any other checkpoints should be entered by you manually. The test log provides two
macros for this purpose: <code class="computeroutput"><a class="link" href="BOOST_TEST_CHECKPOINT.html#BOOST_TEST_CHECKPOINT">BOOST_TEST_CHECKPOINT</a></code> - to specify a "named" checkpoint
and <code class="computeroutput"><a class="link" href="BOOST_TEST_PASSPOINT.html#BOOST_TEST_PASSPOINT">BOOST_TEST_PASSPOINT</a></code> - to specify an "unnamed" checkpoint.
</p>
<div class="section">
<div class="titlepage"><div><div><h6 class="title">
<a name="utf.user-guide.test-output.log.testing-tool-args"></a>Logging tool arguments</h6></div></div></div>
<p class="first-line-indented">
Most of the <a class="link" href="../testing-tools.html" title="The UTF testing tools &#8230; or tester's toolbox for all occasions">testing tools</a> print values of their arguments to the output
stream in some form of log statement. If arguments type does not support <code class="computeroutput">operator&lt;&lt;(std::ostream&amp;,
ArgumentType const&amp;)</code> interface you will get a compilation error. You can either implement above
interface or prohibit the <a class="link" href="../testing-tools.html" title="The UTF testing tools &#8230; or tester's toolbox for all occasions">testing tools</a> 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>
<pre class="inline-synopsis">
<a name="BOOST_TEST_DONT_PRINT_LOG_VALUE"></a>BOOST_TEST_DONT_PRINT_LOG_VALUE(<span class="emphasis"><em>ArgumentType</em></span>)</pre>
<div class="example">
<a name="utf.user-guide.test-output.log.testing-tool-args.example32"></a><p class="title"><b>Example&#160;44.&#160;BOOST_TEST_DONT_PRINT_LOG_VALUE usage</b></p>
<div class="example-contents">
<p>
Try to comment out BOOST_TEST_DONT_PRINT_LOG_VALUE statement and you end up with compile time error.
</p>
<pre class="programlisting">#define BOOST_TEST_MODULE example
#include &lt;boost/test/included/unit_test.hpp&gt;
#include &lt;utility&gt;
//____________________________________________________________________________//
typedef std::pair&lt;int,float&gt; pair_type;
BOOST_TEST_DONT_PRINT_LOG_VALUE( pair_type );
BOOST_AUTO_TEST_CASE( test_list )
{
pair_type p1( 2, 5.5 );
pair_type p2( 2, 5.501 );
BOOST_CHECK_EQUAL( p1, p2 );
}
//____________________________________________________________________________//
</pre>
<table border="0" summary="Simple list" class="simplelist"><tr>
<td><code class="literal"><a href="../../../../src/examples/example32.cpp" target="_top">Source code</a></code></td>
<td> | </td>
<td><code class="literal"><a href="#" target="_top" id="id543736" onclick="toggle_element( 'example32-output', 'id543736', 'Show output', 'Hide output' ); return false;">Show output</a></code></td>
</tr></table>
<pre class="example-output" id="example32-output">Running 1 test case...
test.cpp(16): error in "test_list": check p1 == p2 failed [ != ]
*** 1 failure detected in test suite "example"
</pre>
</div>
</div>
<br class="example-break">
</div>
<div class="section">
<div class="titlepage"><div><div><h6 class="title">
<a name="utf.user-guide.test-output.log.runtime-config"></a>Runtime configuration</h6></div></div></div>
<p class="first-line-indented">
The active log level threshold can be configured at runtime using the parameter
<a class="link" href="../runtime-config/reference.html" title="Runtime parameters reference">log_level</a>. The test log output format can be
selected using either parameter <a class="link" href="../runtime-config/reference.html" title="Runtime parameters reference">log_format</a> or the
parameter <a class="link" href="../runtime-config/reference.html" title="Runtime parameters reference">output_format</a>.
</p>
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright &#169; 2001-2012 Gennadiy Rozental</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="../test-output.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../test-output.html"><img src="../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="BOOST_TEST_MESSAGE.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink