mirror of
https://github.com/boostorg/test.git
synced 2026-02-18 14:32:11 +00:00
288 lines
19 KiB
HTML
288 lines
19 KiB
HTML
<html>
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
|
|
<title>-guide User's guide</title>
|
|
<link rel="stylesheet" href="../../../../../../doc/src/boostbook.css" type="text/css">
|
|
<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
|
|
<link rel="home" href="../index.html" title="Boost.Test">
|
|
<link rel="up" href="../index.html" title="Boost.Test">
|
|
<link rel="prev" href="intro_objective.html" title="Objective and content">
|
|
</head>
|
|
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
|
|
<table cellpadding="2" width="100%"><tr>
|
|
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
|
|
<td align="center"><a href="../../../../../../index.html">Home</a></td>
|
|
<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
|
|
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
|
|
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
|
|
<td align="center"><a href="../../../../../../more/index.htm">More</a></td>
|
|
</tr></table>
|
|
<hr>
|
|
<div class="spirit-nav">
|
|
<a accesskey="p" href="intro_objective.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.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>
|
|
</div>
|
|
<div class="section">
|
|
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
|
|
<a name="boost_test.users"></a><a class="link" href="users.html" title="-guide User's guide">-guide User's guide</a>
|
|
</h2></div></div></div>
|
|
<h2>
|
|
<a name="boost_test.users.h0"></a>
|
|
<span class="phrase"><a name="boost_test.users.utf"></a></span><a class="link" href="users.html#boost_test.users.utf">.user-guide.intro
|
|
Introduction ... or where to start?</a>
|
|
</h2>
|
|
<p>
|
|
Without further ado, I'd like to start ... but where? It's not obvious what
|
|
is the best order to describe the framework. One can use bottom up approach,
|
|
starting with with basics and going up to cover real interfaces based on them.
|
|
The downside is that you'll have to dig through the multiple pages of information
|
|
you may not never need in real life. One can follow the order of test program
|
|
execution. From test initialization to test tree construction to the report
|
|
and log generation. This also unfortunately may not be most clear way. The
|
|
Boost.Test <span class="emphasis"><em>UTF</em></span> is very flexible and a lot of details of
|
|
various test initialization options may not necessarily important for average
|
|
user, while understanding test output is.
|
|
</p>
|
|
<p>
|
|
Well ... This is a User's Guide after all. Let's go by what <span class="bold"><strong>you</strong></span>
|
|
need to know to successfully use the <span class="emphasis"><em>UTF</em></span>. Thus I follow
|
|
the order of decisions you as a user have to make and order of complexity of
|
|
the problems you have to solve. If you find yourself faces with some unclear
|
|
term feel free to jump directly to the <span class="bold"><strong>Glossary</strong></span>
|
|
section, where I collected short definition for all used terms. And again if
|
|
you want to jump right into coding the <span class="bold"><strong>Tutorials</strong></span>
|
|
section would be a better place to start.
|
|
</p>
|
|
<p>
|
|
The <span class="emphasis"><em>UTF</em></span> has several usage variants. And the first decision
|
|
you have to make is which one to use. These variants are covered in section
|
|
dedicated to <span class="bold"><strong>Usage variants</strong></span>. The next step,
|
|
probably the most important for you, is to start writing test cases, bind them
|
|
in test suites and implement your checks. First two topics are covered in
|
|
<span class="bold"><strong>Test organization</strong></span> section, while <span class="bold"><strong>Testing tools</strong></span> section arms you with rich set of tools
|
|
enough to implement almost arbitrary check you need.
|
|
</p>
|
|
<p>
|
|
Next you'll learn how to understand and manipulate the <span class="emphasis"><em>UTF</em></span>
|
|
output in a <span class="bold"><strong>Test output</strong></span> section. At that point
|
|
you should be able to build and run most simple test modules and almost inevitable
|
|
find a need to configure how the test module is executed. Whether you want
|
|
to change output format, select which test case to run or run test cases in
|
|
random order these and may other runtime configuration parameters are described
|
|
in <span class="bold"><strong>Runtime configuration</strong></span> section.
|
|
</p>
|
|
<p>
|
|
One of the first non trivial things you might want to add to your test module
|
|
is test fixture. Fixture support is covered in <span class="bold"><strong>Test fixture</strong></span>
|
|
section. Usually the default test module initialization will work just fine,
|
|
but if you want to implement some custom initialization or change how default
|
|
initialization behaves you need to first look in <span class="bold"><strong>Test
|
|
module initialization</strong></span> section. Here you'll learn about various options
|
|
the <span class="emphasis"><em>UTF</em></span> provides for you to customize this behaviour.
|
|
</p>
|
|
<p>
|
|
Finally you might want to learn about how the <span class="emphasis"><em>UTF</em></span> implements
|
|
entry points into the test modules. This is especially important if you intend
|
|
to implement main function yourself (and not use the main function provided
|
|
by the <span class="emphasis"><em>UTF</em></span>). The <span class="bold"><strong>Test runners</strong></span>
|
|
section covers this subject. Different usage variants employ slightly different
|
|
approached to implementing test module entry points and presents slightly different
|
|
interfaces. This section intended for advanced user some of the details of
|
|
the implementation are described there.
|
|
</p>
|
|
<h3>
|
|
<a name="boost_test.users.h1"></a>
|
|
<span class="phrase"><a name="boost_test.users.utf0"></a></span><a class="link" href="users.html#boost_test.users.utf0">.user-guide.usage-variants
|
|
The <span class="emphasis"><em>UTF</em></span> usage variants ... or the Buridan's
|
|
donkey parable</a>
|
|
</h3>
|
|
<p>
|
|
The <span class="emphasis"><em>UTF</em></span> presents you with 4 different variants how it
|
|
can be used.
|
|
</p>
|
|
<div class="orderedlist"><ol class="orderedlist" type="1">
|
|
<li class="listitem">
|
|
The static library variant
|
|
</li>
|
|
<li class="listitem">
|
|
The dynamic library variant
|
|
</li>
|
|
<li class="listitem">
|
|
The single-header variant
|
|
</li>
|
|
<li class="listitem">
|
|
The external test runner variant
|
|
</li>
|
|
</ol></div>
|
|
<p>
|
|
Unlike the Buridan's donkey though, you shouldn't have problems deciding which
|
|
one to use, since there are clear reasons why would you prefer each one.
|
|
</p>
|
|
<p>
|
|
In most cases to compile a test module based on the <span class="emphasis"><em>UTF</em></span>
|
|
all you need to include is just the single header
|
|
</p>
|
|
<pre class="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">unit_test</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span>
|
|
</pre>
|
|
<p>
|
|
This header includes internally most of the other headers that contains the
|
|
<span class="emphasis"><em>UTF</em></span> definitions. Some advanced features, like the floating
|
|
point comparison or the logged expectations testing, are defined in independent
|
|
headers and need to be included explicitly.
|
|
</p>
|
|
<h4>
|
|
<a name="boost_test.users.h2"></a>
|
|
<span class="phrase"><a name="boost_test.users.utf1"></a></span><a class="link" href="users.html#boost_test.users.utf1">.user-guide.static-lib-variant
|
|
The static library variant of the <span class="emphasis"><em>UTF</em></span></a>
|
|
</h4>
|
|
<p>
|
|
The <span class="emphasis"><em>UTF</em></span> can be built into a static library. If you opt
|
|
to link a test module with the <span class="bold"><strong>standalone static library</strong></span>,
|
|
this usage is called the static library variant of the <span class="emphasis"><em>UTF</em></span>.
|
|
</p>
|
|
<p>
|
|
The test runner supplied with this variant required you to implement the <span class="bold"><strong>test module</strong></span> initialization function that matches one
|
|
of the two specifications depending on the compilation flag <code class="computeroutput"><span class="identifier">BOOST_TEST_ALTERNATIVE_INIT_API</span></code>.
|
|
If flag isn't defined you are required to match the original specification.
|
|
If you define the flag <code class="computeroutput"><span class="identifier">BOOST_TEST_ALTERNATIVE_INIT_API</span></code>
|
|
during a test module compilation you are required to use the alternative initialization
|
|
function specification. The <span class="emphasis"><em>UTF</em></span> provides an ability to
|
|
<span class="bold"><strong>automatically generate</strong></span> an empty test module
|
|
initialization function with correct specification if no custom initialization
|
|
is required by a test module.
|
|
</p>
|
|
<p>
|
|
If you opted to use an alternative initialization API, for a test module to
|
|
be able to link with prebuilt library, the flag <code class="computeroutput"><span class="identifier">BOOST_TEST_ALTERNATIVE_INIT_API</span></code>
|
|
has to be defined both during library and a test module compilation.
|
|
</p>
|
|
<h4>
|
|
<a name="boost_test.users.h3"></a>
|
|
<span class="phrase"><a name="boost_test.users.utf2"></a></span><a class="link" href="users.html#boost_test.users.utf2">.user-guide.dynamic-lib-variant
|
|
The dynamic library variant of the <span class="emphasis"><em>UTF</em></span></a>
|
|
</h4>
|
|
<p>
|
|
In the project with large number of test modules <a class="link" href="../">the
|
|
static library variant</a> of the <span class="emphasis"><em>UTF</em></span> may cause you
|
|
to waste a lot of disk space, since the <span class="emphasis"><em>UTF</em></span> is linked
|
|
statically with every test module. The solution is to link with the <span class="emphasis"><em>UTF</em></span>
|
|
built into a dynamic library. If you opt to link a test module with the prebuilt
|
|
dynamic library, this usage is called the dynamic library variant of the <span class="emphasis"><em>UTF</em></span>.
|
|
This variant requires you to define the flag <code class="computeroutput"><span class="identifier">BOOST_TEST_DYN_LINK</span></code>
|
|
either in a makefile or before the header <code class="computeroutput"><span class="identifier">boost</span><span class="special">/</span><span class="identifier">test</span><span class="special">/</span><span class="identifier">unit_test</span><span class="special">.</span><span class="identifier">hpp</span></code> inclusion.
|
|
</p>
|
|
<p>
|
|
The test runner supplied with this variant requires you to implement the <span class="bold"><strong>test module</strong></span> initialization function that matches the
|
|
alternative initialization function signature. The <span class="emphasis"><em>UTF</em></span>
|
|
provides an ability to <span class="bold"><strong>automatically generate</strong></span>
|
|
an empty test module initialization function with correct signature if no custom
|
|
initialization is required by a test module.
|
|
</p>
|
|
<div class="note"><table border="0" summary="Note">
|
|
<tr>
|
|
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../doc/src/images/note.png"></td>
|
|
<th align="left">Note</th>
|
|
</tr>
|
|
<tr><td align="left" valign="top"><p>
|
|
: The name of the test module initialization function is not enforced, since
|
|
the function is passed as an argument to the test runner.
|
|
</p></td></tr>
|
|
</table></div>
|
|
<h4>
|
|
<a name="boost_test.users.h4"></a>
|
|
<span class="phrase"><a name="boost_test.users.utf3"></a></span><a class="link" href="users.html#boost_test.users.utf3">.user-guide.single-header-variant
|
|
The single-header variant of the <span class="emphasis"><em>UTF</em></span></a>
|
|
</h4>
|
|
<p>
|
|
If you prefer to avoid the <span class="bold"><strong>standalone library compilation</strong></span>,
|
|
you should use the single-header variant of the <span class="emphasis"><em>UTF</em></span>. This
|
|
variant is implemented, as it follows from its name, in the single header
|
|
</p>
|
|
<pre class="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>
|
|
</pre>
|
|
<p>
|
|
An inclusion of the header causes the complete implementation of the <span class="emphasis"><em>UTF</em></span>
|
|
to be included as a part of a test module's source file. The header
|
|
</p>
|
|
<pre class="programlisting"><span class="identifier">boost</span><span class="special">/</span><span class="identifier">test</span><span class="special">/</span><span class="identifier">unit_test</span><span class="special">.</span><span class="identifier">hpp</span></pre>
|
|
<p>
|
|
doesn't have to be included anymore. You don't have to worry about disabling
|
|
<span class="bold"><strong>auto-linking</strong></span> feature either. It's done in
|
|
the implementation header already. This variant can't be used with the <xref
|
|
linkend="multi-file-test-module.def" endterm="multi-file-test-module.def"/>.
|
|
Otherwise it's almost identical from the usage prospective to the static library
|
|
variant of the <span class="emphasis"><em>UTF</em></span>. In fact the only difference is the
|
|
name of the include file:
|
|
</p>
|
|
<pre class="programlisting"><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></pre>
|
|
<p>
|
|
instead of
|
|
</p>
|
|
<pre class="programlisting"><span class="identifier">boost</span><span class="special">/</span><span class="identifier">test</span><span class="special">/</span><span class="identifier">unit_test</span><span class="special">.</span><span class="identifier">hpp</span></pre>
|
|
<p>
|
|
.
|
|
</p>
|
|
<p>
|
|
The test runner supplied with this variant requires you to implement the <link
|
|
linkend="test-module.def">test module</link> initialization
|
|
function that matches one of the two specifications depending on the compilation
|
|
flag <code class="computeroutput"><span class="identifier">BOOST_TEST_ALTERNATIVE_INIT_API</span></code>.
|
|
If flag isn't defined you are required to match the original specification.
|
|
If you define the flag <code class="computeroutput"><span class="identifier">BOOST_TEST_ALTERNATIVE_INIT_API</span></code>
|
|
during a test module compilation you are required to use the alternative initialization
|
|
function specification. The <span class="emphasis"><em>UTF</em></span> provides an ability to
|
|
<link linkend="utf.user-guide.initialization.auto-generation">automatically
|
|
generate</link> an empty test module initialization function with correct
|
|
specification if no custom initialization is required by a test module.
|
|
</p>
|
|
<h4>
|
|
<a name="boost_test.users.h5"></a>
|
|
<span class="phrase"><a name="boost_test.users.utf4"></a></span><a class="link" href="users.html#boost_test.users.utf4">.user-guide.extern-test-runner-variant
|
|
The external test runner variant of the <span class="emphasis"><em>UTF</em></span></a>
|
|
</h4>
|
|
<p>
|
|
All other usage variants employ the build-in test runners. If you plan to use
|
|
an external test runner with your test module you need to build it as a dynamic
|
|
library. This usage of the <span class="emphasis"><em>UTF</em></span> is called the external
|
|
test runner variant of the <span class="emphasis"><em>UTF</em></span>. The variant requires you
|
|
to define the flag <code class="computeroutput"><span class="identifier">BOOST_TEST_DYN_LINK</span></code>
|
|
either in a makefile or before the header <filename class="headerfile">boost/test/unit_test.hpp</filename>
|
|
inclusion. An external test runner utility is required to link with dynamic
|
|
library.
|
|
</p>
|
|
<p>
|
|
If an external test runner is based on the test runner built in to the dynamic
|
|
library (like the standalone boost_test_runner utility supplied by the <span class="emphasis"><em>UTF</em></span>),
|
|
it requires you to implement the <link linkend="test-module.def">
|
|
test module</link> initialization function that matches the alternative
|
|
initialization function signature. The <span class="emphasis"><em>UTF</em></span> provides an
|
|
ability to <link linkend="utf.user-guide.initialization.auto-generation">automatically
|
|
generate </link> an empty test module initialization function with correct
|
|
signature if no custom initialization is required by a test module.
|
|
</p>
|
|
<div class="note"><table border="0" summary="Note">
|
|
<tr>
|
|
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../doc/src/images/note.png"></td>
|
|
<th align="left">Note</th>
|
|
</tr>
|
|
<tr><td align="left" valign="top"><p>
|
|
: An advanced test runner doesn't have to be based on the build-in one and
|
|
may require a different test module initialization function signature and/or
|
|
name.
|
|
</p></td></tr>
|
|
</table></div>
|
|
</div>
|
|
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
|
|
<td align="left"></td>
|
|
<td align="right"><div class="copyright-footer">Copyright © 2001-2013 Gennadiy Rozental<p>
|
|
Distributed under the Boost Software License, Version 1.0. (See accompanying
|
|
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>)
|
|
</p>
|
|
</div></td>
|
|
</tr></table>
|
|
<hr>
|
|
<div class="spirit-nav">
|
|
<a accesskey="p" href="intro_objective.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.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>
|
|
</div>
|
|
</body>
|
|
</html>
|