3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
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">
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>
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>
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>
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>.
45 <div class="important"><table border="0" summary="Important">
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>
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
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:
62 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
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
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
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
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;
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.
94 The default initialization function provided by the framework is defined
95 with the following signature in the global namespace:
97 <pre class="programlisting"><span class="keyword">bool</span> <span class="identifier">init_unit_test</span><span class="special">();</span>
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.
105 For overriding the default definition:
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,
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,
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.
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-2019 Boost.Test
126 Distributed under the Boost Software License, Version 1.0. (See accompanying
127 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>)
132 <div class="spirit-nav">
133 <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>