数据类型、生成器和文件格式

概述

Coco 测试引擎使用 JSON 格式存储测试数据和配置选项。在下文中，我们将讨论 JSON 与 C++ 类型之间的对应关系、用于创建输入数据的生成器以及数据文件和配置文件的格式和结构。

数据目录

Coco 测试引擎的配置和数据文件存储在公共目录中。根据 Coco 测试引擎的运行方式，此目录的指定方式不同。

使用 cocotestengine 程序，它通过 --data-dir 选项指定。
使用第三方框架集成时，尝试以下顺序的三种可能：
- 使用 COCOTEST_SET_DATADIR 宏定义的源代码中的目录，
- COCOTEST_DATADIR 环境变量的内容，或
- 当前工作目录。

数据类型

测试数据以 JSON 文件格式序列化。值是从其 JSON 中的字符串表示形式中读取的，并通过 COCOTEST_FETCH 宏解析为相应的 C++ 类型。另一方面，C++ 类型中的值通过 COCOTEST_CHECK 宏序列化为相应的 JSON 类型。以下是所有支持的数据类型及其 JSON 和 C++ 等效类型列表。

名称	JSON 类型	C++ 类型
Null	`null`	(表示缺失值，将导致错误)
布尔	`true` 或 `false`	`bool`
整数	number	`int`、`long`、`long long`
无符号整数	number	`unsigned int`、`unsigned long`、`unsigned long long`
浮点数	number	`double`
字符串	string	`std::string`、`QString`[*]

[*] 需要 COCOTEST_HAS_QT 预处理器宏定义。

测试数据文件

数据文件包含用于执行特定测试的输入值以及与结果进行比较的预期输出值。其文件名格式为<testname>.data.json。基本名称<testname>必须与测试源代码中COCOTEST和COCOTEST_BEGIN宏的参数相匹配。

数据文件包含一个顶层JSON对象，该对象可以有一个可选的"types"成员，后面跟一个必需的"data"成员。

{
    "types": {
        ...
    },
    "data": [
        ...
    ]
}

"types"成员是一个对象，它包含必需的成员"inputs"和"outputs"。这些成员反过来也是对象，其成员分别是输入和输出参数的名称。每个参数也是一个拥有必需属性"type"的对象。属性"type"的值必须是数据类型部分表格中Name列的条目之一。

"types": {
    "inputs": {
        "<input1>": {
            "type": "<input1 type>"
        },
        "<input2>": {
            "type": "<input2 type>"
        },
        ...
    },
    "outputs": {
        "<output1>": {
            "type": "<output1 type>"
        },
        "<output2>": {
            "type": "<output2 type>"
        },
        ...
    }
}

"data"成员是一个对象的数组。每个对象代表一条数据记录，包含必需的成员"inputs"和"outputs"，以及可选的成员"validated"和"crash"。成员"inputs"和"outputs"必须包含名称/值对，其中名称是"types"字段中定义的相同参数名称，而值是执行测试将使用的数据。特别是，输入参数将用于填充COCOTEST_FETCH宏声明的变量的值，而输出参数将用于验证COCOTEST_CHECK宏的参数变量。

"data": [
    {
        "inputs": {
            "<input1>": <input1 value>,
            "<input2>": <input2 value>,
            ...
        },
        "outputs": {
            "<output1>": <output1 value>,
            "<output2>": <output2 value>,
            ...
        },
        "validated": true,
        "crash": true
    },
    {
        "inputs": {
            "<input1>": <input1 value>,
            "<input2>": <input2 value>,
            ...
        },
        "outputs": {
            "<output1>": <output1 value>,
            "<output2>": <output2 value>,
            ...
        }
    }
]

生成器

名称	参数	输出C++类型	输出描述
UniformInt	`min`，`max`	`int`	在[min, max]范围内的均匀分布的整数。
UniformFloat	`min`，`max`	`double`	在[min, max]范围内的均匀分布的浮点数。
PositiveInt	`mean`	`int`	以`mean`为期望值的指数分布[*]非负整数。
ExponentialFloat	`mean`	`double`	以`mean`为期望值的指数分布[*]非负浮点数。
NormalFloat	`mean`，`stdev`	`double`	以`mean`为中心，标准差为`stdev`的高斯分布的浮点数。
RegExpString	`meanLength`，`pattern`，可选：`characterRanges`	`std::string`，`QString`	匹配正则表达式`pattern`的随机字符串。参数`meanLength`确定由*和+运算符产生的子字符串的平均长度。可选参数`characterRanges`是一个包含 Unicode区块名称（Unicode区块名称），例如 "Latin-1 补充"，和以下形式的范围`[min, max]`，例如 `["a", "z"]` 和 `[1234, 1400]` 这个列表决定了生成的字符串中会出现哪些字符。如果未设置，则默认范围为基本拉丁字母。

[*] 指数分布表示从0到mean和从mean到无穷大的值出现的概率相同。

配置文件

cocotestengine的配置文件以JSON格式编写。其名称的格式为<testname>.cfg.json，其中<testname>是它所指的测试的名称。

它包含两个部分。""inputs""部分包含测试代码中关于COCOTEST_FETCH 宏的参数条目，而""outputs""部分包含测试中COCOTEST_CHECK 宏使用的变量的名称。

""inputs""部分中的每个条目都有一个由COCOTEST_FETCH 宏声明的变量的名称；例如下文中的 <input1> 或 <input2>。每个条目都是一个字典，指定了生成该变量值的生成器。字典中有一个条目，"generator" 指定了生成器的名称；注意，生成器创建的值的类型必须与测试代码中COCOTEST_FETCH语句声明的变量的类型一致。字典中还有更多的条目，每个生成器的每个参数和其值对应一个。所有这些条目都是必需的，但需要哪些条目取决于生成器。

""outputs""部分包含所有在测试中以COCOTEST_CHECK 宏为参数的变量的名称；它们的顺序不重要。

{
    "inputs": {
        "<input1>": {
            "generator": "<generator1 name>",
            "<param1_1>": <param1_1 value>,
            "<param1_2>": <param1_2 value>,
            ...
        },
        "<input2>": {
            "generator": "<generator2 name>",
            "<param2_1>": <param2_1 value>,
            "<param2_2>": <param2_2 value>,
            ...
        },
        ...
    },
    "outputs": [
        "<output1>",
        "<output2>",
        ...
    ]
}

运行配置文件

运行配置文件用于与第三方框架集成。它是用JSON格式编写的。其名称的形式为<testname>.run.json，其中<testname> 是它所引用的测试名称。

它具有以下格式，其中只要求"exec_mode" 和 "max_tries"：

{
    "exec_mode": <Mode>,
    "max_coverage": <Float>,
    "max_time": <Integer>,
    "max_tries": <Integer>,
    "save_interval": <Integer>,
    "seed": <Integer>,
    "verbose": <Boolean>
}

参数具有以下效果：

"exec_mode"：确定执行模式。值可能如下：
- "Test"：运行现有行，并验证结果是否与数据文件中的结果一致。
- "Learn"：运行现有行；然后将其输出存储到数据文件中。
- "Discovery"：发现新的测试。
此条目是必需的。有关详细信息，请参阅运行模式。
"max_coverage"：设置发现停止后的覆盖率。
值是一个小数，表示百分比。如果在发现过程中，覆盖率达到或超过此值，则发现停止。如果参数为负值或不存在，则在检查发现过程结束时忽略覆盖率。
"max_time"：设置发现过程的最大持续时间。
值是一个整数，表示发现过程可能持续的时间（以秒为单位）。如果达到或超过此时间，则发现停止。如果参数值为0或不存在，则忽略发现过程的持续时间。
"max_tries"：设置用于发现过程的新生成行的最大数量。
值是一个整数。如果超过该数量，则发现停止。此条目是必需的。
"save_interval"：找到的测试数据的自动保存间隔。
该参数是一个整数，指定秒数。如果它大于0，则指定从当前找到的行保存到数据文件中的时间的间隔。如果该值为0，则在发现过程结束之前不保存数据。默认值为60秒。
"seed"：用于测试数据生成中随机数生成器的种子。
默认情况下，将使用自从纪元以来的秒数。
"verbose"：如有额外的输出，则打印。

执行状态

在进行回归测试时，记录在 .csexe 文件中的执行也将包含行的状态。这是判断COCOTEST_CHECK()对所有比较是否成功以及行是否经过验证的组合。

PASSED：测试成功且已验证
CHECK_MANUALLY：测试成功但 未验证
FAILED：测试 未成功 且已验证
INCIDENT：测试 未成功 且 未验证

测试数据编辑器与第三方单元测试框架集成