devn00b
/
EQ2EMu


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285
							<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Output streams testing tool</title>
<link rel="stylesheet" href="../../boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../index.html" title="Boost.Test">
<link rel="up" href="../testing_tools.html" title="Writing unit tests">
<link rel="prev" href="custom_predicates.html" title="Custom predicate support">
<link rel="next" href="internal_details.html" title="BOOST_TEST: details on expressions">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="custom_predicates.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../testing_tools.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="internal_details.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="boost_test.testing_tools.output_stream_testing"></a><a class="link" href="output_stream_testing.html" title="Output streams testing tool">Output
      streams testing tool</a>
</h3></div></div></div>
<p>
        How would you perform correctness test for
      </p>
<pre class="programlisting"><span class="keyword">operator</span><span class="special">&lt;&lt;</span> <span class="special">(</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">ostream</span> <span class="special">&amp;,</span> <span class="special">...</span> <span class="special">)</span></pre>
<p>
        operations?
      </p>
<p>
        You can print into the standard output stream and manually check that it
        is matching your expectations. Unfortunately, this is not really acceptable
        for the regression testing and doesn't serve a long term purpose of a unit
        test.
      </p>
<p>
        You can use <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">stringstream</span></code> and compare resulting output
        buffer with the expected pattern string, but you are required to perform
        several additional operations with every check you do. So it becomes tedious
        very fast.
      </p>
<p>
        The class <code class="computeroutput"><a class="link" href="../../boost/test_tools/output_test_stream.html" title="Class output_test_stream">boost::test_tools::output_test_stream</a></code>
        is designed to automate these tasks for you. This is a simple, but powerful
        tool for testing standard <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">ostream</span></code>
        based output operation. The class <code class="computeroutput"><span class="identifier">output_test_stream</span></code>
        complies to <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">ostream</span></code> interface so it can be used in
        place of any <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">ostream</span></code> parameter. It provides several
        test methods to validate output content, including test for match to expected
        output content or test for expected output length. Flushing, synchronizing,
        string comparison and error message generation is automated by the tool implementation.
      </p>
<p>
        All <code class="computeroutput"><span class="identifier">output_test_stream</span></code> validation
        member functions by default flush the stream once the check is performed.
        If you want to perform several checks with the same output, specify parameter
        <code class="computeroutput"><span class="identifier">flush_stream</span></code> with value
        <code class="computeroutput"><span class="keyword">false</span></code> <a href="#ftn.boost_test.testing_tools.output_stream_testing.f0" class="footnote" name="boost_test.testing_tools.output_stream_testing.f0"><sup class="footnote">[16]</sup></a>.
      </p>
<p>
        In some cases manual generation of expected output is either too time consuming
        or is impossible at all because of sheer volume. A possible way to address
        that issue is to split the test in two steps:
      </p>
<div class="orderedlist"><ol class="orderedlist" type="1">
<li class="listitem">
            first by checking the expected output manually
          </li>
<li class="listitem">
            second to save this output to ensure that future checks produce the same
            output
          </li>
</ol></div>
<p>
        The class <code class="computeroutput"><span class="identifier">output_test_stream</span></code>
        allows both the matching of the output content versus a <span class="emphasis"><em>pattern
        file</em></span> and generation of this pattern file. The command line parameter
        <a class="link" href="../utf_reference/rt_param_reference/save_pattern.html" title="save_pattern"><code class="computeroutput"><span class="identifier">save_pattern</span></code></a> may be used to either
        generate a new pattern file, or to check against an existing pattern.
      </p>
<h4>
<a name="boost_test.testing_tools.output_stream_testing.h0"></a>
        <span class="phrase"><a name="boost_test.testing_tools.output_stream_testing.usages"></a></span><a class="link" href="output_stream_testing.html#boost_test.testing_tools.output_stream_testing.usages">Usage</a>
      </h4>
<p>
        There are two ways to employ the class <code class="computeroutput"><span class="identifier">output_test_stream</span></code>:
      </p>
<div class="orderedlist"><ol class="orderedlist" type="1">
<li class="listitem">
            explicit output checks and
          </li>
<li class="listitem">
            pattern file matching
          </li>
</ol></div>
<h5>
<a name="boost_test.testing_tools.output_stream_testing.h1"></a>
        <span class="phrase"><a name="boost_test.testing_tools.output_stream_testing.explicit_output_checks"></a></span><a class="link" href="output_stream_testing.html#boost_test.testing_tools.output_stream_testing.explicit_output_checks">Explicit
        output checks</a>
      </h5>
<p>
        Use the instance of class <code class="computeroutput"><span class="identifier">output_test_stream</span></code>
        as an output stream and check output content using tool's methods.
      </p>
<h6>
<a name="boost_test.testing_tools.output_stream_testing.h2"></a>
        <span class="phrase"><a name="boost_test.testing_tools.output_stream_testing.example_descr"></a></span><a class="link" href="output_stream_testing.html#boost_test.testing_tools.output_stream_testing.example_descr">Example:
        Explicit output checks with <code class="computeroutput"><span class="identifier">output_test_stream</span></code></a>
      </h6>
<div class="informaltable"><table class="table">
<colgroup><col></colgroup>
<thead><tr><th>
                <p>
                  Code
                </p>
              </th></tr></thead>
<tbody><tr><td>
<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="preprocessor">#define</span> <span class="identifier">BOOST_TEST_MODULE</span> <span class="identifier">example</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">test</span><span class="special">/</span><span class="identifier">included</span><span class="special">/</span><span class="identifier">unit_test</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">test</span><span class="special">/</span><span class="identifier">tools</span><span class="special">/</span><span class="identifier">output_test_stream</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">test_tools</span><span class="special">::</span><span class="identifier">output_test_stream</span><span class="special">;</span>

<span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span> <span class="identifier">test</span> <span class="special">)</span>
<span class="special">{</span>
  <span class="identifier">output_test_stream</span> <span class="identifier">output</span><span class="special">;</span>
  <span class="keyword">int</span> <span class="identifier">i</span><span class="special">=</span><span class="number">2</span><span class="special">;</span>
  <span class="identifier">output</span> <span class="special">&lt;&lt;</span> <span class="string">"i="</span> <span class="special">&lt;&lt;</span> <span class="identifier">i</span><span class="special">;</span>
  <span class="identifier">BOOST_TEST</span><span class="special">(</span> <span class="special">!</span><span class="identifier">output</span><span class="special">.</span><span class="identifier">is_empty</span><span class="special">(</span> <span class="keyword">false</span> <span class="special">)</span> <span class="special">);</span>
  <span class="identifier">BOOST_TEST</span><span class="special">(</span> <span class="identifier">output</span><span class="special">.</span><span class="identifier">check_length</span><span class="special">(</span> <span class="number">3</span><span class="special">,</span> <span class="keyword">false</span> <span class="special">)</span> <span class="special">);</span>
  <span class="identifier">BOOST_TEST</span><span class="special">(</span> <span class="identifier">output</span><span class="special">.</span><span class="identifier">is_equal</span><span class="special">(</span> <span class="string">"i=3"</span> <span class="special">)</span> <span class="special">);</span>
<span class="special">}</span>
</pre>
              </td></tr></tbody>
</table></div>
<div class="informaltable"><table class="table">
<colgroup><col></colgroup>
<thead><tr><th>
                <p>
                  Output
                </p>
              </th></tr></thead>
<tbody><tr><td>
<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="special">&gt;</span> <span class="identifier">example</span>
<span class="identifier">Running</span> <span class="number">1</span> <span class="identifier">test</span> <span class="keyword">case</span><span class="special">...</span>
<span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">(</span><span class="number">15</span><span class="special">):</span> <span class="identifier">error</span> <span class="identifier">in</span> <span class="string">"test"</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">output</span><span class="special">.</span><span class="identifier">is_equal</span><span class="special">(</span> <span class="string">"i=3"</span> <span class="special">)</span> <span class="identifier">has</span> <span class="identifier">failed</span><span class="special">.</span> <span class="identifier">Output</span> <span class="identifier">content</span><span class="special">:</span> <span class="string">"i=2"</span>

<span class="special">***</span> <span class="number">1</span> <span class="identifier">failures</span> <span class="identifier">is</span> <span class="identifier">detected</span> <span class="identifier">in</span> <span class="identifier">test</span> <span class="identifier">suite</span> <span class="string">"example"</span>
</pre>
              </td></tr></tbody>
</table></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>
          Use of <code class="computeroutput"><span class="keyword">false</span></code> to prevent output
          flushing in first two invocation of check functions. Unless you want to
          perform several different checks for the same output you wouldn't need
          to use it though. Your test will look like a sequence of output operators
          followed by one check.
        </p></td></tr>
</table></div>
<div class="tip"><table border="0" summary="Tip">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../../../../../doc/src/images/tip.png"></td>
<th align="left">Tip</th>
</tr>
<tr><td align="left" valign="top"><p>
          Try to perform checks as frequently as possible. It not only simplifies
          patterns you compare with, but also allows you to more closely identify
          possible source of failure.
        </p></td></tr>
</table></div>
<h5>
<a name="boost_test.testing_tools.output_stream_testing.h3"></a>
        <span class="phrase"><a name="boost_test.testing_tools.output_stream_testing.pattern_file_matching"></a></span><a class="link" href="output_stream_testing.html#boost_test.testing_tools.output_stream_testing.pattern_file_matching">Pattern
        file matching</a>
      </h5>
<p>
        The <span class="emphasis"><em>pattern file</em></span> is a companion file containing the
        patterns that the stream should match. Your testing will look like a series
        of output operators followed by match pattern checks repeated several times.
      </p>
<p>
        In the example below, the file <code class="computeroutput"><span class="identifier">pattern_file</span></code>
        contains the patterns that should match.
      </p>
<pre class="programlisting">i=2
File: test.cpp Line:XXX
</pre>
<h6>
<a name="boost_test.testing_tools.output_stream_testing.h4"></a>
        <span class="phrase"><a name="boost_test.testing_tools.output_stream_testing.example_descr0"></a></span><a class="link" href="output_stream_testing.html#boost_test.testing_tools.output_stream_testing.example_descr0">Example:
        Pattern file matching with <code class="computeroutput"><span class="identifier">output_test_stream</span></code></a>
      </h6>
<div class="informaltable"><table class="table">
<colgroup><col></colgroup>
<thead><tr><th>
                <p>
                  Code
                </p>
              </th></tr></thead>
<tbody><tr><td>
<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="preprocessor">#define</span> <span class="identifier">BOOST_TEST_MODULE</span> <span class="identifier">example</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">test</span><span class="special">/</span><span class="identifier">included</span><span class="special">/</span><span class="identifier">unit_test</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">test</span><span class="special">/</span><span class="identifier">tools</span><span class="special">/</span><span class="identifier">output_test_stream</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">test_tools</span><span class="special">::</span><span class="identifier">output_test_stream</span><span class="special">;</span>

<span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span> <span class="identifier">test</span> <span class="special">)</span>
<span class="special">{</span>
  <span class="identifier">output_test_stream</span> <span class="identifier">output</span><span class="special">(</span> <span class="string">"pattern_file"</span><span class="special">,</span> <span class="special">!</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">unit_test</span><span class="special">::</span><span class="identifier">runtime_config</span><span class="special">::</span><span class="identifier">save_pattern</span><span class="special">()</span> <span class="special">);</span>
  <span class="keyword">int</span> <span class="identifier">i</span><span class="special">=</span><span class="number">2</span><span class="special">;</span>
  <span class="identifier">output</span> <span class="special">&lt;&lt;</span> <span class="string">"i="</span> <span class="special">&lt;&lt;</span> <span class="identifier">i</span><span class="special">;</span>
  <span class="identifier">BOOST_TEST</span><span class="special">(</span> <span class="identifier">output</span><span class="special">.</span><span class="identifier">match_pattern</span><span class="special">()</span> <span class="special">);</span>

  <span class="identifier">output</span> <span class="special">&lt;&lt;</span> <span class="string">"\nFile: "</span> <span class="special">&lt;&lt;</span> <span class="identifier">__FILE__</span> <span class="special">&lt;&lt;</span> <span class="string">" Line:YYY"</span><span class="special">;</span>
  <span class="identifier">BOOST_TEST</span><span class="special">(</span> <span class="identifier">output</span><span class="special">.</span><span class="identifier">match_pattern</span><span class="special">()</span> <span class="special">);</span> <a class="co" name="boost_test.testing_tools.output_stream_testing.c0" href="output_stream_testing.html#boost_test.testing_tools.output_stream_testing.c1"><img src="../../../../../../doc/src/images/callouts/1.png" alt="1" border="0"></a>
<span class="special">}</span>
</pre>
                <div class="calloutlist"><table border="0" summary="Callout list"><tr>
<td width="5%" valign="top" align="left"><p><a name="boost_test.testing_tools.output_stream_testing.c1"></a><a href="#boost_test.testing_tools.output_stream_testing.c0"><img src="../../../../../../doc/src/images/callouts/1.png" alt="1" border="0"></a> </p></td>
<td valign="top" align="left"><p>
                      This line generates the error Line:YYY != Line:XXX
                    </p></td>
</tr></table></div>
              </td></tr></tbody>
</table></div>
<div class="informaltable"><table class="table">
<colgroup><col></colgroup>
<thead><tr><th>
                <p>
                  Output
                </p>
              </th></tr></thead>
<tbody><tr><td>
<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="special">&gt;</span> <span class="identifier">example</span>
<span class="identifier">Running</span> <span class="number">1</span> <span class="identifier">test</span> <span class="keyword">case</span><span class="special">...</span>
<span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">(</span><span class="number">16</span><span class="special">):</span> <span class="identifier">error</span> <span class="identifier">in</span> <span class="string">"test"</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">output</span><span class="special">.</span><span class="identifier">match_pattern</span><span class="special">()</span> <span class="identifier">has</span> <span class="identifier">failed</span><span class="special">.</span> <span class="identifier">Mismatch</span> <span class="identifier">at</span> <span class="identifier">position</span> <span class="number">23</span>
<span class="special">...</span><span class="number">5.</span><span class="special">..</span>
<span class="special">...</span><span class="number">4.</span><span class="special">..</span>

<span class="special">***</span> <span class="number">1</span> <span class="identifier">failures</span> <span class="identifier">is</span> <span class="identifier">detected</span> <span class="identifier">in</span> <span class="identifier">test</span> <span class="identifier">suite</span> <span class="string">"example"</span>
</pre>
              </td></tr></tbody>
</table></div>
<div class="tip"><table border="0" summary="Tip">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../../../../../doc/src/images/tip.png"></td>
<th align="left">Tip</th>
</tr>
<tr><td align="left" valign="top"><p>
          Try to perform checks as frequently as possible, because it allows you
          to more closely identify possible source of failure
        </p></td></tr>
</table></div>
<div class="footnotes">
<br><hr style="width:100; text-align:left;margin-left: 0">
<div id="ftn.boost_test.testing_tools.output_stream_testing.f0" class="footnote"><p><a href="#boost_test.testing_tools.output_stream_testing.f0" class="para"><sup class="para">[16] </sup></a>
          This parameter is supported on all comparison methods, see the class <code class="computeroutput"><a class="link" href="../../boost/test_tools/output_test_stream.html" title="Class output_test_stream">documentation.</a></code>
        </p></div>
</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-2019 Boost.Test
      contributors<p>
        Distributed under the Boost Software License, Version 1.0. (See accompanying
        file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
      </p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="custom_predicates.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../testing_tools.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="internal_details.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>