Corrade/TestSuite/Tester.h file

Class Corrade::TestSuite::Tester, macros CORRADE_TEST_MAIN(), CORRADE_VERIFY(), CORRADE_COMPARE(), CORRADE_COMPARE_AS(), CORRADE_COMPARE_WITH(), CORRADE_EXPECT_FAIL(), CORRADE_EXPECT_FAIL_IF(), CORRADE_INFO(), CORRADE_WARN(), CORRADE_FAIL_IF(), CORRADE_SKIP(), CORRADE_ITERATION(), CORRADE_BENCHMARK()

Contents

Namespaces

namespace Corrade
Root namespace.
namespace Corrade::TestSuite
Test suite.

Classes

class Corrade::TestSuite::Tester
Base class for tests and benchmarks.
class Corrade::TestSuite::Tester::TesterConfiguration
Tester configuration.

Defines

#define CORRADE_TEST_MAIN(Class)
Create main() function for given TestSuite::Tester subclass.
#define CORRADE_VERIFY(...)
Verify an expression in a test case.
#define CORRADE_COMPARE(actual, expected)
Compare two values in a test case.
#define CORRADE_COMPARE_AS(actual, expected, ...)
Compare two values in a test case with explicitly specified type.
#define CORRADE_COMPARE_WITH(actual, expected, comparatorInstance)
Compare two values in a test case with explicitly specified comparator.
#define CORRADE_EXPECT_FAIL(message)
Expect failure in a test case in all following checks in the same scope.
#define CORRADE_EXPECT_FAIL_IF(condition, message)
Conditionally expect failure in a test case in all following checks in the same scope.
#define CORRADE_INFO(...) new in Git master
Print an info message.
#define CORRADE_WARN(...) new in Git master
Print a warning message.
#define CORRADE_FAIL_IF(condition, message) new in Git master
Explicitly fail a test case if a condition is false.
#define CORRADE_SKIP(...)
Skip a test case.
#define CORRADE_ITERATION(...) new in 2020.06
Annotate an iteration in a test case.
#define CORRADE_BENCHMARK(batchSize)
Run a benchmark in a test case.

Define documentation

#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.

Parameters
... Expression to verify

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

std::string s("hello");
CORRADE_VERIFY(!s.empty());

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.

Parameters
actual Calculated value
expected Ground truth value

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.

Parameters
actual Calculated value
expected Ground truth value
... Type to compare as

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.

Parameters
actual Calculated value
expected Ground truth value
comparatorInstance Instance of a comparator to compare with

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.

Parameters
message Message which will be printed as an indication of an expected failure

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.

Parameters
condition The failure is expected only if the condition evaluates to true
message Message which will be printed as an indication of an expected failure

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.

Parameters
... Message to print

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.

Parameters
... Warning to print

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_IF(condition, message) new in Git master

Explicitly fail a test case if a condition is false.

Parameters
condition Condition that's expected to evaluate to true
message Failure message which will be printed if the condition is false

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(delta > 0.05f && !extremelyStable,
    "Low precision due to system instability, delta is" << delta);

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_SKIP(...)

Skip a test case.

Parameters
... Message which will be printed as an indication of a skipped test

Skips all following checks in given test case. 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_ITERATION(...) new in 2020.06

Annotate an iteration in a test case.

Parameters
... Value to print in a failure diagnostic

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() {
    std::string a = "hello", b = "world";
    CORRADE_BENCHMARK(1000) {
        volatile std::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.