Single-header testing framework with pretty-printed output. More...

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <time.h>

Include dependency graph for test.h:

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

Classes
struct	_TrFailureMsg

Macros
#define	TR_RESET (_tr_use_colors() ? "\x1b[0m" : "")
#define	TR_BOLD (_tr_use_colors() ? "\x1b[1m" : "")
#define	TR_DIM (_tr_use_colors() ? "\x1b[2m" : "")
#define	TR_GREEN (_tr_use_colors() ? "\x1b[32m" : "")
#define	TR_RED (_tr_use_colors() ? "\x1b[31m" : "")
#define	TR_YELLOW (_tr_use_colors() ? "\x1b[33m" : "")
#define	TR_WHITE (_tr_use_colors() ? "\x1b[97m" : "")
#define	TR_MAX_FAILURES_PER_TEST 16
#define	TR_FAILURE_MSG_LEN 256
#define	EXPECT(cond)
	Evaluates a condition. Records and counts the failure if false.
#define	EXPECT_FATAL(cond)
	Like EXPECT but aborts immediately on failure.
#define	EXPECT_STR8_EQ(a, b)
	Asserts two String8 values are exactly equal.
#define	TEST_CASE(name)
	Declares a test case function.
#define	BEGIN_SUITE(name)
	Open a named suite block. Must be paired with END_SUITE.
#define	END_SUITE
	Close a suite block opened with BEGIN_SUITE.
#define	RUN_TEST(name)
	Execute a test case and print the result.

Typedefs
typedef void(*	_TrTestFn) (void)

Functions
static int	_tr_use_colors (void)
static void	_tr_record_failure (const char file, int line, const char expr)
static void	_tr_run_test (_TrTestFn fn, const char *name)
	Executes a single test function, times it, and prints the result.
static void	_tr_suite_begin (const char *name)
	Prints the suite header and resets per-suite counters.
static void	_tr_suite_end (void)
	Called after all tests in a suite have run.
static void	tr_begin (const char *title)
	Print the top-level banner. Call once at the start of main().
static int	tr_end (void)
	Print the results summary. Return value is the process exit code.

Variables
static _TrFailureMsg	_tr_fail_buf [16]
static int	_tr_fail_count = 0
static int	_tr_total = 0
static int	_tr_passed = 0
static int	_tr_failed = 0
static int	_tr_suite_total = 0
static int	_tr_suite_failed = 0

Detailed Description

Single-header testing framework with pretty-printed output.

Everything in one place: test case definitions, assertions, suite grouping, timing, ANSI colors, and the results summary.

Layout: cbase test suite

Base

PASS macros_math (0ms)

PASS macros_linked_list (0ms)

FAIL strings_operations (0ms)

test_base.c:42 EXPECT(hw.size == 11)

Memory

PASS arena_allocation (1ms)

Results

----------------------------------------

15 tests 14 passed 1 failed

EXPECT
#define EXPECT(cond)
Evaluates a condition. Records and counts the failure if false.
Definition test.h:161

Usage in test files: #include "test/test.h"

#include "base/base_strings.h"

TEST_CASE(my_feature)

{

EXPECT(1 + 1 == 2);

EXPECT_FATAL(ptr != NULL);

EXPECT_STR8_EQ(result, STR8("expected"));

}

base_strings.h
Sized UTF-8 string slices (String8) and manipulation utilities.

STR8
#define STR8(s)
Wraps a C string literal into a String8 at compile time.
Definition base_strings.h:106

test.h
Single-header testing framework with pretty-printed output.

EXPECT_STR8_EQ
#define EXPECT_STR8_EQ(a, b)
Asserts two String8 values are exactly equal.
Definition test.h:193

TEST_CASE
#define TEST_CASE(name)
Declares a test case function.
Definition test.h:205

EXPECT_FATAL
#define EXPECT_FATAL(cond)
Like EXPECT but aborts immediately on failure.
Definition test.h:175

Usage in main.c: #include "test/test.h"

#include "test_base.c"

#include "test_memory.c"

int main(void)

{

tr_begin("cbase test suite");

BEGIN_SUITE("Base") {

RUN_TEST(macros_math);

RUN_TEST(macros_linked_list);

} END_SUITE;

BEGIN_SUITE("Memory") {

RUN_TEST(arena_allocation);

} END_SUITE;

return tr_end();

}

BEGIN_SUITE
#define BEGIN_SUITE(name)
Open a named suite block. Must be paired with END_SUITE.
Definition test.h:330

tr_end
static int tr_end(void)
Print the results summary. Return value is the process exit code.
Definition test.h:304

END_SUITE
#define END_SUITE
Close a suite block opened with BEGIN_SUITE.
Definition test.h:335

RUN_TEST
#define RUN_TEST(name)
Execute a test case and print the result.
Definition test.h:346

tr_begin
static void tr_begin(const char *title)
Print the top-level banner. Call once at the start of main().
Definition test.h:294

Copyright: 2026 Alfred Jijo (MIT License)

Definition in file test.h.

Macro Definition Documentation

◆ BEGIN_SUITE

#define BEGIN_SUITE ( name )

Value:

do { \

_tr_suite_begin(name);

Open a named suite block. Must be paired with END_SUITE.

BEGIN_SUITE("Memory") {
    RUN_TEST(arena_allocation);
} END_SUITE;

Definition at line 330 of file test.h.

◆ END_SUITE

#define END_SUITE

Value:

_tr_suite_end();                                                                           \
}                                                                                          \
while (0)

Close a suite block opened with BEGIN_SUITE.

Definition at line 335 of file test.h.

◆ EXPECT

#define EXPECT ( cond )

Value:

do {                                                                                       \
    if (!(cond)) {                                                                     \
        _tr_record_failure(__FILE__, __LINE__, #cond);                             \
        _tr_failed++;                                                              \
    }                                                                                  \
} while (0)

Evaluates a condition. Records and counts the failure if false.

Definition at line 161 of file test.h.

◆ EXPECT_FATAL

#define EXPECT_FATAL ( cond )

Value:

do {                                                                                       \
    if (!(cond)) {                                                                     \
        _tr_record_failure(__FILE__, __LINE__, #cond);                             \
        _tr_failed++;                                                              \
        printf("    %s[FATAL]%s %s:%d: %s\n",                                      \
               TR_RED,                                                             \
               TR_RESET,                                                           \
               __FILE__,                                                           \
               __LINE__,                                                           \
               #cond);                                                             \
        abort();                                                                   \
    }                                                                                  \
} while (0)

Like EXPECT but aborts immediately on failure.

Use before any pointer dereference or operation where continuing would cause undefined behaviour.

Definition at line 175 of file test.h.

◆ EXPECT_STR8_EQ

#define EXPECT_STR8_EQ	(		a,
			b )

Value:

EXPECT(str8_match((a), (b)))

str8_match

static b32 str8_match(String8 a, String8 b)

Returns 1 if a and b contain identical bytes (case-sensitive).

Definition base_strings.h:239

Asserts two String8 values are exactly equal.

Definition at line 193 of file test.h.

◆ RUN_TEST

#define RUN_TEST ( name )

Value:

_tr_run_test(test_##name, #name)

_tr_run_test

static void _tr_run_test(_TrTestFn fn, const char *name)

Executes a single test function, times it, and prints the result.

Definition test.h:224

Execute a test case and print the result.

The test function must have been defined with TEST_CASE(name) in a unity-included .c file above this call site.

Definition at line 346 of file test.h.

◆ TEST_CASE

#define TEST_CASE ( name )

Value:

static void test_##name(void)

Declares a test case function.

Expands to: static void test_name(void)

Definition at line 205 of file test.h.

◆ TR_BOLD

#define TR_BOLD (_tr_use_colors() ? "\x1b[1m" : "")

Definition at line 105 of file test.h.

◆ TR_DIM

#define TR_DIM (_tr_use_colors() ? "\x1b[2m" : "")

Definition at line 106 of file test.h.

◆ TR_FAILURE_MSG_LEN

#define TR_FAILURE_MSG_LEN 256

Definition at line 121 of file test.h.

◆ TR_GREEN

#define TR_GREEN (_tr_use_colors() ? "\x1b[32m" : "")

Definition at line 107 of file test.h.

◆ TR_MAX_FAILURES_PER_TEST

#define TR_MAX_FAILURES_PER_TEST 16

Definition at line 120 of file test.h.

◆ TR_RED

#define TR_RED (_tr_use_colors() ? "\x1b[31m" : "")

Definition at line 108 of file test.h.

◆ TR_RESET

#define TR_RESET (_tr_use_colors() ? "\x1b[0m" : "")

Definition at line 104 of file test.h.

◆ TR_WHITE

#define TR_WHITE (_tr_use_colors() ? "\x1b[97m" : "")

Definition at line 110 of file test.h.

◆ TR_YELLOW

#define TR_YELLOW (_tr_use_colors() ? "\x1b[33m" : "")

Definition at line 109 of file test.h.

Typedef Documentation

◆ _TrTestFn

typedef void(* _TrTestFn) (void)

Definition at line 207 of file test.h.

Function Documentation

◆ _tr_record_failure()

void _tr_record_failure	(	const char *	file,
		int	line,
		const char *	expr )

static

Definition at line 131 of file test.h.

◆ _tr_run_test()

void _tr_run_test	(	_TrTestFn	fn,
		const char *	name )

static

Executes a single test function, times it, and prints the result.

Resets the failure capture buffer before calling fn, then compares the global failure counter before and after to detect new failures. Prints a green PASS or red FAIL line with the test name and elapsed milliseconds. On failure, prints each buffered failure message indented beneath the test name.

Do not call this directly - use the RUN_TEST macro.

Parameters

fn	The test function to run.
name	The display name of the test (stringified by RUN_TEST).

Definition at line 224 of file test.h.

◆ _tr_suite_begin()

void _tr_suite_begin ( const char * name )

static

Prints the suite header and resets per-suite counters.

Called by BEGIN_SUITE. Resets _tr_suite_total and _tr_suite_failed to zero so per-suite statistics are tracked independently.

Parameters

name	The suite display name.

Definition at line 270 of file test.h.

◆ _tr_suite_end()

void _tr_suite_end ( void )

static

Called after all tests in a suite have run.

Currently a no-op reserved for future suite-level summary output (e.g. a per-suite pass/fail count line). The _tr_suite_total and _tr_suite_failed counters are available here if you want to uncomment a summary.

Definition at line 285 of file test.h.

◆ _tr_use_colors()

int _tr_use_colors ( void )

static

Definition at line 98 of file test.h.

◆ tr_begin()

void tr_begin ( const char * title )

static

Print the top-level banner. Call once at the start of main().

Parameters

title The suite title string.

Definition at line 294 of file test.h.

◆ tr_end()

int tr_end ( void )

static

Print the results summary. Return value is the process exit code.

Returns: 0 if all tests passed, 1 if any failed.

Definition at line 304 of file test.h.

Variable Documentation

◆ _tr_fail_buf

_TrFailureMsg _tr_fail_buf[16]

static

Definition at line 127 of file test.h.

◆ _tr_fail_count

int _tr_fail_count = 0

static

Definition at line 128 of file test.h.

◆ _tr_failed

int _tr_failed = 0

static

Definition at line 154 of file test.h.

◆ _tr_passed

int _tr_passed = 0

static

Definition at line 153 of file test.h.

◆ _tr_suite_failed

int _tr_suite_failed = 0

static

Definition at line 156 of file test.h.

◆ _tr_suite_total

int _tr_suite_total = 0

static

Definition at line 155 of file test.h.

◆ _tr_total

int _tr_total = 0

static

Definition at line 152 of file test.h.

Classes

Macros

Typedefs

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ BEGIN_SUITE

◆ END_SUITE

◆ EXPECT

◆ EXPECT_FATAL

◆ EXPECT_STR8_EQ

◆ RUN_TEST

◆ TEST_CASE

◆ TR_BOLD

◆ TR_DIM

◆ TR_FAILURE_MSG_LEN

◆ TR_GREEN

◆ TR_MAX_FAILURES_PER_TEST

◆ TR_RED

◆ TR_RESET

◆ TR_WHITE

◆ TR_YELLOW

Typedef Documentation

◆ _TrTestFn

Function Documentation

◆ _tr_record_failure()

◆ _tr_run_test()

◆ _tr_suite_begin()

◆ _tr_suite_end()

◆ _tr_use_colors()

◆ tr_begin()

◆ tr_end()

Variable Documentation

◆ _tr_fail_buf

◆ _tr_fail_count

◆ _tr_failed

◆ _tr_passed

◆ _tr_suite_failed

◆ _tr_suite_total

◆ _tr_total