Hexo主题功能测试-自动化测试篇

本文是 matery 主题自动化测试体系的完整教程，与其余 4 篇功能测试文章（内容 tag / 交互视觉 / 布局页面 / Markdown 语法）配套——那 4 篇是"测试靶场"，本文是"测试引擎"。权威依据：tools/tests/release-test.sh（L1-L14，13 层 156 行纯编排）、docs/superpowers/specs/2026-08-06-layout-test-cases.md。

1. 测试金字塔总览

┌──────────────┐
│  L2 生产 URL  │  发版后：20 页面 HTTP 200 + 功能标记（curl）
│  L9/L10 SW   │  发版前：Vercel 测试域 SW 冒烟（playwright）
├──────────────┤
│  L11 Playwright 集成 │  真实浏览器：特效/词云/懒加载/阅读模式等 15 项
├──────────────┤
│  L14 视觉断言 │  visual-assert 精确数值：7 套件（生产阻塞，本地默认跳过）
├──────────────┤
│  L13 单测门禁 │  node 直跑：13 个 .test.js + 4 个 shell 单测
├──────────────┤
│  L1 构建验证  │  hexo g Success + 产物完整（index.html > 1000B）
└──────────────┘

2. release-test.sh 用法

# 完整跑（构建 + 生产检查 + SW 冒烟 + playwright 集成）——发版门禁
tools/tests/release-test.sh

# 跳过构建（public/ 已就绪）
tools/tests/release-test.sh --skip-build

# 本地迭代（端口自适应探测，跳过远程 SW 冒烟 L10 + playwright 集成 L11）
tools/tests/release-test.sh --local

# 仅跳过远程 SW 冒烟（保留 playwright 集成）
tools/tests/release-test.sh --skip-l10

基址：生产固定 https://blog.17lai.site（443，绝无端口）；本地 LOCAL_BASE 走端口自适应——探测顺序 BLOG_PORT 环境变量 → TEST_BASE 环境变量 → 根 _config.yml 的 server.port（docker 4000）→ 4100，取第一个 HTTP 200；成功后导出 TEST_BASE/TEST_URL，36 个测试文件自动跟随。

执行顺序（156 行纯编排，非文档顺序）：L0 preflight → L10 → L01 → L02 → L03_05 → L07 → L08 → L09 → L11 → L12 → L2i → L13 → L13a → L14 → TC 索引校验 → 汇总。注意 L10 最先跑（在 L01 之前）——旧文档常写反。

发版铁律：tools/cicd.sh -r 发布后必须跑 tools/tests/release-test.sh 验证生产环境。

3. L1-L14 各层覆盖内容

L11 Playwright 集成清单（真实浏览器）

4. 单测清单（tools/tests/）

L13 门禁单测（release-test.sh 直跑）

# node 单测（纯单测/静态，无浏览器依赖）
unit-toc.test.js          # TOC 折叠配置（collapseDepth 0||6 falsy 陷阱）
unit-search.test.js       # 搜索三引擎
unit-multilang.test.js    # 多语言配置
unit-encrypt2.test.js     # 加密扩展（片段 + wiki）
unit-wiki-helper.test.js  # wiki helper
lang-fallback.test.js     # 回落链 4 级（13 断言）
echarts-charts.test.js    # ECharts 图表
banner-bg.test.js         # banner 与背景偏好联动
homepage.test.js          # 首页结构
imgsize-unit.test.js      # 图片尺寸注入脚本的单元测试（normalizeImgUrl 协议相对 URL 补全 + 本地/网络图片尺寸读取逻辑）
search-integration.test.js
infinite-scroll-aos.test.js
unit-standalone.test.js   # 独立页排除法判定 + 语言前缀豁免（22 断言）

# shell 单测
unit-css-architecture.test.sh   # CSS 架构（编译产物关键选择器）
unit-version.test.sh            # 版本递增进位（防 12.99→12.100）
unit-retry.test.sh              # 退避重试库
unit-deploy-target.test.sh      # 部署目标切换（hexo/hexoback 双激活校验）

其他单测（原 run-tests.sh L1 / L8 段，已并入 release-test.sh）

unit-encrypt.test.js      # 自研加密体系（AES-GCM + PBKDF2 闭环，9 用例）
unit-fontawesome.test.py  # FontAwesome 精简脚本

5. 外部依赖重试与降级（lib/retry.sh）

第三方网络抖动不可避免（Algolia API / CDN 视频 / 音乐 API），且外部服务不可用不是产品缺陷，不应拦发版。tools/tests/lib/retry.sh 统一处理：

source tools/tests/lib/retry.sh

# exit-code 判定：退避重试 3 次（1s/4s/9s + 抖动）
retry_run "L2 搜索" "node tools/tests/search-integration.test.js"

# 输出模式判定（release-test L11 用）
retry_match "L2d 视频" "node .../videobg-integration.test.js" "PASS=.*FAIL=0"

失败分类（全失败时按日志签名区分）：

6. 第三方拦截 + ERR_ABORTED 排除（lib/browser-env.js）

playwright 测试的共享环境辅助，统一"页面自身错误"归属：

const { interceptThirdParty, collectPageErrors } = require('./lib/browser-env');

const env = collectPageErrors(page, BASE);   // 持续累积 JS 异常 + 同源资源失败
await interceptThirdParty(page);             // 拦截已知污染源
// 断言：env.jsErrors.length === 0 && env.sameOriginFailures.length === 0

7. 压缩开关验证（cicd.sh）

tools/cicd.sh 按模式注入压缩开关（sed 替换根 _config.yml 的 # minify-switch 标记行）：

验证方法：

# 1. debug 构建（未压缩）
tools/cicd.sh -d
head -c 300 public/css/main.css   # 多行、带缩进、有注释

# 2. 压缩构建（-t 本地编译测试，压缩无 CDN）
tools/cicd.sh -t
head -c 300 public/css/main.css   # 单行、无注释、体积显著变小

构建后 cicd.sh 会还原 _config.yml（仅当改动只涉及 minify-switch 标记行时），避免工作区脏。

8. 环境就绪、单实例锁与基址自适应

门禁前先过 preflight（环境预检，step 0），未就绪则秒级失败并打印修复命令，避免"跑一半才发现 server 挂了"：

# 未就绪时打印的 3 条修复命令（任选其一）
docker compose -f docker-compose.test.yml exec -T hexo bash -c 'tools/cicd.sh -d'
tools/test.sh server
docker compose -f docker-compose.test.yml exec -T hexo bash -c 'pm2 restart all'

--prepare 自动就绪：容器未跑则启动、产物无效则重建、最后复检。

单实例锁：门禁启动即在 ${TMPDIR:-/tmp}/opencode/gate.lock 取锁，并发运行被直接拒绝（打印持锁 PID）；陈旧锁自动接管，trap EXIT 释放。禁止并发门禁——并发会互相 kill 本地 server。

基址与端口自适应：见 §2 的基址段（生产 443 固定 / 本地端口探测）——36 个测试文件靠导出的 TEST_BASE/TEST_URL 自动跟随。

9. L14 视觉断言层

tools/visual-assert/*.json 共 16 套件，门禁 L14 只跑其中 7 套：layout-checks、dark-mode、search-modal、reward-modal、homepage、about、footer。

⚠️ make visual-assert 陷阱：该 make 目标依赖 build，build 会原地改写 themes/matery/_config.yml 占位符 → 触发 L5 版本一致性 4 项失败。正确用法：node tools/visual-assert.js run --local [tools/visual-assert/<suite>.json]，或交给 L14 层跑。

10. TC 索引与 git hooks

测试的权威来源是 tools/tests/**；生成的 TC 表位于 docs/superpowers/specs/2026-08-06-layout-test-cases.md 的 <!-- GENERATED:START --> 与 <!-- GENERATED:END --> 之间。

首次克隆需启用一次：git config core.hooksPath .githooks。门禁报"TC 清单不一致"时，跑 make tc-index 再提交（旁路 git commit --no-verify）。

当前索引：13 层 / 33 测试文件 / 3 lib 文件 / 251 断言 / 84 用例名。

11. flake 可见化与基线参考值

flake 可见化：被重试后通过的项目记入 FLAKY_LIST，门禁末尾打印 ⚠️ 本次门禁 flaky: N 项（…）；它不改变 PASS/FAIL 计数，只让抖动可见。

3 个 lib：assert.sh（82 行）、retry.sh（114 行，负责 flake 追踪）、preflight.sh（230 行）。browser-env.js 为 playwright 共享辅助（见 §6）。

12. 如何新增一个测试用例

步骤

1. 确定测试类型：
   • 纯单测 / 静态断言（无浏览器）→ 归 L13（node 直跑）
   • playwright 集成（需 chromium + server）→ 归 L11
2. 创建测试文件 tools/tests/xxx.test.js（node:test 或 playwright）
3. 外部依赖测试：用 retry_run / retry_match 包装（lib/retry.sh），全失败自动分类降级
4. playwright 测试：用 lib/browser-env.js 的 interceptThirdParty + collectPageErrors 统一错误归属
5. 注册到 release-test.sh 对应层（L11 或 L13 段），输出格式对齐（PASS=N FAIL=0 或 N 通过 / 0 失败）
6. 本地验证：tools/tests/release-test.sh --local（跑 L13 + curl 断言）；发版门禁跑全量
7. 同步 TC 索引：新增/改动后必须让 TC 索引同步（.githooks/pre-commit 自动完成；或手动 make tc-index）——否则门禁 --check 报"TC 清单不一致"

已知覆盖缺口：以下 4 个测试文件存在但未挂入任何层——unit/helpers.test.js、unit/utils.test.js（仅被 L13a 的 unit/** 覆盖率 glob 附带执行）、wiki-integration.test.js、infinite-scroll-integration.test.js（纯 playwright，从不运行）。新增用例时注意别重蹈覆辙。

断言输出约定

release-test.sh 按输出模式判定通过/失败，测试文件末尾必须输出可匹配的汇总行：

console.log(`\n结果: PASS=${pass} FAIL=${fail}`);
process.exit(fail > 0 ? 1 : 0);

测试用例权威清单

docs/superpowers/specs/2026-08-06-layout-test-cases.md（全量 layout 测试用例）+ docs/testing/TESTING-PYRAMID-GUIDE.md（测试方法论）——新增功能后同步更新用例清单与 release-test.sh 覆盖。

⚠️ 已知坑

坑 5：改配置后必须 clean 构建

现象：跑门禁时 L1 构建验证通过但功能断言失败。

原因：本地预览使用旧缓存产物，测试断言的是旧版行为。

正确做法：跑门禁前必须 npm run clean && npm run build，或使用 tools/tests/release-test.sh --prepare 自动就绪。

坑 6：source/_data/* 增量缓存误判

现象：修改友链/相册数据后，L2 URL 断言页面空白或数据不更新。

原因：Hexo 增量缓存误判「已缓存未变化」。

正确做法：修改数据文件后先 rm -f db.json && npm run build 再跑门禁。容器环境用 tools/cicd.sh -d（内置 clean）。

附：测试体系速查表