企业官网建设流程全解析

AVA Snapshot Workflow 实战：移除快照断言时数据的清理与保留机制

【免费下载链接】avaNode.js test runner that lets you develop with confidence 🚀项目地址: https://gitcode.com/gh_mirrors/ava/ava

导读

在 AVA 测试框架中，快照（snapshot）文件与测试代码的生命周期需要保持同步：当测试中的t.snapshot()断言被删除时，旧快照数据应当如何处理？本文基于 AVA 仓库test/snapshot-workflow目录下的工作流测试套件，深入解析"移除快照断言"这一场景的两种行为——普通运行下旧数据被保留、--update-snapshots更新模式下旧数据被彻底清除——并从源码层面揭示.snap二进制文件与.md报告文件的生成与清理机制。

一、场景定位：快照工作流测试套件

AVA 的test/snapshot-workflow目录专门用于"模拟编写和维护基于快照的测试过程中可能出现的各种情境"。其核心思路（见 README）是：

大多数测试由一个 fixture（夹具）组成，其中包含可以两种方式运行的测试文件（带或不带TEMPLATE=true），以模拟用户对测试代码做出修改。fixture 会被复制到临时目录后由 AVA 调用，随后测试断言快照文件是否按预期方式发生了变化。

本场景对应的测试文件为 removing-snapshots.js，其中包含两个串行用例：

test.serial( 'Removing a snapshot assertion retains its data', beforeAndAfter, { cwd: cwd('removing-snapshots'), expectChanged: false, }, ); test.serial( 'With --update-snapshots, removing a snapshot assertion removes its data', beforeAndAfter, { cwd: cwd('removing-snapshots'), cli: ['--update-snapshots'], expectChanged: true, }, );

两个用例共用一个 fixture，仅通过cli参数区分是否传入--update-snapshots，从而对照出 AVA 在两种模式下的不同行为。所有用例均使用test.serial()串行执行，这是为了避免 CI 机器同时承担多次 AVA 调用的负担（见 README）。

二、Fixture 结构：模拟"删除一个快照断言"

fixture 位于 test/snapshot-workflow/fixtures/removing-snapshots，其测试文件 test.js 是一个带条件编译的模板：

const {default: test} = await import(process.env.TEST_AVA_IMPORT_FROM); test('foo', t => { t.snapshot({foo: 'one'}); if (process.env.TEMPLATE) { t.snapshot({foo: 'two'}); } });

• 当TEMPLATE=true运行时：测试块foo会记录两个快照（{foo: 'one'}和{foo: 'two'}），用于生成 fixture 的初始快照状态；
• 当TEMPLATE未设置时：测试只记录一个快照（{foo: 'one'}），模拟开发者在删除了第二个t.snapshot()断言之后的"新代码"。

fixture 的初始状态

运行TEMPLATE=true npx ava --update-snapshots（即 README 中约定的初始化方式）后，fixture 目录下生成两类文件：

1. 快照报告 test.js.md（人类可读的报告，可提交到版本控制用于 diff）：

# Snapshot report for `test.js` The actual snapshot is saved in `test.js.snap`. Generated by [AVA](https://avajs.dev). ## foo > Snapshot 1 { foo: 'one', } > Snapshot 2 { foo: 'two', }

2. 快照数据文件test.js.snap（二进制格式，实际比较的依据）。从源码 lib/snapshot-manager.js 可知，该文件以AVA Snapshot v3的可读前缀开头，使用 CBOR 编码序列化（由cbor2库完成），并附加 SHA-256 校验和以保证完整性。

三、测试宏：beforeAndAfter 如何验证行为

两个用例共用 helpers/macros.js 中定义的beforeAndAfter宏，其执行流程如下：

1. 读取变更前状态：通过readSnapshots(cwd)读取 fixture 中的test.js.snap（解压后）和test.js.md；
2. 复制到临时目录：withTemporaryFixture将 fixture 复制到临时目录，避免污染源 fixture；
3. 运行 AVA：在临时目录中执行fixture(cli, ...)，cli决定是否携带--update-snapshots；
4. 读取变更后状态：再次读取临时目录中的.snap与.md；
5. 断言差异：
   • 若expectChanged: false，断言前后.md完全一致（t.is）、.snap深度相等（t.deepEqual）；
   • 若expectChanged: true，断言前后均发生变化（t.not/t.notDeepEqual），并对两个报告做concordance.diff生成差异快照。

readSnapshots用到了源码导出的extractCompressedSnapshot函数（见 lib/snapshot-manager.js），配合gunzipSync解压出快照的真实内容——这正是"移除断言"场景下检验.snap中数据是否真正被删除的依据。

差异快照：删除操作的实际表现

测试为expectChanged: true的用例录制的快照报告位于 snapshots/removing-snapshots.js.md，其内容即为.md报告变更前后的 diff：

# Snapshot report for `test.js` ... ## foo > Snapshot 1 { foo: 'one', } - - > Snapshot 2 - - { - foo: 'two', - }

带-前缀的行正是被删除的Snapshot 2及其数据{foo: 'two'}。这直观证明：在--update-snapshots模式下，AVA 不仅更新了.snap二进制数据文件，还同步重写了.md报告——两个文件始终保持一致。

四、源码剖析：快照管理器如何决定保留还是删除

理解两种行为的差异，关键在于SnapshotManager的加载与保存逻辑（lib/snapshot-manager.js）。

加载阶段：根据 updating 初始化新旧块

load()函数（lib/snapshot-manager.js）读取已有.snap后，将数据解码为blocksByTitle（按测试标题分组的快照块），然后分派到两个 Map：

oldBlocksByTitle: blocksByTitle, newBlocksByTitle: updating ? new Map() : blocksByTitle,

• 普通模式（updating: false）：newBlocksByTitle直接引用旧数据。这意味着即使本次运行中没有再次调用某个t.snapshot()，旧的快照数据仍然会被视为"当前"快照而保留下来——对应第一个用例"Removing a snapshot assertion retains its data"。
• 更新模式（updating: true）：newBlocksByTitle初始化为空 Map，旧的快照块只存在于oldBlocksByTitle中作为参照。每次运行中的t.snapshot()调用都会将新数据写入空 Map（见recordSerialized，lib/snapshot-manager.js）；没有被再次记录的旧块自然就"消失"了。

保存阶段：重建快照文件

save()方法（lib/snapshot-manager.js）负责将newBlocksByTitle中的内容重新编码为.snap二进制文件，并同步生成.md报告（generateReport）。因此：

• 更新模式下，被删除断言的快照不会进入新的newBlocksByTitle，最终两个文件都被重写，旧数据被彻底清除；
• 一个有趣的边界情况：更新模式下如果newBlocksByTitle为空（例如删除的断言恰好是该测试文件中唯一的快照），save()会返回changedFiles: [snapPath, reportPath]并触发文件清理——即删除快照文件本身，而不是写入空文件。

解码容错：更新模式忽略损坏

load()中还有一个细节（lib/snapshot-manager.js）：解码.snap失败时，普通模式会记录snapshotError并在比较时抛出；而updating模式下所有解码错误都会被丢弃（// Discard all decoding errors when updating snapshots），因为更新模式反正会整体重建快照文件。这与"移除断言后旧数据失效"的理念一脉相承：更新模式下旧快照的价值仅在于供skipSnapshot等操作保留引用，其余场景一律以本次运行为准。

五、从测试到实践：开发者的操作指南

结合 docs/04-snapshot-testing.md 与 docs/05-command-line.md，将本场景映射到真实开发流程：

1. 删除t.snapshot()断言后直接运行测试：

$ ava

旧快照数据会被保留（与本次未删除断言时行为一致），测试正常通过，.snap与.md均不变。

2. 删除断言后主动更新快照：

$ ava --update-snapshots

或使用短标志ava -u（见 docs/05-command-line.md）。此时被删除断言对应的旧快照数据会从.snap中清除，.md报告同步重写，便于你在版本控制中通过 diff 审查变化：

$ git diff test/snapshots/main.js.md

3. 只更新特定测试：将--update-snapshots与--match或.only()组合使用（见 docs/04-snapshot-testing.md），避免大范围重写快照文件。

4. 利用报告文件做代码审查：.md报告（如 fixture 的 test.js.md）是"可提交到版本控制用于 diff"的辅助文件；真正参与比较的是.snap。删除快照断言后，只要运行过--update-snapshots，提交.md的 diff 即可清晰展示哪些快照被移除。

注意：AVA 支持通过package.json中的ava.snapshotDir配置指定快照的固定存放位置（见 docs/06-configuration.md 与 docs/04-snapshot-testing.md），目录结构会镜像测试文件的相对布局；若对预编译测试文件运行 AVA，则会借助 source map 定位原始文件来决定快照存放位置。

六、总结

理解这一机制后，你就可以放心地重构测试代码：普通运行下删除断言不会造成数据丢失，而--update-snapshots则会忠实反映"测试代码当前声明了哪些快照"。两者配合使用，恰好构成一套安全、可审计的快照维护工作流。

【免费下载链接】avaNode.js test runner that lets you develop with confidence 🚀项目地址: https://gitcode.com/gh_mirrors/ava/ava