hegel Namespace Reference

Main namespace. More...

Namespaces
namespace	generators
	Hegel generators.
namespace	stateful
	Stateful (model-based) property testing.

Classes
class	GTestFailure
	The exception the GoogleTest integration raises for a test case that fails an assertion. More...
class	FailureOrigin
	Interface for an exception that names its own failure origin. More...
struct	TestLocation
	Where a test is defined. More...
class	Database
	Configure the Hegel database. More...
struct	Settings
	Configuration options for hegel::test(). More...
class	TestCase
	Handle to the currently-executing test case. More...
class	Worker
	Handle to a worker started by TestCase::spawn(). More...

Enumerations
enum class	Verbosity { Quiet , Normal , Verbose , Debug }
	Verbosity levels. More...
enum class	HealthCheck { FilterTooMuch , TooSlow , TestCasesTooLarge , LargeInitialTestCase }
	Health checks. More...
enum class	Phase {   Explicit , Reuse , Generate , Target ,   Shrink }
	Phases of a property-test run. More...
enum class	Mode { TestRun , SingleTestCase }
	How much of a run the engine performs. More...
enum class	Backend { Auto , Default , Urandom }
	Source of randomness the engine draws from. More...

Functions
void	test (const std::function< void(TestCase &)> &test_fn, const Settings &settings={}, const std::vector< std::string > &failure_blobs={}, const char *caller_file=HEGEL_CALLER_FILE, const char *caller_function=HEGEL_CALLER_FUNCTION, int caller_line=HEGEL_CALLER_LINE)
	Run a Hegel test.
void	test (const std::function< void(TestCase &)> &test_fn, const TestLocation &location, const Settings &settings={}, const std::vector< std::string > &failure_blobs={})
	Run a Hegel test that names itself in its failure report.
const char *	verbosity_to_string (Verbosity v)
	Convert Verbosity enum to command-line string.
std::vector< HealthCheck >	all_health_checks ()
	All health checks, suitable for full suppression.
std::vector< Phase >	all_phases ()
	All phases, the default for Settings::phases.

Detailed Description

Main namespace.

Enumeration Type Documentation

Backend

enum class hegel::Backend

strong

Source of randomness the engine draws from.

Enumerator
Auto	Choose automatically (the default): Urandom when running inside Antithesis, Default otherwise.
Default	Expand a single seeded PRNG. Runs are reproducible from the seed and shrinking / replay work as usual.
Urandom	Read fresh entropy from /dev/urandom on every draw. Intended for running under Antithesis; you almost certainly don't want it otherwise.

HealthCheck

enum class hegel::HealthCheck

strong

Health checks.

Enumerator
FilterTooMuch	Test filters out too many generated examples.
TooSlow	Test cases are running too slowly.
TestCasesTooLarge	Generated test cases are too large.
LargeInitialTestCase	First generated test case is unusually large.

Mode

enum class hegel::Mode

strong

How much of a run the engine performs.

Enumerator
TestRun	Full property-test run. The default.
SingleTestCase	Produce exactly one test case and stop, with no shrinking. Useful for exploratory probes.

Phase

enum class hegel::Phase

strong

Phases of a property-test run.

Enumerator
Explicit	Run hard-coded explicit examples.
Reuse	Replay counterexamples persisted in the database.
Generate	Randomly generate fresh test cases.
Target	Hill-climb toward observed target scores.
Shrink	Shrink failing examples toward minimal counterexamples.

Verbosity

enum class hegel::Verbosity

strong

Verbosity levels.

Enumerator
Quiet	Minimal output (used by TUI).
Normal	Default - standard test output.
Verbose	More detailed output.
Debug	Maximum verbosity + engine-side shrinker tracing.

Function Documentation

all_health_checks()

std::vector< HealthCheck > hegel::all_health_checks ( )

inline

All health checks, suitable for full suppression.

Returns

A vector containing every HealthCheck variant.

all_phases()

std::vector< Phase > hegel::all_phases ( )

inline

All phases, the default for Settings::phases.

Returns

A vector containing every Phase variant.

test() [1/2]

void hegel::test	(	const std::function< void(TestCase &)> &	test_fn,
		const Settings &	settings = {},
		const std::vector< std::string > &	failure_blobs = {},
		const char *	caller_file = HEGEL_CALLER_FILE,
		const char *	caller_function = HEGEL_CALLER_FUNCTION,
		int	caller_line = HEGEL_CALLER_LINE )

Run a Hegel test.

This is the underlying entry point that HEGEL_TEST expands to.

Settings::database_key defaults to "<file>::<name>", where the file is the one holding the call and the name is the enclosing GoogleTest test (Suite.Name) or, outside a test framework, the enclosing function.

Inside a GoogleTest test the failure report's header names that test and the line of the call. Outside one it reads --- Failure ---. Pass a TestLocation to the overload below to name it yourself.

#include "hegel/hegel.h"
 
int main() {
    hegel::test([](hegel::TestCase& tc) {
        namespace gs = hegel::generators;
        auto x = tc.draw(gs::integers<int>({.min_value = 0, .max_value =
100})); auto y = tc.draw(gs::integers<int>({.min_value = 0, .max_value =
100}));
 
        // Property: x + y >= x (true for non-negative integers)
        if (x + y < x) {
            throw std::runtime_error("Addition underflow!");
        }
    }, {.test_cases = 1000});
 
    return 0;
}

Parameters

test_fn	The test function to run repeatedly. Receives a TestCase which it uses to draw values, make assumptions, and record notes.
settings	Configuration settings (test count, debug mode, etc.)
failure_blobs	The base64 blobs encoding the engine choices that led to failures. Multiple blobs can be passed in for bookkeeping, but only the first one is run.
caller_file	Filled in by the compiler with the file of the call.
caller_function	Filled in by the compiler with the function holding the call.
caller_line	Filled in by the compiler with the line of the call.

Exceptions

std::runtime_error

if any test case fails

See also

Settings for configuration settings

test() [2/2]

void hegel::test	(	const std::function< void(TestCase &)> &	test_fn,
		const TestLocation &	location,
		const Settings &	settings = {},
		const std::vector< std::string > &	failure_blobs = {} )

Run a Hegel test that names itself in its failure report.

Behaves like the overload above. The failure report's header names location's test and source line instead of reading --- Failure ---, and Settings::database_key defaults to the location's file and name.

hegel::test(my_body, {"my_property", __FILE__, __LINE__},
            {.test_cases = 500});

Parameters

test_fn	The test function to run repeatedly.
location	Where the test is defined.
settings	Configuration settings (test count, debug mode, etc.)
failure_blobs	The base64 blobs encoding the engine choices that led to failures. Multiple blobs can be passed in for bookkeeping, but only the first one is run.

Exceptions

std::runtime_error

if any test case fails

verbosity_to_string()

const char * hegel::verbosity_to_string ( Verbosity v )

inline

Convert Verbosity enum to command-line string.

Parameters

v	The verbosity level

Returns

The string representation for CLI argument