varch/doc/unitt.md

## 介绍

`unitt`是一个用于C语言的简单单元测试模块。它定义了多种函数指针类型，涵盖了时钟、测试、测试前设置、测试后清理以及随机输入生成等相关功能对应的类型，同时定义了表示测试用例和测试套件的结构体。此外，还提供了一系列用于断言各种条件是否满足的函数以及执行测试套件的函数，并且通过宏定义方便地对测试用例和测试执行流程进行简化定义与操作，有助于开发者在C语言项目中高效地开展单元测试工作，检查代码功能是否符合预期。

## 接口

### 函数

#### `unitt_det_true`函数
```c
int unitt_det_true(int condition, const char* message);
```
**函数说明**：用于断言给定的条件是否为真。在测试过程中，通过传入要评估的条件表达式以及当条件不满足（即断言失败）时显示的提示消息，如果条件为真，则表示该断言通过，函数返回`UNITT_E_OK`（值为0）；若条件为假，则断言失败，函数返回`UNITT_E_FAIL`（值为 -1），同时可能会依据具体的测试框架实现来输出相应的错误提示消息。
**参数介绍**：
- `condition`：要评估的条件表达式，通常是一个返回值为布尔类型（在C语言中以整型表示，非0为真，0为假）的表达式，例如变量之间的比较、逻辑运算结果等，用于判断特定的测试预期是否满足。
- `message`：当断言失败时需要显示的提示消息，是一个字符串常量，用于告知开发者具体哪个测试条件未通过以及相关的错误信息，方便定位问题所在。

#### `unitt_det_false`函数
```c
int unitt_det_false(int condition, const char* message);
```
**函数说明**：与`unitt_det_true`相反，用于断言给定的条件是否为假。若传入的条件表达式计算结果为假，则断言通过，函数返回`UNITT_E_OK`；若条件为真，则断言失败，函数返回`UNITT_E_FAIL`，同时也会按照设定显示相应的错误提示消息（若测试框架支持消息输出）。
**参数介绍**：
- `condition`：待评估的条件表达式，和`unitt_det_true`中的类似，是一个能得出布尔类型结果（以整型体现）的表达式，不过这里期望其结果为假来使断言通过。
- `message`：断言失败时展示的提示消息，同样为字符串常量，用于清晰指出测试中期望为假的条件却为真的这种错误情况相关信息。

#### `unitt_det_equal`函数
```c
int unitt_det_equal(int expected, int actual, const char* message);
```
**函数说明**：用于断言两个整数是否相等。在单元测试中对比预期的整数值和实际得到的整数值，如果二者相等，则该断言通过，函数返回`UNITT_E_OK`；若不相等，断言失败，返回`UNITT_E_FAIL`，并且会显示指定的错误提示消息来帮助开发者知晓是哪个整数比较出现了差异。
**参数介绍**：
- `expected`：预期的整数值，即开发者期望在测试中得到的整数结果，作为对比的标准值参与断言判断。
- `actual`：实际的整数值，是测试执行后实际产生的整数值，会和预期值进行比较，以此确定是否符合测试预期。
- `message`：当两个整数不相等、断言失败时要显示的提示消息，通过详细的文字描述让开发者能快速明白是哪两个整数对比出现了问题以及对应的测试场景等信息。

#### `unitt_det_nequal`函数
```c
int unitt_det_nequal(int expected, int actual, const char* message);
```
**函数说明**：用于断言两个整数是否不相等。若传入的预期整数值和实际整数值确实不相等，则断言通过，函数返回`UNITT_E_OK`；若二者相等，断言失败，函数返回`UNITT_E_FAIL`，同时会展示对应的错误提示消息，告知开发者本应不相等的两个整数却相等了这一不符合预期的情况。
**参数介绍**：
- `expected`：预期的整数值，作为对比参照，期望其和实际值不同来使断言通过。
- `actual`：实际得到的整数值，与预期值进行对比，用于确定是否满足不相等的断言要求。
- `message`：在断言失败（即两个整数相等）时显示的提示消息，帮助开发者了解具体是哪组整数比较出现了违背预期的情况以及相关测试背景信息。

#### `unitt_det_null`函数
```c
int unitt_det_null(void* pointer, const char* message);
```
**函数说明**：用于断言给定的指针是否为`NULL`。在测试涉及指针操作的代码时，若传入的指针值为`NULL`，则表示该断言通过，函数返回`UNITT_E_OK`；若指针不为`NULL`，则断言失败，函数返回`UNITT_E_FAIL`，同时会输出对应的错误提示消息，方便开发者知晓哪个指针的`NULL`性判断出现了问题。
**参数介绍**：
- `pointer`：要评估的指针变量，其值会被检查是否为`NULL`，以验证相关代码对于指针为空情况的处理是否符合预期，比如函数是否正确处理了传入空指针的边界情况等。
- `message`：当指针不为`NULL`、断言失败时展示的提示消息，详细说明是哪个指针未满足预期的`NULL`状态以及相关的测试情况，便于定位问题源头。

#### `unitt_det_nnull`函数
```c
int unitt_det_nnull(void* pointer, const char* message);
```
**函数说明**：与`unitt_det_null`相反，用于断言给定的指针是否不为`NULL`。若传入的指针不为`NULL`，则断言通过，函数返回`UNITT_E_OK`；若指针为`NULL`，断言失败，函数返回`UNITT_E_FAIL`，并且会显示相应的错误提示消息来提示开发者指针为空不符合预期的情况。
**参数介绍**：
- `pointer`：待评估的指针变量，期望其值不为`NULL`来使断言成立，常用于检查函数返回的指针是否有效、结构体中的指针成员是否正确赋值等测试场景中。
- `message`：在指针为`NULL`、断言失败时要显示的提示消息，告知开发者具体是哪个指针没有达到不为`NULL`的预期以及对应的测试背景等信息，有助于排查问题。

#### `unitt_det_float`函数
```c
int unitt_det_float(float expected, float actual, float epsilon, const char* message);
```
**函数说明**：用于断言两个浮点数是否近似相等。由于浮点数在计算机中的存储和运算存在精度问题，不能简单地用相等判断，所以通过传入可接受的差值（`epsilon`）来确定近似相等的范围。若两个浮点数的差值在`epsilon`范围内，则认为它们近似相等，断言通过，函数返回`UNITT_E_OK`；若差值超出范围，则断言失败，函数返回`UNITT_E_FAIL`，同时会输出指定的错误提示消息告知开发者浮点数比较不符合预期的情况。
**参数介绍**：
- `expected`：预期的浮点数，是开发者期望在测试中得到的浮点数结果，作为近似相等判断的一个参照值。
- `actual`：实际得到的浮点数，与预期浮点数进行对比，依据二者差值和`epsilon`的比较来确定是否满足近似相等的断言要求。
- `epsilon`：可接受的差值，用于界定两个浮点数近似相等的范围，即只要`|expected - actual| <= epsilon`，就认为两个浮点数近似相等，该参数需根据具体的测试精度需求合理设置。
- `message`：当两个浮点数差值超出`epsilon`范围、断言失败时显示的提示消息，帮助开发者明白是哪两个浮点数比较出现了不符合近似相等预期的情况以及对应的测试场景等信息。

#### `unitt_det_string`函数
```c
int unitt_det_string(const char* expected, const char* actual, const char* message);
```
**函数说明**：用于断言两个字符串是否相等。会逐个字符比较传入的预期字符串和实际字符串，如果二者完全一致，则断言通过，函数返回`UNITT_E_OK`；若存在任何字符不同，则断言失败，函数返回`UNITT_E_FAIL`，同时会输出对应的错误提示消息，告知开发者是哪两个字符串比较出现了不一致的情况以及相关测试背景信息。
**参数介绍**：
- `expected`：预期的字符串，即开发者期望在测试中得到的字符串内容，作为对比的标准字符串参与断言判断。
- `actual`：实际的字符串，是测试执行后实际产生的字符串内容，会和预期字符串进行逐一字符的比较，以此确定是否符合测试预期。
- `message`：当两个字符串不相等、断言失败时要显示的提示消息，通过详细文字描述让开发者能快速知晓是哪组字符串对比出现了问题以及对应的测试场景等信息。

#### `unitt_fail_handle`函数
```c
int unitt_fail_handle(const char* name);
```
**函数说明**：用于处理测试失败的情况，当某个测试用例执行失败时，通过传入该失败测试用例的名称，函数可以执行相应的失败处理逻辑，比如记录失败信息、输出特定的错误提示等，并且无论具体处理过程如何，该函数最终都会返回`UNITT_E_OK`，表示对失败情况的处理流程已执行完毕。
**参数介绍**：
- `name`：失败测试用例的名称，为字符串常量，依据这个名称可以定位到具体是哪个测试用例出现了问题，进而执行针对性的失败处理操作，例如在测试报告中准确记录是哪个测试环节失败等。

#### `unitt_execute`函数
```c
void unitt_execute(UNITT* suites, uint32_t count, unitt_failcb_t failcb, const char* specific, const char* filename);
```
**函数说明**：负责执行一系列的测试套件。它会遍历传入的测试套件数组，按照每个测试套件中包含的测试用例依次执行测试操作，在测试过程中会调用相应的设置函数（若有）、执行测试函数、进行断言判断、调用清理函数（若有）等，并依据测试结果更新相关的统计信息（如测试执行次数、通过次数、总耗时等）。如果有测试用例失败，还会调用传入的失败回调函数来处理失败情况。同时，可以根据传入的特定测试名称参数选择只执行某个特定的测试用例，也能指定输出结果的文件名（若为`NULL`则输出到标准输出），以此灵活地控制测试执行和结果输出方式。
**参数介绍**：
- `suites`：指向`UNITT`结构体类型的测试套件数组的指针，`UNITT`结构体中包含了测试套件名称、测试用例数组、测试用例数量以及用于计时的时钟函数指针等关键信息，通过该指针能定位到要执行的各个测试套件及其内部的测试用例情况，是执行测试的核心数据来源。
- `count`：测试套件数组中的元素个数，即要执行的测试套件的数量，用于确定循环遍历测试套件的次数，确保每个测试套件都能被正确处理。
- `failcb`：指向失败回调函数的指针，其类型为`unitt_failcb_t`，当测试用例出现失败情况时，会调用该指针指向的函数来处理失败相关的操作，比如记录失败日志、输出错误提示等，开发者可以自定义符合该类型要求的函数来实现个性化的失败处理逻辑。
- `specific`：特定的测试名称，为字符串常量，若不为`NULL`，则表示只执行名称与之匹配的那个特定测试用例，实现有针对性的测试执行；若为`NULL`，则会依次执行所有测试套件中的全部测试用例。
- `filename`：输出结果的文件名，若为`NULL`，则测试结果会输出到标准输出（通常是控制台）；若指定了具体的文件名，则测试结果会按照一定格式写入到对应的文件中，方便后续查看和分析测试情况。