TST - Simple C Testing Framework

A lightweight, single-header unit testing framework for C and C++ with zero dependencies

Features • Quick Start • Documentation • Examples • Contributing

</div>

📋 Table of Contents

Overview
Features
Quick Start
Examples
HTML Reports
Documentation
Supported Platforms
Building from Source
Running Tests
Contributing
License
Authors
Acknowledgments

Overview

TST is a modern, lightweight unit testing framework designed specifically for C programs (with full C++ compatibility). Born from the frustration of dealing with complex test frameworks that require extensive build configurations and dependencies, TST provides a simple yet powerful testing solution in a single header file.

Why TST?

🚀 Zero Setup: Just include tst.h and start writing tests
📦 Single Header: Less than 300 lines of code, no external dependencies
🎯 Simple Syntax: Intuitive macros that feel natural in C
⚡ Fast: Minimal overhead, optimized for performance
🔍 Rich Output: Structured logs perfect for both humans and CI/CD pipelines
📊 HTML Reports: Beautiful interactive dashboards with source code extraction
🏷️ Tag-Based Filtering: Run specific test subsets with command-line tags
📈 Data-Driven Tests: Built-in support for parameterized testing
⏱️ Performance Timing: Integrated CPU time measurement
🔧 Flexible: Works with any C compiler on any platform

Features

Core Testing Features

✅ Hierarchical Test Organization: Suites → Cases → Sections
✅ Multiple Assertion Types: tstcheck, tstassert, tstexpect
✅ Conditional Execution: tstskipif for runtime test skipping
✅ Tag-Based Filtering: Selective test execution with +Tag / -Tag
✅ Data-Driven Testing: Automatic iteration over test data arrays
✅ Performance Measurement: Built-in tstclock for timing
✅ Formatted Messages: Printf-style assertion messages
✅ Rich Diagnostics: Notes, output blocks, and custom logging

HTML Report Generator (t2h)

📊 Interactive Dashboards: Click to expand logs and source code
🎨 Syntax Highlighting: Color-coded C/C++ source with keyword highlighting
📁 Multi-Suite Support: Consolidate multiple test logs into one report
🌓 Light/Dark Themes: Toggle between themes for comfortable viewing
📈 Visual Statistics: Pie charts and progress bars for pass/fail/skip distribution
🔍 Source Extraction: Automatic extraction of test case source code
🎯 Line Number Mapping: Links between logs and source code

Developer Experience

🛠️ No Build System Required: Direct compilation with any C compiler
📝 Self-Documenting: Test names serve as specifications
🐛 CI/CD Friendly: --report-error flag for build pipelines
🌍 Cross-Platform: Linux, macOS, Windows (WSL, MinGW, MSVC)
🔗 Zero Dependencies: Uses only standard C library

Quick Start

Installation

Option 1: Copy the Header (Recommended)

Download tst.h and copy it to your project:

# Download from GitHub
curl -o tst.h https://raw.githubusercontent.com/rdentato/tst/main/src/tst.h

# Or clone the repository
git clone https://github.com/rdentato/tst.git
cp tst/src/tst.h /path/to/your/project/

Option 2: Clone the Repository

git clone https://github.com/rdentato/tst.git
cd tst

Your First Test

Create a file test_example.c:

#include "tst.h"

tstsuite("My First Test Suite") {
    tstcase("Basic Arithmetic") {
        tstcheck(1 + 1 == 2, "Addition works");
        tstcheck(5 * 4 == 20, "Multiplication works");
    }
    
    tstcase("String Functions") {
        tstcheck(strlen("hello") == 5);
        tstcheck(strcmp("abc", "abc") == 0);
    }
}

Compile and Run

# Compile (no special flags needed)
gcc -o test_example test_example.c

# Run tests
./test_example

Output:

----- SUIT / test_example.c "My First Test Suite" 2025-11-27 10:30:45
CASE,-- Basic Arithmetic
    4 PASS|  1 + 1 == 2
    5 PASS|  5 * 4 == 20
    `--- 0 FAIL | 2 PASS | 0 SKIP
CASE,-- String Functions
    9 PASS|  strlen("hello") == 5
   10 PASS|  strcmp("abc", "abc") == 0
    `--- 0 FAIL | 2 PASS | 0 SKIP
^^^^^ RSLT \ 0 FAIL | 4 PASS | 0 SKIP 2025-11-27 10:30:45

Examples

Data-Driven Testing

Test the same logic with multiple inputs:

tstcase("Factorial Tests") {
    struct {int input; int expected;} tstdata[] = {
        {0, 1},
        {1, 1},
        {5, 120},
        {10, 3628800}
    };
    
    tstsection("Calculate factorial(%d)", tstcurdata.input) {
        int result = factorial(tstcurdata.input);
        tstcheck(result == tstcurdata.expected,
                "Expected %d, got %d", tstcurdata.expected, result);
    }
}

Tag-Based Filtering

Organize tests by type and run selectively:

tstsuite("API Tests") {
    tstcase("Fast Unit Test", -SlowTests) {
        tstcheck(quick_function() == 0);
    }
    
    tstcase("Database Integration", +RequiresDB, +Integration) {
        tstcheck(db_connect() == 0);
        tstcheck(db_query("SELECT 1") == 0);
    }
}

Run only fast tests:

./test_api -SlowTests

Run integration tests:

./test_api +Integration

Performance Measurement

Measure execution time with built-in timing:

tstclock("Sort 10000 elements") {
    quicksort(array, 10000);
}

tstcheck(is_sorted(array, 10000));
tstcheck(tstelapsed() < 1000000, "Should complete in < 1s");

Conditional Skipping

Skip tests based on runtime conditions:

tstcase("Database Tests") {
    int db_available = check_database();
    
    tstskipif(!db_available) {
        tstcheck(db_query("SELECT * FROM users") == 0);
        tstcheck(db_insert("user1") == 0);
    }
}

For more examples, see the tutorial directory or the programmer's manual.

Shell Testing with tst.sh

TST also provides tst.sh, a bash library for writing shell-based tests that produce TST-formatted output.

Quick Shell Test Example

#!/bin/bash
source "path/to/tst.sh"

tstsuite_begin "Shell Script Tests" "$0"

tstcase_begin "File operations"
  # Auto-detect line numbers
  tstpass "test -f README.md"
  
  result=$(cat README.md | wc -l)
  if [ "$result" -gt 0 ]; then
    tstpass "README.md has content"
  else
    tstfail "README.md has content" "File is empty"
  fi
tstcase_end

tstcase_begin "Command tests"
  tstnote "Testing basic commands"
  
  # Explicit line number (for helper functions)
  if ls /tmp > /dev/null 2>&1; then
    tstpass $LINENO "ls /tmp succeeds"
  fi
tstcase_end

tstsuite_end

Features

TST-Compatible Output: Generates logs that work with t2h HTML reports
Auto-Detect Line Numbers: Uses ${BASH_LINENO[0]} for automatic line tracking
Flexible API: Mirror of tst.h functions for bash scripts
Helper Functions: Built-in comparisons (tst_equal, tst_greater, etc.)

See the Programmer's Manual for complete tst.sh documentation.

HTML Reports

The t2h utility converts test logs into beautiful, interactive HTML reports.

<div align="center"> <img src="docs/html_report.png" alt="HTML Report Example" width="90%"> <p><em>Example of an interactive HTML test report generated by t2h</em></p> </div>

Generate a Report

# From test output
./test_program | t2h > report.html

# From log files
t2h test1.log test2.log > consolidated.html

# With light theme
t2h --light test.log > report.html

Features

Interactive UI

Click test cases to expand logs
Toggle between log and source views
Collapsible sections for multi-suite reports
Light/Dark theme toggle

</td> <td width="50%">

Rich Visualizations

Collapsable test case details
Color-coded status indicators
Color-coded log lines
Syntax-highlighted source code

</td> </tr> </table>

Building t2h

cd src
make t2h

# Or manually
gcc -o t2h t2h.c -lm

Documentation

Quick Reference

| Document | Description | |----------|-------------| | Programmer's Manual | Comprehensive guide with tutorials and examples | | Reference Manual | Complete API reference for tst.h, tst.sh, and t2h | | Tutorial | Step-by-step introduction to TST features | | Design Documents | Architecture and implementation details |

Key Concepts

Test Suite: Top-level container (one per source file)
Test Case: Group of related checks with partial results
Test Section: Isolated subsection with setup/teardown
Assertions: tstcheck (continue), tstassert (abort), tstexpect (silent)
Tags: Runtime filters for selective test execution
Data-Driven: Arrays named tstdata for parameteri

Tst

Install / Use

README

TST - Simple C Testing Framework

📋 Table of Contents

Overview

Why TST?

Features

Core Testing Features

HTML Report Generator (t2h)

Developer Experience

Quick Start

Installation

Option 1: Copy the Header (Recommended)

Option 2: Clone the Repository

Your First Test

Compile and Run

Examples

Data-Driven Testing

Tag-Based Filtering

Performance Measurement

Conditional Skipping

Shell Testing with tst.sh

Quick Shell Test Example

Features

HTML Reports

Generate a Report

Features

Building t2h

Documentation

Quick Reference

Key Concepts