CuTest：轻量级 C 语言单元测试框架实战指南

1. 引言

在 C 语言开发中，单元测试往往被忽视，原因不外乎「没有趁手的框架」「集成成本高」「项目工期紧」。然而，随着项目规模增长，缺乏测试带来的回归风险会成倍放大。CuTest（C Unit Test）正是为解决这一痛点而生的轻量级单元测试框架------它只有一个 .c 文件和一个 .h 头文件，零依赖、零配置，却能提供断言、测试用例组织、自动运行与结果统计等核心能力。

本文将带你从零上手 CuTest：先介绍它的设计理念与核心 API，再通过一个真实可编译运行的示例演示如何编写、组织和运行测试，最后讨论它在实际工程中的集成方式与常见陷阱。

2. CuTest 是什么

CuTest 是一个用纯 C 语言编写的微型单元测试框架，由 Asim Jalis 于 2002 年左右发布。它的全部代码只有两个文件：

CuTest.h：声明测试相关的类型与函数。
CuTest.c：实现测试运行器、断言宏与结果输出。

它的设计哲学可以概括为三点：

极简：不依赖任何第三方库，不要求构建系统，直接编译进你的测试程序即可。
可移植：遵循 C89/C99 标准，几乎可以在任何支持 C 编译器的平台上运行。
透明：测试结果以纯文本输出，便于在 CI 中解析，也便于阅读。

与 Google Test、CppUnit 等重量级框架不同，CuTest 没有 mock 机制、没有参数化测试、没有测试套件的层级继承，它只做一件事：让开发者用最少的代码把「断言 + 用例组织 + 结果统计」跑起来。对于中小型 C 项目，这往往已经足够。

3. 核心 API 速览

CuTest 的 API 非常精简，核心就三个概念：测试用例（Test） 、测试套件（Suite） 和 测试运行器（Runner）。

3.1 断言宏

CuTest 提供了一组断言宏，用于在测试函数中检查条件：

宏	作用
`CuAssertTrue(tc, cond)`	断言条件为真
`CuAssertFalse(tc, cond)`	断言条件为假
`CuAssertIntEquals(tc, expected, actual)`	断言两个 int 相等
`CuAssertStrEquals(tc, expected, actual)`	断言两个字符串相等
`CuAssertPtrEquals(tc, expected, actual)`	断言两个指针相等
`CuAssert(tc, cond, message)`	带自定义消息的断言

所有断言宏的第一个参数都是 CuTest* tc，它代表当前正在运行的测试上下文。断言失败时，框架会记录失败信息并继续执行当前测试函数（而非像某些框架那样立即中止），这有助于在一次运行中收集尽可能多的失败点。

3.2 测试用例与套件

一个测试用例就是一个 void TestXxx(CuTest* tc) 函数，内部使用断言宏检查被测代码的行为。多个相关用例可以注册进同一个测试套件：

c 复制代码

void TestAdd(CuTest* tc) {
    CuAssertIntEquals(tc, 5, add(2, 3));
}

void TestSub(CuTest* tc) {
    CuAssertIntEquals(tc, 1, sub(3, 2));
}

CuSuite* suite = CuSuiteNew();
CuSuiteAddSuite(suite, CuSuiteInit());  // 或逐个添加
SUITE_ADD_TEST(suite, TestAdd);
SUITE_ADD_TEST(suite, TestSub);

SUITE_ADD_TEST 是一个便捷宏，等价于 CuSuiteAdd(suite, CuNewTest("TestAdd", TestAdd))。

3.3 运行与统计

测试运行器负责执行套件中的所有用例并输出结果：

c 复制代码

CuSuiteRun(suite);
CuSuiteSummary(suite, output);
CuSuiteDetails(suite, output);

CuSuiteRun 依次执行每个用例；CuSuiteSummary 输出简洁的统计信息（共多少、通过多少、失败多少）；CuSuiteDetails 输出每个失败用例的详细信息，包括文件名、行号和失败原因。

4. 完整实战：测试一个计算器模块

下面我们通过一个完整的例子，演示 CuTest 从编写到运行的全过程。假设我们要测试一个简单的整数计算器模块 calc.c。

4.1 被测模块

c 复制代码

// calc.h
#ifndef CALC_H
#define CALC_H

int add(int a, int b);
int sub(int a, int b);
int mul(int a, int b);
int div(int a, int b);  // b 为 0 时返回 0

#endif

c 复制代码

// calc.c
#include "calc.h"

int add(int a, int b) { return a + b; }
int sub(int a, int b) { return a - b; }
int mul(int a, int b) { return a * b; }
int div(int a, int b) { return b == 0 ? 0 : a / b; }

4.2 编写测试文件

c 复制代码

// test_calc.c
#include "CuTest.h"
#include "calc.h"

void TestAdd(CuTest* tc) {
    CuAssertIntEquals(tc, 5, add(2, 3));
    CuAssertIntEquals(tc, 0, add(-1, 1));
}

void TestSub(CuTest* tc) {
    CuAssertIntEquals(tc, 1, sub(3, 2));
}

void TestMul(CuTest* tc) {
    CuAssertIntEquals(tc, 6, mul(2, 3));
}

void TestDiv(CuTest* tc) {
    CuAssertIntEquals(tc, 2, div(6, 3));
    CuAssertIntEquals(tc, 0, div(1, 0));  // 除零保护
}

CuSuite* CalcSuite() {
    CuSuite* suite = CuSuiteNew();
    SUITE_ADD_TEST(suite, TestAdd);
    SUITE_ADD_TEST(suite, TestSub);
    SUITE_ADD_TEST(suite, TestMul);
    SUITE_ADD_TEST(suite, TestDiv);
    return suite;
}

int main(void) {
    CuString* output = CuStringNew();
    CuSuite* suite = CalcSuite();

    CuSuiteRun(suite);
    CuSuiteSummary(suite, output);
    CuSuiteDetails(suite, output);
    printf("%s\n", output->buffer);

    return suite->failCount == 0 ? 0 : 1;
}

4.3 编译与运行

将 CuTest.c、CuTest.h、calc.c、calc.h、test_calc.c 放在同一目录，然后编译：

bash 复制代码

gcc -o test_calc test_calc.c calc.c CuTest.c
./test_calc

预期输出：

复制代码

OK (4 tests, 4 assertions)

如果某个断言失败，输出会变成类似：

复制代码

TestTestDiv: test_calc.c:25: expected <2> but was <3>
!!!FAILURES!!!
Run: 4  Failed: 1

main 函数返回非零值，方便接入 CI 系统判断测试是否通过。

5. 测试套件的组织与扩展

当测试用例增多时，建议按模块拆分测试文件，每个模块提供一个 XxxSuite() 工厂函数，再在统一的 main 中汇总：

c 复制代码

CuSuite* CalcSuite();
CuSuite* StringSuite();
CuSuite* ListSuite();

int main(void) {
    CuString* output = CuStringNew();
    CuSuite* all = CuSuiteNew();

    CuSuiteAddSuite(all, CalcSuite());
    CuSuiteAddSuite(all, StringSuite());
    CuSuiteAddSuite(all, ListSuite());

    CuSuiteRun(all);
    CuSuiteSummary(all, output);
    CuSuiteDetails(all, output);
    printf("%s\n", output->buffer);

    return all->failCount == 0 ? 0 : 1;
}

这种「每个模块一个 Suite 工厂 + 顶层汇总」的模式，让测试结构随项目自然生长，而无需引入复杂的测试框架配置。

6. 在真实工程中的集成建议

6.1 与 Makefile 集成

在 Makefile 中增加一个 test 目标：

makefile 复制代码

TEST_SRC = test_calc.c calc.c CuTest.c
test: $(TEST_SRC)
	gcc -o test_runner $(TEST_SRC)
	./test_runner

6.2 与 CI 集成

由于 CuTest 的 main 返回非零表示有失败用例，可以直接接入 GitHub Actions、GitLab CI 等系统，无需额外解析脚本。

6.3 常见陷阱

不要在多线程测试中共享 CuTest* tc：CuTest 本身不是线程安全的，每个线程应使用独立的 runner。
断言宏只应在测试函数内使用 ：不要在生产代码中调用 CuAssert*。
注意 CuAssertStrEquals 的 NULL 处理：传入 NULL 字符串时行为需自行确认，建议先判空再断言。

7. 总结

CuTest 用不到一千行代码，提供了 C 语言单元测试最核心的能力：断言、用例组织、自动运行与结果统计。它没有花哨的特性，却足够稳定可靠，非常适合中小型 C 项目快速建立测试体系。如果你的项目正在寻找一个「零依赖、五分钟上手」的测试方案，CuTest 是一个值得尝试的选择。

8. 参考资料

CuTest 官方主页：http://cutest.sourceforge.net/
CuTest 源码（GitHub 镜像）：https://github.com/asi1024/cutest