Tour

Welcome to the C++ Runtime Testing library tour! Here, you can find out how and why you should use this library.

Tests & expectations

The core of the library stands in the "test" and "expect" macros. Here is the most basic example of a test suite you can write using this library:

#include <runtime_testing>

int main() {
    test("This is a passing test!", [&]() {
        expect(1 + 2 == 3);
    });

    test("This is a failing test!", [&]() {
        expect(3 * 3 == 6);
    });

    return runtime_testing::finalizeTesting();
}

There is a lot to see here. First of all, the two main objects that are called: test and expect. They are both macro-s, therefore they belong to no namespace. test is called with two parameters: a std::string that represents the description of the test and a std::function<void()> representing the test function itself. Inside the test function, operations can be executed safely, since possible failure is caught and reported. After executing different operations, you generally want to verify that some state is the way we want it to be. In this case, the expect macro can be called with a single argument (a boolean expression) and the test fails if the expectation fails.

For example, the output for this program is:

base.cpp:5: This is a passing test!: PASSED
base.cpp:9: This is a failing test!: FAILED
	base.cpp:10: 3 * 3 == 6 is false

Process finished with exit code 1

The exit code is 0 if all tests pass, or equal to the number of failed tests if tests failed. Also, the runtime_testing::finalizeTesting() at the end of the test generates a file (by default called report.json) that encapsulates all the information available about this test run. The JSON for the example above looks something like this:

{
  "numTests": 2,
  "numFailedTests": 1,
  "tests": [
    {
      "description": "This is a passing test!",
      "file": "base.cpp",
      "line": 5,
      "passed": true
    },
    {
      "description": "This is a failing test!",
      "file": "base.cpp",
      "line": 9,
      "passed": false,
      "failureMessage": "base.cpp:10: 3 * 3 == 6 is false"
    }
  ]
}