1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>Test module's initialization</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="entry_point_overview.html" title="Test module's entry point"> 10<link rel="next" href="test_module_runner_overview.html" title="Test module runner"> 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="entry_point_overview.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="test_module_runner_overview.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.test_module_init_overview"></a><a class="link" href="test_module_init_overview.html" title="Test module's initialization">Test 28 module's initialization</a> 29</h3></div></div></div> 30<p> 31 In order for a unit test module to successfully link and execute, it has 32 to have access to the <span class="emphasis"><em>test module's initialization function</em></span>. 33 the module's initialization function is called only once during the execution 34 of the program, just before the <a class="link" href="test_module_runner_overview.html" title="Test module runner"><span class="emphasis"><em>test 35 module runner</em></span></a> is run. By default, the <span class="emphasis"><em>Unit Test 36 Framework</em></span> provides a default definition of initialization function. 37 The only thing you have to do is to instruct the framework in which translation 38 unit (<code class="computeroutput"><span class="identifier">cpp</span></code> file) it needs 39 to provide the definition. You do it by defining macro <a class="link" href="../utf_reference/link_references/link_boost_test_module_macro.html" title="BOOST_TEST_MODULE"><code class="computeroutput"><span class="identifier">BOOST_TEST_MODULE</span></code></a> in the designated 40 file. The default implementation assigns the name to the <a class="link" href="../section_glossary.html#ref_test_module">test 41 module</a> as well as the <a class="link" href="../tests_organization/test_tree/master_test_suite.html" title="Master test suite">master 42 test suite</a>. The name to be assigned is specified by the value of the 43 macro <a class="link" href="../utf_reference/link_references/link_boost_test_module_macro.html" title="BOOST_TEST_MODULE"><code class="computeroutput"><span class="identifier">BOOST_TEST_MODULE</span></code></a>. 44 </p> 45<div class="important"><table border="0" summary="Important"> 46<tr> 47<td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../../../../../../doc/src/images/important.png"></td> 48<th align="left">Important</th> 49</tr> 50<tr><td align="left" valign="top"><p> 51 For a test module consisting of multiple source files you have to define 52 <a class="link" href="../utf_reference/link_references/link_boost_test_module_macro.html" title="BOOST_TEST_MODULE"><code class="computeroutput"><span class="identifier">BOOST_TEST_MODULE</span></code></a> in a single 53 test file only. Otherwise you end up with multiple instances of the initialization 54 function. 55 </p></td></tr> 56</table></div> 57<p> 58 There is practically no need to ever alter the default behavior of the test 59 module's initialization function. The <span class="emphasis"><em>Unit Test Framework</em></span> 60 provides superior tools for performing customization tasks: 61 </p> 62<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 63<li class="listitem"> 64 for automatic registration of test cases and test suites in the test 65 tree, see section <a class="link" href="../tests_organization.html" title="Declaring and organizing tests">Tests 66 organization</a>; 67 </li> 68<li class="listitem"> 69 in order to assign the custom name to the master test suite define macro 70 <a class="link" href="../utf_reference/link_references/link_boost_test_module_macro.html" title="BOOST_TEST_MODULE"><code class="computeroutput"><span class="identifier">BOOST_TEST_MODULE</span></code></a> to desired 71 value; 72 </li> 73<li class="listitem"> 74 in order to access the command-line parameters (except the ones consumed 75 by the <span class="emphasis"><em>Unit Test Framework</em></span>), use the interface of 76 the <a class="link" href="../tests_organization/test_tree/master_test_suite.html" title="Master test suite">master 77 test suite</a>; 78 </li> 79<li class="listitem"> 80 in order to perform a global initialization of the state required by 81 the test cases, <a class="link" href="../tests_organization/fixtures/global.html" title="Global fixture">global 82 fixtures</a> offer a superior alternative: you can specify global 83 set-up and tear-down in one place, allow access to the global data from 84 every test case, and guarantee that clean-up and tear-down is repeated 85 each time the tests are re-run during the execution of the program; 86 </li> 87<li class="listitem"> 88 if the need for custom module initialization is only driven by legacy 89 code (written against old versions of the <span class="emphasis"><em>Unit Test Framework</em></span>), 90 it is recommended to update your program's code. 91 </li> 92</ul></div> 93<p> 94 The default initialization function provided by the framework is defined 95 with the following signature in the global namespace: 96 </p> 97<pre class="programlisting"><span class="keyword">bool</span> <span class="identifier">init_unit_test</span><span class="special">();</span> 98</pre> 99<p> 100 Return value <code class="computeroutput"><span class="keyword">true</span></code> indicates 101 a successful initialization. Value <code class="computeroutput"><span class="keyword">false</span></code> 102 indicates initialization failure. 103 </p> 104<p> 105 For overriding the default definition: 106 </p> 107<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 108<li class="listitem"> 109 <a class="link" href="single_header_customizations/init_func.html" title="Customizing the module's initialization function">see 110 here</a>, for header-only usage variant, 111 </li> 112<li class="listitem"> 113 <a class="link" href="static_lib_customizations/init_func.html" title="Customizing the module's initialization function">see 114 here</a>, for static library usage variant, 115 </li> 116<li class="listitem"> 117 <a class="link" href="shared_lib_customizations/init_func.html" title="Customizing the module's initialization function">see 118 here</a>, for shared library usage variant. 119 </li> 120</ul></div> 121</div> 122<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 123<td align="left"></td> 124<td align="right"><div class="copyright-footer">Copyright © 2001-2020 Boost.Test contributors<p> 125 Distributed under the Boost Software License, Version 1.0. (See accompanying 126 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>) 127 </p> 128</div></td> 129</tr></table> 130<hr> 131<div class="spirit-nav"> 132<a accesskey="p" href="entry_point_overview.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="test_module_runner_overview.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a> 133</div> 134</body> 135</html> 136
