深入解析 Wing math.sign() 与 Hangar 快照测试:从 SDK 源码、tf-aws 编译产物到模拟器验证
深入解析 Wing math.sign() 与 Hangar 快照测试:从 SDK 源码、tf-aws 编译产物到模拟器验证
本篇技术指南以 Wing 仓库中 sign.test.w 的 tf-aws 编译快照 为主线,讲解 Wing 标准库 math.sign() 的函数语义与底层实现,同时拆解 Hangar E2E 测试套件如何为 sign.test.w 生成编译与运行两类快照,帮助读者理解 Wing 的"纯计算程序如何编译成 Terraform 产物、如何在模拟器中完成断言"这一完整链路。
一、快照文件是什么:Hangar E2E 测试的产物
sign.test.w_compile_tf-aws.md 位于 tools/hangar/__snapshots__/test_corpus/sdk_tests/math/ 目录下,文件命名遵循 <被测文件>_<用例类型>_<目标平台>.md 的规范:
- 用例类型
compile:执行wing compile后,将编译产物以 Markdown 代码块的形式固化为快照; - 目标平台
tf-aws:编译目标是 Terraform + AWS 平台。
同目录下还配套存在 sign.test.w_test_sim.md(运行于模拟器 sim 的测试快照),两者共同构成对 sign.test.w 的完整 E2E 验证。快照正文第一行的链接 ../../../../../../tests/sdk_tests/math/sign.test.w 指向被测源码,即仓库中的 sign.test.w。
快照由 createMarkdownSnapshot 函数 生成,其路径拼接逻辑为:tools/hangar/__snapshots__/test_corpus/<被测文件相对目录>/<文件名>_<用例>_<目标>.md,对应的路径常量定义在 paths.ts(snapshotDir = tools/hangar/__snapshots__)。
二、被测对象:sign.test.w 与 math.sign() 的使用方式
被测源码 sign.test.w 完整内容如下:
bring math;
let negative = -11;
let zero = 0;
let positive = 18;
let negative_num = -4.11;
let zero_num = 0.0;
let positive_num = 8.18;
assert(math.sign(negative) == -1);
assert(math.sign(zero) == 0);
assert(math.sign(positive) == 1);
assert(math.sign(negative_num) == -1);
assert(math.sign(zero_num) == 0);
assert(math.sign(positive_num) == 1);
test "inflight absolute" {
assert(math.sign(negative) == -1);
assert(math.sign(zero) == 0);
assert(math.sign(positive) == 1);
assert(math.sign(negative_num) == -1);
assert(math.sign(zero_num) == 0);
assert(math.sign(positive_num) == 1);
}
该测试覆盖了三类关键输入,构成了 math.sign() 的完整语义矩阵:
| 输入 | 期望返回值 | 覆盖意图 |
|---|---|---|
-11(负整数) |
-1 |
负数符号 |
0(零) |
0 |
零的特殊返回值 |
18(正整数) |
1 |
正数符号 |
-4.11(负浮点数) |
-1 |
非整数输入 |
0.0(浮点零) |
0 |
浮点零与整数零行为一致 |
8.18(正浮点数) |
1 |
非整数输入 |
值得注意的细节:文件顶部的 6 个 assert 属于 preflight(预飞)阶段,在编译期即可求值;而 test "inflight absolute" { ... } 块则是 inflight(飞行)阶段的测试用例,只有 wing test 运行到模拟器或云环境时才会执行。这种"preflight 断言 + inflight 测试"的双层写法,正是 Wing 语言"基础设施与运行时代码统一建模"理念在测试中的体现——同一个 math.sign() 调用在两种阶段下都必须语义一致。
三、SDK 底层实现:直接委托 JavaScript Math.sign
math.sign() 的官方 API 签名与语义见 math 模块 API 参考:math.sign(value: num): num,"Returns 1 or -1, indicating the sign of the number passed as an argument, 0 for 0"。
其底层实现位于 SDK 源码 math.ts:
/**
* Returns 1 or -1, indicating the sign of the number passed as an argument, 0 for 0.
* @param value The input number.
*/
public static sign(value: number): number {
return Math.sign(value);
}
从实现可以看到:math.sign() 并非 Wing 编译器内置的语法糖,而是直接委托给 JavaScript 引擎的 Math.sign(value)。这意味着它的行为与 ECMAScript 规范一致:
- 正数返回
1,负数返回-1,0与-0返回0(符号位不区分); - 该函数同时是
Math类上的静态方法(public static),因此在 preflight 与 inflight 阶段均可调用——这正是sign.test.w中两个阶段都能使用同一 API 的原因。
Util 类本身是一个纯工具类(私有构造函数,见 math.ts),全部成员为静态方法/常量,无需实例化,直接 bring math; 后即可使用。SDK 中同一模块还提供了 abs、floor、ceil、round、sqrt、log、三角/反三角函数、min/max/median/mode/arithmeticMean 等数十个数学工具方法,sign 是其中语义最简单、最适合做"全场景边界验证"的函数。
四、tf-aws 编译快照解析:main.tf.json 里有什么
快照正文只包含一个代码块——main.tf.json:
{
"//": {
"metadata": {
"backend": "local",
"stackName": "root"
},
"outputs": {}
},
"provider": {
"aws": [
{}
]
}
}
这份产物揭示了几条关键事实:
- 纯计算程序不会产生云资源:
sign.test.w全程只做数值断言,没有声明任何 Bucket、Queue、Function 等云资源,因此main.tf.json中没有任何resource段。整个 Terraform 栈只包含一个空的awsprovider 声明块[{ }]。 - 元数据字段:
metadata.backend为local(本地状态后端),stackName为root(根栈名称),outputs为空——没有定义输出变量。 - 快照经过了路径与元数据净化:生成快照时,sanitize_json_paths 函数 会移除
terraform段与//.metadata.version(cdktf 版本号),并将资源路径替换为<SOURCE>、<ASSET_KEY>等占位符,确保快照在不同机器、不同 SDK 版本下保持稳定,不会因绝对路径或版本号波动而触发无意义的快照 diff。
这一"编译结果为空壳栈"的快照,恰恰是 Hangar 测试体系的价值所在:它能以文本形式精确锁定"一个不含云资源的 Wing 程序在 tf-aws 平台上的编译输出"这一基线,任何编译行为的变化(例如突然多生成一个空资源、provider 配置改变)都会在 CI 中被快照比对捕获。
五、sim 测试快照解析:模拟器中的运行结果
配套快照 sign.test.w_test_sim.md 记录了 wing test -t sim 在模拟器中的标准输出:
pass ─ sign.test.wsim » root/Default/test:inflight absolute
Tests 1 passed (1)
Snapshots 1 skipped
Test Files 1 passed (1)
Duration <DURATION>
分析这份输出:
pass ─ sign.test.wsim » root/Default/test:inflight absolute:测试通过,测试全名为root/Default/test:inflight absolute,对应源码中test "inflight absolute"定义的用例;Tests 1 passed (1):1 个测试全部通过——验证了 preflight 阶段的 6 个assert编译通过,inflight 阶段的 6 个断言在运行时也全部成立;Duration <DURATION>:原输出中的实际耗时被 sanitizeOutput 统一替换为<DURATION>占位符,同理端口号、时间戳、绝对路径也都被规范化,保证快照可重复生成。
模拟器(sim)是 Wing 的本地运行环境,无需真实 AWS 账号即可执行 inflight 代码,因此这份快照证明:math.sign() 在"编译期求值"与"运行时求值"两条路径上都返回一致的、符合预期的结果。
六、快照如何生成:Hangar 的完整工作流
Hangar(tools/hangar/)是 Wing 的 E2E 测试套件,其快照生成链路如下:
- 测试用例生成:generate_tests.ts 递归扫描
tests/sdk_tests目录下的所有.w文件,为每个文件生成两个 vitest 测试用例(wing compile -t tf-aws与wing test -t sim),写入test_corpus目录。 - 编译测试:compileTest 函数 在源目录执行
wing compile -t tf-aws,产物落在<源目录>/target/<文件名>.tfaws/,随后收集main.tf.json与.wing目录中的 preflight/inflight 产物,经净化后交给createMarkdownSnapshot落盘。 - 运行测试:testTest 函数 在临时目录执行
wing test -t sim,收集stdout.log与stderr.log,同样生成快照。 - 快照比对:
createMarkdownSnapshot通过 vitest 的toMatchFileSnapshot与已存在的快照文件进行逐字比对,任何输出变化都会导致测试失败。
其中 runWingCommand(utils.ts)统一负责调用 wing 可执行文件,固定携带 --no-update-check 与 --no-analytics 参数;被测源码目录 tests/sdk_tests 由 paths.ts 中的 sdkTestsDir 常量定义。
七、如何自行复现这份快照
若要亲手复现 sign.test.w 的两份快照,可按以下步骤操作(仓库为只读,运行会在本地生成 target/ 产物与临时文件):
- 进入仓库根目录后,直接运行
wing test -t sim tests/sdk_tests/math/sign.test.w,模拟器会执行test "inflight absolute"并输出与快照stdout.log一致的通过信息(Duration后的耗时为真实值而非<DURATION>占位符)。 - 运行
wing compile -t tf-aws tests/sdk_tests/math/sign.test.w,产物生成于tests/sdk_tests/math/target/sign.test.tfaws/,其中的main.tf.json应与快照中的 JSON 内容一致(注意快照已剔除terraform段与版本号元数据)。 - 若在 Hangar 目录内运行测试套件,则通过
pnpm test(或 vitest)执行生成后的用例,快照比对由 vitest 自动完成;当 Wing 编译器或 SDK 行为发生变化时,可用快照更新机制(--update)刷新基线,但需人工审查 diff 是否符合预期。
结语:一份"空快照"背后的工程价值
sign.test.w_compile_tf-aws.md 虽然只有一份近空的 Terraform JSON,但它同时承担了两重职责:一方面作为 math.sign() 行为规范的活文档——正数得 1、零得 0、负数得 -1,且 preflight/inflight 两阶段行为一致;另一方面作为 Hangar 快照测试的基线,锁定了纯计算程序在 tf-aws 平台上的最小编译产物形态。理解这份快照的生成机制,也就理解了 Wing 项目"以快照驱动回归验证"的测试哲学:每一个 SDK API 的语义变化,都会被镜像到 tools/hangar/__snapshots__/test_corpus/ 下成百上千份可读、可审查、可检索的 Markdown 快照中。