CaraTest

Description

Very basic test framework that I made for Caracal, because QTest didn't support printing the combined results of multiple TestSuits without ugly hacks.

Features

• Combined result of multiple test suits
• Snapshot tests
• Snapshot tool for accepting or rejecting snapshots
• Parameterized tests
• Pretty console output (currently only works on Windows)

Usage

To use CaraTest, you need to include the CaraTest.h header file in your project. The library is designed to be used with C++ and provides a simple interface for defining and running tests.

#include "CaraTest.h"

Helper Functions

CaraTest provides a set of helper functions to make it easier to define and run tests.

CaraTest::getSuite

CaraTest::getSuite("suiteName");

Creates or retrieves a test suite with the given name. If a suite with the specified name does not exist, a new one is created and registered.

CaraTest::getSuite();

Creates or retrieves a test suite with the source location. If the function is called in a global scope, the file name is used as the suite name, otherwise the function name is used.

CaraTest::addTest

CaraTest::addTest("testName", testFunction);

This function lets you define a test with a custom name. The second parameter, testFunction, is a callable (like a lambda or function pointer) that contains the test logic to be executed.

CaraTest::addTest("testName", testFunction, testFunction_Data);

This function lets you define a parameter test with a custom name. The second parameter, testFunction, is a callable (like a lambda or function pointer) that contains the test logic to be executed. The third parameter, testFunction_Data, is a collection of data that will be passed to the test function.

CaraTest::addTest(testFunction);

This function lets you define a test using the name of the source file as the test name. testFunction is a callable (like a lambda or function pointer) that contains the test logic to be executed.

CaraTest::addTest(testFunction, testFunction_Data);

This function lets you define a parameter test using the name of the source file as the test name. testFunction is a callable (like a lambda or function pointer) that contains the test logic to be executed. The second parameter, testFunction_Data, is a collection of data that will be passed to the test function.

CaraTest::runAll

int CaraTest::runAll(argc, argv);

Runs all the tests that have been created and registered with CaraTest::getSuite or CaraTest::addTest.

Test Functions

CaraTest provides a set of functions for verifying conditions in your unit tests. When a test fails, these functions generate a detailed error message, including the source code location (using std::source_location).

Fail

CaraTest::fail();

CaraTest provides a set of functions for verifying conditions in your unit tests. When a test fails, these functions generate a detailed error message, including the source code location (using std::source_location).

Skip

CaraTest::skip();

Skips the execution of the current test.

IsTrue

CaraTest::isTrue(value);

Checks if the given value is true. If the value is false, the test fails.

IsFalse

CaraTest::isFalse(value);

Checks if the given value is false. If the value is true, the test fails.

AreEqual

CaraTest::areEqual(expected, actual);

Checks if the expected value is equal to the actual value. If they are not equal, the test fails and an error message is generated.

EqualsFile

CaraTest::areEqual(snapshotFilePath, actual);

Checks if the contents of the file at snapshotFilePath are equal to the actual value. If they are not equal, the test fails and a .snapshot file is generated.

Macro

CARATEST_DEBUG_BREAK_ON_PARTIAL_MATCH(firstValue, secondValue);

This macro is used to trigger a debug break when the first value matches the second value. It is useful for debugging tests where you want to inspect the values at a specific point in the code.

stringify

The error messages generated by CaraTest are automatically stringified using the CaraTest::stringify function. For example, if you pass a bool to the areEqual function, it will be automatically converted to a string representation. To support custom types, you can implement the stringify function for your type.

enum class TokenKind
{
    Plus,
    Minus,
    ...
};

std::string stringify(TokenKind kind)
{
    switch (kind)
    {
        case TokenKind::Plus:
            return std::string("Plus");
        case TokenKind::Minus:
            return std::string("Minus");
        ...
    }
}

Make sure to include the header where you define the stringify function in your test file, so that CaraTest can find it when generating error messages. The following types are already supported by CaraTest:

• bool
• int
• long long
• const char*
• QString
• QStringView
• std::string
• std::chrono::nanoseconds
• std::tuple

Snapshot tool

CaraTestSnapshotTool can be used to accept or reject snapshots. The tool uses a file watcher to automatically update the list of snapshots when files are added or removed. For the tool to work, you need to have to select the directory where the snapshots are generated. The tool will then show all snapshots in that directory, allowing you to choose to accept or reject each snapshot.

Commandline parameters

The library currently has 2 commandline parameters to make debugging tests easier.

• break_on_fail

This parameter triggers a debug break inside the AreEqual function. This allows us to inspect the parameters and we can go up the callstack into the failing test.

• break_and_rerun_on_fail

This parameter triggers a debug break in the catch statement of the failed function and runs the test again. This allows us to step through the whole test again.