.user-guide.intro Introduction ... or where to start?

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 UTF 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.

Well ... This is a User's Guide after all. Let's go by what you need to know to successfully use the UTF. 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 Glossary section, where I collected short definition for all used terms. And again if you want to jump right into coding the Tutorials section would be a better place to start.

The UTF 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 Usage variants. 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 Test organization section, while Testing tools section arms you with rich set of tools enough to implement almost arbitrary check you need.

Next you'll learn how to understand and manipulate the UTF output in a Test output 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 Runtime configuration section.

One of the first non trivial things you might want to add to your test module is test fixture. Fixture support is covered in Test fixture 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 Test module initialization section. Here you'll learn about various options the UTF provides for you to customize this behaviour.

Finally you might want to learn about how the UTF 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 UTF). The Test runners 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.

.user-guide.usage-variants The UTF usage variants ... or the Buridan's donkey parable

The UTF presents you with 4 different variants how it can be used.

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.

In most cases to compile a test module based on the UTF all you need to include is just the single header

#include <boost/test/unit_test.hpp>

This header includes internally most of the other headers that contains the UTF 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.

.user-guide.static-lib-variant The static library variant of the UTF

The UTF can be built into a static library. If you opt to link a test module with the standalone static library, this usage is called the static library variant of the UTF.

The test runner supplied with this variant required you to implement the test module initialization function that matches one of the two specifications depending on the compilation flag BOOST_TEST_ALTERNATIVE_INIT_API. If flag isn't defined you are required to match the original specification. If you define the flag BOOST_TEST_ALTERNATIVE_INIT_API during a test module compilation you are required to use the alternative initialization function specification. The UTF provides an ability to automatically generate an empty test module initialization function with correct specification if no custom initialization is required by a test module.

If you opted to use an alternative initialization API, for a test module to be able to link with prebuilt library, the flag BOOST_TEST_ALTERNATIVE_INIT_API has to be defined both during library and a test module compilation.

.user-guide.dynamic-lib-variant The dynamic library variant of the UTF

In the project with large number of test modules the static library variant of the UTF may cause you to waste a lot of disk space, since the UTF is linked statically with every test module. The solution is to link with the UTF 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 UTF. This variant requires you to define the flag BOOST_TEST_DYN_LINK either in a makefile or before the header boost/test/unit_test.hpp inclusion.

The test runner supplied with this variant requires you to implement the test module initialization function that matches the alternative initialization function signature. The UTF provides an ability to automatically generate an empty test module initialization function with correct signature if no custom initialization is required by a test module.

	Note
	: The name of the test module initialization function is not enforced, since the function is passed as an argument to the test runner.

.user-guide.single-header-variant The single-header variant of the UTF

If you prefer to avoid the standalone library compilation, you should use the single-header variant of the UTF. This variant is implemented, as it follows from its name, in the single header

#include <boost/test/included/unit_test.hpp>

An inclusion of the header causes the complete implementation of the UTF to be included as a part of a test module's source file. The header

boost/test/unit_test.hpp

doesn't have to be included anymore. You don't have to worry about disabling auto-linking 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 UTF. In fact the only difference is the name of the include file:

boost/test/included/unit_test.hpp

instead of

boost/test/unit_test.hpp

.

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 BOOST_TEST_ALTERNATIVE_INIT_API. If flag isn't defined you are required to match the original specification. If you define the flag BOOST_TEST_ALTERNATIVE_INIT_API during a test module compilation you are required to use the alternative initialization function specification. The UTF 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.

.user-guide.extern-test-runner-variant The external test runner variant of the UTF

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 UTF is called the external test runner variant of the UTF. The variant requires you to define the flag BOOST_TEST_DYN_LINK 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.

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 UTF), it requires you to implement the <link linkend="test-module.def"> test module</link> initialization function that matches the alternative initialization function signature. The UTF 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.

	Note
	: 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.