kaycxx::test Namespace Reference

Unit test framework functions and types. More...

Classes
class	failure
	Failure result passed to reporters when a test case or suite fails. More...
class	hook
	Registered setup or teardown hook. More...
class	reporter
	Receives lifecycle events from the test runner. More...
struct	run_options
	Configures the execution of registered tests. More...
class	skip_condition
	Condition used by a test case to decide whether it should be skipped before running hooks and test code. More...
class	skipped
	Result object passed to reporters when a test case was skipped. More...
struct	test_filter
	Selects registered tests by source path and full description. More...
class	test_registry
	Owns a set of test suites and the registration stack used while suite bodies execute. More...

Typedefs
using	callback = std::move_only_function< void()>
	Callable block used by tests, suites, and hooks.

Functions
void	after_all (callback body, std::source_location location=std::source_location::current())
	Registers a hook that runs once after all tests in the current suite have finished.
void	after_all (hook value)
	Registers a hook that runs once after all tests in the current suite have finished.
void	after_each (callback body, std::source_location location=std::source_location::current())
	Registers a hook that runs after each test in the current suite and its child suites.
void	after_each (hook value)
	Registers a hook that runs after each test in the current suite and its child suites.
void	before_all (callback body, std::source_location location=std::source_location::current())
	Registers a hook that runs once before any tests in the current suite are executed.
void	before_all (hook value)
	Registers a hook that runs once before any tests in the current suite are executed.
void	before_each (callback body, std::source_location location=std::source_location::current())
	Registers a hook that runs before each test in the current suite and its child suites.
void	before_each (hook value)
	Registers a hook that runs before each test in the current suite and its child suites.
void	describe (std::string_view description, callback body, std::source_location location=std::source_location::current())
	Defines a nested test suite and immediately executes its registration body.
void	it (std::string_view description, callback body, std::source_location location=std::source_location::current())
	Registers a test case in the current suite.
void	it (std::string_view description, skip_condition skip_condition, callback body, std::source_location location=std::source_location::current())
	Registers a test case in the current suite with a skip condition.
int	run_tests ()
	Runs the global test registry and writes the report to standard output.
int	run_tests (int argc, char *argv[])
	Runs the global test registry according to command-line arguments.
int	run_tests (std::ostream &output)
	Runs the global test registry and writes the report to the given stream.
int	run_tests (std::ostream &output, kaycxx::term::ansi_mode ansi_mode)
	Runs the global test registry and writes the report to the given stream.
int	run_tests (test_registry &registry, std::ostream &output)
	Runs the given test registry and writes the report to the given stream.
int	run_tests (test_registry &registry, std::ostream &output, kaycxx::term::ansi_mode ansi_mode)
	Runs the given test registry and writes the report to the given stream.
skip_condition	skip (std::string_view reason="")
	Creates a condition that always skips the test.
skip_condition	skip_if (std::move_only_function< bool()> condition, std::string_view reason="")
	Creates a condition that skips the test when the callback returns true.
skip_condition	skip_unless (std::move_only_function< bool()> condition, std::string_view reason="")
	Creates a condition that skips the test unless the callback returns true.
test_registry &	default_registry ()
	Returns the global registry used by the public DSL functions.
test_registry &	active_registry ()
	Returns the registry currently used by the public DSL functions.
test_registry &	set_active_registry (test_registry &registry)
	Changes the registry used by the public DSL functions.
void	reset_active_registry ()
	Resets the active registry to the default registry.

Detailed Description

Unit test framework functions and types.

Typedef Documentation

callback

using kaycxx::test::callback = typedef std::move_only_function<void()>

Callable block used by tests, suites, and hooks.

The callback is move-only so test code can capture move-only resources.

Function Documentation

active_registry()

test_registry & kaycxx::test::active_registry

(

)

Returns the registry currently used by the public DSL functions.

The active registry is the default registry unless it has been changed explicitly. This is mainly useful for self-tests and custom embedding scenarios that need to collect DSL registrations in an isolated registry.

Returns

The active test registry.

after_all() [1/2]

void kaycxx::test::after_all	(	callback	body,
		std::source_location	location = std::source_location::current()
	)

Registers a hook that runs once after all tests in the current suite have finished.

Parameters

body	The hook callback to register.
location	Source location used when the hook throws an exception without its own location.

after_all() [2/2]

void kaycxx::test::after_all

(

hook

value

)

Registers a hook that runs once after all tests in the current suite have finished.

Parameters

value

The hook to register.

after_each() [1/2]

void kaycxx::test::after_each	(	callback	body,
		std::source_location	location = std::source_location::current()
	)

Registers a hook that runs after each test in the current suite and its child suites.

Hooks run from the innermost suite to the outermost suite.

Parameters

body	The hook callback to register.
location	Source location used when the hook throws an exception without its own location.

after_each() [2/2]

void kaycxx::test::after_each

(

hook

value

)

Registers a hook that runs after each test in the current suite and its child suites.

Parameters

value

The hook to register.

before_all() [1/2]

void kaycxx::test::before_all	(	callback	body,
		std::source_location	location = std::source_location::current()
	)

Registers a hook that runs once before any tests in the current suite are executed.

Parameters

body	The hook callback to register.
location	Source location used when the hook throws an exception without its own location.

before_all() [2/2]

void kaycxx::test::before_all

(

hook

value

)

Registers a hook that runs once before any tests in the current suite are executed.

Parameters

value

The hook to register.

before_each() [1/2]

void kaycxx::test::before_each	(	callback	body,
		std::source_location	location = std::source_location::current()
	)

Registers a hook that runs before each test in the current suite and its child suites.

Hooks run from the outermost suite to the innermost suite.

Parameters

body	The hook callback to register.
location	Source location used when the hook throws an exception without its own location.

before_each() [2/2]

void kaycxx::test::before_each

(

hook

value

)

Registers a hook that runs before each test in the current suite and its child suites.

Parameters

value

The hook to register.

default_registry()

test_registry & kaycxx::test::default_registry

(

)

Returns the global registry used by the public DSL functions.

Returns

The default test registry.

describe()

void kaycxx::test::describe	(	std::string_view	description,
		callback	body,
		std::source_location	location = std::source_location::current()
	)

Defines a nested test suite and immediately executes its registration body.

Tests and hooks registered inside the body are added to the nested suite.

Parameters

description	Human-readable suite description.
body	Registration callback that defines child suites, tests, and hooks.
location	Source location of the describe() call.

it() [1/2]

void kaycxx::test::it	(	std::string_view	description,
		callback	body,
		std::source_location	location = std::source_location::current()
	)

Registers a test case in the current suite.

Parameters

description	Human-readable test description.
body	Test callback to execute when the test case runs.
location	Source location of the test registration.

it() [2/2]

void kaycxx::test::it	(	std::string_view	description,
		skip_condition	skip_condition,
		callback	body,
		std::source_location	location = std::source_location::current()
	)

Registers a test case in the current suite with a skip condition.

The skip condition is checked before before_each hooks and test code are executed.

Parameters

description	Human-readable test description.
skip_condition	Condition deciding if the test should be skipped.
body	Test callback to execute when the test case runs.
location	Source location of the test registration.

run_tests() [1/6]

int kaycxx::test::run_tests

(

)

Runs the global test registry and writes the report to standard output.

Returns

Process exit code 0 when all tests pass, otherwise 1.

run_tests() [2/6]

int kaycxx::test::run_tests	(	int	argc,
		char *	argv[]
	)

Runs the global test registry according to command-line arguments.

Positional path filters select tests by source file or directory. The repeatable -t and –test-name-pattern options select full descriptions with regular expressions. Supported actions are –help and –write-ctest.

Parameters

argc	Number of command-line arguments.
argv	Command-line argument values.

Returns

Process exit code 0 when the command succeeds, otherwise non-zero.

run_tests() [3/6]

int kaycxx::test::run_tests

(

std::ostream &

output

)

Runs the global test registry and writes the report to the given stream.

Parameters

output

Output stream receiving the test report.

Returns

Process exit code 0 when all tests pass, otherwise 1.

run_tests() [4/6]

int kaycxx::test::run_tests	(	std::ostream &	output,
		kaycxx::term::ansi_mode	ansi_mode
	)

Runs the global test registry and writes the report to the given stream.

Parameters

output	Output stream receiving the test report.
ansi_mode	Controls ANSI/VT control sequence output.

Returns

Process exit code 0 when all tests pass, otherwise 1.

run_tests() [5/6]

int kaycxx::test::run_tests	(	test_registry &	registry,
		std::ostream &	output
	)

Runs the given test registry and writes the report to the given stream.

Parameters

registry	Registry containing the suites to run.
output	Output stream receiving the test report.

Returns

Process exit code 0 when all tests pass, otherwise 1.

run_tests() [6/6]

int kaycxx::test::run_tests	(	test_registry &	registry,
		std::ostream &	output,
		kaycxx::term::ansi_mode	ansi_mode
	)

Runs the given test registry and writes the report to the given stream.

Parameters

registry	Registry containing the suites to run.
output	Output stream receiving the test report.
ansi_mode	Controls ANSI/VT control sequence output.

Returns

Process exit code 0 when all tests pass, otherwise 1.

set_active_registry()

test_registry & kaycxx::test::set_active_registry

(

test_registry &

registry

)

Changes the registry used by the public DSL functions.

Parameters

registry

Registry to use for following DSL registrations.

Returns

The previously active registry.

skip()

skip_condition kaycxx::test::skip

(

std::string_view

reason = ""

)

Creates a condition that always skips the test.

Parameters

reason

Optional reason why the test should be skipped.

Returns

The skip condition.

skip_if()

skip_condition kaycxx::test::skip_if	(	std::move_only_function< bool()>	condition,
		std::string_view	reason = ""
	)

Creates a condition that skips the test when the callback returns true.

Parameters

condition	Callback returning true when the test should be skipped.
reason	Optional reason why the test should be skipped.

Returns

The skip condition.

skip_unless()

skip_condition kaycxx::test::skip_unless	(	std::move_only_function< bool()>	condition,
		std::string_view	reason = ""
	)

Creates a condition that skips the test unless the callback returns true.

Parameters

condition	Callback returning true when the test should run.
reason	Optional reason why the test should be skipped.

Returns

The skip condition.