defuddle 如何用 fixture 回归测试解决 `menu` 误伤正文容器的经典案例(issue 106)
defuddle 如何用 fixture 回归测试解决 #menu 误伤正文容器的经典案例(issue #106)
导读
本文以 defuddle 仓库中的 issues--106-menu-id 测试用例(HTML 夹具 与 期望输出)为切入点,剖析一个在正文抽取器中极具代表性的难题:当网页把真正的文章内容放进 id="menu" 这样的"导航语义"容器时,通用抽取器如何避免误删。读完本文,你将理解 defuddle 的精确选择器 / 部分选择器两级去除机制、id 与 class 属性在匹配策略上的本质差异,以及 fixture 对比测试如何锁定这类回归问题。
一、场景复现:一个名叫 menu 的正文容器
issues--106-menu-id 模拟的是一家餐厅的菜单页面(对应 issue #106 的真实反馈场景)。页面结构非常典型:
<main>
<h1>Our Restaurant</h1>
<p>Welcome to our restaurant. Below you will find our full menu with seasonal selections.</p>
<div id="menu"> <!-- 问题焦点:整个菜单位于 id="menu" 容器内 -->
<h2>Appetizers</h2>
<p>Spring rolls with sweet chili sauce — a perfect way to start your meal.</p>
<h2>Main Course</h2>
<p>Grilled salmon with roasted vegetables, served with a lemon butter sauce.</p>
<h2>Desserts</h2>
<p>Chocolate lava cake with vanilla ice cream — our signature dessert.</p>
</div>
<p>Please ask your server about daily specials and allergen information.</p>
</main>
页面头部是 <nav> 导航(Home / About 链接),底部是 <footer> 版权信息,中间 id="menu" 的 div 里才是用户真正想读的菜单正文。任何把 #menu 当作导航区块一刀切掉的选择器,都会把 Appetizers / Main Course / Desserts 三块正文全部删光——这正是该 fixture 要守护的边界。
对照期望输出可见,defuddle 完整保留了正文,同时干净地剔除了导航与页脚:
## Our Restaurant
Welcome to our restaurant. Below you will find our full menu with seasonal selections.
## Appetizers
Spring rolls with sweet chili sauce — a perfect way to start your meal.
## Main Course
Grilled salmon with roasted vegetables, served with a lemon butter sauce.
## Desserts
Chocolate lava cake with vanilla ice cream — our signature dessert.
Please ask your server about daily specials and allergen information.
文件开头的 JSON 块(title / author / site / published)是 fixture 测试体系的固定元数据前置,由 tests/fixtures.test.ts 中的 createComparableResult 生成,用于对比时同时校验元数据与正文。
二、两级去除机制:精确选择器为何"误伤" #menu
defuddle 的去除逻辑集中在 removeBySelector(src/removals/selectors.ts),它先收集所有命中精确选择器的元素,再处理部分匹配,最后统一从 DOM 移除。EXACT_SELECTORS 定义在 src/constants.ts,包含大量强语义的精确规则,其中导航类规则包括:
'nav',
'.navigation',
'#navigation',
'[role="navigation" i]',
'.menu',
// '#menu', // see issue #106
注意第 161 行:'#menu' 被显式注释掉了,并标注 see issue #106。这就是本次 issue 的直接修复——#menu 不再进入精确去除清单。
为什么精确选择器会误伤?关键在于 #menu 这样的 id 语义与 .menu 类名语义不同:class="menu" 在真实站点中几乎总是导航菜单(因此 .menu 保留在清单中),而 id="menu" 常见于"内容锚点"或"页面区块容器",餐厅菜单页、产品目录页、文档目录页都可能用它包住真正的正文。id 是页面级唯一标识,语义远比 class 松散,一刀切删除的代价是整块内容消失。
同类取舍在源码中处处可见,例如 '.hero' 同样因 issue #132 被注释(src/constants.ts),'time' 因 issue #136 被注释(src/constants.ts),'[href*="/category"]' 因 issue #131 被注释——这些都是在"导航语义选择器"与"内容误伤"之间反复权衡留下的证据。
三、部分选择器为何放过了裸 id="menu"
除了精确选择器,defuddle 还有一套部分匹配机制:从 TEST_ATTRIBUTES(class、id、data-testid、data-qa 等,见 src/constants.ts)中收集属性值,再用 PARTIAL_SELECTORS 做大小写不敏感的子串匹配。与 menu 相关的部分模式只有两个(src/constants.ts):
'-menu',
'menu-',
也就是说,sub-menu、menu-item 这类带连字符的类名会被部分匹配命中,而裸 menu 不会——-menu 需要前导连字符,menu- 需要尾随连字符。
更关键的是 id 的特殊处理(src/removals/selectors.ts):无分隔符的 id 使用"锚定匹配"而非子串匹配。id="menu" 不含 -、_、:、. 等分隔符,所以它必须整体等于某个部分选择器 token 才会被移除;而 PARTIAL_SELECTORS_ANCHORED_REGEX(src/constants.ts)中的 menu- / -menu 都带连字符,menu 永远无法精确等于它们。因此 id="menu" 在部分匹配这一级也是安全的。
这两条防线(精确清单注释 #menu + 锚定匹配规则)叠加,才保证了 fixture 中 id="menu" 容器安然无恙。
四、评分系统的兜底:menu 只降分、不删除
去除选择器之外,defuddle 的 ContentScorer 还维护着一份"降分但不删除"的负面词汇表。menu 同时出现在 navigationIndicators(src/removals/scoring.ts)和 nonContentPatterns(src/removals/scoring.ts)中,用于对疑似导航区块做内容评分惩罚。它的作用是:当某个容器 class 含 menu 且文本密度、链接特征像导航时,压低其得分,从而在"主内容定位"阶段输给真正的正文区块——但绝不会仅凭关键词直接删除元素。
这与 issue #106 的修复形成互补:选择器负责硬删除,评分负责软排序。即便某个站点用了 class="menu-content" 之类的变体绕过了精确与部分匹配,只要它的内容价值足够高(标题、段落、图片密度),评分机制仍会把它判定为正文而非导航。这也是 defuddle 面对海量 CMS 模板的容错策略:宁可保留可疑内容,也绝不误删真实正文。
五、回归保障:fixture 对比测试如何守住修复
单行注释的修复并不难,难的是防止未来重构重新引入。defuddle 的 fixture 测试体系(tests/fixtures.test.ts)专门解决这个问题:
- 自动扫描 tests/fixtures 目录下所有
.html夹具; - 用
Defuddle处理每个夹具,与 tests/expected 目录下同名.md期望文件做归一化对比(忽略属性顺序、归一化内嵌 SVG); - 期望文件缺失时生成基线;结果不一致时直接让测试失败。
任何人对 EXACT_SELECTORS / PARTIAL_SELECTORS / scoring.ts 的改动,只要导致 id="menu" 内容被误删,issues--106-menu-id 用例就会立刻报红。仓库中类似命名的大量 fixture(如 issues--132-hero-class、issues--136-time-element、issues--131-category-links)共同构成了一张覆盖"选择器误伤"风险的回归网。
若想本地验证,可按该测试套件的约定操作:向 tests/fixtures 新增 .html 夹具后运行测试生成基线,再审查 tests/expected 中生成的期望文件。日常查看抽取结果也可以直接用 CLI:node src/cli.ts parse <html 文件> -m --json(选项定义见 src/cli.ts),-m 输出 Markdown,--json 附带元数据。
六、设计启示:通用抽取器在"导航语义"上的取舍
#menu 案例折射出通用正文抽取器的核心矛盾:语义类名(nav、menu、header)在大多数站点指向导航,但总有个别站点用它命名正文容器。defuddle 给出的答案是分层的:
- 精确选择器只删语义最确定的(
nav、footer、.menu),对有正文容器嫌疑的 id 选择器(#menu、#header)一律谨慎处理; - 部分选择器用锚定匹配约束无分隔符 id,避免子串误伤;
- 评分系统用关键词降分而非删除,为内容价值留出兜底;
- fixture 回归测试把每个真实 issue 固化为永久防线。
对读者而言,这个案例的实操价值在于:调试任何正文抽取器时,如果发现内容被整块删除,第一反应应当是检查精确选择器清单里是否躺着 #xxx 形式的 id 规则——id 是页面内容锚点的重灾区,而 .class 规则的误伤面相对可控。这正是 issue #106 留给 defuddle 并沉淀进测试体系的最重要一课。