Boost C++ Libraries

Checkpoints may be used to indicate the state of the running test with more granularity in case a fatal error occurs during the test. The checkpoints are also convenient for checks in loops as they might provide more information about the occurrence of a failure.

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 )
{
}

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

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

void foo( int ) {}

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"