unity-test-framework-c

Overview

Disambiguation up front: this skill covers ThrowTheSwitch Unity - a C unit-testing library at throwtheswitch.org/unity and github.com/ThrowTheSwitch/Unity. It is distinct from the Unity game-engine Test Framework at docs.unity3d.com (a managed-test runner inside the Unity 3D editor). The two tools share only a name; they have unrelated origins, APIs, and consumers. If you reached this skill looking for the Unity-the-game-engine test framework, the canonical package is com.unity.test-framework documented at docs.unity3d.com and covered by qa-game/unity-test-framework.

Unity is, per throwtheswitch.org/unity, "a Unit-Testing framework written in 100% pure ANSI C" that is "carefully written and self-tested to be portable, working efficiently on tiny 8-bit microcontrollers to 64-bit powerhouses". Per the README at github.com/ThrowTheSwitch/Unity, it is "a single C file and a pair of headers, allowing it to be added to your existing build setup". The framework lets the developer "test in C without littering your source code with additional requirements" - there is no preprocessor magic, no auto-generated main, no C++ requirement.

Composes with:

• ceedling-build-runner - the build orchestration that calls generate_test_runner.rb and stitches Unity + CMock + the test binary.
• ceedling-mocks-reference - 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. Per the throwtheswitch page above, it runs "efficiently on tiny 8-bit microcontrollers".
• 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

Per the Unity README:

#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();
}

Per the README: a Unity test is "just a C function that takes no arguments and returns nothing. By convention, it starts with the word 'test' or 'spec'." 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.

Assertion families

Per the Unity README:

The _MESSAGE suffix is the canonical way to attach context - failures print the message inline. The _ARRAY suffix turns any equality macro into an array-comparing one (third arg is element count).

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

Per the same README, 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

Per the Unity configuration guide (linked above), key defines:

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

Standalone (no Ceedling):

jobs:
  unity-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - name: Install toolchain
        run: sudo apt-get install -y gcc-arm-none-eabi qemu-system-arm ruby
      - name: Generate runners
        run: |
          for t in test/test_*.c; do
            ruby ext/Unity/auto/generate_test_runner.rb "$t" "${t%.c}_Runner.c"
          done
      - name: Build + run on host
        run: |
          gcc -O0 -g -DUNITY_INCLUDE_DOUBLE \
              -I src -I ext/Unity/src \
              src/*.c ext/Unity/src/unity.c \
              test/test_*.c test/*_Runner.c \
              -o build/unity_host
          ./build/unity_host | tee build/host.log
          ! grep -q ':FAIL:' build/host.log
      - name: Cross-build + QEMU run
        run: |
          arm-none-eabi-gcc -mcpu=cortex-m4 -mthumb -O0 -g \
              --specs=rdimon.specs \
              -I src -I ext/Unity/src \
              src/*.c ext/Unity/src/unity.c \
              test/test_*.c test/*_Runner.c \
              -o build/unity_arm.elf -lrdimon
          qemu-system-arm -M mps2-an385 -cpu cortex-m4 \
              -nographic -semihosting-config enable=on,target=native \
              -kernel build/unity_arm.elf | tee build/arm.log
          ! grep -q ':FAIL:' build/arm.log

For Ceedling-driven projects, see ceedling-build-runner for the canonical ceedling test:all + JUnit XML flow.

Anti-patterns

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-mocks-reference.
• 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.
• Distinct from: Unity game-engine Test Framework - docs.unity3d.com/Packages/com.unity.test-framework@latest (covered by qa-game/unity-test-framework).
• Sibling skills: ceedling-build-runner, ceedling-mocks-reference, googletest-embedded-arm, qemu-system-test-runner, embedded-coverage-strategy-reference.