unity-test-framework-c

Overview

This skill covers ThrowTheSwitch Unity - a C unit-testing library ("a single C file and a pair of headers") at throwtheswitch.org/unity and github.com/ThrowTheSwitch/Unity, running on 8-bit MCUs through 64-bit hosts with no preprocessor magic, no auto-generated main, and no C++ requirement.

It is distinct from the Unity game-engine Test Framework (com.unity.test-framework, a runner inside the Unity 3D editor at docs.unity3d.com, covered by unity-test-framework). The two share only a name.

Composes with:

• ceedling-build-runner - the build orchestration that calls generate_test_runner.rb and stitches Unity + CMock + the test binary.
• ceedling-build-runner's references/cmock.md - the CMock-generated mocks Unity asserts against.
• qemu-system-test-runner - for running the cross-built binary on a virtual Cortex-M.
• embedded-coverage-strategy-reference - for the gcov / llvm-cov instrumentation.

When to use

• Unit-under-test is pure C (not C++). For C++ use googletest-embedded-arm.
• Target may be tiny - Unity works on 8-bit AVR / PIC, 16-bit MSP430, and 32-bit Cortex-M0/M3/M4/M7/M33.
• The team already has Ceedling, or wants the canonical ThrowTheSwitch-stack pairing of Unity + CMock + CException.
• The MCU has limited RAM - Unity's footprint is dramatically smaller than GoogleTest's.

Authoring

Minimal test

#include "unity.h"
#include "ringbuffer.h"

void setUp(void) {
    /* runs before each test */
}

void tearDown(void) {
    /* runs after each test */
}

void test_ringbuffer_initially_empty(void) {
    ringbuffer_t rb;
    ringbuffer_init(&rb);
    TEST_ASSERT_TRUE(ringbuffer_is_empty(&rb));
    TEST_ASSERT_EQUAL_size_t(0, ringbuffer_size(&rb));
}

void test_ringbuffer_push_increments_size(void) {
    ringbuffer_t rb;
    ringbuffer_init(&rb);
    TEST_ASSERT_EQUAL_INT(0, ringbuffer_push(&rb, 42));
    TEST_ASSERT_EQUAL_size_t(1, ringbuffer_size(&rb));
}

int main(void) {
    UNITY_BEGIN();
    RUN_TEST(test_ringbuffer_initially_empty);
    RUN_TEST(test_ringbuffer_push_increments_size);
    return UNITY_END();
}

A Unity test is a C function taking no arguments, named with a test or spec prefix. UNITY_BEGIN() initialises counters; RUN_TEST(name) invokes setUp -> test fn -> tearDown and captures the result; UNITY_END() prints the summary and returns a non-zero exit code on failure.

Assertions

The common assertions - TEST_ASSERT_TRUE(c), TEST_ASSERT_EQUAL_INT(a,b) (with _INT8 / _INT16 / _INT32 / _INT64 and _UINT / _HEX widths), TEST_ASSERT_EQUAL_FLOAT(a,b) / TEST_ASSERT_FLOAT_WITHIN(delta,a,b), TEST_ASSERT_EQUAL_STRING(a,b), TEST_ASSERT_EQUAL_MEMORY(a,b,len), TEST_ASSERT_NULL(p). Append _ARRAY to compare arrays (third arg is element count) and _MESSAGE to attach a custom failure string.

The full assertion-family table and the build-time config defines are in references/assertion-api.md.

Skipping and failing explicitly

void test_only_when_calibrated(void) {
    if (!device_calibrated()) {
        TEST_IGNORE_MESSAGE("device not calibrated; skip");
    }
    /* normal asserts */
}

TEST_IGNORE() records an "ignored" result, distinct from pass/fail in the summary.

generate_test_runner.rb

The Ruby script auto/generate_test_runner.rb scans a test file, finds every test_* and spec_* function, and emits a <file>_Runner.c that wires them up:

ruby /path/to/Unity/auto/generate_test_runner.rb \
    test/test_ringbuffer.c test/test_ringbuffer_Runner.c

Then compile test_ringbuffer.c + test_ringbuffer_Runner.c + unity.c and link. Ceedling does this implicitly - see ceedling-build-runner.

Building

Host build (fast inner loop)

gcc -Wall -O0 -g -DUNITY_INCLUDE_DOUBLE \
    -I src -I ext/Unity/src \
    src/ringbuffer.c \
    ext/Unity/src/unity.c \
    test/test_ringbuffer.c test/test_ringbuffer_Runner.c \
    -o test_ringbuffer
./test_ringbuffer

-DUNITY_INCLUDE_DOUBLE enables the _DOUBLE macros (off by default to save flash on tiny MCUs - per the Unity config docs).

Cortex-M0 cross-build (under QEMU)

arm-none-eabi-gcc -mcpu=cortex-m0 -mthumb -O0 -g \
    -DUNITY_OUTPUT_COLOR \
    --specs=rdimon.specs \
    -I src -I ext/Unity/src \
    src/ringbuffer.c ext/Unity/src/unity.c \
    test/test_ringbuffer.c test/test_ringbuffer_Runner.c \
    -o test_ringbuffer.elf -lrdimon
qemu-system-arm -M mps2-an385 -cpu cortex-m0 \
    -nographic -semihosting-config enable=on,target=native \
    -kernel test_ringbuffer.elf

--specs=rdimon.specs provides the ARM semihosting library (developer.arm.com GNU Toolchain), so Unity's printf-based reporting reaches QEMU's stdio.

Build-time configuration

Key defines (UNITY_INCLUDE_DOUBLE, UNITY_OUTPUT_CHAR, UNITY_OUTPUT_COLOR, UNITY_FIXTURE_NO_EXTRAS, UNITY_EXCLUDE_SETJMP) are tabulated in references/assertion-api.md, per the Unity configuration guide.

Running

Console output

Unity prints one line per result + a summary:

test/test_ringbuffer.c:34:test_ringbuffer_initially_empty:PASS
test/test_ringbuffer.c:42:test_ringbuffer_push_increments_size:PASS

-----------------------
2 Tests 0 Failures 0 Ignored
OK

The format is <file>:<line>:<test_name>:<PASS|FAIL|IGNORE>. Failures include the assertion details:

test/test_ringbuffer.c:48:test_overflow_returns_minus_one:FAIL: Expected -1 Was 0

Exit code

UNITY_END() returns the failure count (int). Use it from main:

int main(void) {
    UNITY_BEGIN();
    RUN_TEST(test_x);
    return UNITY_END();   /* 0 on all-pass; non-zero on any failure */
}

CI tools that gate on exit code (CMake CTest, GitHub Actions run: step) work natively.

Parsing results

Console parsing

Unity's text output is intentionally simple - a grep -c ':FAIL:' is enough for a smoke gate:

./test_ringbuffer | tee results.txt
fails=$(grep -c ':FAIL:' results.txt || true)
[ "$fails" -eq 0 ] || exit 1

JUnit XML via Ceedling

Ceedling wraps Unity and emits a JUnit XML report at build/artifacts/test/report.xml - see ceedling-build-runner. The schema matches GoogleTest's, so the same JUnit pipeline works for both.

Custom output

Override UNITY_OUTPUT_CHAR(c) at build time:

/* unity_config.h */
#define UNITY_OUTPUT_CHAR(c)    serial_putc(c)
#define UNITY_OUTPUT_FLUSH()    serial_flush()

On bare-metal, send results over UART → host serial → CI log file.

CI integration

The standalone (no Ceedling) GitHub Actions pipeline - generate runners, build + run on host, then cross-build and run under QEMU - is in references/ci-integration.md. For Ceedling-driven projects, see ceedling-build-runner for the canonical ceedling test:all + JUnit XML flow.

Anti-patterns

Anti-pattern	Why it fails	Fix
Hand-maintaining the test runner	Drift: a new test_* function is silently skipped	Run generate_test_runner.rb in the build; or use Ceedling
TEST_ASSERT_EQUAL_INT on size_t	Width mismatch warns on 64-bit hosts, may overflow on 8-bit	Use TEST_ASSERT_EQUAL_size_t or width-specific _UINT32
TEST_ASSERT_TRUE(strcmp(a,b) == 0)	Failure message reports "Expected true, got false" - useless	Use TEST_ASSERT_EQUAL_STRING(a,b)
TEST_ASSERT_EQUAL_MEMORY with len=sizeof(*p) on a struct with padding	Padding bytes vary; intermittent failures	Initialise structs with memset(.., 0, sizeof) before fill, or compare fields individually
Calling RUN_TEST outside UNITY_BEGIN/UNITY_END	Asserts work but the summary is wrong	Always bracket runs with UNITY_BEGIN / UNITY_END
Mixing the C library with the game-engine Test Framework	Build sees two unity.h headers; one wins randomly	Don't co-locate; keep unity-test-framework to game-engine projects
Float comparison with TEST_ASSERT_EQUAL_FLOAT and exact values	Floating-point equality is fragile	Use TEST_ASSERT_FLOAT_WITHIN(epsilon, a, b)
UNITY_EXCLUDE_SETJMP on a target that has setjmp	Loses early-abort on fatal assert; tests run on after corruption	Only exclude when the toolchain genuinely lacks setjmp

Limitations

• No native parameterised tests. Unity has no TEST_P equivalent. Loop with a fixture struct and call TEST_ASSERT_* inside; report the iteration via _MESSAGE suffix.
• No native test discovery. Without generate_test_runner.rb (or Ceedling), each test must be manually listed in main.
• Single-threaded. Unity's failure-recovery uses setjmp/ longjmp; concurrent tests in the same process collide. RTOS tests should run tests serially on the test thread.
• No GoogleMock-style matchers. Mocks live in CMock; matcher expressivity is per ceedling-build-runner's references/cmock.md.
• TEST_ASSERT_EQUAL_FLOAT precision is configurable but global. UNITY_FLOAT_PRECISION applies to every float compare in the suite; per-test precision needs _WITHIN.
• 8-bit targets benefit from UNITY_FIXTURE_NO_EXTRAS. Default builds include features (per-test color, fixture hooks) that bloat tiny MCUs.

References

Cited inline. Foundational documents:

• ThrowTheSwitch Unity overview - www.throwtheswitch.org/unity.
• Unity README - github.com/ThrowTheSwitch/Unity.
• Unity Configuration Guide - github.com/ThrowTheSwitch/Unity/blob/master/docs/UnityConfigurationGuide.md.
• ARM GNU Toolchain (--specs=rdimon.specs, semihosting) - developer.arm.com Tools and Software / GNU Toolchain.
• Unity game-engine Test Framework (separate tool; see unity-test-framework) - docs.unity3d.com/Packages/com.unity.test-framework@latest.
• Sibling skills: ceedling-build-runner (CMock semantics in its references/cmock.md), googletest-embedded-arm, qemu-system-test-runner, embedded-coverage-strategy-reference.