boost/test
2
0
Fork 0
mirror of https://github.com/boostorg/test.git synced 2026-02-19 02:42:13 +00:00
Code Issues Projects Releases Wiki Activity

latest state of sources

Browse Source 
Fixes #4982

[SVN r75007]
This commit is contained in:
Gennadiy Rozental
2011-10-17 11:13:55 +00:00
parent 743a0220a2
commit dbec26921f
29 changed files with 2762 additions and 1425 deletions
Download Patch File Download Diff File Expand all files Collapse all files

150
doc/src/utf.user-guide.initialization.xml Normal file
View File

@@ -0,0 +1,150 @@
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE chapter PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" "../../../../tools/boostbook/dtd/boostbook.dtd" [
<!ENTITY utf "<acronym>UTF</acronym>">
]>
<section id="utf.user-guide.initialization">
<title>Test module initialization &hellip; or ready, set &hellip;</title>
<titleabbrev>Test module initialization</titleabbrev>
<para role="first-line-indented">
There are two tasks that you may need to perform before actual testing can start:
</para>
<itemizedlist>
<listitem>
<simpara>
The test tree needs to be built (unless you are using automated test units registration).
</simpara>
</listitem>
<listitem>
<simpara>
Custom test module initialization needs to be performed. This includes
initialization of the code under test and custom tune-up of the &utf; parameters (for example the test log or the
test results report output streams redirection).
</simpara>
</listitem>
</itemizedlist>
<para role="first-line-indented">
The function dedicated for this purpose is called <firstterm>the test module initialization function</firstterm>. Alternatively you can
employ global fixtures, covered in details, including differences in two approaches, in
<xref linkend="utf.user-guide.fixture"/>.
</para>
<para role="first-line-indented">
The &utf; requires you to implement the test module initialization function. The test runner supplied with the static
library or single-header variants of the &utf; requires the specific function specification. The test runner supplied
with the dynamic library variant of the &utf; requires the specific initialization function signature only. <!-- TO FIX: specific specification -->
</para>
<para role="first-line-indented">
For many <link linkend="test-module.def">test modules</link> you don't need to do any custom initialization
and test tree construction is automated. In this case you don't really need the initialization function and
the &utf; provides a way to automatically generate an empty one for you.
</para>
<para role="first-line-indented">
Original design of the &utf; supported the manual test tree construction only. Later versions introduced the
automated registration of test units. In later versions of the &utf; the original initialization function
specification became inconvenient and unnecessary unsafe. So the alternative initialization function specification
was introduced. This change is not backward compatible. The test runners supplied with the static library and
single-header variants of the &utf; by default still require original initialization function specification, but
support <link linkend="utf.compilation.flags">compilation flags</link> that switch to the alternative one. The test
runner supplied with dynamic library variant of the &utf; requires new specification and doesn't support
original one. The plan is to deprecate the original initialization function specification in one of the future
releases and ultimately to stop supporting it.
</para>
<para role="first-line-indented">
The initialization function invocation is monitored by the &utf; the same way as all the test cases. An unexpected
exception or system error detected during initialization function invocation is treated as initialization error and
is reported as such.
</para>
<section id="utf.user-guide.initialization.orig-signature">
<title>Original initialization function signature and name</title>
<titleabbrev>Original initialization function</titleabbrev>
<para role="first-line-indented">
The original design of the &utf; initialization required you to implement the function with the following
specification:
</para>
<programlisting><classname>boost::unit_test::test_suite</classname>* init_unit_test_suite( int argc, char* argv[] );</programlisting>
<para role="first-line-indented">
This function was intended to initialize and return a master test suite. The null value was considered an initialization
error. The current design of the &utf; maintains master test suite instance internally and does not treat the null result
value as an initialization error. In fact it's recommended to return null value always and register test units in the
master test suite using the regular test suite add interface. The only way to indicate an initialization error is to throw the
<classname>boost::unit_test::framework::setup_error</classname> exception.
</para>
<para role="first-line-indented">
The initialization function parameters argc, argv provide the command line arguments specified during test
module invocation. It's guarantied that any framework-specific command line arguments are excluded. To be
consisted with the alternative initialization function specification it's recommended though to access the
command line arguments using the master test suite interface.
</para>
</section>
<section id="utf.user-guide.initialization.alt-signature">
<title>Alternative initialization function signature and name</title>
<titleabbrev>Alternative initialization function</titleabbrev>
<para role="first-line-indented">
The alternative design of the &utf; initialization requires you to implement a function with the following
specification:
</para>
<programlisting>bool init_unit_test();</programlisting>
<para role="first-line-indented">
The result value of this function indicates whether or not initialization was successful. To register test
units in a master test suite use the test suite add interface. To access command line arguments use the master
test suite interface. It's guarantied that any framework-specific command line arguments are excluded.
</para>
</section>
<section id="utf.user-guide.initialization.signature-typedef">
<title>Initialization function signature access</title>
<para role="first-line-indented">
The test runner interface needs to refer to the initialization function signature. The &utf; provides the typedef
that resolves to proper signature in all configurations:
</para>
<programlisting>namespace boost {
namespace unit_test {
#ifdef BOOST_TEST_ALTERNATIVE_INIT_API
typedef bool (*init_unit_test_func)();
#else
typedef test_suite* (*init_unit_test_func)( int, char* [] );
#endif
}
}</programlisting>
</section>
<section id="utf.user-guide.initialization.auto-generation">
<title>Automated generation of the test module initialization function</title>
<titleabbrev>Automated generation</titleabbrev>
<para role="first-line-indented">
To automatically generate an empty test module initialization function you need to define
<xref linkend="utf.flag.main" endterm="utf.flag.main"/> before including the
<filename class="headerfile">boost/test/unit_test.hpp</filename> header. The value of this define is ignored.
Alternatively you can define the macro <xref linkend="utf.flag.module" endterm="utf.flag.module"/> to be equal to
any string (not necessarily in quotes). This macro causes the same result as
<xref linkend="utf.flag.main" endterm="utf.flag.main"/>, and in addition the macro value becomes the name of the
master test suite.
</para>
<important>
<simpara>
For a test module consisting of multiple source files you have to define these flags in a single test file only.
Otherwise you end up with multiple instances of the initialization function.
</simpara>
</important>
</section>
</section>