Boost C++ Libraries

In most cases, the Unit Test Framework can't provide an exact location where system error occurs or uncaught C++ exception is thrown from. To be able to pinpoint it as close as possible the Unit Test Framework keeps track of checkpoints - the location a test module passed through.

The Unit Test Framework keeps track of checkpoints at test case entrance, exit, fixture initialization, and at test tool invocation point.

Any other checkpoints should be entered by you manually if you need more granularity in case a fatal error occurs during the test. The Unit Test Framework provides two macros for this purpose:

The checkpoints are also convenient for checks in loops as they might provide more information about the occurrence of a failure (although superseded by [links boost_test.test_output.test_tools_support_for_logging.contexts contexts]).

Named checkpoints

The macro BOOST_TEST_CHECKPOINT is intended to be used to inject named checkpoint position. The macro signature is as follows:

BOOST_TEST_CHECKPOINT(checkpoint_message);

The message formatted at the checkpoint position is saved and reported by the exception logging functions (if any occurs). Similarly to the BOOST_TEST_MESSAGE the message can be formatted from any standard output stream compliant components.

Example: BOOST_TEST_CHECKPOINT usage

#define BOOST_TEST_MODULE example
#include <boost/test/included/unit_test.hpp>

extern void foo( int i );

BOOST_AUTO_TEST_CASE( test_external_interface )
{
  for( int i = 3; i >=0; i-- ) {
    BOOST_TEST_CHECKPOINT( "Calling foo with i=" << i );
    foo( i );
  }
}

void goo( int )
{
}

#if defined(BOOST_MSVC) && (BOOST_MSVC > 1900)
// VS2017+ compiler optimizations may cause this code NOT to crash.
#pragma optimize("", off)
#endif

void foo( int i )
{
    goo( 2/(i-1) );
}

#if defined(BOOST_MSVC) && (BOOST_MSVC > 1900)
#pragma optimize("", on)
#endif

> example
Running 1 test case...
unknown location(0): fatal error in "test_external_interface": signal: integer divide by zero; address of failing instruction: 0x00048090
test.cpp(9): last checkpoint: Calling foo with i=1

*** 1 failures is detected in test suite "example"

Unnamed checkpoints

The macro BOOST_TEST_PASSPOINT is intended to be used to inject an unnamed checkpoint position. The macro signature is as follows:

BOOST_TEST_PASSPOINT();

Unlike the macro BOOST_TEST_CHECKPOINT this macro doesn't require any message to be supplied with it. It's just a simple "been there" marker that records file name and line number code passes through.

Example: BOOST_TEST_PASSPOINT usage

#define BOOST_TEST_MODULE example
#include <boost/test/included/unit_test.hpp>

#if defined(BOOST_MSVC) && (BOOST_MSVC > 1900)
// VS2017+ compiler optimizations may cause this code NOT to crash.
#pragma optimize("", off)
#endif


void foo( int ) {}

#if defined(BOOST_MSVC) && (BOOST_MSVC > 1900)
#pragma optimize("", on)
#endif

BOOST_AUTO_TEST_CASE( test_case )
{
  int* p = 0;

  BOOST_TEST_PASSPOINT();
  ++p;

  BOOST_TEST_PASSPOINT();
  ++p;

  BOOST_TEST_PASSPOINT();
  foo( *p );
}

> example
Running 1 test case...
unknown location(0): fatal error in "test_case": memory access violation at address: 0x00000008: no mapping at fault address
test.cpp(16): last checkpoint

*** 1 failures is detected in test suite "example"