仓颉 mock 框架宏指南:@On 与 @Called 的桩配置与调用验证实战
仓颉 mock 框架宏指南:@On 与 @Called 的桩配置与调用验证实战
导读
std.unittest.mock.mockmacro 是仓颉单元测试 mock 框架的宏包,为开发者提供仅有的两个宏:@On 与 @Called。前者是配置 API 的唯一入口,用于定义 mock/spy 对象成员(以及顶层/静态声明)的行为;后者是验证 API 的核心构造器,用于生成验证语句并断言测试代码与 mock/spy 对象之间的交互。读完本文,你将掌握仓颉 mock 框架从"打桩配置"到"调用验证"的完整链路:桩签名、参数匹配器、操作 API、预期基数、验证块与验证模式,并可直接套用仓库内的实战代码模式编写可维护的单元测试。
mockmacro 包:mock 框架的两个入口宏
在仓颉标准库中,mock 框架的能力分布在两个包中:
std.unittest.mock:提供mock<T>()、spy<T>()构造函数,以及Matchers、Verify、VerifyStatement等配置/验证 API(见 unittest_mock 包总览);std.unittest.mock.mockmacro:提供宏@On与@Called,二者分别是 配置 API 与 验证 API 的语法入口(见 mockmacro 包总览)。
使用时需在测试文件中同时导入两个包(示例来自 mock 框架入门):
import std.unittest.mock.*
import std.unittest.mock.mockmacro.*
两个宏的职责对比如下:
| 宏 | 所属体系 | 核心功能 | 产物 |
|---|---|---|---|
@On |
配置 API | 定义 mock/spy 对象成员(或重新定义 spy 对象、打桩顶层/静态声明)的行为 | 桩(Stub)声明 |
@Called |
验证 API | 创建验证语句,用于断言调用是否发生、次数、参数及顺序 | VerifyStatement 实例 |
@On 宏:配置 API 的唯一入口
@On 宏调用构造桩签名,并返回一个 ActionSelector 子类型实例,通过其上的操作 API 指定桩触发后的行为(详见 mock 基础概念及用法)。
基本用法
最简单的打桩形式如下:当 mock 对象 storage 收到 getComments 方法调用且参数为 testId 时,返回 testComments:
@On(storage.getComments(testId)).returns(testComments)
一个完整的桩声明包含四部分:
@On宏调用中描述的桩签名;- 描述桩行为的操作(如
returns、throws); - (可选)用于设置预期的基数说明符(如
once()、times(2)); - (可选)续体(
then()),支持链式指定后续操作。
桩签名:可打桩的实体与写法
签名用于匹配特定调用子集,可匹配方法、属性 getter/setter、字段读写、静态成员以及顶层函数/变量。实例成员的签名结构为 <mock 对象名>.<成员名>(<参数匹配器>*):
@On(foo.method(0, 1)) // 带参数 0 和 1 的方法调用
@On(foo.method(param1: 0, param2: 1)) // 带命名参数的方法调用
@On(foo.prop) // 属性 getter
@On(foo.prop = 3) // 参数为 3 的属性 setter
独立声明的签名不依赖 mock 对象:
- 顶层函数:
<函数名>(<参数匹配器>*); - 静态函数:
<类名>.<静态方法名>(<参数匹配器>*); - 顶层变量/静态属性字段:
<名称>或<名称> = <参数匹配器>。
运算符函数同样可打桩,此时接收者必须是 mock/spy 对象的单个引用,参数必须是匹配器:
@On(foo + 3) // 'operator func +',参数为 3
@On(foo[0]) // 'operator func []',参数为 0
可打桩的声明包括类和接口的实例成员(含 final 成员)、静态函数/属性/字段、顶层函数和变量;不能打桩扩展成员、Foreign 函数、局部函数与变量、构造器、常量及任意私有声明。
参数匹配器
每个桩签名必须为所有参数提供匹配器,匹配器通过 Matchers 类的静态方法生成,并支持省略 Matcher. 前缀的语法糖。常用匹配器如下:
| 匹配器 | 描述 | 语法糖 |
|---|---|---|
any() |
匹配任意参数 | _ 符号 |
eq(value) |
与 value 结构相等 |
单个 identifier 和常量字面量 |
same(reference) |
与 reference 引用相等 |
单个 identifier |
ofType<T>() |
仅匹配 T 类型的值 |
- |
argThat(predicate) |
仅匹配谓词筛选出的值 | - |
none() |
匹配 Option 类型的 None 值 |
- |
示例:
let p = mock<Printer>()
@On(p.print(_)) // 使用 "_" 代替 any()
@On(p.print(eq("foo"))) // 只匹配 "foo" 参数
@On(p.print("foo")) // 常量字符串可省略显式匹配器
@On(p.print(ofType<Bar>())) // 仅匹配 Bar 类型的参数
let hasQuestionMark = { arg: String => arg.contains("?") }
@On(p.print(argThat(hasQuestionMark))) // 只匹配包含问号的字符串
若方法有默认参数且未显式指定,则默认使用 any() 匹配器。重要规则:函数调用若作为参数匹配器位置出现,会被视为对匹配器的调用,而非真实参数求值,因此 @On(foo.bar(calculateArgument())) 是不正确的写法;应先求出值再传入标识符。
操作 API
每个桩必须指定一个操作。通用操作适用于所有桩:
throws(exception)/throws(exceptionFactory):抛出指定异常(或由工厂构造异常);fails():一旦触发桩,测试立即失败,用于断言某调用"绝不应发生"。
函数与 Getter 类操作(R 为返回类型):
returns():不做任何操作返回(),仅R为Unit时可用;returns(value: R):返回固定值;returns(valueFactory: () -> R):由工厂构造返回值;returnsConsecutively(values):依次返回列表中的下一个元素。
Setter 类操作:doesNothing() 忽略调用(等价于返回 Unit 的 returns())。
spy 特有操作:callsOriginal() 调用原始方法、getsOriginal() 读取原始 getter/字段、setsOriginal() 调用原始 setter/写字段。
预期与基数说明符
除 fails 和 returnsConsecutively 外,操作均返回 CardinalitySelector,可附加预期:once()、atLeastOnce()、anyTimes()、times(expectedTimes)、times(min!, max!)、atLeastTimes(minTimesExpected)。anyTimes() 用于放宽预期(桩从未被触发也不失败);其余说明符会检查上下限——触发次数超过上限立即失败,不足下限在测试代码执行完毕后检查。各操作默认预期基数如下:
| 操作 | 默认期望基数 | 允许自定义 |
|---|---|---|
fails |
不可调用 | 否 |
returns |
atLeastOnce | 是 |
returnsConsecutively |
times(values.size) | 否 |
throws |
atLeastOnce | 是 |
doesNothing |
atLeastOnce | 是 |
(calls/gets/sets)Original |
atLeastOnce | 是 |
桩链(续体)
returnsConsecutively、once()、times(n) 返回续体(Continuation),可通过 then() 继续指定新操作。总预期为链上各段预期之和:
// 依次返回 1、2、3、4
@On(foo.bar()).returnsConsecutively(1, 2, 3, 4)
// 等价写法
@On(foo.bar()).returnsConsecutively(1, 2).then().returnsConsecutively(3, 4)
经典的重试场景:
@On(service.request()).throws(TimeoutException()).times(NUM_OF_RETRIES - 1).
then().returns(response).once()
spy 对象与重新定义
spy 对象默认将成员调用委托给底层真实实例;未命中桩时,mock 抛运行时错误(测试失败),spy 则调用原始实现。可通过 @On 重新定义 spy 行为,如"先超时一次,再走真实实现":
let serviceSpy = spy(service)
@On(serviceSpy.request()).throws(TimeoutException()).once().then().callsOriginal()
静态成员或顶层函数/变量的打桩行为类似 spy:未打桩的声明会调用原始实现。同一声明可用多个桩按参数区分行为,后声明的桩优先;每个桩的预期必须各自满足(桩使用指南)。
@Called 宏:验证语句与验证 API
验证 API 通过在测试执行期间构建的调用日志来运行断言,可验证:调用是否发生、调用次数、调用参数、调用顺序(详见 mock 框架验证 API)。Verify 类是验证 API 的入口,@Called 宏则用于构造验证语句。
验证语句
@Called 宏调用产生 VerifyStatement 实例,它接受桩签名(与 @On 相似),并适用参数匹配器规则:
@Called(foo.bar(1, _)) // 匹配 bar 调用,第一个参数为 1
@Called(Foo.baz) // 匹配 baz 静态属性 getter 调用
注意:@Called 的参数范围内不允许使用 capture 等值监听器匹配器(见 桩使用指南)。
基数函数
VerifyStatement 提供与桩基数说明符类似的函数:once()、atLeastOnce()、times(expectedTimes)、times(min!, max!)、atLeastTimes(minTimesExpected)、never()。这些函数返回同一实例,同一语句不能重置基数,且必须在传入验证块之前设置;未显式设置时使用默认基数。
Verify.that(@Called(foo.bar()).atLeastOnce())
Verify.that(@Called(foo.bar()).once())
验证块:that / unordered / ordered
验证语句本身不执行任何验证,必须放入验证块。调用验证块时立即验证,且不改变调用日志状态(日志中的每个调用可被任意数量的块检查)。单个块仅检查块内语句提及对象的调用。
Verify.that(statement):Verify.unordered(Partial, statement)的别名,检查单个语句,无需列出该对象的所有调用;Verify.unordered(...):无序验证,只检查调用次数,默认基数atLeastOnce();Verify.ordered(...):有序验证,检查调用的确切顺序,默认基数once(),且必须列出块内对象的所有调用,任何未列出的调用都会导致验证失败。
for (i in 0..4) {
foo.bar(i % 2)
}
// 无序:至少调用一次参数 0 和 1 的 bar
Verify.unordered(
@Called(foo.bar(0)),
@Called(foo.bar(1))
)
// 有序:严格按 0、1、0、1 的顺序调用
Verify.ordered(
@Called(foo.bar(0)),
@Called(foo.bar(1)),
@Called(foo.bar(0)),
@Called(foo.bar(1))
)
有序验证还支持跨多个对象检查顺序;若漏列调用,会输出类似如下报告:
验证失败
以下调用未匹配到任何语句:
foo.bar(...) at example_test.cj:6
Exhaustive 与 Partial 模式
无序验证包括两种模式(枚举 Exhaustiveness,见 unittest_mock 枚举):
- Exhaustive(默认):必须列出验证语句所提及 mock/spy 对象的所有调用;
- Partial:只列出部分调用,忽略其余调用。
for (i in 0..4) {
foo.bar(i)
}
// 失败:foo.bar() 的两次调用未在块中列出
Verify.unordered(
@Called(foo.bar(0)).once(),
@Called(foo.bar(1)).once()
)
// 通过:忽略无关调用
Verify.unordered(Partial,
@Called(foo.bar(0)).once(),
@Called(foo.bar(1)).once()
)
动态构建验证块
ordered 与 unordered 均有接受 lambda 的重载,可通过 checkThat(statement) 动态添加语句,适合验证次数在运行时才确定的情况:
let totalTimes = 40
for (i in 0..totalTimes) {
foo.bar(i % 2)
}
Verify.ordered { v =>
for (j in 0..totalTimes) {
v.checkThat(@Called(foo.bar(eq(j % 2))))
}
}
其他工具 API
Verify 类还提供:noInteractions(mocks) 检查指定对象无任何调用;clearInvocationLog() 将日志重置为空(不影响桩预期),用于缩小验证范围:
foo.bar()
Verify.that(@Called(foo.bar())) // OK
Verify.noInteractions(foo) // 失败,foo.bar() 调用在日志中
Verify.clearInvocationLog() // 清除日志
Verify.noInteractions(foo) // OK
Verify.that(@Called(foo.bar())) // 失败
Verify 类的完整静态方法签名见 unittest_mock 包类文档。
验证错误
验证失败时抛出 VerificationFailedException(框架会给出报告,不要捕获该异常)。失败类型包括:调用次数太少/太多、语句不匹配、调用不匹配、意外调用(有序块)、无用交互(noInteractions)。另一种失败类型不相交的语句不是测试代码本身的问题:当单个调用可匹配多条语句(例如同一块内同时使用 draw(_) 与 draw(ofType<Dot>()))时触发,框架不允许语句与调用之间模糊匹配。
典型实战模式
验证调用数量与缓存行为
func testDataCaching() {
let uncachedRepo = spy(Repository())
let invalidationTracker = mock<InvalidationTracker>()
@On(invalidationTracker.getTimestamp()).returns(0)
let cachedRepo = CachedRepistory(uncachedRepo, invalidationTracker)
for (i in 0..10) {
cachedRepo.get(TEST_ID)
}
// 只查询了一次基础 repo,且无其他调用
Verify.unordered(Exhaustive,
@Called(uncachedRepo.get(TEST_ID)).once()
)
Verify.clearInvocationLog()
@On(invalidationTracker.getTimestamp()).returns(1)
for (i in 0..10) {
cachedRepo.get(TEST_ID)
}
// 自上次清除日志后仅一次调用
Verify.unordered(Exhaustive,
@Called(uncachedRepo.get(TEST_ID)).once()
)
}
验证带特定参数的调用
let canvas = spy(Canvas())
canvas.draw(Triangle())
// 使用 'that' 块
Verify.that(@Called(canvas.draw(ofType<Dot>())).times(3))
Verify.that(@Called(canvas.draw(ofType<Line>())).times(3))
// 或使用部分无序验证块(不关心绘制顺序)
Verify.unordered(Partial,
@Called(canvas.draw(ofType<Dot>())).times(3),
@Called(canvas.draw(ofType<Line>())).times(3)
)
// 验证从未调用入参为 Square 类型的 draw
Verify.that(@Called(canvas.draw(ofType<Square>)).never())
注意:同一验证块中的语句必须明确只匹配一个调用;@Called(canvas.draw(_)).times(7) 与 @Called(canvas.draw(ofType<Dot>())).times(3) 同块会因模糊匹配而失败。
验证调用顺序
let plane = spy(Plane())
FlightBuilder(plane).planFlight(Shenzhen, Shanghai, Beijing).execute()
Verify.ordered(
@Called(plane.takeOffAt(Shenzhen)),
@Called(plane.landAt(Shanghai)),
@Called(plane.takeOffAt(Shanghai)),
@Called(plane.landAt(Beijing))
)
预期与验证 API 的分工
配置桩时的预期已覆盖一部分断言,建议避免重复验证块中的配置步骤。一般规则:预期用于自动检查桩是否被触发,验证 API 用于补充检查具体调用次数与参数:
let foo = mock<Foo>()
@On(foo.bar(_)).returns() // 如果从未使用此桩,测试失败
foo.bar(1)
foo.bar(2)
Verify.unordered(
@Called(foo.bar(1)).once(),
@Called(foo.bar(2)).once()
)
上述用例也可完全用预期重写:
let foo = mock<Foo>()
@On(foo.bar(1)).returns().once() // 预期只被调用一次,参数为 1
@On(foo.bar(2)).returns().once() // 预期只被调用一次,参数为 2
foo.bar(1)
foo.bar(2)
// 如果没有桩被触发,则测试失败
编译与运行前提
- 使用 cjpm:运行
cjpm test即可自动启用 mock 框架,无需额外配置; - 直接使用 cjc:mock 通过
--mock=on标志控制,且编译依赖被打桩类所在包p的其他包时也必须带上该标志;在测试中使用 mock 对象(cjc --test)不需要额外标志(详见 mock 基础概念及用法)。
接口始终可以被 mock;从另一个包 mock 类时,类及其超类需按特定方式编译,且只能 mock 预编译库(如 stdlib)中的接口、不能 mock 其中的类。
小结
@On 与 @Called 是仓颉 mock 框架的两大支柱:@On 负责"设定期望行为"(打桩),@Called 负责"验证实际交互"(断言)。两者共享同一套桩签名与参数匹配器语法,配合 mock/spy 构造函数、Matchers 匹配器、Verify 验证块、Exhaustiveness 模式与 CardinalitySelector 基数说明符,即可在不修改生产代码的前提下完成依赖隔离、异常场景、调用数量/参数/顺序等全部常见测试需求。更多进阶用法(共享桩、参数捕获、桩模式、合成字段等)可继续阅读仓库中的 mock 框架入门、mock 基础概念及用法、桩使用指南 与 mock 框架验证 API。