深入解析 Wing math.sign() 与 Hangar 快照测试:从 SDK 源码、tf-aws 编译产物到模拟器验证

原创2026-10-13 19:01:011,658 阅读
文章标签:编程语言编译器云原生语言运行时

深入解析 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": [
      {}
    ]
  }
}

这份产物揭示了几条关键事实:

  1. 纯计算程序不会产生云资源:sign.test.w 全程只做数值断言,没有声明任何 Bucket、Queue、Function 等云资源,因此 main.tf.json 中没有任何 resource 段。整个 Terraform 栈只包含一个空的 aws provider 声明块 [{ }]。
  2. 元数据字段:metadata.backend 为 local(本地状态后端),stackName 为 root(根栈名称),outputs 为空——没有定义输出变量。
  3. 快照经过了路径与元数据净化:生成快照时,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 测试套件,其快照生成链路如下:

  1. 测试用例生成:generate_tests.ts 递归扫描 tests/sdk_tests 目录下的所有 .w 文件,为每个文件生成两个 vitest 测试用例(wing compile -t tf-aws 与 wing test -t sim),写入 test_corpus 目录。
  2. 编译测试:compileTest 函数 在源目录执行 wing compile -t tf-aws,产物落在 <源目录>/target/<文件名>.tfaws/,随后收集 main.tf.json 与 .wing 目录中的 preflight/inflight 产物,经净化后交给 createMarkdownSnapshot 落盘。
  3. 运行测试:testTest 函数 在临时目录执行 wing test -t sim,收集 stdout.log 与 stderr.log,同样生成快照。
  4. 快照比对:createMarkdownSnapshot 通过 vitest 的 toMatchFileSnapshot 与已存在的快照文件进行逐字比对,任何输出变化都会导致测试失败。

其中 runWingCommand(utils.ts)统一负责调用 wing 可执行文件,固定携带 --no-update-check 与 --no-analytics 参数;被测源码目录 tests/sdk_tests 由 paths.ts 中的 sdkTestsDir 常量定义。

七、如何自行复现这份快照

若要亲手复现 sign.test.w 的两份快照,可按以下步骤操作(仓库为只读,运行会在本地生成 target/ 产物与临时文件):

  1. 进入仓库根目录后,直接运行 wing test -t sim tests/sdk_tests/math/sign.test.w,模拟器会执行 test "inflight absolute" 并输出与快照 stdout.log 一致的通过信息(Duration 后的耗时为真实值而非 <DURATION> 占位符)。
  2. 运行 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 段与版本号元数据)。
  3. 若在 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 快照中。

登录后查看全文
wing