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_SKIP(), 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(expression)
Verify an expression in TestSuite::Tester subclass.
#define CORRADE_COMPARE(actual, expected)
Compare two values in TestSuite::Tester subclass.
#define CORRADE_COMPARE_AS(actual, expected, Type...)
Compare two values in TestSuite::Tester subclass with explicitly specified type.
#define CORRADE_COMPARE_WITH(actual, expected, comparatorInstance)
Compare two values in TestSuite::Tester subclass with explicitly specified comparator.
#define CORRADE_EXPECT_FAIL(message)
Expect failure in all following checks in the same scope.
#define CORRADE_EXPECT_FAIL_IF(condition, message)
Conditionally expect failure in all following checks in the same scope.
#define CORRADE_SKIP(message)
Skip test case.
#define CORRADE_BENCHMARK(batchSize)
Run a benchmark.

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(expression)

Verify an expression in TestSuite::Tester subclass.

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:

std::unique_ptr<int> i{new int};
CORRADE_VERIFY(i);

#define CORRADE_COMPARE(actual, expected)

Compare two values in TestSuite::Tester subclass.

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 given type implements equality comparison operators and is printable via Utility::Debug.

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

Compare two values in TestSuite::Tester subclass with explicitly specified type.

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);

See also TestSuite::Comparator class documentation for example of more involved comparisons.

Note that this macro is usable only if the type passed to it is printable via Utility::Debug and is convertible to / usable with given comparator type.

#define CORRADE_COMPARE_WITH(actual, expected, comparatorInstance)

Compare two values in TestSuite::Tester subclass with explicitly specified comparator.

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

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

See TestSuite::Comparator class documentation for more information.

Note that this macro is usable only if the type passed to it is printable via Utility::Debug and is usable with given comparator type.

#define CORRADE_EXPECT_FAIL(message)

Expect failure in all following checks in the same scope.

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

Expects failure in all following CORRADE_VERIFY(), CORRADE_COMPARE() and CORRADE_COMPARE_AS() checks in the same scope. In most cases it will be until the end of the function, but you can limit the scope by placing relevant checks in a separate block:

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

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

If any of the following checks passes, an error will be printed to output.

#define CORRADE_EXPECT_FAIL_IF(condition, message)

Conditionally expect failure 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 into output as indication of 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 !!).

#define CORRADE_SKIP(message)

Skip test case.

Parameters
message Message which will be printed into output as indication of 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.");
}

#define CORRADE_BENCHMARK(batchSize)

Run a benchmark.

Benchmarks the following block or expression by measuring batchSize iterations of given block. Use in conjunction with TestSuite::Tester::addBenchmarks() and others. 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.