Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

PrevUpHomeNext

Checkpoints for accurate failure location

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

Code

#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 value )
{
  BOOST_TEST_CHECKPOINT( "Inside goo with value '" << value << "'");
}

void foo( int i )
{
  if( i == 1 )
      throw std::runtime_error("Undefined Behaviour ahead!");
  // following line may not raise an exception on some compilers:
  // Undefined Behaviour is implementation specific
  goo( 2/(i-1) );
}

Output

> example
Running 1 test case...
unknown location(0): fatal error: in "test_external_interface": std::runtime_error: Undefined Behaviour ahead!
../doc/examples/example22.run-fail.cpp(17): last checkpoint: Calling 'foo' with i=1

*** 1 failure is detected in the test module "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

Code

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

void foo( int value ) {
  BOOST_TEST_CHECKPOINT("Inside foo with value '" << value << "' (should not be there)");
}

BOOST_AUTO_TEST_CASE( test_case )
{
  int* p = 0;

  BOOST_TEST_PASSPOINT();
  ++p;

  BOOST_TEST_PASSPOINT();
  ++p;

  BOOST_TEST_PASSPOINT();
  foo( *p );
}

Output

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

PrevUpHomeNext