test_framework.h File Reference

Platform-agnostic test framework for capi_selftest project. Copyright (c) 2025-2026 Analog Devices, Inc. More...

#include <errno.h>
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>

Include dependency graph for test_framework.h:

Classes
struct	test_framework_count
	Test result counts. More...
struct	test_framework_config
	Test framework configuration. More...
struct	test_case
	Test case entry for table-driven testing. More...

Macros
#define	TEST_FRAMEWORK_DEFAULT_TIMEOUT_MS   10000U
	Default whole-run timeout used when config->timeout_ms is 0.
#define	SKIP_HW_ABSENT   "HW_ABSENT"
	Skip category used when a hardware block is absent.
#define	SKIP_IRQ_ABSENT   "IRQ_ABSENT"
	Skip category used when an interrupt line is absent.
#define	SKIP_BSP_ABSENT   "BSP_ABSENT"
	Skip category used when a BSP symbol is absent.
#define	SKIP_UNSAFE   "UNSAFE"
	Skip category used when a test could disturb board state.
#define	SKIP_NOT_IMPLEMENTED   "NOT_IMPLEMENTED"
	Skip category used for intentionally unsupported behavior.
#define	SKIP_BOARD_STATE   "BOARD_STATE"
	Skip category used when board wiring or state prevents a test.
#define	SKIP_FEATURE_DISABLED   "FEATURE_DISABLED"
	Skip category used when a feature is disabled in this build.
#define	TEST_BEGIN(module, name)
	Select the current module and test name.
#define	TEST_CHECKPOINT()
	Record the current function and line for timeout diagnostics.
#define	TEST_BEGIN_UART(backend, name)
	Begin a UART test and checkpoint before the UART operation runs.
#define	TEST_PASS()
	Record a passing test result.
#define	TEST_FAIL(message)
	Record a failing test result with a fixed message.
#define	TEST_FAIL_VAL(message, got, expected)
	Record a failing test result with got/expected values.
#define	TEST_SKIP(message)
	Record an uncategorized skip and return from the current test.
#define	TEST_SKIP_CAT(category, message)
	Record a categorized skip and return from the current test.
#define	TEST_SKIP_CAT_OR_CLEANUP(category, message)
	Categorized skip that releases the test's hardware on the way out.
#define	TEST_INFO(message)
	Print informational text without changing result counts.
#define	TEST_VALUE(name, value)
	Print a named hexadecimal value without changing result counts.
#define	TEST_SECTION(name)
	Print a human-readable section marker.
#define	TEST_RUN_START()
	Start a test run and reset result counts.
#define	TEST_RUN_END()
	Finish a test run and print the summary.
#define	TEST_CONTRACT_BEGIN(module, backend, kind, detail)
	Begin a backend contract test name.
#define	TEST_ASSERT_ACT(condition, name, on_fail)
	Shared body: assert a condition, run on_fail before returning.
#define	TEST_ASSERT(condition, name)
	Assert that a condition is true and return on failure.
#define	TEST_ASSERT_OR_CLEANUP(condition, name)
	Assert a condition; release the test's hardware on failure.
#define	TEST_ASSERT_EQ_ACT(actual, expected, name, on_fail)
	Shared body: assert equality, run on_fail before returning.
#define	TEST_ASSERT_EQ(actual, expected, name)
	Assert that two integer-like values are equal.
#define	TEST_ASSERT_EQ_OR_CLEANUP(actual, expected, name)
	Assert equality; release the test's hardware on failure.
#define	TEST_ASSERT_NEQ_ACT(actual, expected, name, on_fail)
	Shared body: assert inequality, run on_fail before returning.
#define	TEST_ASSERT_NEQ(actual, expected, name)
	Assert that two integer-like values are different.
#define	TEST_ASSERT_NEQ_OR_CLEANUP(actual, expected, name)
	Assert inequality; release the test's hardware on failure.
#define	TEST_ASSERT_RANGE_ACT(value, minimum, maximum, name, on_fail)
	Shared body: assert an inclusive range, run on_fail on failure.
#define	TEST_ASSERT_RANGE(value, minimum, maximum, name)
	Assert that a value is inside an inclusive range.
#define	TEST_ASSERT_RANGE_OR_CLEANUP(value, minimum, maximum, name)
	Assert an inclusive range; release the hardware on failure.
#define	TEST_ASSERT_COMPARE_ACT(actual, expected, name, invalid_op, relation, on_fail)
	Internal helper used by relational assertion macros.
#define	TEST_ASSERT_COMPARE(actual, expected, name, invalid_op, relation)
	Relational assertion that returns on failure.
#define	TEST_ASSERT_GT(actual, expected, name)
	Assert that actual is greater than expected.
#define	TEST_ASSERT_LT(actual, expected, name)
	Assert that actual is less than expected.
#define	TEST_ASSERT_GTE(actual, expected, name)
	Assert that actual is greater than or equal to expected.
#define	TEST_ASSERT_LTE(actual, expected, name)
	Assert that actual is less than or equal to expected.
#define	TEST_ASSERT_GT_OR_CLEANUP(actual, expected, name)
	Assert actual > expected; release the hardware on failure.
#define	TEST_ASSERT_LT_OR_CLEANUP(actual, expected, name)
	Assert actual < expected; release the hardware on failure.
#define	TEST_ASSERT_GTE_OR_CLEANUP(actual, expected, name)
	Assert actual >= expected; release the hardware on failure.
#define	TEST_ASSERT_LTE_OR_CLEANUP(actual, expected, name)
	Assert actual <= expected; release the hardware on failure.
#define	TEST_ASSERT_OK_OR_NOTSUP_ACT(result, name, on_fail)
	Shared body: accept 0 or -ENOTSUP, run on_fail otherwise.
#define	TEST_ASSERT_OK_OR_NOTSUP(result, name)
	Accept either success or an explicitly unsupported operation.
#define	TEST_ASSERT_OK_OR_NOTSUP_OR_CLEANUP(result, name)
	Accept success or unsupported; release the hardware otherwise.
#define	TEST_WAIT_UNTIL(condition, maximum_us, step_us)
	Poll a condition until it becomes true or the timeout expires.
#define	TEST_ASSERT_NEAR_ACT(actual, expected, tolerance, name, on_fail)
	Shared body: assert a tolerance band, run on_fail on failure.
#define	TEST_ASSERT_NEAR(actual, expected, tolerance, name)
	Assert that actual is within tolerance of expected.
#define	TEST_ASSERT_NEAR_OR_CLEANUP(actual, expected, tolerance, name)
	Assert a tolerance band; release the hardware on failure.
#define	TEST_ASSERT_COUNTER_DIR_ACT(first, second, direction, name, on_fail)
	Shared body: assert counter direction, run on_fail on failure.
#define	TEST_ASSERT_COUNTER_DIR(first, second, direction, name)
	Assert that a counter moved in the requested direction.
#define	TEST_ASSERT_COUNTER_DIR_OR_CLEANUP(first, second, direction, name)
	Assert counter direction; release the hardware on failure.

Typedefs
typedef int(*	test_framework_write_fn) (void *context, const uint8_t *data, uint32_t length)
	Test framework output function.
typedef void(*	test_framework_wait_us_fn) (void *context, uint32_t duration_us)
	Test framework delay function.
typedef void(*	test_framework_watchdog_arm_fn) (void *context, uint32_t timeout_ms)
	Watchdog arm function for the whole-run timeout.
typedef void(*	test_framework_watchdog_disarm_fn) (void *context)
	Watchdog disarm function.

Functions
int	test_framework_init (const struct test_framework_config *config)
	Initialize the test framework.
void	test_framework_remove (void)
	Remove the test framework configuration.
void	test_framework_reset (void)
	Reset the current test context and counts.
void	test_framework_run_start (void)
	Start a test run, reset its counts and arm the watchdog.
void	test_framework_run_end (void)
	Disarm the watchdog, print the final counts and end the run.
void	test_framework_begin (const char *module, const char *name)
	Select the current test module and test name.
void	test_framework_set_name (const char *name)
	Select the current test name.
void	test_framework_checkpoint (const char *func, int line)
	Record the last reached source location (function and line).
void	test_framework_on_timeout (void)
	Report from the platform watchdog handler that the run hung.
void	test_framework_begin_uart (const char *backend, const char *name, const char *func, int line)
	Begin a UART test as a special case.
void	test_framework_pass (void)
	Record and report a passing test.
void	test_framework_fail (const char *format,...)
	Record and report a failing test.
void	test_framework_skip (const char *category, const char *message)
	Record and report a skipped test.
void	test_framework_info (const char *message)
	Report test information without changing the counts.
void	test_framework_value (const char *name, uint64_t value)
	Report a named test value without changing the counts.
void	test_framework_section (const char *name)
	Print a human-readable section marker.
void	test_framework_wait_us (uint32_t duration_us)
	Invoke the configured microsecond delay callback.
void	test_framework_get_count (struct test_framework_count *count)
	Read the current test counts.
int	test_framework_run_cases (const char *module, const struct test_case *cases, size_t count)
	Run a table of test cases, respecting skip flags.

Detailed Description

Platform-agnostic test framework for capi_selftest project. Copyright (c) 2025-2026 Analog Devices, Inc.

SPDX-License-Identifier: BSD-3-Clause

Macro Definition Documentation

SKIP_BOARD_STATE

#define SKIP_BOARD_STATE   "BOARD_STATE"

Skip category used when board wiring or state prevents a test.

SKIP_BSP_ABSENT

#define SKIP_BSP_ABSENT   "BSP_ABSENT"

Skip category used when a BSP symbol is absent.

SKIP_FEATURE_DISABLED

#define SKIP_FEATURE_DISABLED   "FEATURE_DISABLED"

Skip category used when a feature is disabled in this build.

SKIP_HW_ABSENT

#define SKIP_HW_ABSENT   "HW_ABSENT"

Skip category used when a hardware block is absent.

SKIP_IRQ_ABSENT

#define SKIP_IRQ_ABSENT   "IRQ_ABSENT"

Skip category used when an interrupt line is absent.

SKIP_NOT_IMPLEMENTED

#define SKIP_NOT_IMPLEMENTED   "NOT_IMPLEMENTED"

Skip category used for intentionally unsupported behavior.

SKIP_UNSAFE

#define SKIP_UNSAFE   "UNSAFE"

Skip category used when a test could disturb board state.

TEST_ASSERT

#define TEST_ASSERT	(		condition,
			name )

Value:

    TEST_ASSERT_ACT(condition, name, (void)0)

Assert that a condition is true and return on failure.

TEST_ASSERT_ACT

#define TEST_ASSERT_ACT	(		condition,
			name,
			on_fail )

Value:

    do { \
        bool _test_result = (bool)(condition); \
        test_framework_set_name((name)); \
        if (!_test_result) { \
            test_framework_fail("assert line %d", __LINE__); \
            on_fail; \
            return -1; \
        } \
        test_framework_pass(); \
    } while (0)

Shared body: assert a condition, run on_fail before returning.

TEST_ASSERT_COMPARE

#define TEST_ASSERT_COMPARE	(		actual,
			expected,
			name,
			invalid_op,
			relation )

Value:

    TEST_ASSERT_COMPARE_ACT(actual, expected, name, invalid_op, relation, \
                (void)0)

Relational assertion that returns on failure.

TEST_ASSERT_COMPARE_ACT

#define TEST_ASSERT_COMPARE_ACT	(		actual,
			expected,
			name,
			invalid_op,
			relation,
			on_fail )

Value:

    do { \
        long long _test_actual = (long long)(actual); \
        long long _test_expected = (long long)(expected); \
        test_framework_set_name((name)); \
        if (_test_actual invalid_op _test_expected) { \
            test_framework_fail("got=%lld %s=%lld", _test_actual, \
                        (relation), _test_expected); \
            on_fail; \
            return -1; \
        } \
        test_framework_pass(); \
    } while (0)

Internal helper used by relational assertion macros.

TEST_ASSERT_COUNTER_DIR

#define TEST_ASSERT_COUNTER_DIR	(		first,
			second,
			direction,
			name )

Value:

    TEST_ASSERT_COUNTER_DIR_ACT(first, second, direction, name, (void)0)

Assert that a counter moved in the requested direction.

TEST_ASSERT_COUNTER_DIR_ACT

#define TEST_ASSERT_COUNTER_DIR_ACT	(		first,
			second,
			direction,
			name,
			on_fail )

Value:

    do { \
        unsigned long _test_first = (unsigned long)(first); \
        unsigned long _test_second = (unsigned long)(second); \
        int _test_direction = (int)(direction); \
        bool _test_valid; \
        test_framework_set_name((name)); \
        if (_test_direction == 0) \
            _test_valid = _test_second > _test_first; \
        else if (_test_direction == 1) \
            _test_valid = _test_second < _test_first; \
        else \
            _test_valid = _test_second != _test_first; \
        if (!_test_valid) { \
            test_framework_fail("first=%lu second=%lu direction=%d", \
                        _test_first, _test_second, \
                        _test_direction); \
            on_fail; \
            return -1; \
        } \
        test_framework_pass(); \
    } while (0)

Shared body: assert counter direction, run on_fail on failure.

TEST_ASSERT_COUNTER_DIR_OR_CLEANUP

#define TEST_ASSERT_COUNTER_DIR_OR_CLEANUP	(		first,
			second,
			direction,
			name )

Value:

    TEST_ASSERT_COUNTER_DIR_ACT(first, second, direction, name, CLEANUP)

Assert counter direction; release the hardware on failure.

TEST_ASSERT_EQ

#define TEST_ASSERT_EQ	(		actual,
			expected,
			name )

Value:

    TEST_ASSERT_EQ_ACT(actual, expected, name, (void)0)

Assert that two integer-like values are equal.

TEST_ASSERT_EQ_ACT

#define TEST_ASSERT_EQ_ACT	(		actual,
			expected,
			name,
			on_fail )

Value:

    do { \
        long long _test_actual = (long long)(actual); \
        long long _test_expected = (long long)(expected); \
        test_framework_set_name((name)); \
        if (_test_actual != _test_expected) { \
            test_framework_fail("got=%lld expected=%lld", \
                        _test_actual, _test_expected); \
            on_fail; \
            return -1; \
        } \
        test_framework_pass(); \
    } while (0)

Shared body: assert equality, run on_fail before returning.

TEST_ASSERT_EQ_OR_CLEANUP

#define TEST_ASSERT_EQ_OR_CLEANUP	(		actual,
			expected,
			name )

Value:

    TEST_ASSERT_EQ_ACT(actual, expected, name, CLEANUP)

Assert equality; release the test's hardware on failure.

TEST_ASSERT_GT

#define TEST_ASSERT_GT	(		actual,
			expected,
			name )

Value:

    TEST_ASSERT_COMPARE(actual, expected, name, <=, "expected_gt")

Assert that actual is greater than expected.

TEST_ASSERT_GT_OR_CLEANUP

#define TEST_ASSERT_GT_OR_CLEANUP	(		actual,
			expected,
			name )

Value:

    TEST_ASSERT_COMPARE_ACT(actual, expected, name, <=, "expected_gt", \
                CLEANUP)

Assert actual > expected; release the hardware on failure.

TEST_ASSERT_GTE

#define TEST_ASSERT_GTE	(		actual,
			expected,
			name )

Value:

    TEST_ASSERT_COMPARE(actual, expected, name, <, "expected_gte")

Assert that actual is greater than or equal to expected.

TEST_ASSERT_GTE_OR_CLEANUP

#define TEST_ASSERT_GTE_OR_CLEANUP	(		actual,
			expected,
			name )

Value:

    TEST_ASSERT_COMPARE_ACT(actual, expected, name, <, "expected_gte", \
                CLEANUP)

Assert actual >= expected; release the hardware on failure.

TEST_ASSERT_LT

#define TEST_ASSERT_LT	(		actual,
			expected,
			name )

Value:

    TEST_ASSERT_COMPARE(actual, expected, name, >=, "expected_lt")

Assert that actual is less than expected.

TEST_ASSERT_LT_OR_CLEANUP

#define TEST_ASSERT_LT_OR_CLEANUP	(		actual,
			expected,
			name )

Value:

    TEST_ASSERT_COMPARE_ACT(actual, expected, name, >=, "expected_lt", \
                CLEANUP)

Assert actual < expected; release the hardware on failure.

TEST_ASSERT_LTE

#define TEST_ASSERT_LTE	(		actual,
			expected,
			name )

Value:

    TEST_ASSERT_COMPARE(actual, expected, name, >, "expected_lte")

Assert that actual is less than or equal to expected.

TEST_ASSERT_LTE_OR_CLEANUP

#define TEST_ASSERT_LTE_OR_CLEANUP	(		actual,
			expected,
			name )

Value:

    TEST_ASSERT_COMPARE_ACT(actual, expected, name, >, "expected_lte", \
                CLEANUP)

Assert actual <= expected; release the hardware on failure.

TEST_ASSERT_NEAR

#define TEST_ASSERT_NEAR	(		actual,
			expected,
			tolerance,
			name )

Value:

    TEST_ASSERT_NEAR_ACT(actual, expected, tolerance, name, (void)0)

Assert that actual is within tolerance of expected.

TEST_ASSERT_NEAR_ACT

#define TEST_ASSERT_NEAR_ACT	(		actual,
			expected,
			tolerance,
			name,
			on_fail )

Value:

    do { \
        long long _test_actual = (long long)(actual); \
        long long _test_expected = (long long)(expected); \
        long long _test_tolerance = (long long)(tolerance); \
        long long _test_delta = _test_actual - _test_expected; \
        test_framework_set_name((name)); \
        if (_test_delta < 0) \
            _test_delta = -_test_delta; \
        if (_test_delta > _test_tolerance) { \
            test_framework_fail("got=%lld expected=%lld tolerance=%lld", \
                        _test_actual, _test_expected, \
                        _test_tolerance); \
            on_fail; \
            return -1; \
        } \
        test_framework_pass(); \
    } while (0)

Shared body: assert a tolerance band, run on_fail on failure.

TEST_ASSERT_NEAR_OR_CLEANUP

#define TEST_ASSERT_NEAR_OR_CLEANUP	(		actual,
			expected,
			tolerance,
			name )

Value:

    TEST_ASSERT_NEAR_ACT(actual, expected, tolerance, name, CLEANUP)

Assert a tolerance band; release the hardware on failure.

TEST_ASSERT_NEQ

#define TEST_ASSERT_NEQ	(		actual,
			expected,
			name )

Value:

    TEST_ASSERT_NEQ_ACT(actual, expected, name, (void)0)

Assert that two integer-like values are different.

TEST_ASSERT_NEQ_ACT

#define TEST_ASSERT_NEQ_ACT	(		actual,
			expected,
			name,
			on_fail )

Value:

    do { \
        long long _test_actual = (long long)(actual); \
        long long _test_expected = (long long)(expected); \
        test_framework_set_name((name)); \
        if (_test_actual == _test_expected) { \
            test_framework_fail("got=%lld should_not_equal=%lld", \
                        _test_actual, _test_expected); \
            on_fail; \
            return -1; \
        } \
        test_framework_pass(); \
    } while (0)

Shared body: assert inequality, run on_fail before returning.

TEST_ASSERT_NEQ_OR_CLEANUP

#define TEST_ASSERT_NEQ_OR_CLEANUP	(		actual,
			expected,
			name )

Value:

    TEST_ASSERT_NEQ_ACT(actual, expected, name, CLEANUP)

Assert inequality; release the test's hardware on failure.

TEST_ASSERT_OK_OR_NOTSUP

#define TEST_ASSERT_OK_OR_NOTSUP	(		result,
			name )

Value:

    TEST_ASSERT_OK_OR_NOTSUP_ACT(result, name, (void)0)

Accept either success or an explicitly unsupported operation.

TEST_ASSERT_OK_OR_NOTSUP_ACT

#define TEST_ASSERT_OK_OR_NOTSUP_ACT	(		result,
			name,
			on_fail )

Value:

    do { \
        int _test_result = (int)(result); \
        test_framework_set_name((name)); \
        if (_test_result != 0 && _test_result != -ENOTSUP) { \
            test_framework_fail("ret=%d expected 0 or -ENOTSUP", \
                        _test_result); \
            on_fail; \
            return -1; \
        } \
        test_framework_pass(); \
    } while (0)

Shared body: accept 0 or -ENOTSUP, run on_fail otherwise.

TEST_ASSERT_OK_OR_NOTSUP_OR_CLEANUP

#define TEST_ASSERT_OK_OR_NOTSUP_OR_CLEANUP	(		result,
			name )

Value:

    TEST_ASSERT_OK_OR_NOTSUP_ACT(result, name, CLEANUP)

Accept success or unsupported; release the hardware otherwise.

TEST_ASSERT_OR_CLEANUP

#define TEST_ASSERT_OR_CLEANUP	(		condition,
			name )

Value:

    TEST_ASSERT_ACT(condition, name, CLEANUP)

Assert a condition; release the test's hardware on failure.

TEST_ASSERT_RANGE

#define TEST_ASSERT_RANGE	(		value,
			minimum,
			maximum,
			name )

Value:

    TEST_ASSERT_RANGE_ACT(value, minimum, maximum, name, (void)0)

Assert that a value is inside an inclusive range.

TEST_ASSERT_RANGE_ACT

#define TEST_ASSERT_RANGE_ACT	(		value,
			minimum,
			maximum,
			name,
			on_fail )

Value:

    do { \
        long long _test_value = (long long)(value); \
        long long _test_minimum = (long long)(minimum); \
        long long _test_maximum = (long long)(maximum); \
        test_framework_set_name((name)); \
        if (_test_value < _test_minimum || \
            _test_value > _test_maximum) { \
            test_framework_fail("value=%lld range=[%lld,%lld]", \
                        _test_value, _test_minimum, \
                        _test_maximum); \
            on_fail; \
            return -1; \
        } \
        test_framework_pass(); \
    } while (0)

Shared body: assert an inclusive range, run on_fail on failure.

TEST_ASSERT_RANGE_OR_CLEANUP

#define TEST_ASSERT_RANGE_OR_CLEANUP	(		value,
			minimum,
			maximum,
			name )

Value:

    TEST_ASSERT_RANGE_ACT(value, minimum, maximum, name, CLEANUP)

Assert an inclusive range; release the hardware on failure.

TEST_BEGIN

#define TEST_BEGIN	(		module,
			name )

Value:

    test_framework_begin((module), (name))

Select the current module and test name.

TEST_BEGIN_UART

#define TEST_BEGIN_UART	(		backend,
			name )

Value:

    test_framework_begin_uart((backend), (name), __func__, __LINE__)

Begin a UART test and checkpoint before the UART operation runs.

UART may be the report transport, so this announces context before a possible UART hang can silence the log.

TEST_CHECKPOINT

#define TEST_CHECKPOINT

(

)

Value:

    test_framework_checkpoint(__func__, __LINE__)

Record the current function and line for timeout diagnostics.

TEST_CONTRACT_BEGIN

#define TEST_CONTRACT_BEGIN	(		module,
			backend,
			kind,
			detail )

Value:

    TEST_BEGIN(module "." backend ".CONTRACT", kind "." detail)

Begin a backend contract test name.

TEST_FAIL

#define TEST_FAIL

(

message

)

Value:

    test_framework_fail("%s", (message))

Record a failing test result with a fixed message.

TEST_FAIL_VAL

#define TEST_FAIL_VAL	(		message,
			got,
			expected )

Value:

    test_framework_fail("%s got=%lld expected=%lld", (message), \
                (long long)(got), (long long)(expected))

Record a failing test result with got/expected values.

TEST_FRAMEWORK_DEFAULT_TIMEOUT_MS

#define TEST_FRAMEWORK_DEFAULT_TIMEOUT_MS   10000U

Default whole-run timeout used when config->timeout_ms is 0.

TEST_INFO

#define TEST_INFO

(

message

)

Value:

    test_framework_info((message))

Print informational text without changing result counts.

TEST_PASS

#define TEST_PASS

(

)

Value:

    test_framework_pass()

Record a passing test result.

TEST_RUN_END

#define TEST_RUN_END

(

)

Value:

    test_framework_run_end()

Finish a test run and print the summary.

TEST_RUN_START

#define TEST_RUN_START

(

)

Value:

    test_framework_run_start()

Start a test run and reset result counts.

TEST_SECTION

#define TEST_SECTION

(

name

)

Value:

    test_framework_section((name))

Print a human-readable section marker.

TEST_SKIP

#define TEST_SKIP

(

message

)

Value:

    do { \
        test_framework_skip(NULL, (message)); \
        return 0; \
    } while (0)

Record an uncategorized skip and return from the current test.

TEST_SKIP_CAT

#define TEST_SKIP_CAT	(		category,
			message )

Value:

    do { \
        test_framework_skip((category), (message)); \
        return 0; \
    } while (0)

Record a categorized skip and return from the current test.

TEST_SKIP_CAT_OR_CLEANUP

#define TEST_SKIP_CAT_OR_CLEANUP	(		category,
			message )

Value:

    do { \
        test_framework_skip((category), (message)); \
        CLEANUP; \
        return 0; \
    } while (0)

Categorized skip that releases the test's hardware on the way out.

A skip decided after the test has already brought hardware up must undo it, exactly like a failing assertion does. Expands the enclosing CLEANUP; see the _OR_CLEANUP assertion forms below.

TEST_VALUE

#define TEST_VALUE	(		name,
			value )

Value:

    test_framework_value((name), (uint64_t)(value))

Print a named hexadecimal value without changing result counts.

TEST_WAIT_UNTIL

#define TEST_WAIT_UNTIL	(		condition,
			maximum_us,
			step_us )

Value:

    do { \
        uint32_t _test_waited = 0U; \
        uint32_t _test_step = (uint32_t)(step_us); \
        uint32_t _test_maximum = (uint32_t)(maximum_us); \
        if (_test_step == 0U) \
            _test_step = 100U; \
        while (!(condition) && _test_waited < _test_maximum) { \
            test_framework_wait_us(_test_step); \
            _test_waited += _test_step; \
        } \
    } while (0)

Poll a condition until it becomes true or the timeout expires.

Typedef Documentation

test_framework_wait_us_fn

typedef void(* test_framework_wait_us_fn) (void *context, uint32_t duration_us)

Test framework delay function.

Parameters

context	- Delay-specific context.
duration_us	- Delay duration in microseconds.

test_framework_watchdog_arm_fn

typedef void(* test_framework_watchdog_arm_fn) (void *context, uint32_t timeout_ms)

Watchdog arm function for the whole-run timeout.

The platform owns the timer. The framework calls this at run start to arm a one-shot watchdog. When it expires the platform's handler must call test_framework_on_timeout() and then halt the run.

Parameters

context	- Watchdog-specific context.
timeout_ms	- Timeout in milliseconds for the entire run.

test_framework_watchdog_disarm_fn

typedef void(* test_framework_watchdog_disarm_fn) (void *context)

Watchdog disarm function.

Parameters

context

- Watchdog-specific context.

test_framework_write_fn

typedef int(* test_framework_write_fn) (void *context, const uint8_t *data, uint32_t length)

Test framework output function.

Parameters

context	- Output-specific context.
data	- Data to transmit.
length	- Number of bytes to transmit.

Returns

0 in case of success, negative error code otherwise.

Function Documentation

test_framework_begin()

void test_framework_begin	(	const char *	module,
		const char *	name )

Select the current test module and test name.

Parameters

module	- Test module name.
name	- Test name.

test_framework_begin_uart()

void test_framework_begin_uart	(	const char *	backend,
		const char *	name,
		const char *	func,
		int	line )

Begin a UART test as a special case.

UART tests can hang (for example when reconfiguring the console UART). This announces the test and records a checkpoint BEFORE the body runs, so a hang is attributable to this exact test. Prefer the TEST_BEGIN_UART() macro.

Parameters

backend	- UART backend name.
name	- Test name.
func	- Enclosing function name (func).
line	- Source line number (LINE).

test_framework_checkpoint()

void test_framework_checkpoint	(	const char *	func,
		int	line )

Record the last reached source location (function and line).

Used so a whole-run hang can report where execution stopped. Prefer the TEST_CHECKPOINT() macro over calling this directly. Uses func and LINE rather than FILE: on a microcontroller FILE bakes the full build-host path into flash, while func is a small literal and LINE costs nothing.

Parameters

func	- Enclosing function name (func).
line	- Source line number (LINE).

test_framework_fail()

void test_framework_fail	(	const char *	format,
			... )

Record and report a failing test.

Parameters

format

- Failure detail format.

test_framework_get_count()

void test_framework_get_count

(

struct test_framework_count *

count

)

Read the current test counts.

Parameters

count

- Destination counts.

test_framework_info()

void test_framework_info

(

const char *

message

)

Report test information without changing the counts.

Parameters

message

- Information message.

test_framework_init()

int test_framework_init

(

const struct test_framework_config *

config

)

Initialize the test framework.

Parameters

config

- Framework configuration.

Returns

0 in case of success, negative error code otherwise.

test_framework_on_timeout()

void test_framework_on_timeout

(

void

)

Report from the platform watchdog handler that the run hung.

Prints the last test context, the last reached source location and the partial counts. Safe to call once from the timeout handler; it does not itself halt the processor.

test_framework_pass()

void test_framework_pass

(

void

)

Record and report a passing test.

test_framework_remove()

void test_framework_remove

(

void

)

Remove the test framework configuration.

test_framework_reset()

void test_framework_reset

(

void

)

Reset the current test context and counts.

test_framework_run_cases()

int test_framework_run_cases	(	const char *	module,
		const struct test_case *	cases,
		size_t	count )

Run a table of test cases, respecting skip flags.

Iterates through the table, calling TEST_BEGIN for each entry:

• skip == true -> reported via test_framework_skip(SKIP_FEATURE_DISABLED).
• run == NULL -> reported as a SKIP_NOT_IMPLEMENTED skip.
• otherwise -> run() is executed.

Every case is visited even if an earlier one fails, so the run summary stays complete; the first non-zero run() result is returned.

Parameters

module	- Test module name (passed to TEST_BEGIN).
cases	- Array of test cases.
count	- Number of entries in the cases array.

Returns

0 if all pass/skip, first non-zero run() result otherwise.

test_framework_run_end()

void test_framework_run_end

(

void

)

Disarm the watchdog, print the final counts and end the run.

test_framework_run_start()

void test_framework_run_start

(

void

)

Start a test run, reset its counts and arm the watchdog.

test_framework_section()

void test_framework_section

(

const char *

name

)

Print a human-readable section marker.

Parameters

name	- Section name.

test_framework_set_name()

void test_framework_set_name

(

const char *

name

)

Select the current test name.

Parameters

name	- Test name.

test_framework_skip()

void test_framework_skip	(	const char *	category,
		const char *	message )

Record and report a skipped test.

Parameters

category	- Optional skip category.
message	- Skip reason.

test_framework_value()

void test_framework_value	(	const char *	name,
		uint64_t	value )

Report a named test value without changing the counts.

Parameters

name	- Value name.
value	- Value to report.

test_framework_wait_us()

void test_framework_wait_us

(

uint32_t

duration_us

)

Invoke the configured microsecond delay callback.

Parameters

duration_us

- Delay duration in microseconds.