libs/test/doc/html/boost_test/adv_scenarios/obsolete_init_func.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>The obsolete initialization function</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="../adv_scenarios.html" title="Advanced Usage Scenarios">
   9 <link rel="prev" href="external_test_runner.html" title="The external test runner usage variant">
  10 <link rel="next" href="../practical_usage_recommendations.html" title="Practical usage recommendations">
  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="external_test_runner.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../adv_scenarios.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="../practical_usage_recommendations.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.adv_scenarios.obsolete_init_func"></a><a class="link" href="obsolete_init_func.html" title="The obsolete initialization function">The obsolete
  28       initialization function</a>
  29 </h3></div></div></div>
  30 <p>
  31         For backwards compatibility, the <span class="emphasis"><em>Unit Test Framework</em></span>
  32         also allows the customization of an initialization function of a different
  33         type. This is called the <span class="emphasis"><em>obsolete initialization function</em></span>.
  34         Its signature is:
  35       </p>
  36 <pre class="programlisting"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">unit_test</span><span class="special">::</span><span class="identifier">test_suite</span><span class="special">*</span> <span class="identifier">init_unit_test_suite</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">argc</span><span class="special">,</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">argv</span><span class="special">[]);</span>
  37 </pre>
  38 <p>
  39         The original design of the <span class="emphasis"><em>Unit Test Framework</em></span> required
  40         of the programmer to implement it. It was intended to initialize and return
  41         the <a class="link" href="../tests_organization/test_tree/master_test_suite.html" title="Master test suite">master
  42         test suite</a>. No <a class="link" href="../tests_organization/test_cases/test_organization_nullary.html#ref_BOOST_AUTO_TEST_CASE">automatic
  43         test case registration</a> was available at that time. The null-pointer
  44         value was considered an initialization error.
  45       </p>
  46 <p>
  47         In the header-only usage variant, you fall back to the obsolete initialization
  48         function signature by omitting the definition of macro <a class="link" href="../utf_reference/link_references/link_boost_test_alternative_init_macro.html" title="BOOST_TEST_ALTERNATIVE_INIT_API"><code class="computeroutput"><span class="identifier">BOOST_TEST_ALTERNATIVE_INIT_API</span></code></a>
  49         in test module code.
  50       </p>
  51 <h6>
  52 <a name="boost_test.adv_scenarios.obsolete_init_func.h0"></a>
  53         <span class="phrase"><a name="boost_test.adv_scenarios.obsolete_init_func.example_descr"></a></span><a class="link" href="obsolete_init_func.html#boost_test.adv_scenarios.obsolete_init_func.example_descr">Example:
  54         using obsolete initialization function</a>
  55       </h6>
  56 <div class="informaltable"><table class="table">
  57 <colgroup><col></colgroup>
  58 <thead><tr><th>
  59                 <p>
  60                   Code
  61                 </p>
  62               </th></tr></thead>
  63 <tbody><tr><td>
  64 <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><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>
  65 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iostream</span><span class="special">&gt;</span>
  66
  67 <span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span><span class="identifier">test1</span><span class="special">)</span>
  68 <span class="special">{</span>
  69   <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="keyword">false</span><span class="special">);</span>
  70 <span class="special">}</span>
  71
  72 <span class="identifier">boost</span><span class="special">::</span><span class="identifier">unit_test</span><span class="special">::</span><span class="identifier">test_suite</span><span class="special">*</span> <span class="identifier">init_unit_test_suite</span><span class="special">(</span><span class="keyword">int</span> <span class="comment">/*argc*/</span><span class="special">,</span> <span class="keyword">char</span><span class="special">*</span> <span class="comment">/*argv*/</span><span class="special">[])</span>
  73 <span class="special">{</span>
  74   <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"using obsolete init"</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
  75   <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
  76 <span class="special">}</span>
  77 </pre>
  78               </td></tr></tbody>
  79 </table></div>
  80 <div class="informaltable"><table class="table">
  81 <colgroup><col></colgroup>
  82 <thead><tr><th>
  83                 <p>
  84                   Output
  85                 </p>
  86               </th></tr></thead>
  87 <tbody><tr><td>
  88 <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="special">&gt;</span> <span class="identifier">custom_obsolete_init</span>
  89 <span class="keyword">using</span> <span class="identifier">obsolete</span> <span class="identifier">init</span>
  90 <span class="identifier">Running</span> <span class="number">1</span> <span class="identifier">test</span> <span class="keyword">case</span><span class="special">...</span>
  91 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">(</span><span class="number">6</span><span class="special">):</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">in</span> <span class="string">"test1"</span><span class="special">:</span> <span class="identifier">check</span> <span class="keyword">false</span> <span class="identifier">has</span> <span class="identifier">failed</span>
  92
  93 <span class="special">***</span> <span class="number">1</span> <span class="identifier">failure</span> <span class="identifier">is</span> <span class="identifier">detected</span> <span class="identifier">in</span> <span class="identifier">the</span> <span class="identifier">test</span> <span class="identifier">module</span> <span class="string">"Master Test Suite"</span>
  94 </pre>
  95               </td></tr></tbody>
  96 </table></div>
  97 <p>
  98         In the static-library usage variant, you need to omit the definition of macro
  99         <a class="link" href="../utf_reference/link_references/link_boost_test_alternative_init_macro.html" title="BOOST_TEST_ALTERNATIVE_INIT_API"><code class="computeroutput"><span class="identifier">BOOST_TEST_ALTERNATIVE_INIT_API</span></code></a>
 100         in test module and compile the <span class="emphasis"><em>Unit Test Framework</em></span> static
 101         library without the compilation flag <a class="link" href="../utf_reference/link_references/link_boost_test_alternative_init_macro.html" title="BOOST_TEST_ALTERNATIVE_INIT_API"><code class="computeroutput"><span class="identifier">BOOST_TEST_ALTERNATIVE_INIT_API</span></code></a>
 102         (this is the default).
 103       </p>
 104 <p>
 105         In the shared-library usage variant, it is not possible to use the obsolete
 106         initialization function.
 107       </p>
 108 <p>
 109         Even if you decide to us the obsolete initialization function, it is recommended
 110         that:
 111       </p>
 112 <div class="orderedlist"><ol class="orderedlist" type="1">
 113 <li class="listitem">
 114             You always return a null-pointer value and install the master test suite
 115             via <code class="computeroutput"><a class="link" href="../../boost/unit_test/test_suite.html#idm46279112866240-bb">test_suite::add</a></code> as illustrated <a class="link" href="../tests_organization/test_cases/test_organization_nullary.html#ref_BOOST_TEST_CASE">here</a>. The current framework does
 116             no longer treat the null-pointer value as failure.
 117           </li>
 118 <li class="listitem">
 119             You signal the failure by throwing <code class="computeroutput"><a class="link" href="../../boost/unit_test/framework/setup_error.html" title="Struct setup_error">boost::unit_test::framework::setup_error</a></code>
 120             exception.
 121           </li>
 122 <li class="listitem">
 123             You access the command-line arguments through the interface of the <a class="link" href="../tests_organization/test_tree/master_test_suite.html" title="Master test suite">master
 124             test suite</a>, and ignore the function's arguments <code class="computeroutput"><span class="identifier">argc</span></code> and <code class="computeroutput"><span class="identifier">argv</span></code>.
 125           </li>
 126 </ol></div>
 127 <div class="caution"><table border="0" summary="Caution">
 128 <tr>
 129 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../../../../../../doc/src/images/caution.png"></td>
 130 <th align="left">Caution</th>
 131 </tr>
 132 <tr><td align="left" valign="top"><p>
 133           The obsolete initialization function is deprecated as its name indicates.
 134           It is recommended to migrate to the new API, and rely on the automated
 135           test unit registration and <a class="link" href="../tests_organization/fixtures.html" title="Fixtures">fixtures</a>
 136           (including <a class="link" href="../tests_organization/fixtures/global.html" title="Global fixture">global
 137           fixtures</a>) for other set-up.
 138         </p></td></tr>
 139 </table></div>
 140 </div>
 141 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 142 <td align="left"></td>
 143 <td align="right"><div class="copyright-footer">Copyright &#169; 2001-2019 Boost.Test
 144       contributors<p>
 145         Distributed under the Boost Software License, Version 1.0. (See accompanying
 146         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>)
 147       </p>
 148 </div></td>
 149 </tr></table>
 150 <hr>
 151 <div class="spirit-nav">
 152 <a accesskey="p" href="external_test_runner.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../adv_scenarios.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="../practical_usage_recommendations.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
 153 </div>
 154 </body>
 155 </html>