Corrade/TestSuite/Tester.h file

#define CORRADE_TEST_MAIN(Class)

Create main() function for given TestSuite::Tester subclass.

Populates TestSuite::Tester::arguments(), instantiates Class, executes the test cases and returns from main() with code based on the test results. This macro has to be used outside of any namespace.

#define CORRADE_VERIFY(...)

Verify an expression in a test case.

If the expression is not true, the expression is printed and execution of given test case is terminated. Example usage:

Containers::StringView s = "hello";
CORRADE_VERIFY(!s.isEmpty());

It is possible to use CORRADE_VERIFY() also on objects with explicit operator bool() without doing explicit conversion (e.g. using !!), for example:

Containers::Pointer<int> i{new int};
CORRADE_VERIFY(i);

This macro is meant to be called in a test case in a TestSuite::Tester subclass. It's possible to also call it in a helper function or lambda called from inside a test case, however note that the very first call to a CORRADE_*() macro captures the caller function name for the test output, which may not be desired when being in a helper function or a lambda. To circumvent that, either call a dummy CORRADE_VERIFY(true) at the top of your test case, or explicitly call setTestCaseName() with either a hardcoded name or e.g. CORRADE_FUNCTION.

#define CORRADE_COMPARE(actual, expected)

Compare two values in a test case.

If the values are not the same, they are printed for comparison and execution of given test case is terminated. Example usage:

int a = 5 + 3;
CORRADE_COMPARE(a, 8);

Comparison of floating-point types is by default done as a fuzzy-compare, see TestSuite::Comparator<float> and TestSuite::Comparator<double> for details.

Note that this macro is usable only if the type passed to it is printable via Utility::Debug. It is meant to be called in a test case in a TestSuite::Tester subclass. It's possible to also call it in a helper function or lambda called from inside a test case with some caveats. See CORRADE_VERIFY() for details.

#define CORRADE_COMPARE_AS(actual, expected, ...)

Compare two values in a test case with explicitly specified type.

Casts the values to a specified typ first and then continues the same as CORRADE_COMPARE(). If the values are not the same, they are printed for comparison and execution of given test case is terminated. Example usage:

CORRADE_COMPARE_AS(std::sin(0.0), 0.0f, float);

Note that this macro is usable only if the type passed to it is printable via Utility::Debug and is convertible to given type. CORRADE_COMPARE_AS() and CORRADE_COMPARE_WITH() can be also used for advanced comparisons with custom comparators, see Advanced comparisons for more information.

This macro is meant to be called in a test case in a TestSuite::Tester subclass. It's possible to also call it in a helper function or lambda called from inside a test case with some caveats. See CORRADE_VERIFY() for details.

#define CORRADE_COMPARE_WITH(actual, expected, comparatorInstance)

Compare two values in a test case with explicitly specified comparator.

A variant of CORRADE_COMPARE_AS() that takes a comparator instance instead of type, useful when you need to pass additional parameters to the comparator. See Advanced comparisons for a high-level introduction and an example. If the comparison fails, a comparator-specific diagnostic is printed and execution of given test case is terminated. Example usage:

CORRADE_COMPARE_WITH("actual.txt", "expected.txt",
    TestSuite::Compare::File{"/common/path/prefix"});

Note that this macro is usable only if the type passed to it is compatible with given comparator, and in some cases the comparator may require the type to also be printable with Utility::Debug.

This macro is meant to be called in a test case in a TestSuite::Tester subclass. It's possible to also call it in a helper function or lambda called from inside a test case with some caveats. See CORRADE_VERIFY() for details.

#define CORRADE_EXPECT_FAIL(message)

Expect failure in a test case in all following checks in the same scope.

Expects a failure in all following CORRADE_VERIFY(), CORRADE_COMPARE(), CORRADE_COMPARE_AS(), CORRADE_COMPARE_WITH() and CORRADE_FAIL_IF() checks in the same scope. Implicitly it will be until the end of the function, but you can limit the scope by placing relevant checks in a separate block. If any check following the macro in the same scope passes, an error will be printed to the output.

{
    CORRADE_EXPECT_FAIL("Not implemented.");
    CORRADE_VERIFY(isFutureClear());
}

int i = 6*7;
CORRADE_COMPARE(i, 42);

The message can be formatted in the same way as in CORRADE_ASSERT(), including stream output operators.

This macro is meant to be called in a test case in a TestSuite::Tester subclass. It's possible to also call it in a helper function or lambda called from inside a test case with some caveats. See CORRADE_VERIFY() for details.

#define CORRADE_EXPECT_FAIL_IF(condition, message)

Conditionally expect failure in a test case in all following checks in the same scope.

With CORRADE_EXPECT_FAIL() it's not possible to write code such as this, because the scope of expected failure will end at the end of the if block:

{
    if(answer != 42)
        CORRADE_EXPECT_FAIL("This is not our universe.");

    CORRADE_COMPARE(6*9, 42); // always fails
}

The solution is to use CORRADE_EXPECT_FAIL_IF():

{
    CORRADE_EXPECT_FAIL_IF(answer != 42, "This is not our universe.");

    CORRADE_COMPARE(6*7, 49); // expect the failure if answer is not 42
}

Similarly to CORRADE_VERIFY(), it is possible to use CORRADE_EXPECT_FAIL_IF() also on objects with explicit operator bool without doing explicit conversion (e.g. using !!).

The message can be formatted in the same way as in CORRADE_ASSERT(), including stream output operators.

This macro is meant to be called in a test case in a TestSuite::Tester subclass. It's possible to also call it in a helper function or lambda called from inside a test case with some caveats. See CORRADE_VERIFY() for details.

#define CORRADE_INFO(...) new in Git master

Print an info message.

Compared to using Utility::Debug directly, the message will be prefixed with INFO, test case name and file/line info to be clear where the message comes from. This then replaces the usual OK, which isn't printed to avoid redundancy in the output. The message can be formatted in the same way as in CORRADE_ASSERT(), including stream output operators:

CORRADE_INFO("The calculated delta is" << delta);

This macro is meant to be called in a test case in a TestSuite::Tester subclass. It's possible to also call it in a helper function or lambda called from inside a test case with some caveats. See CORRADE_VERIFY() for details.

#define CORRADE_WARN(...) new in Git master

Print a warning message.

Like CORRADE_INFO(), but prefixes the output with WARN instead, replacing the usual OK message as well. A warning has no effect on the test result and doesn't end execution of the test case either. The message can be formatted in the same way as in CORRADE_ASSERT(), including stream output operators:

if(delta > 0.05f)
    CORRADE_WARN("The delta" << delta << "is higher than ideal");

CORRADE_VERIFY(delta < 0.1f);

This macro is meant to be called in a test case in a TestSuite::Tester subclass. It's possible to also call it in a helper function or lambda called from inside a test case with some caveats. See CORRADE_VERIFY() for details.

#define CORRADE_FAIL(...) new in Git master

Explicitly fail a test case.

Useful for example to test a particular #define, in which case there's no expression or value to pass to CORRADE_VERIFY() / CORRADE_COMPARE(); or to check that given code path is never reached.

#ifdef CORRADE_TARGET_BIG_ENDIAN
CORRADE_FAIL("The test assumes Big Endian is extinct.");
#endif

union {
    char fourcc[4];
    int value;
} data{{'D', 'I', 'V', 'X'}};

CORRADE_COMPARE(data.value, 0x58564944);

Even though the failure is unconditional, the test case can still continue execution when combined with CORRADE_EXPECT_FAIL() / CORRADE_EXPECT_FAIL_IF(). Such behavior is thus different from CORRADE_ASSERT_UNREACHABLE(), where the macro also tells the compiler the code following it will never be executed, allowing to omit return statements among other things.

The message is prefixed with FAIL including a file and line where the failure happened and execution of given test case is terminated. The message can be formatted in the same way as in CORRADE_ASSERT(), including stream output operators. Note that, however, it isn't meant to be used as the single verification macro in a test case:

void test() {
    …

    if(answer != 42) {
        CORRADE_FAIL("Answer to the Ultimate Question of Life, the Universe, "
            "and Everything is" << answer);
    }

    // Wrong, if the answer is 42, the test case is reported as not having any
    // checks
}

In such a case, CORRADE_FAIL_IF() should be used to ensure it's always reached when running the test:

CORRADE_FAIL_IF(answer != 42, "Answer to the Ultimate Question of Life, the "
    "Universe, and Everything is" << answer);

This macro is meant to be called in a test case in a TestSuite::Tester subclass. It's possible to also call it in a helper function or lambda called from inside a test case with some caveats. See CORRADE_VERIFY() for details.

#define CORRADE_FAIL_IF(condition, message) new in Git master

Explicitly fail a test case if a condition is true.

Useful when the implicit failure diagnostic from CORRADE_VERIFY() or CORRADE_COMPARE() isn't descriptive enough. The message is prefixed with FAIL including a file and line where the failure happened and execution of given test case is terminated. The message can be formatted in the same way as in CORRADE_ASSERT(), including stream output operators:

CORRADE_FAIL_IF(answer != 42, "Answer to the Ultimate Question of Life, the "
    "Universe, and Everything is" << answer);

This macro is meant to be called in a test case in a TestSuite::Tester subclass. It's possible to also call it in a helper function or lambda called from inside a test case with some caveats. See CORRADE_VERIFY() for details.

#define CORRADE_SKIP(...)

Skip a test case.

Skips all following checks in given test case, printing a SKIP in the output. Useful for e.g. indicating that given feature can't be tested on given platform:

if(!bigEndian) {
    CORRADE_SKIP("Big endian compatibility can't be tested on this system.");
}

The message can be formatted in the same way as in CORRADE_ASSERT(), including stream output operators.

This macro is meant to be called in a test case in a TestSuite::Tester subclass. It's possible to also call it in a helper function or lambda called from inside a test case with some caveats. See CORRADE_VERIFY() for details.

#define CORRADE_SKIP_IF_NO_ASSERT() new in Git master

Skip a test case if Corrade asserts are disabled.

If CORRADE_NO_ASSERT or CORRADE_STANDARD_ASSERT is defined, expands to a CORRADE_SKIP() call. Otherwise expands to do {} while(false). To be used in test cases that verify CORRADE_ASSERT() and other assertion macros and which would misbehave or crash if asserts are compiled out or use the standard assertion macro which doesn't contain the custom message and is unaffected by CORRADE_GRACEFUL_ASSERT. Use CORRADE_SKIP_IF_NO_DEBUG_ASSERT() for testing CORRADE_DEBUG_ASSERT() and other debug assertion macros.

This macro is meant to be called in a test case in a TestSuite::Tester subclass. It's possible to also call it in a helper function or lambda called from inside a test case with some caveats. See CORRADE_VERIFY() for details.

#define CORRADE_SKIP_IF_NO_DEBUG_ASSERT() new in Git master

Skip a test case if Corrade debug asserts are disabled.

If CORRADE_NO_DEBUG_ASSERT or CORRADE_STANDARD_ASSERT is defined, expands to a CORRADE_SKIP() call. Otherwise expands to do {} while(false). To be used in test cases that verify CORRADE_DEBUG_ASSERT() and other assertion macros and which would misbehave or crash if asserts are compiled out or use the standard assertion macro which doesn't contain the custom message and is unaffected by CORRADE_GRACEFUL_ASSERT. Use CORRADE_SKIP_IF_NO_ASSERT() for testing CORRADE_ASSERT() and other assertion macros.

This macro is meant to be called in a test case in a TestSuite::Tester subclass. It's possible to also call it in a helper function or lambda called from inside a test case with some caveats. See CORRADE_VERIFY() for details.

#define CORRADE_ITERATION(...) new in 2020.06

Annotate an iteration in a test case.

Annotates loop iterations in order to provide clearer failure diagnostics next to the file/line info. Doesn't print anything if there was no failure. Applies to all following CORRADE_VERIFY(), CORRADE_COMPARE() etc. checks in the same scope, multiple calls in the same scope (or nested scopes) are joined together. See Testing in a loop for an example.

The value can be formatted in the same way as in CORRADE_ASSERT(), including stream output operators.

This macro is meant to be called in a test case in a TestSuite::Tester subclass. It's possible to also call it in a helper function or lambda called from inside a test case with some caveats. See CORRADE_VERIFY() for details.

#define CORRADE_BENCHMARK(batchSize)

Run a benchmark in a test case.

Benchmarks the following block or expression by measuring batchSize iterations of given block. Desired use is in conjunction with TestSuite::Tester::addBenchmarks() and friends, see Benchmarks for an introduction and an example. Only one such loop can be in a function to achieve proper result. Please note that there need to be additional measures in order to prevent the optimizer from removing the benchmark code such as assigning to a volatile variable or combining all the results to a variable, which is then being used outside of the loop.

void benchmark() {
    Containers::StringView a = "hello", b = "world";
    CORRADE_BENCHMARK(1000) {
        volatile Containers::String c = a + b;
    }
}

The resulting measured value is divided by batchSize to represent cost of one iteration.

This macro is meant to be called in a test case in a TestSuite::Tester subclass. It's possible to also call it in a helper function or lambda called from inside a test case with some caveats. See CORRADE_VERIFY() for details.