TestFramework.h File Reference

Shared testing framework for ESP32-C6 comprehensive test suites. More...

#include "esp_log.h"
#include "esp_timer.h"
#include "driver/gpio.h"
#include "freertos/FreeRTOS.h"
#include "freertos/queue.h"
#include "freertos/semphr.h"
#include "freertos/task.h"

Include dependency graph for TestFramework.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	TestResults
	Test execution tracking and results accumulation. More...
struct	TestTaskContext
	Context passed to test task trampoline. More...

Macros
#define	RUN_TEST_1(test_func)
	Standardized test execution macro with timing and result tracking.
#define	RUN_TEST_2(test_name, test_func)
#define	RUN_TEST_GET_MACRO(_1, _2, NAME, ...)   NAME
#define	RUN_TEST(...)   RUN_TEST_GET_MACRO(__VA_ARGS__, RUN_TEST_2, RUN_TEST_1)(__VA_ARGS__)
#define	RUN_TEST_IN_TASK(name, func, stack_size_bytes, priority)
	Run a test function inside its own FreeRTOS task with a custom stack size.
#define	RUN_TEST_SECTION_IF_ENABLED(define_name, section_name, ...)
	Test section configuration helper macros.
#define	RUN_SINGLE_TEST_IF_ENABLED(define_name, test_name, test_func, stack_size, priority)
#define	RUN_TEST_GROUP_IF_ENABLED(define_name, section_name, ...)    RUN_TEST_SECTION_IF_ENABLED(define_name, section_name, __VA_ARGS__)
#define	RUN_TEST_SECTION_IF_ENABLED_WITH_PROGRESS(define_name, section_name, progress_func, ...)
#define	RUN_TEST_SECTION_IF_ENABLED_AUTO_PROGRESS(define_name, section_name, ...)
#define	RUN_TEST_SECTION_IF_ENABLED_WITH_PATTERN(define_name, section_name, blink_count, ...)

Functions
bool	init_test_progress_indicator () noexcept
	Initialize the test progression indicator on GPIO14.
void	flip_test_progress_indicator () noexcept
	Flip the test progression indicator to show next test.
void	cleanup_test_progress_indicator () noexcept
	Cleanup the test progression indicator GPIO.
void	output_section_indicator (uint8_t blink_count=5) noexcept
	Output section start/end indicator on GPIO14.
void	ensure_gpio14_initialized () noexcept
	Automatically initialize GPIO14 test indicator if not already done.
void	test_task_trampoline (void *param)
	FreeRTOS task trampoline to execute a test with a larger dedicated stack.
void	print_test_summary (const TestResults &test_results, const char *test_suite_name, const char *tag) noexcept
	Print standardized test summary.
void	print_test_section_status (const char *tag, const char *test_suite_name) noexcept
	Print standardized test summary.
void	print_test_section_header (const char *tag, const char *section_name, bool enabled=true) noexcept
	Print test section header with consistent formatting.
void	print_test_section_footer (const char *tag, const char *section_name, bool enabled=true) noexcept
	Print test section footer with consistent formatting.

Variables
static bool	g_test_progress_initialized = false
static bool	g_test_progress_state = false
static constexpr gpio_num_t	TEST_PROGRESS_PIN = GPIO_NUM_14

Detailed Description

Shared testing framework for ESP32-C6 comprehensive test suites.

This file provides common testing infrastructure including test result tracking, execution timing, and standardized test execution macros used across all comprehensive test suites.

Author

Nebiyu Tadesse

Date

2025

Copyright

HardFOC

Macro Definition Documentation

RUN_SINGLE_TEST_IF_ENABLED

#define RUN_SINGLE_TEST_IF_ENABLED	(		define_name,
			test_name,
			test_func,
			stack_size,
			priority )

Value:

  do {                                                                                             \
    ensure_gpio14_initialized();                                                                   \
    if (define_name) {                                                                             \
      RUN_TEST_IN_TASK(test_name, test_func, stack_size, priority);                                \
      flip_test_progress_indicator();                                                              \
    } else {                                                                                       \
      ESP_LOGI(TAG, "Test '%s' disabled by configuration", test_name);                             \
    }                                                                                              \
  } while (0)

RUN_TEST

#define RUN_TEST

(

...

)

RUN_TEST_GET_MACRO(__VA_ARGS__, RUN_TEST_2, RUN_TEST_1)(__VA_ARGS__)

RUN_TEST_1

#define RUN_TEST_1

(

test_func

)

Value:

  do {                                                                                             \
    ensure_gpio14_initialized();                                                                   \
    ESP_LOGI(TAG,                                                                                  \
             "\n"                                                                                  \
             "╔══════════════════════════════════════════════════════════════════════════════╗\n"  \
             "║ Running: " #test_func "                                                     \n"    \
             "╚══════════════════════════════════════════════════════════════════════════════╝");  \
    uint64_t start_time = esp_timer_get_time();                                                    \
    bool result = test_func();                                                                     \
    uint64_t end_time = esp_timer_get_time();                                                      \
    uint64_t execution_time = end_time - start_time;                                               \
    g_test_results.add_result(result, execution_time);                                             \
    if (result) {                                                                                  \
      ESP_LOGI(TAG, "[SUCCESS] PASSED: " #test_func " (%.2f ms)", execution_time / 1000.0);        \
    } else {                                                                                       \
      ESP_LOGE(TAG, "[FAILED] FAILED: " #test_func " (%.2f ms)", execution_time / 1000.0);         \
    }                                                                                              \
    vTaskDelay(pdMS_TO_TICKS(100));                                                                \
  } while (0)

Standardized test execution macro with timing and result tracking.

This macro provides:

• Consistent test execution format
• Automatic timing measurement
• Result tracking and logging
• Standardized success/failure reporting

Parameters

test_func

The test function to execute (must return bool)

Requirements:

• TAG must be defined as const char* for logging
• g_test_results must be defined as TestResults instance
• test_func must be a function returning bool (true = pass, false = fail)

Run a single test, either as RUN_TEST(func) or RUN_TEST("name", func)

RUN_TEST_2

#define RUN_TEST_2	(		test_name,
			test_func )

Value:

  do {                                                                                             \
    ensure_gpio14_initialized();                                                                   \
    ESP_LOGI(TAG,                                                                                  \
             "\n"                                                                                  \
             "╔══════════════════════════════════════════════════════════════════════════════╗\n"  \
             "║ Running: %s                                                                 \n"    \
             "╚══════════════════════════════════════════════════════════════════════════════╝",   \
             test_name);                                                                           \
    uint64_t start_time = esp_timer_get_time();                                                    \
    bool result = test_func();                                                                     \
    uint64_t end_time = esp_timer_get_time();                                                      \
    uint64_t execution_time = end_time - start_time;                                               \
    g_test_results.add_result(result, execution_time);                                             \
    if (result) {                                                                                  \
      ESP_LOGI(TAG, "[SUCCESS] PASSED: %s (%.2f ms)", test_name, execution_time / 1000.0);         \
    } else {                                                                                       \
      ESP_LOGE(TAG, "[FAILED] FAILED: %s (%.2f ms)", test_name, execution_time / 1000.0);          \
    }                                                                                              \
    vTaskDelay(pdMS_TO_TICKS(100));                                                                \
  } while (0)

RUN_TEST_GET_MACRO

#define RUN_TEST_GET_MACRO	(		_1,
			_2,
			NAME,
			... )   NAME

RUN_TEST_GROUP_IF_ENABLED

#define RUN_TEST_GROUP_IF_ENABLED	(		define_name,
			section_name,
			... )    RUN_TEST_SECTION_IF_ENABLED(define_name, section_name, __VA_ARGS__)

RUN_TEST_IN_TASK

#define RUN_TEST_IN_TASK	(		name,
			func,
			stack_size_bytes,
			priority )

Run a test function inside its own FreeRTOS task with a custom stack size.

Parameters

name	Test name (string literal)
func	Boolean test function pointer (noexcept)
stack_size_bytes	Task stack size in bytes
priority	Task priority (defaults to 5)

RUN_TEST_SECTION_IF_ENABLED

#define RUN_TEST_SECTION_IF_ENABLED	(		define_name,
			section_name,
			... )

Value:

  do {                                                                                             \
    ensure_gpio14_initialized();                                                                   \
    if (define_name) {                                                                             \
      print_test_section_header(TAG, section_name, true);                                          \
      __VA_ARGS__                                                                                  \
      print_test_section_footer(TAG, section_name, true);                                          \
    } else {                                                                                       \
      print_test_section_header(TAG, section_name, false);                                         \
      ESP_LOGI(TAG, "Section disabled by configuration");                                          \
    }                                                                                              \
  } while (0)

Test section configuration helper macros.

These macros provide conditional test execution based on constexpr constants at the top of test files. They allow test suites to selectively enable/disable specific test categories.

Usage:

1. Define test section enables at the top of your test file using constexpr: static constexpr bool ENABLE_BASIC_TESTS = true; static constexpr bool ENABLE_ADVANCED_TESTS = false;
2. Use the macros to conditionally run test sections: RUN_TEST_SECTION_IF_ENABLED(ENABLE_BASIC_TESTS, "BASIC TESTS", RUN_TEST_IN_TASK("test1", test_function1, 8192, 1); flip_test_progress_indicator(); );

RUN_TEST_SECTION_IF_ENABLED_AUTO_PROGRESS

#define RUN_TEST_SECTION_IF_ENABLED_AUTO_PROGRESS	(		define_name,
			section_name,
			... )

Value:

  RUN_TEST_SECTION_IF_ENABLED_WITH_PROGRESS(define_name, section_name,                             \
                                            flip_test_progress_indicator, __VA_ARGS__)

RUN_TEST_SECTION_IF_ENABLED_WITH_PATTERN

#define RUN_TEST_SECTION_IF_ENABLED_WITH_PATTERN	(		define_name,
			section_name,
			blink_count,
			... )

Value:

  do {                                                                                             \
    ensure_gpio14_initialized();                                                                   \
    if (define_name) {                                                                             \
      print_test_section_header(TAG, section_name, true);                                          \
      output_section_indicator(blink_count); /* Section start indicator */                         \
      __VA_ARGS__                                                                                  \
      output_section_indicator(blink_count); /* Section end indicator */                           \
      print_test_section_footer(TAG, section_name, true);                                          \
    } else {                                                                                       \
      print_test_section_header(TAG, section_name, false);                                         \
      ESP_LOGI(TAG, "Section disabled by configuration");                                          \
    }                                                                                              \
  } while (0)

RUN_TEST_SECTION_IF_ENABLED_WITH_PROGRESS

#define RUN_TEST_SECTION_IF_ENABLED_WITH_PROGRESS	(		define_name,
			section_name,
			progress_func,
			... )

Value:

  do {                                                                                             \
    ensure_gpio14_initialized();                                                                   \
    if (define_name) {                                                                             \
      print_test_section_header(TAG, section_name, true);                                          \
      __VA_ARGS__                                                                                  \
      if (progress_func)                                                                           \
        progress_func();                                                                           \
      print_test_section_footer(TAG, section_name, true);                                          \
    } else {                                                                                       \
      print_test_section_header(TAG, section_name, false);                                         \
      ESP_LOGI(TAG, "Section disabled by configuration");                                          \
    }                                                                                              \
  } while (0)

Function Documentation

cleanup_test_progress_indicator()

void cleanup_test_progress_indicator ( )

inlinenoexcept

Cleanup the test progression indicator GPIO.

Note

This function is automatically called by the test framework

ensure_gpio14_initialized()

void ensure_gpio14_initialized ( )

inlinenoexcept

Automatically initialize GPIO14 test indicator if not already done.

Note

This function is called automatically by the test framework

Here is the call graph for this function:

Here is the caller graph for this function:

flip_test_progress_indicator()

void flip_test_progress_indicator ( )

inlinenoexcept

Flip the test progression indicator to show next test.

Note

This function is automatically called by the test framework macros

Here is the caller graph for this function:

init_test_progress_indicator()

bool init_test_progress_indicator ( )

inlinenoexcept

Initialize the test progression indicator on GPIO14.

Returns

true if successful, false otherwise

Note

This function is automatically called by the test framework

Here is the caller graph for this function:

output_section_indicator()

void output_section_indicator ( uint8_t blink_count = 5 )

inlinenoexcept

Output section start/end indicator on GPIO14.

Parameters

blink_count

Number of blinks to perform (default 5)

Note

This function is automatically called by the test framework macros

print_test_section_footer()

void print_test_section_footer ( const char * tag, const char * section_name, bool enabled = true )

inlinenoexcept

Print test section footer with consistent formatting.

Parameters

section_name	Name of the test section
enabled	Whether the section is enabled

print_test_section_header()

void print_test_section_header ( const char * tag, const char * section_name, bool enabled = true )

inlinenoexcept

Print test section header with consistent formatting.

Parameters

section_name	Name of the test section
enabled	Whether the section is enabled

print_test_section_status()

void print_test_section_status ( const char * tag, const char * test_suite_name )

inlinenoexcept

Print standardized test summary.

Parameters

test_results	The TestResults instance to summarize
test_suite_name	Name of the test suite for logging

Here is the call graph for this function:

Here is the caller graph for this function:

print_test_summary()

void print_test_summary ( const TestResults & test_results, const char * test_suite_name, const char * tag )

inlinenoexcept

Print standardized test summary.

Parameters

test_results	The TestResults instance to summarize
test_suite_name	Name of the test suite for logging

Here is the call graph for this function:

Here is the caller graph for this function:

test_task_trampoline()

void test_task_trampoline ( void * param )

inline

FreeRTOS task trampoline to execute a test with a larger dedicated stack.

Here is the call graph for this function:

Variable Documentation

g_test_progress_initialized

bool g_test_progress_initialized = false

static

g_test_progress_state

bool g_test_progress_state = false

static

TEST_PROGRESS_PIN

constexpr gpio_num_t TEST_PROGRESS_PIN = GPIO_NUM_14

staticconstexpr