1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 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"><</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">></span> 65<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">iostream</span><span class="special">></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"><<</span> <span class="string">"using obsolete init"</span> <span class="special"><<</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">></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#idm45267286747104-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 © 2001-2020 Boost.Test contributors<p> 144 Distributed under the Boost Software License, Version 1.0. (See accompanying 145 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>) 146 </p> 147</div></td> 148</tr></table> 149<hr> 150<div class="spirit-nav"> 151<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> 152</div> 153</body> 154</html> 155
