使用 Polyspace Test xUnit API 编写 C/C++ 测试并通过命令行运行测试

此示例展示了如何使用 Polyspace^® Test™ xUnit API 编写和执行 C/C++ 测试。此测试调用一个函数，使用输入参数值，并验证该函数是否返回期望值。

Polyspace Test xUnit API 包括可在 C/C++ 中调用的宏，用于执行以下操作：

指定测试配置或脚手架（例如测试设置和拆解）。
封装测试体。
指定测试评估。

以及其他操作。除了可用于 C 代码的宏之外，也适用于 C++ 代码的该 API 还提供了可为每个测试实例化的测试脚手架类。

示例文件

要遵循本教程中的步骤，您可以按照本教程中所述将代码复制到 .c 文件中。

或者，本教程中使用的文件位于文件夹 polyspaceroot\polyspace\examples\doc_pstest\getting_started 中，您可以将这些文件复制到可写位置并继续本教程。其中，polyspaceroot 是 Polyspace 的安装文件夹，例如 C:\Program Files\Polyspace\R2026a。

编写测试用例

在此示例中，您使用输入值 5 测试文件 algo.c 中的函数 saturate_and_cache，并检查该函数是否返回期望值 5。

下面的代码展示了一个使用 xUnit API 编写的简单测试。要运行该测试，请将代码保存在文件 test.c 中。

#include <pstunit.h>

/* Tested function. */
extern int saturate_and_cache(int value);

PST_SIMPLE_TEST(test_value_not_saturated) {
    int value_not_saturated = 5;
    int actual_value;
    
    actual_value = saturate_and_cache(value_not_saturated);
    PST_VERIFY_EQ_INT(actual_value, value_not_saturated);
}

#ifndef PSTEST_BUILD
int main(int argc, char *argv[]) {
    PST_ADD_SIMPLE_TEST(test_value_not_saturated);
    return PST_MAIN(argc, argv);
}
#endif

该测试用例包括 Polyspace Test xUnit API 中的以下宏：

PST_SIMPLE_TEST - 这个宏用于为新测试 test_value_not_saturated 定义测试代码。
PST_VERIFY_EQ_INT - 这个宏用于检查其第一个整数参量是否等于其第二个参量。
PST_ADD_SIMPLE_TEST - 这个宏用于将测试添加到已注册测试的列表中。
PST_MAIN - 这个宏表示运行已注册测试的 Polyspace Test main 函数。
PSTEST_BUILD - 这个宏用于从 Polyspace 平台用户界面中的工程编译测试。如果您没有将 main 函数放入预处理器指令 #ifndef PSTEST_BUILD #endif 中，则您会在工程编译过程中看到多个 main 错误。有关详细信息，请参阅在 Polyspace 平台用户界面中向工程添加 C/C++ xUnit 测试。

有关 Polyspace Test API 中提供的宏的详细信息，请参阅：

生成测试用例可执行文件

要生成测试用例可执行文件，需要编译源文件（algo.c 和 saturate.c）以及以下文件：

包含您的测试的文件 test.c。
Polyspace Test 附带的文件 pstunit.c。该文件位于文件夹 polyspaceroot\polyspace\pstest\pstunit\src 中。其中，polyspaceroot 是 Polyspace 的安装文件夹，例如 C:\Program Files\Polyspace\R2026a。

在编译代码时添加文件夹 polyspaceroot\polyspace\pstest\pstunit\include 作为包含文件夹。例如，如果您使用的是 GCC 编译器，请运行以下命令：

gcc algo.c saturate.c test.c polyspaceroot\polyspace\pstest\pstunit\src\pstunit.c -I . -I polyspaceroot\polyspace\pstest\pstunit\include -o testrunner

此命令生成一个名为 testrunner 的可执行文件，其可以执行测试。

运行测试用例可执行文件

运行在上一步中生成的可执行文件。例如，如果您运行了前面的 GCC 命令，请输入以下可执行文件：

testrunner.exe

（或者，在 Linux^® 中，则输入 ./testrunner）。

对于通过的测试结果，您会看到以下日志：

| Running tests   |            |
|-----------------|------------|
| Running         | suite      | pst_default_suite
|-----------------|------------|
| Running         | test       | test_value_not_saturated
|            PASS | test       | test_value_not_saturated
|-----------------|------------|
|            PASS | suite      | pst_default_suite

|        |  Total | Passed | Failed | Incomplete
|--------|--------|--------|--------|------------
| Suites |      1 |      1 |      0 |          0
|  Tests |      1 |      1 |      0 |          0

您可以通过向可执行文件追加标志来修改测试结果格式。例如，如果您只想输出包含失败测试详细信息的简短摘要，则可向可执行文件追加 -format brief 标志。要查看所有可用标志，请输入：

testrunner.exe -h

有关结果格式的详细信息，请参阅Results Format of Tests Written Using Polyspace Test API。

进一步探查

在此示例中，您直接在 main 函数中注册了测试。不过，您也可以分别地注册各个测试，并从 main 函数调用一组已注册测试。这样，您可以继续向组中添加新测试，而无需修改 main 函数。

您可以使用宏 PST_REGFCN 注册一组测试，并使用另一个宏 PST_REGFCN_CALL 从 main 函数调用这些测试。在上面的示例中，将：

int main(int argc, char *argv[]) {
    PST_ADD_SIMPLE_TEST(test_value_not_saturated);
    return PST_MAIN(argc, argv);
}

替换为：


PST_REGFCN(myRegFcn) {
    PST_ADD_SIMPLE_TEST(test_value_not_saturated);
}

int main(int argc, char *argv[]) {
    PST_REGFCN_CALL(myRegFcn);
    return PST_MAIN(argc, argv);
}