Backport lots of new features from the 1.41.0 branch.
[boost:cmake.git] / tools / build / CMake / docs / build / html / _sources / adding_regression_tests.txt
1 .. index:: regression tests; adding
2 .. _adding_regression_tests:
3
4 Adding Regression Tests
5 =======================
6
7 This page describes how to add regression tests for a Boost library in
8 the CMake-based build system. Before adding regression tests, make
9 sure you have already followed the directions for
10 :ref:`boost_library_project_macro` , so that the CMake system
11 recognizes your Boost library project, and (if necessary)
12 :ref:`add_compiled_library`. We also assume that you have already
13 configured your build tree for regression testing of your library, by
14 adding your library project's name to the :ref:`BUILD_TESTS` option
15 described in the section :ref:`testing`.
16
17 In this page, we will assume that your library resides in the
18 subdirectory ``libs/libname``, and that tests for this library are
19 stored in ``libs/libname/test``. The test directory should be listed
20 via :ref:`TESTDIRS` in the call of
21 :ref:`boost_library_project_macro`. Follow these steps to add this new
22 library into Boost's build system. If your library has multiple
23 testing directories listed after :ref:`TESTDIRS`, follow these steps for
24 each one.
25
26 #.  Create a new file ``libs/libname/test/CMakeLists.txt`` file with
27     your favorite text editor. This file will contain instructions for
28     building and running each of the regression tests for your library.
29
30 #.  If your regression test depends on any other part of boost then
31     you will need to inform the build system of such with the
32     following line::
33
34       boost_additional_test_dependencies(libname BOOST_DEPENDS test fusion)
35
36     where 'libname' is the name of your library that you are testing.
37
38 #.  For each test that only needs to be compiled (but not executed),
39     add a ``compile`` or ``compile_fail`` test using the
40     :ref:`boost_test_compile` or :ref:`boost_test_compile_fail`
41     macros, respectively. The most basic usage of these macros
42     provides only the test name, e.g., ::
43
44       boost_test_compile(compile_test)
45       boost_test_compile_fail(compile_fail_test)
46
47     This code will create two regression tests. The first,
48     ``compile_test``, will try to compile the source file
49     ``compile_test.cpp`` in the current source directory. If the
50     compile is successful, the regression test passes. If the compile
51     fails, the regression test fails. The second regression test works
52     the opposite way: it will try to compile
53     ``compile_fail_test.cpp``: if the compilation is successful, the
54     regression test fails. When you run the regression tests (e.g., by
55     calling ``ctest`` from the build directory), the regression tests
56     will execute and produce output like the following::
57
58        Running tests...
59        Start processing tests
60        Test project /Users/dgregor/Projects/boost-darwin
61          1/  2 Testing libname::compile_test            Passed
62          2/  2 Testing libname::compile_fail_test     ***Failed - supposed to fail
63        
64        100% tests passed, 0 tests failed out of 2
65
66 3.  For any tests that need to be built and executed, use the
67     :ref:`boost_test_run` or :ref:`boost_test_run_fail` macros. Both
68     tests will build, link and execute a regression test. The
69     :ref:`boost_test_run` macro expects that executable to return an
70     exit code of zero, while the :ref:`boost_test_run_fail` macro
71     expects that executable to return a non-zero exit code. For
72     example, we might build a simple test ``simple_test`` from the
73     source file ``simple_test.cpp``::
74
75       boost_test_run(simple_test)
76
77     Often, we'll want to link against our own Boost library, which we
78     do using the ``DEPENDS`` argument to ``boost_test_run``::
79
80        boost_test_run(big_test big_test1.cpp big_test2.cpp
81          DEPENDS boost_libname-static
82          )
83      
84     Here, we have created a test ``big_test``, built from the source
85     files ``big_test1.cpp`` and ``big_test2.cpp``, which will link
86     against the static library for ``boost_libname``. We could create
87     a similar test that links against the shared library for
88     ``boost_libname``, passing along compilation flags specific to the
89     shared library::
90
91       boost_test_run(big_test_dll big_test1.cpp big_test2.cpp
92         DEPENDS boost_libname-shared
93         COMPILE_FLAGS "-DBOOST_LIBNAME_DYN_LINK=1"
94         )
95
96     Some tests require command-line arguments. For example, say we
97     want to pass ``-loop 1000`` to a randomized test. We can do so
98     using the ``ARGS`` argument to ``boost_test_run`` (or
99     ``boost_test_run_fail``)::
100
101         boost_test_run(random_test ARGS "-loop" "1000" DEPENDS boost_libname-static)
102
103     Once you have finished describing your regression tests to the
104     CMake system, you're done! Your library will now build, test, and
105     install with CMake and this behavior should be portable across
106     many different platforms.
107