BOOST_AUTO_TEST_CASE_EXPECTED_FAILURES(name, n) is used to decorate a test case with an expected failure count of n. It should appear immediately preceding the macro that defines the test case, such as BOOST_AUTO_TEST_CASE or BOOST_FIXTURE_TEST_CASE. It can be used for test cases declared at file scope or within a test suite. This macro should only be used in the most exceptional of circumstances. Unit tests are designed to provide a safety net of regression tests against our code. If we allow tests to stay failing, we are less motivated to correct them.

As a temporary measure, we may wish to annotate certain tests as known failures. The count n is the number of expected failed assertions during the execution of the test case. When using the CHECK level assertions, the total failure count can be larger than one since the test case continues executing past a failed assertion. When using REQUIRE level assertions, the total failure count will only be one as execution of the test case terminates on the first failed assertion.

If CHECK level assertions are used and the number of failures is less than or equal to n, the test runner will return a status code of 0. If the number of failures is greather than n, the test runner will return a status code of 201. If REQUIRE level assertions are used, the number of expected failures can be at most one and the test runner will return a status code of 200 when one failed assertion is found.

BOOST_AUTO_TEST_CASE_EXPECTED_FAILURES(inserts_text_require_expected, 1)
BOOST_AUTO_TEST_CASE(inserts_text_require_expected)
{
    std::ostringstream dest;

    hello_world(dest);

    BOOST_REQUIRE_EQUAL("scooby-doo", dest.str());
}

	Note
	When using the compiler formatted test output, Visual Studio interprets the failed assertion output as a detected error, it will fail the Post-Build event mechanism recommended in Test Case Design and Maintenance.

Example Source Code