仓颉 unittest 选项注册与描述 API 详解:std.unittest.common 函数篇
仓颉 unittest 选项注册与描述 API 详解:std.unittest.common 函数篇
std.unittest.common 是仓颉单元测试框架的公共支撑包,为框架提供选项校验、选项描述与通用打印等基础能力。本文以该包的函数 API 文档为主体,系统讲解 registerOptionValidator、setOptionInfo、setOrUpdateOptionInfo、toStringOrPlaceholder 四个函数的签名、参数语义与典型应用场景,并结合 @UnittestOption 宏、OptionValidity 枚举、OptionInfo 结构体等关联 API,说明如何为自定义测试选项注册校验器、维护帮助信息,以及如何在框架输出中对任意值进行安全的字符串化。读完本文,你将掌握仓颉 unittest 自定义选项体系的完整链路,并能在自己的测试项目中正确使用这些底层函数。
一、std.unittest.common 包在测试框架中的定位
在仓颉标准库中,unittest 包负责测试框架主体,unittest_testmacro 包提供 @Test、@TestCase、@Configure、@UnittestOption 等声明式宏,而 unittest_common 包 则"为单元测试框架提供了打印所需的类型和一些通用方法"。本包不仅包含本文要讲的 4 个函数,还提供:
- 接口:DataProvider、DataShrinker、DataStrategy、PrettyPrintable、KeyFor;
- 类:Configuration、ConfigurationKey、PrettyPrinter、PrettyText;
- 枚举:Color、OptionValidity;
- 结构体:OptionInfo;
- 异常类:UnittestOptionValidationException。
可以看出,本文涉及的 4 个函数正是围绕"测试选项"这一主题组织起来的:选项如何被验证、如何被描述、如何被打印。它们与 @UnittestOption 宏共同构成"自定义测试配置项"的完整能力。
二、选项验证体系:registerOptionValidator
2.1 函数签名与参数
public func registerOptionValidator(name: String, validator: (Any) -> OptionValidity): Unit
该函数用于注册自定义选项验证器,参数如下:
| 参数 | 类型 | 含义 |
|---|---|---|
name |
String | 选项名称 |
validator |
(Any) -> OptionValidity | 检查选项是否合法的函数 |
验证器以 Any 作为入参,意味着它需要处理该选项可能出现的任意类型的值;返回值 OptionValidity 是验证结论的载体。
2.2 验证结果枚举 OptionValidity
验证器返回的 OptionValidity 枚举共有三个取值:
public enum OptionValidity {
| UnknownOptionType
| InvalidOption(String)
| ValidOption(ConfigurationKey)
}
UnknownOptionType:未知状态,仅在验证出现内部错误时出现,正常流程下不应主动返回该值;InvalidOption(String):选项验证无效,String载荷携带无效的原因描述;ValidOption(ConfigurationKey):选项值有效,载荷中的 ConfigurationKey 是"选项值在配置项中对应键值对的键名"。
从源码结构看,ConfigurationKey 是一个提供了判等(equals / == / !=)与 hashCode 方法的抽象键对象,验证通过后返回它,便于后续在 Configuration 中定位该选项的存储键。
2.3 首选用法:使用 @UnittestOption 宏而非直接调用
原文档特别强调:大多数情况下,用户应该使用 @UnittestOption 宏,而不是直接使用 registerOptionValidator 函数。宏的声明式语法示例见 unittest_testmacro 包的宏文档:
@UnittestOptionString, Int
@UnittestOptionString
@UnittestOptionA, B
@UnittestOptionBool
@UnittestOptionInt
该宏的参数是类型、选项名称、可选的验证器回调和可选的描述。宏层面的严格检查"可以防止笔误和使用错误类型的值"——这正是 registerOptionValidator 在底层落实的机制。
使用宏时应注意其规则:
- 同一配置项不能被
@UnittestOption重复注册; @UnittestOption必须放在顶层;- 若选项允许多种类型,验证器回调参数类型应为
Any;若只有一种类型有效,则验证器回调参数可为该具体类型; - 验证器回调返回类型为
Bool或?String:true表示有效,false表示无效;Some<String>携带无效原因,None表示有效。
2.4 验证失败时的异常
当框架验证选项值合法性时发现问题,会抛出 UnittestOptionValidationException(继承自核心包 Exception)。该异常与 registerOptionValidator 的 InvalidOption(String) 结论相呼应:验证器返回无效结论后,框架据此触发异常,从而保证"只有已注册、已通过校验的配置项才能与单元测试框架一起使用"。
三、选项描述维护:setOptionInfo 与 setOrUpdateOptionInfo
打印帮助页面时需要知道每个选项的名称、合法类型与含义,这正是 OptionInfo 结构体承载的信息:
public struct OptionInfo {
public let description: ?String
public let name: String
public let types!: HashMap<String, ?String> = HashMap()
public let userDefined: Bool
}
其中 types 是"从选项类型名称映射到值的含义"的映射表。setOptionInfo 与 setOrUpdateOptionInfo 就是向这类信息结构中写入描述内容的入口函数。
3.1 setOptionInfo:整体设置选项描述
public func setOptionInfo(
name: String,
types: Array<String>,
description!: ?String = None
): Unit
参数含义:
| 参数 | 类型 | 含义 |
|---|---|---|
name |
String | 选项名称 |
types |
Array<String> | 可以表示的选项值的有效类型列表 |
description |
?String | 选项描述,命名参数且默认值为 None |
该函数一次性为选项配置其所有合法类型与整体描述。types 中的每个字符串即该选项可接受的类型名称,对应 OptionInfo.types 映射表的键集合。
3.2 setOrUpdateOptionInfo:按类型细化描述
public func setOrUpdateOptionInfo(
name: String,
description: ?String,
ty: String,
typeDescription: String
): Unit
参数含义:
| 参数 | 类型 | 含义 |
|---|---|---|
name |
String | 选项名称 |
description |
?String | 选项的描述;若值不为 None,则覆盖先前的值 |
ty |
String | 类型的字符串形式 |
typeDescription |
String | 该选项类型的描述 |
与 setOptionInfo 相比,本函数粒度更细:它针对某一个具体类型(ty)设置描述(typeDescription),同时支持按需覆盖整条描述(description 非 None 时)。这对应 OptionInfo.types 中"类型名 -> 类型含义"的单个键值对写入,以及 OptionInfo.description 的更新。当选项同时支持多种类型、且各类型语义不同时,该函数即可为每个类型分别补充说明。
四、安全字符串化:toStringOrPlaceholder
4.1 函数签名
public func toStringOrPlaceholder<T>(value: T)
功能:将实现 ToString 的参数转换为字符串表达;不支持 ToString 的转换为默认字符串(占位符)。返回值为 String 类型的参数字符串表达。
4.2 设计动机与典型场景
随机(属性)参数化测试是它的重要应用场景之一。在 参数化测试示例 的失败输出中有这样一段说明:
导致测试失败的实际数据:按顺序列出所有参数以及它们实际导致测试失败的值。其中参数应实现
ToString接口,否则将只打印占位符。
也就是说,当框架需要把任意类型的测试入参打印出来以便开发者定位问题时,会优先走 ToString,对无法字符串化的类型则回退到统一占位符,避免打印过程本身抛出异常。这一"能转换就转换、不能转换就占位"的策略,正是 toStringOrPlaceholder 的名字与语义来源,也体现了"打印过程绝不能因为某个参数类型特殊而中断"的健壮性设计。
类似地,Configuration.toString() 在内部对象未实现 ToString 时输出 '<not printable>',与 toStringOrPlaceholder 的占位符思路一致——整个 unittest.common 包在打印环节始终贯彻这一容错约定。
五、综合实战:从注册到使用的完整链路
将上述 API 串联起来,一个自定义测试选项的完整生命周期如下。
5.1 声明选项(推荐方式)
@UnittestOptionString
@Test
func test_that_derived_type_overwrite_parent_type_value_in_configuration() {
let conf = Configuration()
conf.set(KeyOpt.opt, "a")
let value = conf.get(KeyOpt.opt).getOrThrow()
@PowerAssert(value == "a")
}
宏展开后,配置项的键名称由"首字母大写 + Key 前缀"规则生成:名为 zxc 的配置项,有效键为 KeyZxc.zxc。KeyOpt.opt 即由此而来,它实现了 KeyFor 接口(prop name: String),是 Configuration 中配置项的键类型。
5.2 读写与继承语义
Configuration 是"类似 HashMap"的配置容器,提供 get<T>、getByName<T>、set<T>、setByName<T>、remove<T>、removeByName<T>、clone() 等操作,并正确处理继承场景:子类实例写入的配置值可覆盖父类键对应的值(见宏文档中的 Base/Derived 示例)。
5.3 命令行选项的自动转换
除了宏,命令行 --option=value 形式(见 unittest_basics.md)也会被转换为配置参数,转换规则与 @Configure 类似:
- 省略
=value时视为Bool值true,如--no-color生成noColor = true; - 严格为
true/false的值视为Bool; - 有效十进制整数视为
Int64,如--random-seed=42生成randomSeed = 42; - 有效十进制小数视为
Float64; - 引号包裹的字符串按转义规则解码为
String; - 其余情况逐字作为
String。
这些配置项在进入框架前,都需要经过 registerOptionValidator 注册的校验逻辑把关;校验通过后,其名称与类型描述即可通过 setOptionInfo / setOrUpdateOptionInfo 写入 OptionInfo,用于生成帮助页面。
六、小结
std.unittest.common 的 4 个函数分工清晰、相互配合:
| 函数 | 职责 | 核心关联类型 |
|---|---|---|
registerOptionValidator |
注册选项合法性校验器 | OptionValidity、UnittestOptionValidationException |
setOptionInfo |
设置选项的整体描述与合法类型 | OptionInfo |
setOrUpdateOptionInfo |
按具体类型细化选项描述 | OptionInfo、HashMap |
toStringOrPlaceholder |
将任意值安全地转为字符串表达 | ToString、String |
对绝大多数开发者而言,日常使用应优先借助 @UnittestOption 宏的声明式语法(它会自动生成键、注册校验器并维护描述),仅在需要以编程方式动态注册选项、动态更新帮助信息时,才直接调用 registerOptionValidator、setOptionInfo 与 setOrUpdateOptionInfo;而 toStringOrPlaceholder 则作为框架内部通用的安全打印工具,为测试报告的稳定性兜底。理解这套底层 API,有助于在遇到自定义配置项校验失败、帮助信息缺失等问题时,快速定位根因并正确排查。