Hello, Test!

Suppose we wish to test that the following function, declared in hello.hpp and supplied by a static library hello, inserted the text Hello, world!\n to the given stream:

#if !defined(HELLO_HPP)
#define HELLO_HPP

#include <ostream>

extern void hello_world(std::ostream& stream);

#endif

We can accomplish this with the following test, saving it in test_hello.cpp:

#define BOOST_TEST_MAIN
#include <boost/test/included/unit_test.hpp>
#include "hello.hpp"
#include <sstream>

BOOST_AUTO_TEST_CASE(hello_world_inserts_text)
{
    std::ostringstream dest;

    hello_world(dest);

    BOOST_REQUIRE_EQUAL("Hello, world!\n", dest.str());
}

We compile test_hello.cpp and link it against the static library hello using the build environment for our platform to produce an executable. No other source files or libraries are needed. When we run the executable, it will execute our test case.

Suppose that our implementation of hello_world looks like this:

#include "hello.hpp"

void hello_world(std::ostream& stream)
{
}

When we run the unit test executable we obtain output similar to the following:^[1]

Running 1 test case...
src/tutorials/hello_test/1/test/test_hello.cpp(13): fatal error in "hello_world_inserts_text": critical check "Hello, world!\n" == dest.str() failed [Hello, world!
 != ]

*** 1 failure detected in test suite "Master Test Suite"

EXIT STATUS: 201

Oops, it looks like we forgot to implement hello_world!. Let's fix that by changing hello.cpp to the following:

#include "hello.hpp"

void hello_world(std::ostream& stream)
{
    stream << "Hello, world!";
}

We can now rebuild our library, relink our unit test executable and re-run the test:

Running 1 test case...
src/tutorials/hello_test/2/test/test_hello.cpp(13): fatal error in "hello_world_inserts_text": critical check "Hello, world!\n" == dest.str() failed [Hello, world!
 != Hello, world!]

*** 1 failure detected in test suite "Master Test Suite"

EXIT STATUS: 201

Oops, looks like we forgot to insert the newline character. Let's fix that by changing hello.cpp to the following:

#include "hello.hpp"

void hello_world(std::ostream& stream)
{
    stream << "Hello, world!" << std::endl;
}

We rebuild our library, relink our unit test executable again and re-run the test:

Running 1 test case...

*** No errors detected

EXIT STATUS: 0

Now all our tests are passing and we know that hello_world does what we expect it to do. We used std::endl to insert the newline character and it also flushes the output stream after inserting the newline. If we didn't want the output stream to be flushed, we can change hello_world to use a character literal:

#include "hello.hpp"

void hello_world(std::ostream& stream)
{
    stream << "Hello, world!\n";
}

We rebuild and re-run the test to verify that our change didn't break anything:

Running 1 test case...

*** No errors detected

EXIT STATUS: 0

Some Observations

Now that we've seen Boost.Test in action, let's take a closer look at what we have just done:

The entire unit test framework was brought into our test application with a single include <boost/test/included/unit_test.hpp>. We didn't link against any libraries or introduce any run-time dependencies.
We didn't write an implementation of main, but our test executable linked and ran. Why? The preprocessor symbol BOOST_TEST_MAIN instructed Boost.Test to supply an implementation of main that executes all tests registered with the framework.
The macro BOOST_AUTO_TEST_CASE registered our unit test case with the framework and provides the necessary preamble for the implementation of the testing function.
The argument to BOOST_AUTO_TEST_CASE is the name of our test case and is a C++ identifier, not a string.
The test was structured in three phases: setup, exercise, and verify.
- Our setup phase created an output string stream in order to capture the output of hello_world, the system under test.
- The exercise phase called the system under test, our function hello_world.
- The verify phase checked that the function provided the expected output using the assertion macro BOOST_REQUIRE_EQUAL.
- To make the phases of the test obvious, we used blank lines to separate them.
A failing test emits a message that provides information about the location of the failed assertion and the detail of the failure.
The above sequence is a typical example of test-driven development, proceeding through stages of "red", "green" and "refactor".
- We wrote a failing test and just enough implementation to compile the test ("red").
- We then wrote the implementation and ran the test to verify our implementation. We made a simple mistake, so we corrected that and re-ran the test to verify our implementation by passing the test ("green").
- Once our implementation was correct, we looked at possible improvements we might make to the code; in our case we eliminated the side-effect of flushing the output stream ("refactor").
The test code and production code, or system under test, are kept separate. The production code was in a library and the test code was in an executable.
No news is good news! We don't see any noise from test cases when they pass and the test executable emits only a summary of all test cases when all tests pass.

Example Source Code

System under test:
- hello.hpp
- hello.cpp
Tests:
- test_hello.cpp

^[1] The test runner output here is generated from the run-fail rule in Boost.Build which includes the output from the executable and appends the exit code of the process to the output.