Skip to content
Welcome to the new CppUtils documentation!

Namespace: CppUtils::UnitTest

enum class ComparisonOperator {
Equal,
NotEqual,
LessThan,
LessThanOrEqual,
GreaterThan,
GreaterThanOrEqual
};

Relational comparison operators supported in assertion decomposition.

enum class TestStatus {
Success,
Failure,
Skipped
};

Outcome status of an individual test case execution.

using CppUtils::UnitTest::ComparisonOperatorMapping = Type::Mapping<Type::Pair<ComparisonOperator::Equal, String::Hasher{"=="}>, Type::Pair<ComparisonOperator::NotEqual, String::Hasher{"!="}>, Type::Pair<ComparisonOperator::LessThan, String::Hasher{"<"}>, Type::Pair<ComparisonOperator::LessThanOrEqual, String::Hasher{"<="}>, Type::Pair<ComparisonOperator::GreaterThan, String::Hasher{">"}>, Type::Pair<ComparisonOperator::GreaterThanOrEqual, String::Hasher{">="}>>;

Mapping between ComparisonOperator and its string representation.

using CppUtils::UnitTest::ValueTestSuiteBuilder = ParameterizedTestSuiteBuilder<std::tuple<Values...>>;

Builder for registering a test suite parameterized over a discrete pack of values.

using CppUtils::UnitTest::RangeTestSuiteBuilder = ParameterizedTestSuiteBuilder<Range>;

Builder for registering a test suite parameterized over an input range.

ThrowsMatcher<ExceptionType> CppUtils::UnitTest::throws;

Matcher tag variable template for expecting an exception of type ExceptionType.

NoThrowMatcher CppUtils::UnitTest::noThrow;

Matcher instance asserting that an action completes without throwing any exception.

CrashesMatcher CppUtils::UnitTest::crashes;

Matcher instance asserting that an action terminates abnormally.

EventuallyMatcher CppUtils::UnitTest::eventually;

Matcher instance asserting that a predicate eventually becomes true.

CompletesMatcher CppUtils::UnitTest::completes;

Matcher instance asserting that a future or reactive primitive completes.

auto CppUtils::UnitTest::testRunner;

Global test runner instance used for test suite registration and execution.

std::string_view getComparisonOperatorString(ComparisonOperator comparisonOperator) noexcept;

Converts a ComparisonOperator enumerator to its C++ operator string literal.

ParameterDescription
comparisonOperatorEnumerator value.

Returns: Operator string view (e.g. "==", "<=", "!="), or empty string if invalid.

std::optional<ComparisonOperator> getComparisonOperator(std::string_view operatorString) noexcept;

Parses an operator string literal into its corresponding ComparisonOperator.

ParameterDescription
operatorStringOperator symbol string (e.g. "==", "<=").

Returns: ComparisonOperator wrapped in std::optional, or std::nullopt if unknown.

template <ComparisonOperator Operator>
bool applyOperator(const auto& left, const auto& right);
template <ComparisonOperator Operator>
bool compareFloatingPoint(const auto& left, const auto& right);
template <ComparisonOperator Operator>
bool compareIntegers(const auto& left, const auto& right);
template <ComparisonOperator Operator>
bool evaluateComparison(const auto& left, const auto& right);
template <class OperandType>
ExpectationProxy<OperandType> expect(OperandType&& operand, std::source_location location=std::source_location::current()) noexcept;

Asserts an expectation on a value, condition, or callable.

Supports comparison assertions using relational operators:

expect(value) == expected;
expect(score) >= 100;

standalone boolean conditions:

expect(result.has_value());

and matchers:

expect([&] { divide(1, 0); }) == throws<std::invalid_argument>;
expect([&] { divide(1, 2); }) == noThrow;
ParameterDescription
operandValue to compare, boolean condition, or callable to evaluate.
locationSource location used for failure reporting (automatically captured).

Returns: ExpectationProxy evaluating the expectation.

Deliberately skips the current test, reporting it as skipped in test results.

ParameterDescription
messageJustification for skipping the test.
locationSource location used for skip reporting (automatically captured).
void skipIf(bool condition, std::string message, std::source_location location=std::source_location::current());

Conditionally skips the current test if the provided condition evaluates to true.

ParameterDescription
conditionBoolean flag determining whether to skip.
messageJustification for skipping the test.
locationSource location used for skip reporting (automatically captured).
TestSuiteBuilder testSuite(std::string name);

Declares a test suite.

ParameterDescription
nameDescriptive test suite identifier.

Returns: TestSuiteBuilder used to configure dependencies or assign suite body.

void fail(std::string message="Explicit test failure", std::source_location location=std::source_location::current());

Explicitly fails the current test with a diagnostic message.

ParameterDescription
messageDiagnostic description explaining why the test failed.
locationSource location used for failure reporting (automatically captured).
template <String::Hasher eventName = Type::Hash{}, class... Args, class Emitter>
auto watch(Emitter& emitter);

Creates an RAII EventWatcher to observe emitted events.

Template parameterDescription
eventNameHashed string identifying the event.
ArgsPayload parameter types.
ParameterDescription
emitterEvent emitter instance to subscribe to.

Returns: EventWatcher instance managing event subscription.

BenchmarkResult benchmark(std::string name, Type::Callable auto&& function);

Times the synchronous execution of a callable.

ParameterDescription
nameDiagnostic identifier of the benchmark.
functionCallable to measure.

Returns: BenchmarkResult containing measured duration in nanoseconds.

BenchmarkComparison compareBenchmarks(const BenchmarkResult& first, const BenchmarkResult& second);

Compares two benchmark results, logs their relative speedup, and returns the comparison.

ParameterDescription
firstFirst benchmark result (candidate).
secondSecond benchmark result (baseline).

Returns: BenchmarkComparison structure with speedup and relative performance analysis.

void warnIfSlower(const BenchmarkResult& candidate, const BenchmarkResult& baseline);

Emits a warning log if a candidate benchmark ran slower than a baseline benchmark.

ParameterDescription
candidateBenchmark result being evaluated.
baselineReference benchmark result.
void fuzz(std::string name, std::size_t iterations, Type::Callable<Math::DeterministicRandomEngine &> auto&& function, std::uint64_t seed=Math::DeterministicRandomEngine::defaultSeed, std::source_location location=std::source_location::current());

Executes a fuzz testing loop passing a DeterministicRandomEngine to the test body.

ParameterDescription
nameDescriptive identifier of the fuzz test.
iterationsNumber of iterations to execute.
functionTest callback receiving a DeterministicRandomEngine&.
seedInitial pseudo-random number generator seed (defaults to DeterministicRandomEngine::defaultSeed).
locationSource location used for failure reporting (automatically captured).
int executeTests(TestSettings settings);

Runs all registered test suites respecting dependency order and configuration settings.

ParameterDescription
settingsExecution settings controlling verbose output, filtering, and abort conditions.

Returns: Exit code: 0 on success, non-zero if any test suite failed.

TestSettings executeCommands(std::span<const std::string_view> arguments);

Parses command-line arguments into a TestSettings configuration object.

ParameterDescription
argumentsSpan of command-line argument tokens.

Returns: Parsed TestSettings configuration.

TestSettings executeCommands(int argc, const char* const argv[]);

Parses standard main() arguments (argc, argv) into a TestSettings configuration object.

ParameterDescription
argcArgument count.
argvArray of argument strings.

Returns: Parsed TestSettings configuration.