UT (μt)

You can provide a custom printer by inheriting from ut::printer and overloading the operator<<. This is useful for redirecting output to different streams like std::cerr or custom logging frameworks.

namespace ut = boost::ut;

namespace cfg {
struct printer : ut::printer {
  template <class T>
  auto& operator<<(T&& t) {
    std::cerr << std::forward<T>(t);
    return *this;
  };
};
}

template <> auto ut::cfg<ut::override> = ut::runner<ut::reporter<cfg::printer>>{};

UT is designed around a few core abstractions that compose to form a test runner:

1. _test Literal: Creates a test object containing a name and a function.
2. test Object: When assigned a function via operator=, it executes that function.
3. expect: Evaluates an expression. It uses std::source_location to report exactly where a failure occurred.
4. suite: A container that executes a collection of tests.
5. Operators & _i: To allow expect to work with complex expressions (like ==) while maintaining type safety and performance, UT uses integral constant objects (created via _i) to overload comparison operators.

You can override the default test runner by specializing ut::cfg<ut::override>. The runner handles events such as test execution, skipping, assertions, and logging. Implement the on method for the specific events you wish to intercept.

namespace ut = boost::ut;

namespace cfg {
  class runner {
   public:
    template <class... Ts> auto on(ut::events::test<Ts...> test) { test(); }
    template <class... Ts> auto on(ut::events::skip<Ts...>) {}
    template <class TExpr> auto on(ut::events::assertion<TExpr>) -> bool { return true; }
    auto on(ut::events::fatal_assertion) {}
    template <class TMsg> auto on(ut::events::log<TMsg>) {}
  };
}

template<> auto ut::cfg<ut::override> = cfg::runner{};

The primary way to perform assertions in UT is using the expect() function.

By default, expect(condition) will report a failure if the condition is false but allow the test to continue. To make an assertion fatal (terminating the test immediately upon failure), wrap the condition in fatal().

To ensure that failed expressions are printed clearly in the output (e.g., 1 == 2 instead of just false), use the User Defined Literal (UDL) _i for integer constants. This allows UT to override comparison operators and prevents accidental type mismatches.

#include <boost/ut.hpp>

int main() {
    using namespace boost::ut;

    // Standard assertion
    expect(1_i == 2);

    // Fatal assertion (stops execution on failure)
    expect(fatal(1 == 2_i));
    expect(1_i == 2); // This line will not be executed if the previous one fails
}

UT provides a log utility for printing information during test execution.

• Stream-based logging: Use boost::ut::log << ... for standard stream output.
• Formatting-based logging: If using C++20 with std::format support, you can use boost::ut::log("format string", args...) for more advanced formatting.

#include <boost/ut.hpp>

int main() {
    using namespace boost::ut;

// Stream logging
"logging"_test = [] {
        boost::ut::log << "pre";
        expect(42_i == 43) << "message on failure";
        boost::ut::log << "post";
    };

// Formatting logging (C++20)
"logging_format"_test = [] {
        boost::ut::log("\npre  {} == {}", 42, 43);
        expect(42_i == 43) << "message on failure";
        boost::ut::log("\npost {} == {} -> {}", 42, 43, 42 == 43);
    };
}

UT is a single-header or single-module C++20 unit testing framework. You can integrate it using several methods:

1. Manual Integration

Download the latest boost/ut.hpp (header) or boost/ut.cppm (module) and include/import it in your project.

2. CMake Integration

If you have installed UT via CMake, use find_package to import the Boost::ut target. Linking against this target automatically handles include directories.

3. Conan Integration

The boost-ext-ut package is available on Conan Center. Add boost-ext-ut/2.3.1 to your conanfile.

4. Build and Install from Source

cmake -Bbuild -H.
cd build && make         # run tests
cd build && make install # install

find_package(ut REQUIRED)
add_library(my_test my_test.cpp)
target_link_libraries(my_test PRIVATE Boost::ut)

You can group tests into named suites by defining a lambda in a specific namespace or variable. This is useful for separating error-handling tests or specific module tests.

#include <boost/ut.hpp>

namespace ut = boost::ut;

ut::suite errors = [] {
    using namespace ut;

"throws"_test = [] {
        expect(throws([] { throw 0; }));
    };
    "doesn't throw"_test = [] {
        expect(nothrow([] {}));
    };
};

int main() {}

UT supports BDD style testing using given, when, and then blocks to describe test scenarios clearly.

#include <boost/ut.hpp>

int main() {
    using namespace boost::ut;
    using namespace boost::ut::bdd;

"scenario"_test = [] {
        given("I have...") = [] {
            when("I run...") = [] {
                then("I expect 1...") = [] { expect(1_i == 1); };
                then("I expect 2...") = [] { expect(1 == 1_i); };
            };
        };
    };
}