仓颉 unittest 选项注册与描述 API 详解:std.unittest.common 函数篇

原创2026-10-14 23:17:001,444 阅读
文章标签:文档知识库

仓颉 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 个函数,还提供:

可以看出,本文涉及的 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,有助于在遇到自定义配置项校验失败、帮助信息缺失等问题时,快速定位根因并正确排查。

登录后查看全文
CangjieCorpus