• 编程语言
• 编译器
• 云原生
• 语言运行时

云上测试成本高昂、耗时漫长，如何在不真正部署到云端的前提下，持续验证 Wing 应用与依赖库的合成输出没有回归？Wing 在wing test中内置了一套云测试快照（cloud test snapshots）机制：当针对tf-aws等云端目标运行测试且全部通过时，框架会自动把编译器产物快照捕获到<入口文件>.tf-aws.snap.md，并在 CI 中仅做"零部署"比对。本文以仓库中真实存在的快照样例 main.w.tf-aws.snap.md 为解剖对象，逐段讲解快照文件的生成规则、字段含义，并深入到 snapshots.ts 源码与官方 CLI 文档，帮助你掌握快照的完整生命周期：何时捕获、如何断言、怎样更新。

一、为什么需要云测试快照

Wing 的测试框架支持两个层面的测试：在本地模拟器（sim）中快速执行，以及通过-t tf-aws等目标部署到真实云环境执行。针对云端目标逐条运行测试虽然真实，却存在明显的现实约束——正如 RFC 2024-03-24-snapshot-tests.md 中所描述的：每次提交都在真实云上跑完全部测试既不现实（耗时很长）也代价高昂（云资源费用），同时还需要维护一套复杂的 AWS 账号环境。

云测试快照正是为缓解这一约束而生的轻量方案。其设计思路与 AWS CDK 的集成测试快照类似：在本地开发环境完整部署并跑通测试后，捕获一份"合成输出"快照提交进仓库；在 CI 环境中不再部署，而是重新合成输出并与快照比对。一旦输出发生变化（例如 SDK 升级、依赖变更、代码改动导致 IaC 模型变化），测试就会失败并给出 diff，从而在没有云环境的情况下捕获回归。

从 snapshots-help.ts 中可以看到该机制的官方描述：

When testing against a cloud target (e.g. -t tf-aws), if all tests pass, the compiler output will be captured under "<entrypoint>.snap.md".

即：只有云目标（非sim）且测试全部通过时，才会生成快照。

二、快照的捕获流程与命名规则

2.1 触发时机：先测试，后快照

在 test.ts 的testOne流程中，快照捕获被严格置于测试成功之后：

• 首先根据目标平台计算快照模式（determineSnapshotMode）；
• 若需要执行（sim或DEPLOY模式），则编译并把应用部署到目标平台执行测试；
• 一旦有任一测试失败，则跳过快照捕获（success = !results.some((r) => !r.pass)）；
• 全部通过后才调用captureSnapshot。

值得注意的是，为了让快照可复现，测试编译时会把 root id 固定为"root"（rootId: (options.rootId ?? target === "sim") ? "root" : ...），而普通云测试则使用随机 id。这正是快照中能看到"path": "root/Default/Default/Bucket/Default"、"stackName": "root"等稳定标识的原因。

2.2 命名规则：<entrypoint>.<target>.snap.md

快照文件的命名在 snapshots.ts 中定义：

const snapshotFile = `${entrypoint}.${target}.snap.md`;

因此示例入口main.w针对tf-aws目标生成的快照即为main.w.tf-aws.snap.md，与本文分析的 fixture 完全一致。官方 CLI 文档 02-cli-user-manual.md 中的示例也印证了这一点：test_bucket.test.w跑通后会生成test_bucket.test.w.tf-aws.snap.md。

2.3 快照内容：Markdown 包装的合成产物

createMarkdownSnapshot（snapshots.ts）会遍历合成输出目录，按扩展名收集文件并组装成标准 Markdown：

• 包含的文件类型：**/*.js、**/*.json、**/*.tf、**/*.ts、**/*.yaml、**/*.yml；
• 排除的文件：connections.json、tree.json、**/*.zip、**/*.map，以及所有以.开头的隐藏目录（如.wing，通过dot: false排除）；
• 安全性检查：若产物中出现绝对路径的require("...")调用（如/...或C:\...），捕获会直接失败，避免快照携带不可移植的绝对路径。

最终createMarkdown生成如下模板结构：

# `main.w.tf-aws.snap.md` ## main.tf.json ```json { ... }

即每个合成文件占一个 `##` 小节，语言标签取自文件扩展名。本文的 fixture 只包含一个 `main.tf.json` 文件，这是 Wing 编译器针对 `tf-aws` 目标合成的 Terraform 配置。 ## 三、逐段解读 `main.w.tf-aws.snap.md` ### 3.1 顶层结构 ```json { "//": { "metadata": { "backend": "local", "stackName": "root", "version": "0.20.7" }, "outputs": {} }, "provider": { "aws": [ {} ] }, "resource": { ... }, "terraform": { ... } }

• //.metadata：CDKTF 生成的元信息。backend: local表示使用本地 Terraform 状态后端；stackName: root对应合成栈名（与 2.1 中固定 root id 相呼应）；version: 0.20.7是当前仓库 winglang 包对应的编译器/SDK 版本号，版本变化本身不会自动改写快照，但会引起合成输出差异从而触发断言失败。
• provider.aws：声明了 AWS provider（此处为空对象，因为本样例无需显式 provider 配置）。
• resource：实际创建的云资源，本例为 S3 桶及其 CORS 配置。
• terraform：Terraform 后端与 provider 版本锁定，详见 3.4。

3.2aws_s3_bucket：桶资源与命名前缀

"aws_s3_bucket": { "Bucket": { "//": { "metadata": { "path": "root/Default/Default/Bucket/Default", "uniqueId": "Bucket" } }, "bucket_prefix": "bucket-c88fdc5f-", "force_destroy": false } }

这段输出直接来自 tf-aws 平台对cloud.Bucket的实现（packages/@winglang/sdk/src/target-tf-aws/bucket.ts）：

• path与uniqueId：root/Default/Default/Bucket/Default展示了资源在应用树中的层级路径，uniqueId是资源在 Terraform 中的稳定标识。对应源码中createEncryptedBucket(this, ...)以"Default"为资源名创建S3Bucket。
• bucket_prefix：bucket-c88fdc5f-由ResourceNames.generateName(scope, BUCKET_PREFIX_OPTS)生成。源码中的BUCKET_PREFIX_OPTS（bucket.ts 第 37-44 行）规定了严格的命名约束：maxLen: 37（Terraform 要求前缀 3-37 字符）、仅小写字母数字与连字符、并以-结尾以区分 Wing 生成部分与 Terraform 追加的随机后缀。前缀中的c88fdc5f属于资源的确定性哈希（由构造树路径推导），因此同一份源码在不同机器上合成的快照是一致的——这正是快照机制可复现的前提。
• force_destroy：对应cloud.BucketProps.forceDestroy（默认false）。注意一个细节：createEncryptedBucket（bucket.ts 第 159-186 行）中实际写入的forceDestroy是!!isTestEnvironment || forceDestroy，即测试环境下会被强制置为true，便于测试结束后清理资源。本快照中显示false，是因为快照重新编译时并未开启testing: true标志（参见 snapshots.ts 中"为了快照而再次编译"的注释）。

3.3aws_s3_bucket_cors_configuration：默认 CORS 规则

"aws_s3_bucket_cors_configuration": { "Bucket_CorsConfiguration-1357ca3a_A4CCA40A": { "//": { "metadata": { "path": "root/Default/Default/Bucket/CorsConfiguration-1357ca3a" } }, "bucket": "${aws_s3_bucket.Bucket.id}", "cors_rule": [ { "allowed_headers": ["*"], "allowed_methods": ["GET","POST","PUT","DELETE","HEAD"], "allowed_origins": ["*"], "expose_headers": [], "max_age_seconds": 0 } ] } }

• 为什么默认就有 CORS 配置：tf-aws 的Bucket构造函数中if (props.cors ?? true)默认开启 CORS，并使用cloud.DEFAULT_BUCKET_CORS_CONFIGURATION（定义于 cloud/bucket.ts）。该默认值正是快照中的五个方法GET/POST/PUT/DELETE/HEAD、allowedHeaders: ["*"]、allowedOrigins: ["*"]、exposeHeaders: []、maxAge: 0s。
• 资源命名：CorsConfiguration-1357ca3a来自addCorsRule（bucket.ts 第 73-97 行）中的`CorsConfiguration-${this.node.addr.slice(-8)}`，即取节点地址的后 8 位十六进制；A4CCA40A则是 CDKTF 生成的唯一 id 后缀，path中的CorsConfiguration-1357ca3a与uniqueId中的前后缀共同构成稳定可寻址的标识。
• bucket引用：${aws_s3_bucket.Bucket.id}是 Terraform 资源间引用，表示 CORS 配置依赖同一个桶。
• cors_rule的惰性求值：corsRule在源码中使用Lazy.anyValue包裹，实际值在合成时由收集到的corsRules数组动态生成，支持后续多次addCorsRule追加规则。

3.4terraform段：后端与 provider 版本

"terraform": { "backend": { "local": { "path": "./terraform.tfstate" } }, "required_providers": { "aws": { "source": "aws", "version": "5.56.1" } } }

• backend.local：快照样例使用本地状态文件./terraform.tfstate，说明这是本地/CI 可执行的合成输出；
• required_providers.aws：锁定 AWS provider 版本为5.56.1（当前仓库 winglang 依赖锁定的版本）。这一约束意味着快照比对同时隐含了对 provider 版本的敏感性——升级 provider 可能引起合成输出的差异。

四、--snapshots五种模式与自动判定逻辑

快照行为由--snapshots <mode>（或-s <mode>）开关控制，共五种模式（帮助文本见 snapshots-help.ts，完整说明见 02-cli-user-manual.md 的 "Cloud test snapshots" 一节）：

自动判定逻辑实现在determineSnapshotMode（snapshots.ts），两条硬性规则值得特别注意：

1. sim目标永不快照：无论显式指定何种模式，只要target === BuiltinPlatform.SIM一律返回NEVER。快照机制只服务于云端目标（tf-*、awscdk等）。
2. auto由 CI 决定：未显式指定模式时，若process.env.CI存在则进入ASSERT，否则进入DEPLOY。

对应的单元测试覆盖见 snapshots.test.ts，其中专门验证了sim即使在显式DEPLOY/ASSERT/UPDATE下也会被强制禁用。

五、CI 集成：从 "部署+捕获" 到 "零部署断言"

5.1 本地环境（未设 CI）

$ wing test -t tf-aws test_bucket.test.w ✔ Compiling test_bucket.test.w to tf-aws... ✔ terraform init ✔ terraform apply ... ✔ Snapshot test_bucket.test.w.tf-aws.snap.md...

部署并执行测试，全部通过后捕获快照（对应DEPLOY模式）。

5.2 CI 环境（设CI=1）

$ CI=1 wing test -t tf-aws test_bucket.test.w ✔ Snapshot test_bucket.test.w.tf-aws.snap.md...

只做合成与比对，不再触碰云端（ASSERT模式）。

5.3 失配时的失败信息

$ CI=1 wing test -t tf-aws test_bucket.test.w ✖ Snapshot test_bucket.test.w.tf-aws.snap.md... Snapshot mismatch: - Expected: test_bucket.test.w.tf-aws.snap.md - Actual: test_bucket.test.w.tf-aws.snap.md.actual

在captureSnapshot（snapshots.ts）的ASSERT分支中，失配时会把新产物写入<snapshotFile>.actual，优先通过系统diff命令渲染统一 diff（CI 下禁用颜色），然后删除临时文件并抛出以Snapshot mismatch:为前缀的错误；若快照文件根本不存在则直接报Snapshot file does not exist。

错误提示同时给出两条恢复路径（snapshots-help.ts）：

Update with '--snapshots=update' To disable this behavior run with '--snapshots=never'

即：确认变更是预期回归后，用--snapshots=update刷新快照；或在本轮确实需要真实云测试时用--snapshots=never关闭。UPDATE模式本身"跳过部署、直接写快照"（snapshots.ts），因此官方文档特别提醒：谨慎使用，因为它可能把回归行为固化进快照。

5.4 测试级别的行为差异

在 test.test.ts 中可以观察到--retry与--parallel等选项与快照机制的配合：失败的测试会自动重试，且只有最终全部通过才进入快照环节；测试结果汇总报告（pass/fail）由renderTestReport渲染。

六、用源码测试验证快照的确定性

snapshots.test.ts 是对本文快照机制最直接的验证：它动态生成一个包含cloud.Bucket与test "put"用例的main.w，分别以UPDATE、DEPLOY模式捕获快照，并逐字节比对仓库中的 main.w.tf-aws.snap.md（expect(snapshot).toStrictEqual(expected)）。测试覆盖的关键结论：

• NEVER模式下不会产生任何快照文件；
• UPDATE与DEPLOY生成的快照内容完全一致（证明快照不依赖部署过程）；
• ASSERT在快照缺失时报错；在快照被篡改（如把force_destroy改为true）时报出 diff；在完全一致时通过。

这份 fixture 本身即仓库 CI 的一部分：只要 tf-aws 平台的合成输出有任何非预期变化，快照断言就会失败并暴露差异。

七、实操建议与注意事项

1. 把快照文件视为契约：<入口>.tf-aws.snap.md应提交进版本库，并在每次依赖或 SDK 升级后主动 review diff，避免"带病"更新。
2. 区分环境行为：本地默认deploy、CI 默认assert的切换依赖CI环境变量；如需强制某一种行为，显式传--snapshots=<mode>。
3. sim 目标没有快照：本地模拟器测试请使用常规断言（assert/expect）承担功能验证，快照只负责云端合成输出的回归防护。
4. 关注快照的可复现性：快照之所以稳定，是因为编译阶段固定了 root id、命名前缀使用确定性哈希、且排除了.wing、zip、map 等易变产物；若自行扩展平台，应保持相同的确定性约束。
5. 阅读入口：机制实现集中在 snapshots.ts 与 snapshots-help.ts，CLI 行为规范见 02-cli-user-manual.md，设计初衷见 RFC 2024-03-24-snapshot-tests.md，tf-aws 平台资源生成见 packages/@winglang/sdk/src/target-tf-aws/bucket.ts。

通过本文，你已经能够：读懂任意<入口>.tf-aws.snap.md快照中每个字段的来源与含义，理解wing test快照在本地与 CI 下的完整行为差异，并在合成输出发生非预期变化时，依据 diff 与--snapshots模式做出正确的处置决策。

• 编程语言
• 编译器
• 云原生
• 语言运行时