libs/test/doc/html/boost_test/testing_tools/custom_predicates.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Custom predicate support</title>
   5 <link rel="stylesheet" href="../../boostbook.css" type="text/css">
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
   7 <link rel="home" href="../../index.html" title="Boost.Test">
   8 <link rel="up" href="../testing_tools.html" title="Writing unit tests">
   9 <link rel="prev" href="expected_failures.html" title="Expected failures specification">
  10 <link rel="next" href="output_stream_testing.html" title="Output streams testing tool">
  11 </head>
  12 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  13 <table cellpadding="2" width="100%"><tr>
  14 <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
  15 <td align="center"><a href="../../../../../../index.html">Home</a></td>
  16 <td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
  17 <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
  18 <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
  19 <td align="center"><a href="../../../../../../more/index.htm">More</a></td>
  20 </tr></table>
  21 <hr>
  22 <div class="spirit-nav">
  23 <a accesskey="p" href="expected_failures.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="output_stream_testing.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
  24 </div>
  25 <div class="section">
  26 <div class="titlepage"><div><div><h3 class="title">
  27 <a name="boost_test.testing_tools.custom_predicates"></a><a class="link" href="custom_predicates.html" title="Custom predicate support">Custom predicate
  28       support</a>
  29 </h3></div></div></div>
  30 <p>
  31         Even though supplied testing tools cover wide range of possible checks and
  32         provide detailed report on cause of error in some cases you may want to implement
  33         and use custom predicate that perform complex check and produce intelligent
  34         report on failure. To satisfy this need testing tools implement custom predicate
  35         support. There two layers of custom predicate support implemented by testing
  36         tools toolbox: with and without custom error message generation.
  37       </p>
  38 <p>
  39         The first layer is supported by <a class="link" href="../utf_reference/testing_tool_ref/assertion_boost_level_predicate.html" title="BOOST_&lt;level&gt;_PREDICATE"><code class="computeroutput"><span class="identifier">BOOST_</span><span class="special">&lt;</span><span class="identifier">level</span><span class="special">&gt;</span><span class="identifier">_PREDICATE</span></code></a> family of testing tools.
  40         You can use it to check any custom predicate that reports the result as boolean
  41         value. The values of the predicate arguments are reported by the tool automatically
  42         in case of failure.
  43       </p>
  44 <h6>
  45 <a name="boost_test.testing_tools.custom_predicates.h0"></a>
  46         <span class="phrase"><a name="boost_test.testing_tools.custom_predicates.example_descr"></a></span><a class="link" href="custom_predicates.html#boost_test.testing_tools.custom_predicates.example_descr">Example:
  47         Custom predicate support using <code class="computeroutput"><span class="identifier">BOOST_</span><span class="special">&lt;</span><span class="identifier">level</span><span class="special">&gt;</span><span class="identifier">_PREDICATE</span></code></a>
  48       </h6>
  49 <div class="informaltable"><table class="table">
  50 <colgroup><col></colgroup>
  51 <thead><tr><th>
  52                 <p>
  53                   Code
  54                 </p>
  55               </th></tr></thead>
  56 <tbody><tr><td>
  57 <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>
  58 <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>
  59
  60 <span class="keyword">bool</span> <span class="identifier">is_even</span><span class="special">(</span> <span class="keyword">int</span> <span class="identifier">i</span> <span class="special">)</span>
  61 <span class="special">{</span>
  62   <span class="keyword">return</span> <span class="identifier">i</span><span class="special">%</span><span class="number">2</span> <span class="special">==</span> <span class="number">0</span><span class="special">;</span>
  63 <span class="special">}</span>
  64
  65 <span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span> <span class="identifier">test_is_even</span> <span class="special">)</span>
  66 <span class="special">{</span>
  67   <span class="identifier">BOOST_CHECK_PREDICATE</span><span class="special">(</span> <span class="identifier">is_even</span><span class="special">,</span> <span class="special">(</span><span class="number">14</span><span class="special">)</span> <span class="special">);</span>
  68
  69   <span class="keyword">int</span> <span class="identifier">i</span> <span class="special">=</span> <span class="number">17</span><span class="special">;</span>
  70   <span class="identifier">BOOST_CHECK_PREDICATE</span><span class="special">(</span> <span class="identifier">is_even</span><span class="special">,</span> <span class="special">(</span><span class="identifier">i</span><span class="special">)</span> <span class="special">);</span>
  71 <span class="special">}</span>
  72 </pre>
  73               </td></tr></tbody>
  74 </table></div>
  75 <div class="informaltable"><table class="table">
  76 <colgroup><col></colgroup>
  77 <thead><tr><th>
  78                 <p>
  79                   Output
  80                 </p>
  81               </th></tr></thead>
  82 <tbody><tr><td>
  83 <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>
  84 <span class="identifier">Running</span> <span class="number">1</span> <span class="identifier">test</span> <span class="keyword">case</span><span class="special">...</span>
  85 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">(</span><span class="number">13</span><span class="special">):</span> <span class="identifier">error</span> <span class="identifier">in</span> <span class="string">"test_is_even"</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">is_even</span><span class="special">(</span> <span class="identifier">i</span> <span class="special">)</span> <span class="identifier">has</span> <span class="identifier">failed</span> <span class="keyword">for</span> <span class="special">(</span> <span class="number">17</span> <span class="special">)</span>
  86
  87 <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>
  88 </pre>
  89               </td></tr></tbody>
  90 </table></div>
  91 <p>
  92         To use second layer your predicate has to return <code class="computeroutput"><a class="link" href="../../header/boost/test/tools/assertion_result_hpp.html#boost.test_tools.predicate_result">boost::test_tools::predicate_result</a></code>.
  93       </p>
  94 <p>
  95         This class encapsulates boolean result value along with any error or information
  96         message you opt to report.
  97       </p>
  98 <p>
  99         Usually you construct the instance of class <code class="computeroutput"><a class="link" href="../../header/boost/test/tools/assertion_result_hpp.html#boost.test_tools.predicate_result">boost::test_tools::predicate_result</a></code>
 100         inside your predicate function and return it by value. The constructor expects
 101         one argument - the boolean result value. The constructor is implicit, so
 102         you can simply return boolean value from your predicate and <code class="computeroutput"><a class="link" href="../../header/boost/test/tools/assertion_result_hpp.html#boost.test_tools.predicate_result">boost::test_tools::predicate_result</a></code>
 103         is constructed automatically to hold your value and empty message. You can
 104         also assign boolean value to the constructed instance. You can check the
 105         current predicate value by using <code class="computeroutput"><span class="keyword">operator</span><span class="special">!</span></code> or directly accessing public read-only property
 106         <code class="computeroutput"><span class="identifier">p_predicate_value</span></code>. The error
 107         message is stored in public read-write property <code class="computeroutput"><span class="identifier">p_message</span></code>.
 108       </p>
 109 <h6>
 110 <a name="boost_test.testing_tools.custom_predicates.h1"></a>
 111         <span class="phrase"><a name="boost_test.testing_tools.custom_predicates.example_descr0"></a></span><a class="link" href="custom_predicates.html#boost_test.testing_tools.custom_predicates.example_descr0">Example:
 112         Custom predicate support using class boost::test_tools::predicate_result</a>
 113       </h6>
 114 <div class="informaltable"><table class="table">
 115 <colgroup><col></colgroup>
 116 <thead><tr><th>
 117                 <p>
 118                   Code
 119                 </p>
 120               </th></tr></thead>
 121 <tbody><tr><td>
 122 <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>
 123 <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>
 124
 125 <span class="identifier">boost</span><span class="special">::</span><span class="identifier">test_tools</span><span class="special">::</span><span class="identifier">predicate_result</span>
 126   <span class="identifier">compare_lists</span><span class="special">(</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">list</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">l1</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">list</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">l2</span> <span class="special">)</span>
 127 <span class="special">{</span>
 128   <span class="keyword">if</span><span class="special">(</span> <span class="identifier">l1</span><span class="special">.</span><span class="identifier">size</span><span class="special">()</span> <span class="special">!=</span> <span class="identifier">l2</span><span class="special">.</span><span class="identifier">size</span><span class="special">()</span> <span class="special">)</span>
 129   <span class="special">{</span>
 130     <span class="identifier">boost</span><span class="special">::</span><span class="identifier">test_tools</span><span class="special">::</span><span class="identifier">predicate_result</span> <span class="identifier">res</span><span class="special">(</span> <span class="keyword">false</span> <span class="special">);</span>
 131
 132     <span class="identifier">res</span><span class="special">.</span><span class="identifier">message</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="string">"Different sizes ["</span> <span class="special">&lt;&lt;</span> <span class="identifier">l1</span><span class="special">.</span><span class="identifier">size</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="string">"!="</span> <span class="special">&lt;&lt;</span> <span class="identifier">l2</span><span class="special">.</span><span class="identifier">size</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="string">"]"</span><span class="special">;</span>
 133
 134     <span class="keyword">return</span> <span class="identifier">res</span><span class="special">;</span>
 135   <span class="special">}</span>
 136   <span class="keyword">return</span> <span class="keyword">true</span><span class="special">;</span>
 137 <span class="special">}</span>
 138
 139 <span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span> <span class="identifier">test_list_comparison</span> <span class="special">)</span>
 140 <span class="special">{</span>
 141   <span class="identifier">std</span><span class="special">::</span><span class="identifier">list</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span> <span class="identifier">l1</span><span class="special">,</span> <span class="identifier">l2</span><span class="special">;</span>
 142   <span class="identifier">l1</span><span class="special">.</span><span class="identifier">push_back</span><span class="special">(</span> <span class="number">1</span> <span class="special">);</span>
 143   <span class="identifier">l1</span><span class="special">.</span><span class="identifier">push_back</span><span class="special">(</span> <span class="number">2</span> <span class="special">);</span>
 144
 145   <span class="identifier">BOOST_TEST</span><span class="special">(</span> <span class="identifier">compare_lists</span><span class="special">(</span> <span class="identifier">l1</span><span class="special">,</span> <span class="identifier">l2</span> <span class="special">)</span> <span class="special">);</span>
 146 <span class="special">}</span>
 147 </pre>
 148               </td></tr></tbody>
 149 </table></div>
 150 <div class="informaltable"><table class="table">
 151 <colgroup><col></colgroup>
 152 <thead><tr><th>
 153                 <p>
 154                   Output
 155                 </p>
 156               </th></tr></thead>
 157 <tbody><tr><td>
 158 <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="identifier">Running</span> <span class="number">1</span> <span class="identifier">test</span> <span class="keyword">case</span><span class="special">...</span>
 159 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">(</span><span class="number">28</span><span class="special">):</span> <span class="identifier">error</span> <span class="identifier">in</span> <span class="string">"test_list_comparizon"</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">compare_lists</span><span class="special">(</span> <span class="identifier">l1</span><span class="special">,</span> <span class="identifier">l2</span> <span class="special">)</span> <span class="identifier">has</span> <span class="identifier">failed</span><span class="special">.</span> <span class="identifier">Different</span> <span class="identifier">sizes</span> <span class="special">[</span><span class="number">2</span><span class="special">!=</span><span class="number">0</span><span class="special">]</span>
 160
 161 <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>
 162 </pre>
 163               </td></tr></tbody>
 164 </table></div>
 165 </div>
 166 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 167 <td align="left"></td>
 168 <td align="right"><div class="copyright-footer">Copyright &#169; 2001-2019 Boost.Test
 169       contributors<p>
 170         Distributed under the Boost Software License, Version 1.0. (See accompanying
 171         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>)
 172       </p>
 173 </div></td>
 174 </tr></table>
 175 <hr>
 176 <div class="spirit-nav">
 177 <a accesskey="p" href="expected_failures.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="output_stream_testing.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
 178 </div>
 179 </body>
 180 </html>