assertions

Macros for expectations and assertions. More...

Collaboration diagram for assertions:

Macros
#define	FAIL()
	Unconditionally fail the current test fatally.
#define	ADD_FAILURE()
	Unconditionally add a failure.
#define	ADD_FAILURE_AT(file, line)
	Unconditionally add a failure with custom filename and line number.
#define	SCOPED_TRACE()
	Add scope information to failure reports. More...
#define	EXPECT_TRUE(condition)
	Condition evaluates to true.
#define	EXPECT_FALSE(condition)
	Condition evaluates to false.
#define	EXPECT_NEAR(val1, val2, abs_error)
	Distance between val1 and val2 is less than or equal to abs_error.
#define	EXPECT_EQ(val1, val2)
	Equality. (val1 == val2) More...
#define	EXPECT_NE(val1, val2)
	Inequality. (val1 != val2)
#define	EXPECT_LE(val1, val2)
	Less than or equal. (val1 <= val2)
#define	EXPECT_LT(val1, val2)
	Less than. (val1 < val2)
#define	EXPECT_GE(val1, val2)
	Greater than or equal. (val1 >= val2)
#define	EXPECT_GT(val1, val2)
	Greater than. (val1 > val2)
#define	EXPECT_PRED1(pred, v1)
	Use a predicate function which returns a bool. More...
#define	EXPECT_PRED_FORMAT1(pred_format, v1)
	Use a predicate function which returns an AssertionResult. More...
#define	EXPECT_NO_FATAL_FAILURE(statement)
	Tests that statement doesn't add any new fatal failures. More...
#define	EXPECT_THROW(statement, expected_exception)
	The statement must throw an exception of expected_exception type.
#define	EXPECT_ANY_THROW(statement)
	The statement must throw an exception of any type.
#define	EXPECT_NO_THROW(statement)
	The statement must not throw any exception.

Functions
AssertionResult	AssertionFailure ()
	Constructs a failure message that implicitly converts to bool. More...
AssertionResult	AssertionSuccess ()
	Opposite of AssertionFailure().

Detailed Description

Macros for expectations and assertions.

Every EXPECT macro has a matching ASSERT macro. The difference is whether or not to continue testing the current unit. For example, EXPECT_TRUE(true) reports a failure and continues while ASSERT_TRUE(false) reports a failure and terminates the current test unit. Typically, EXPECT will provide the most information for debugging, but ASSERT is better when subsequent failures would add useless clutter or confusion to the test report.

It is important to consider that ASSERT failures terminate a test by returning from the current function. Any functions containing an ASSERT must be declared with a return type of void or you will get a compiler error. If the ASSERT is in a function called by your test, the test will not stop running, only the current function. This is behavior you can depend on, for example, to ensure any cleanup is run to prevent resource leaks. However, test fixtures are usually a better way to handle initialization and cleanup.

All macros allow appending of extra information to the failure report. This can be very helpful to someone trying to fix a failing test. The PrintTo() formatters are used for appending values.

TEST(MyTestCase, MyTestName){
    EXPECT_EQ(6, 2*3) << "Compiler is failing to do basic math.";
    std::array<int, 4> a;
    for (int i=0; i<4; ++i) {
        ASSERT_EQ(0, a[i]) << "Array was not checked past index " << i << ".";
    }
}

Macro Definition Documentation

#define SCOPED_TRACE

(

)

Add scope information to failure reports.

Your tests may be implemented in a way that makes it difficult to determine where a failure has occurred. For example, you may be calling a subroutine multiple times in the same test. Using SCOPED_TRACE is a fast way to add helpful information.

TEST(ThisThat, OtherThing) {
    {
        SCOPED_TRACE() << "Check 1";  // The message "Check 1" will appear
        check(1);                     // on failures in this scope.
    }
    // Leaving scope, no more extra message.
    check(2);
}

#define EXPECT_EQ	(		val1,
			val2
	)

Equality. (val1 == val2)

A special case is triggered when both values are the same type of floating point. In this case the values are equal if they are within 4 ULPs (at 1.0). Complex numbers of the same floating point type are also compared this way. This is ideal for DSP values which typically range from -1...1. Consider using EXPECT_NEAR if you are working with significantly smaller or larger numbers.

#define EXPECT_PRED1	(		pred,
			v1
	)

Use a predicate function which returns a bool.

Also available are EXPECT_PRED2(pred, v1, v2) and EXPECT_PRED3(pred, v1, v2, v3).

If you have a function that returns true or false, or any value that can be implicitly converted to bool, this will print its arguments for free.

int HasCommonDenominatorGT1(int x, int y) {
    if (y == 0) return x;
    if (y == 1) return 0;
    return HasCommonDenominatorGT1(y, x%y);
}

TEST(Numbers, Denominator){
    EXPECT_PRED2(HasCommonDenominatorGT1, 100, 20);
}

#define EXPECT_PRED_FORMAT1	(		pred_format,
			v1
	)

Use a predicate function which returns an AssertionResult.

Also available are EXPECT_PRED_FORMAT2(pred_format, v1, v2) and EXPECT_PRED_FORMAT3(pred_format, v1, v2, v3).

The most flexibility for generating failure messages comes from defining predicate functions that return AssertionSuccess() or AssertionFailure(). In fact, most of the EXPECT|ASSERT macros are implemented this way.

For each variable, the predicate function is passed a text string of the expression and the evaluated result. You may use value types or reference types for the result parameters.

int HasCommonDenominatorGT1(int x, int y) {
    if (y == 0) return x;
    if (y == 1) return 0;
    return HasCommonDenominatorGT1(y, x%y);
}

testing::AssertionResult AssertCommonDenominator(
        const char* x_expr, const char* y_expr, int x, int y) {
   if (HasCommonDenominatorGT1(x,y)) return testing::AssertionSuccess();
   return ::testing::AssertionFailure()
       << x_expr << " and " << y_expr << " (" << x << " and " << y
       << ") have no common divisor as determined by HasCommonDenominatorGT1(x,y)."
}

TEST(Numbers, Denominator){
    EXPECT_PRED_FORMAT2(AssertCommonDenominator, 99, 20);
}

#define EXPECT_NO_FATAL_FAILURE

(

statement

)

Tests that statement doesn't add any new fatal failures.

When a function terminates on a fatal (ASSERT) failure the caller will continue to run when it returns. You can stop the test with ASSERT_NO_FATAL_FAILURE or use EXPECT_NO_FATAL_FAILURE to provide more information.

TEST(FooBar, SubRoutines) {
    ASSERT_NO_FATAL_FAILURE(Foo());
    EXPECT_NO_FATAL_FAILURE({
        Bar();
    }) << "More information";
}

Function Documentation

AssertionResult AssertionFailure ( )

inline

Constructs a failure message that implicitly converts to bool.

If you build a function that returns true or false to indicate passing or failing status, you can instead return AssertionFailure() or AssertionSuccess() with additional information.

testing::AssertionResult IsEven(int n) {
    if ((n % 2) == 0)
        return ::testing::AssertionSuccess() << n << " is even";
    else
        return ::testing::AssertionFailure() << n << " is odd";
}

TEST(Numbers, IsEven){
    EXPECT_TRUE(IsEven(4));
    EXPECT_FALSE(IsEven(5));
}