Time-out for test cases

The Unit Test Framework provides the decorator timeout that specifies a time-out for a specific test unit. The argument time is always expressed in seconds ans wall-clock time.

For test-cases, the time-out value sets the maximum allowed duration for the test. If this time is exceeded, the test case is reported as failed. On some systems, the Unit Test Framework is able to force the test-case to stop through a SIGALRM signal (see below).

For test-suites, the time-out value sets the maximum allowed duration for the entire suite to complete. This duration is the accumulated time of all the test-cases contained in the sub-tree rooted on the test-suite, plus some extra execution time needed by the Unit Test Framework. For each test-units under a test-suite with time-out, the maximum allowed duration is set as being the test-suite time out minus the accumulated execution time before the execution of the test-unit. If this test-unit is a test-case, it is equivalent to setting the decorator timeout to the test-case with a time-out value expressed as before.

In case the test-suite times out, the suite is flagged as timed-out and failed, and all the test units (suites and cases) that have not been executed up to the time-out point are all skipped.

Example: decorator timeout

Code
#define BOOST_TEST_MODULE decorator_11 #include <boost/test/included/unit_test.hpp> namespace utf = boost::unit_test; BOOST_AUTO_TEST_CASE(test1, * utf::timeout(2)) { #ifdef BOOST_SIGACTION_BASED_SIGNAL_HANDLING for(;;) {} BOOST_TEST(true); #else BOOST_TEST(false); #endif }

Code

#define BOOST_TEST_MODULE decorator_11
#include <boost/test/included/unit_test.hpp>
namespace utf = boost::unit_test;

BOOST_AUTO_TEST_CASE(test1, * utf::timeout(2))
{
#ifdef BOOST_SIGACTION_BASED_SIGNAL_HANDLING
  for(;;) {}
  BOOST_TEST(true);
#else
  BOOST_TEST(false);
#endif
}

Output
> decorator_11 Running 1 test case... unknown location(0): fatal error: in "test1": signal: SIGALRM (timeout while executing function) test.cpp(5): last checkpoint: "test1" entry. *** 1 failures is detected in test module "decorator_11"

Output

> decorator_11
Running 1 test case...
unknown location(0): fatal error: in "test1": signal: SIGALRM (timeout while executing function)
test.cpp(5): last checkpoint: "test1" entry.

*** 1 failures is detected in test module "decorator_11"

	Note
	The macro `BOOST_SIGACTION_BASED_SIGNAL_HANDLING` is defined if Boost.Test is able to force the test-case to stop. This feature is for instance not supported on Windows. The Unit Test Framework will still be able to report the test-case as failed (once the test-case finishes).

	Note
	The support of test suite level time-out has been added in Boost 1.70 / Unit Test Framework v3.10