kaycxx-test

C++ unit test framework with hierarchical suites, lifecycle hooks, skipping, test filtering, and CTest discovery.

GitHub | API Documentation

Requirements

• C++23 compiler and standard library
• Exception support
• Run-time type information (RTTI)

Usage

Tests are declared with one top-level suite, nested describe blocks, and it test cases. The linked test library provides main() and runs every registered suite.

#include <kaycxx/test.hpp>

using namespace kaycxx::test;

suite("calculator") {
    describe("addition", [] {
        it("adds positive numbers", [] {
            assert_equal(2 + 3, 5);
        });

        it("adds negative numbers", [] {
            assert_equal(-2 + -3, -5);
        });
    });
}

The assertion functions are part of kaycxx::test and are included by <kaycxx/test.hpp>. Tests can also use another exception-based assertion library. An exception that leaves a test body is reported as a failed test, while kaycxx::test::assertion_error additionally preserves rendered actual and expected values and remains a normal reported failure in break-on-exception mode.

CMake users consume the installed package with:

find_package(kaycxx-test 0.3.2 CONFIG REQUIRED)

add_executable(my-project-tests
    test/calculator.test.cpp
)
target_link_libraries(my-project-tests PRIVATE
    my-project
    kaycxx::test
)

No separate main.cpp is needed for the test executable.

Non-CMake users can use pkg-config:

c++ -std=c++23 test/calculator.test.cpp $(pkg-config --cflags --libs kaycxx-test) -o my-project-tests

Assertions

Assertions are ordinary functions which throw assertion_error when their condition is not met.

Assertions record their source locations automatically.

• assert_true and assert_false check boolean values.
• assert_equal and assert_not_equal compare values for equality.
• assert_greater, assert_greater_or_equal, assert_less, and assert_less_or_equal compare ordered values.
• assert_null and assert_not_null check nullable values.
• assert_match and assert_not_match check strings against regular expressions.
• assert_close and assert_not_close compare numeric values at a selected precision.
• assert_contain and assert_not_contain check strings and ranges for contained values.
• assert_throw and assert_not_throw check exceptions.

Custom Assertions

An assertion library which only needs to report structured failures can depend on the header target and throw assertion_error:

find_package(kaycxx-test 0.3.2 CONFIG REQUIRED)
target_link_libraries(my-assertions PUBLIC kaycxx::test-headers)

The corresponding pkg-config package is kaycxx-test-headers and provides compiler flags without linker flags.

#include <source_location>
#include <string>

#include <kaycxx/test/assertion_error.hpp>

void assert_positive(int value, std::source_location location = std::source_location::current()) {
    if (value <= 0) {
        throw kaycxx::test::assertion_error{
            "Expected value to be positive",
            {},
            std::to_string(value),
            "positive",
            location
        };
    }
}

kaycxx::test-headers provides headers and compile requirements without linking libkaycxx-test.a. An assertion library using the built-in assertion functions also uses compiled formatting helpers and must link to kaycxx::test instead.

Example Output

Running the test executable produces a hierarchical report. The test framework adds colors automatically when the output is connected to a supported terminal.

When both tests pass:

If addition incorrectly returns 5 instead of -5 for the negative numbers:

Guides

• Writing Tests explains suite, describe, it, registration order, dynamic test generation, and callback lifetimes.
• Hooks and State explains setup and teardown hooks, inherited hook order, shared state, and hook failures.
• Skipping Tests explains unconditional and dynamic skip conditions.
• Running and Filtering explains command-line filters, regular expressions, output, and exit codes.
• CMake and CTest explains test executables, the standard test target, and per-test CTest discovery.

Build From Source

cmake --preset release
cmake --build --preset release

kaycxx-test is always built as a static library because it supplies the test executable's main() function.

Install

cmake --install build/release --prefix /tmp/root

If no prefix is specified, CMake installs to /usr/local by default on Unix systems.

Development

Run all tests:

cmake --preset debug
cmake --build --preset debug --target test

Generate API documentation with Doxygen:

cmake --build --preset debug --target apidoc

The generated HTML documentation is written to build/debug/apidoc/html/index.html.