External Boost Test Runner Usage

The External Boost Test Runner has been created so as to permit the discovery and execution of unit tests contained in a build that is not compiled as an executable but is compiled as a dynamic-link library. The command line options of the Boost External Test Runner are:

–init

used to define the name of the initialization function to call, which by default is the Boost UTF supplied init_unit_test function. The initialization function needs to be exported in a C style interface otherwise the Boost External Test Runner will fail to find the entry point of the method.

–test

used to define the path and the name of the DLL containing the Boost UTF tests.

–list-debug

used to define the path of the output XML file that will contain the test suites, the respective tests contained in the test suite, the source file and the line number where the test has been declared. A sample XML generated by the command directive <–list-debug> is shown here below

<?xml version="1.0" encoding="UTF-8" ?>
<BoostTestFramework source="D:\dev\svn\SampleBoostProject\Debug\TestProject.dll">
    <TestSuite id="1" name="Master Test Suite">
        <TestSuite id="2" name="ExampleTestSuite">
            <TestCase id="65536" name="NumberTestCaseA" file="d:\dev\svn\testproject\numbertest.cpp" line="39" />
            <TestCase id="65537" name="NumberTestCaseB" file="d:\dev\svn\testproject\numbertest.cpp" line="54" />
            <TestCase id="65538" name="NumberTestCaseC" file="d:\dev\svn\testproject\numbertest.cpp" line="66" />
            <TestCase id="65539" name="NumberTestCaseD" file="d:\dev\svn\testproject\numbertest.cpp" line="80" />
            <TestCase id="65540" name="NumberTestCaseE" file="d:\dev\svn\testproject\numbertest.cpp" line="92" />
            <TestCase id="65541" name="NumberTestCaseF" file="d:\dev\svn\testproject\numbertest.cpp" line="104" />
            <TestCase id="65542" name="NumberTestCaseG" file="d:\dev\svn\testproject\numbertest.cpp" line="118" />
            <TestCase id="65543" name="NumberTestCaseH" file="d:\dev\svn\testproject\numbertest.cpp" line="134" />
            <TestCase id="65544" name="NumberTestCaseI" file="d:\dev\svn\testproject\numbertest.cpp" line="156" />
            <TestCase id="65545" name="NumberTestCaseJ" file="d:\dev\svn\testproject\numbertest.cpp" line="168" />
            <TestCase id="65546" name="NumberTestCaseK" file="d:\dev\svn\testproject\numbertest.cpp" line="190" />
        </TestSuite>
    </TestSuite>
</BoostTestFramework>

–list

used to define the path of the output XML file similar to –list-debug, but will contain only the test suites and the names of the tests. A sample XML generated by the command directive –list is shown here below

<?xml version="1.0" encoding="UTF-8" ?>
<BoostTestFramework source="D:\dev\svn\SampleBoostProject\Debug\TestProject.dll">
    <TestSuite id="1" name="Master Test Suite">
        <TestSuite id="2" name="ExampleTestSuite">
            <TestCase id="65536" name="NumberTestCaseA" />
            <TestCase id="65537" name="NumberTestCaseB" />
            <TestCase id="65538" name="NumberTestCaseC" />
            <TestCase id="65539" name="NumberTestCaseD" />
            <TestCase id="65540" name="NumberTestCaseE" />
            <TestCase id="65541" name="NumberTestCaseF" />
            <TestCase id="65542" name="NumberTestCaseG" />
            <TestCase id="65543" name="NumberTestCaseH" />
            <TestCase id="65544" name="NumberTestCaseI" />
            <TestCase id="65545" name="NumberTestCaseJ" />
            <TestCase id="65546" name="NumberTestCaseK" />
        </TestSuite>
    </TestSuite>
</BoostTestFramework>

The typical command line usage of the Boost External Test Runner so as to enumerate tests is

BoostExternalTestRunner.exe –test "{source}" –list-debug "{out}"

where {source} would be replaced by the full or relative path along with the filename of the DLL containing the Boost UTF tests and {out} would be replaced by the full or relative path along with filename of where the output XML file containing the enumeration of tests would be generated at.

An example of the enumeration command is

BoostExternalTestRunner.exe –test "D:\dev\svn\SampleBoostProject\Debug\TestProject.dll" –list-debug "D:\dev\svn\SampleBoostProject\Debug\TestProject.detailed.xml"

The typical command line usage of the Boost External Test Runner so as to execute tests is

BoostExternalTestRunner.exe –test "{source}" {boost-args}

where {source} would be replaced by the full or relative path along with the filename of the dll containing the Boost UTF tests and {boost-args} would contain Boost UTF directives as documented at http://www.boost.org/doc/libs/1_55_0/libs/test/doc/html/utf/user-guide.html or more specifically at http://www.boost.org/doc/libs/1_55_0/libs/test/doc/html/utf/user-guide/runtime-config/run-by-name.html

An example of a valid Boost External Test Runner command so as to run a specific test is BoostExternalTestRunner.exe –test "D:\dev\svn\SampleBoostProject\Debug\TestProject.dll" –log_level=test_suite –run_test=ExampleTestSuite/NumberTestCaseA.

Another example command where a user might want to execute all tests without specifying any Boost UTF options is BoostExternalTestRunner.exe –test "D:\dev\svn\SampleBoostProject\Debug\TestProject.dll".

In order for the External Boost Test Runner to be able to successfully load, discover and execute tests of a DLL build containing the Boost Unit Tests the following conditions must be observed:

i) Both the External Test Runner and DLL must be built with same configuration type (debug or release).

ii) Both the External Test Runner and DLL must be built with same target solution (Win32 or x64).

iii) Both the External Test Runner and dll must be built using the same version of Boost.

iv) stdafx.h must contain the following #define and the following #include.

#ifndef BOOST_TEST_DYN_LINK
#define BOOST_TEST_DYN_LINK
#endif

#include <boost/test/unit_test.hpp>