Home

UT Control: Modules Overview

This page provides an overview of three core header files within the UT (Unit Testing) framework:

1. ut_control_plane.h
2. ut_kvp.h
3. ut_log.h

These modules work together to enable a streamlined unit testing process, offering functionality for message handling, key-value pair (KVP) data parsing, and logging.

1. ut_control_plane.h: Message-Based Control Plane

Purpose

This module establishes a control plane that facilitates communication between different parts of the system under test. It operates on a message-based paradigm, allowing components to register callback functions that are triggered when specific messages are received.

Key Features

• Initialisation (UT_ControlPlane_Init): Creates a control plane instance associated with a designated port for monitoring incoming messages.
• Callback Registration (UT_ControlPlane_RegisterCallbackOnMessage): Associates message keys (strings) with user-defined callback functions. These callbacks are invoked when a message with the corresponding key is received.
• Life-cycle Management (UT_ControlPlane_Start, UT_ControlPlane_Stop, UT_ControlPlane_Exit): Controls the control plane's operation, allowing you to start/stop message monitoring and release resources when finished.

Usage Example

ut_controlPlane_instance_t *controlPlane = UT_ControlPlane_Init(8080); // Monitor port 8080
UT_ControlPlane_RegisterCallbackOnMessage(controlPlane, "command1", myCallback, NULL); // Register callback for "command1"
UT_ControlPlane_Start(controlPlane);
// ... (Control plane runs, executing callbacks as messages are received)
UT_ControlPlane_Stop(controlPlane);
UT_ControlPlane_Exit(controlPlane); 

For more detailed information on ut-control_plane see ut_control_plane: Overview (ut_control_plane.h)

2. ut_kvp.h: Key-Value Pair (KVP) Parsing

Purpose

This module simplifies the parsing and handling of configuration data stored in key-value pair (KVP) format. It provides functions for reading KVP data from files or memory and retrieving values by key.

Key Features

• KVP Instance Management (ut_kvp_createInstance, ut_kvp_destroyInstance): Creates and destroys instances for holding KVP data.
• Data Loading (ut_kvp_open, ut_kvp_openMemory): Parses KVP data from files or memory buffers into KVP instances.
• Value Retrieval (ut_kvp_getBoolField, ut_kvp_getStringField, etc.): Retrieves values of different data types (boolean, string, integer, float) based on their keys.

Usage Example

ut_kvp_instance_t *kvp = ut_kvp_createInstance();
ut_kvp_open(kvp, "config.txt"); // Load KVP data from file
bool enabled = ut_kvp_getBoolField(kvp, "featureEnabled"); 
char buffer[256];
ut_kvp_getStringField(kvp, "name", buffer, sizeof(buffer));
ut_kvp_destroyInstance(kvp);

ut_kvp: Support for Includes in YAML Files

The ut_kvp module has been enhanced internally to support including external YAML files, providing a way to modularize and reuse configuration data.

Key Features:

• Local File Inclusion: Reference YAML files within your project's directory structure using the !include file:xxx directive.
• Remote File Inclusion: Fetch YAML files from URLs using the !include https://... directive.
• Unlimited Nesting: Include as many files as needed, and those files can include other files, forming a hierarchical structure.

For more detailed on ut_kvp.h ut_kvp: Support for Includes in YAML files

3. ut_log.h: Logging Utilities

Purpose

This module offers logging functionality tailored for unit testing. It enables easy logging of messages to the console (with optional colors) and to a file for detailed analysis.

Key Features

• Logging Macros (UT_LOG, UT_LOG_STEP, UT_LOG_INFO, etc.): Convenient macros for logging messages with different severity levels and automatic inclusion of file/line information.
• Log File Management (UT_log_setLogFilePath, UT_log_getLogFilename): Functions to set the log file path and retrieve the log file name.
• Core Logging Functions (UT_log, UT_logPrefix): Underlying functions for formatted logging, including timestamps and optional prefixes.

Usage Example

UT_log_setLogFilePath("/path/to/logfile.txt");
UT_LOG("Starting test...");
UT_LOG_STEP("Executing step 1");
// ... test logic
UT_LOG_ERROR("Test failed!");

For more detailed information on ut_log.h see ut-log: Overview: UT-Log