eslint-plugin-unicorn 的 assertToken 工具：从 AVA 快照报告理解 token 断言与错误消息设计

eslint-plugin-unicorn 的 assertToken 工具：从 AVA 快照报告理解 token 断言与错误消息设计

【免费下载链接】eslint-plugin-unicornMore than 300 powerful ESLint rules项目地址: https://gitcode.com/GitHub_Trending/es/eslint-plugin-unicorn

assertToken是 eslint-plugin-unicorn 中一个轻量但十分重要的内部工具函数，用于在规则进行代码修复（fix）时对 ESLintSourceCode返回的 token 做防御性断言，确保代码重写所依赖的 token 结构与预期一致。本文以仓库中的 AVA 快照报告 test/unit/snapshots/assert-token.js.md 为切入点，结合 assertToken 源码 与 单元测试，逐层剖析该工具的匹配语义、错误消息格式、issue 上报机制，以及它在no-for-each、prefer-module等规则修复流程中的真实调用方式。读完本文，你将理解为什么一个看似只有 27 行的工具函数，却能成为插件修复逻辑中不可或缺的"安全阀"。

快照报告里藏着什么：先读懂这份文件本身

test/unit/snapshots/assert-token.js.md是由测试运行器 AVA 自动生成的快照报告（Snapshot report），它对应同一目录下的二进制快照文件test/unit/snapshots/assert-token.js.snap。这类文件的机制是：

• 测试运行后，AVA 会把t.snapshot()捕获的序列化结果保存到.snap文件；
• .md报告是这份快照的人类可读版本，方便在代码评审和 diff 中直接查看；
• 头部注释标明Generated by AVA，意味着该文件不应被手工维护，而应由ava test --update-snapshots之类的命令更新。

快照中唯一的内容是一个名为 "Error message" 的测试快照，记录了一次断言失败时assertToken抛出的完整Error对象：

Expected token '{"value":"expectedValue"}' or '{"type":"expectedType"}', got '{"value":"b","type":"a"}'. Please open an issue at https://github.com/sindresorhus/eslint-plugin-unicorn/issues/new?title=`test-rule`: Unexpected token '{"value":"b","type":"a"}'.

这条消息并非随意拼接的文案，它精确刻画了assertToken的三个设计目标：清晰列出期望（可能有多项，用or连接）、如实报告实际（只展示value和type两个关键字段）、把异常转化为可追踪的 issue（自动携带 URL 编码的标题）。下文逐一展开。

assertToken 的三种匹配方式

在 rules/utils/assert-token.js 中，assertToken暴露了三个参数：token（被断言的 ESLint token 对象）、expected（期望值）、ruleId（当前规则名，仅用于错误消息）以及可选的test（自定义判定函数）。匹配逻辑按优先级依次是：

1. test函数短路：若传入了test且test(token)返回真值，函数直接返回，不再做后续比对。这为规则的调用方提供了完全自定义的判定入口，例如 prefer-optional-catch-binding.js 用isOpeningParenToken/isClosingParenToken判断catch前后的括号 token 是否为左右圆括号。

2. expected的字符串简写：expected若是字符串，会被等价为{value: expected}。因此在 no-for-each.js 中写expected: 'return'，实际等价于断言该 token 的value === 'return'。

3. expected的对象/数组匹配：expected总是被归一化为数组（单个值包装成数组），然后逐项检查：对每个期望 token，其每一个键值对（Object.entries）都必须与token上同名属性严格相等（===）。这意味着：

• {type: 'a', value: 'b'}要求两个字段同时命中；
• {type: 'a'}只校验类型，{value: 'b'}只校验取值；
• ['a', 'b', 'c']等价于[{value: 'a'}, {value: 'b'}, {value: 'c'}]，只要其中任意一个期望匹配即通过（some语义）；
• 反之，expected中若含有token上不存在的属性（如{nonExistingProperty: ''}），由于严格相等不成立，断言必然失败——单元测试 专门验证了这一行为，说明该工具同样能捕获"调用方对 token 结构的错误假设"。

test/unit/assert-token.js的第一组用例 "Pass on matched token" 完整覆盖了上述全部通过路径：对象全匹配、仅type、仅value、字符串简写、test函数返回true、数组期望命中其一；第二组 "Throw error when not match" 则覆盖了所有失败路径，包括test返回false、非存在属性断言、数组期望全部落空等场景。

错误消息的构造细节与 issue 上报机制

当所有匹配路径都未命中时，assert-token.js 会构造并抛出Error。其消息生成顺序是：

1. actual：只取token.value和token.type两个字段做JSON.stringify。快照中的got '{"value":"b","type":"a"}'即来自测试传入的{value: 'b', type: 'a', extraKeyInToken: ''}——额外的extraKeyInToken被有意剔除，单元测试 用t.false(error.message.includes('extraKeyInToken'))固化了"消息中不应包含多余字段"这一约定，避免暴露无关的 token 内部数据。

2. expected：每个期望 token 独立序列化后用or拼接。快照中的'{"value":"expectedValue"}' or '{"type":"expectedType"}'对应测试传入的数组['expectedValue', {type: 'expectedType'}]——字符串简写被展开成{value: 'expectedValue'}后再进入消息，所以期望列表里每一项都保留了完整的 JSON 形态。

3. issue 链接：ISSUE_LINK_PREFIX固定为https://github.com/sindresorhus/eslint-plugin-unicorn/issues/new?，标题格式为`{ruleId}`: Unexpected token {actual}，并经encodeURIComponent转义后拼接到链接上。快照中%60test-rule%60正是`test-rule`的编码结果。这一设计让"工具自身假设被打破"的异常（理论上在规则修复时不应发生）能直接转化为一个预填了规则名与实际 token 的 issue，显著降低用户反馈成本。测试中t.true(error.message.includes(correctIssueLink))正是按同样的编码规则构造期望链接来验证的。

注意快照消息中的␊是 AVA 对换行符\n的转义显示：assertToken抛出的消息本体是两行文本——第一行说明期望与实际，第二行引导打开 issue。

在真实规则修复流程中的五种调用场景

从源码检索可以看到，assertToken通过 rules/utils/index.js 统一导出，并被 5 个规则在修复器中实际调用，形成清晰的"修复前自检"模式：

以 prefer-module.js 为例，修复器先把const require(...)改写为import ...：在调用fixer.replaceText(constToken, 'import')之前，先用assertToken确认首个 token 确实是关键字const；随后对=和:也做同样断言。这种"先断言、后改写"的顺序，保证当 AST 结构因未来 ESLint 版本或新语法出现偏移时，规则会以带 issue 链接的明确报错迅速暴露问题，而不是静默产出错误的修复文本。而 prefer-optional-catch-binding.js 展示了test与expected组合使用的形态：先由isOpeningParenToken做函数级判断，同时保留expected: '('作为消息层面的可读期望值。

从快照到测试：一份可自我验证的契约

值得强调的是，快照文件本身就是测试体系的一环：test/unit/assert-token.js中 "Error message" 用例在运行时会生成与快照完全一致的错误对象，若未来有人修改消息模板（比如调整or的连接词、变更value/type的字段选取、改动 issue 链接结构），AVA 会立即以快照 diff 的方式标记不匹配，强制维护者同步审视这一对外可观察的行为。因此这份 快照报告 不仅是调试辅助，更是assertToken错误消息格式的"可执行文档"。

对于希望在自己的 ESLint 插件中借鉴该模式的开发者，可以直接复用这套思路：把assertToken视为对sourceCode.getFirstToken、getTokenBefore、getTokenAfter等 API 返回结果的类型守卫——在依赖具体 token 形态的修复逻辑入口处先断言，用统一格式的异常和 issue 链接兜底，再配合t.snapshot()固化错误消息，就能在"规则正确性"与"故障可诊断性"之间取得很好的平衡。

【免费下载链接】eslint-plugin-unicornMore than 300 powerful ESLint rules项目地址: https://gitcode.com/GitHub_Trending/es/eslint-plugin-unicorn