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 集成 │  真实浏览器：特效/词云/懒加载/阅读模式等 18 项
├──────────────┤
│  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（语言解析/侧栏渲染/canonical 回落，10 用例）
helpers.test.js           # 字数统计三 helper（wordcount/min2read/totalcount；加密 origin/wiki 去重/回落/缓存重置，52 断言）
unit-sidebar-i18n.test.js # 侧栏 i18n 查表 + 回退链（当前→fallback→default→key，5 用例）
unit-sidebar-keys.test.js # 门禁校验器 sidebar-keys.js 行为（4 wiki × 9 语言覆盖，4 用例）
lang-fallback.test.js     # 回落链 4 级（13 断言）
unit-i18n-core.test.js   # i18n 核心回落语义（resolveI18n 四级链 + cfg 防御，10 用例）
unit-i18n-helper.test.js  # t() helper（fallback_lang + 大小写容错，5 用例）
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 计数，只让抖动可见。

具体 PASS 条数随版本增长（每新增一条断言即变化），以实际输出为准，不写死数字。

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 清单不一致"

已知覆盖缺口：wiki-integration.test.js、infinite-scroll-integration.test.js 两个文件存在但未挂入任何层（纯 playwright，无浏览器时必失败；由 L11 或发版前手动 playwright 验证覆盖）。新增用例时注意别重蹈覆辙。

mock 必须模拟真实 Hexo 对象（Query 而非普通数组）

写单测 mock site / locals 时，必须贴合 Hexo 的真实对象，否则单测全绿也拦不住构建级故障：

• site.posts / site.pages 是 Hexo 的 Query（类数组对象），.filter() 返回的仍是 Query 而非数组，且不能 for...of——必须先 .toArray() 取真数组。
• helpers.test.js（字数统计）最初用普通数组 mock，单测全绿；真实构建却 wikiPages is not iterable → 全部 HTML 输出 0 字节。补上 toArray() 后才覆盖到真实路径。

教训：mock 越接近真实对象，单测才越能拦住构建级故障；用普通数组替代 Query 会测不出 toArray() 缺失。

代码模板

L13 单测模板（node:test，无浏览器依赖）：

// tools/tests/my-feature.test.js
const { describe, it } = require('node:test');
const assert = require('node:assert/strict');
const fs = require('fs');
const path = require('path');

const PUBLIC = path.resolve(__dirname, '../../public');

describe('my-feature', () => {
  it('should render expected element', () => {
    const html = fs.readFileSync(path.join(PUBLIC, 'index.html'), 'utf8');
    assert.ok(html.includes('expected-marker'), 'missing expected marker');
  });
});

// 末尾输出（release-test.sh 通过此行判定）
const pass = 1, fail = 0;
console.log(`\n结果: PASS=${pass} FAIL=${fail}`);
process.exit(fail > 0 ? 1 : 0);

L11 playwright 模板（需 chromium + server）：

// tools/tests/my-interaction.test.js
const { chromium } = require('playwright');
const { interceptThirdParty, collectPageErrors } = require('./lib/browser-env');

const BASE = process.env.TEST_BASE || 'http://localhost:4000';
let browser, page;
let pass = 0, fail = 0;

async function setup() {
  browser = await chromium.launch();
  page = await browser.newPage();
  await interceptThirdParty(page);
}

async function testFeature() {
  const env = collectPageErrors(page, BASE);
  await page.goto(`${BASE}/posts/xxxxx/`, { waitUntil: 'networkidle' });
  const el = await page.$('.my-feature');
  if (el) { pass++; } else { fail++; console.error('FAIL: .my-feature not found'); }
  // 检查无 JS 异常
  if (env.jsErrors.length > 0) { fail++; console.error('FAIL: JS errors', env.jsErrors); }
  else { pass++; }
}

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

挂入门禁：在哪里加一行

L13（node 单测）：在 release-test.sh 的 ## L13 段追加一行：

run_test "my-feature" "node tools/tests/my-feature.test.js"

L11（playwright 集成）：在 release-test.sh 的 ## L11 段追加：

retry_match "my-interaction" "node tools/tests/my-interaction.test.js" "PASS=.*FAIL=0"

retry_match 包装外部依赖测试——网络抖动时自动重试 3 次，全失败降级为 warn 而非 fail（见 §5）。

完整示例：新增一个「侧边栏折叠」测试

1. 需求：验证文章页侧边栏在窄屏下自动折叠
2. 类型：需浏览器 → L11 playwright
3. 创建 tools/tests/sidebar-collapse.test.js（用上面 L11 模板）
4. 挂入：在 release-test.sh L11 段加 retry_match 行
5. 验证：tools/tests/release-test.sh --local 确认 PASS
6. TC 同步：make tc-index（或等 pre-commit hook 自动完成）

断言输出约定

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 覆盖。

13. 性能验证（LCP 基线，手工）

性能指标（LCP）不在自动化门禁内——它需要 Lighthouse 真机采样 + 网络条件控制，断言型测试无法稳定表达。验证方式是基线文档 + 复现命令：

• 基线文档：docs/analysis/LCP-V2-BASELINE-2026-09-18.md（资源计数 / Lighthouse desktop+mobile / LCP 元素身份 / §5 复现命令 / §7 优化实施）
• 优化四手段（2026-09-18~20）：关键 CSS preload · highlight 按 layout 条件加载 · markmap 本地化+异步 · 文章页首屏图 preload
• 门槛：mobile LCP ≤ 2.5s（Search Console「40 个 URL 超标」为观测口径）
• 陷阱：noscript 不剥离会让资源计数虚高 4 条/页（基线文档 §1.3），任何复测前必须先剥离
• 触发条件：改动 head 内资源加载顺序/条件（CSS/JS/图片）后必须复测

⚠️ 已知坑

坑 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）。

附：测试 ↔ 功能对照表

用途：想知道"某个功能有没有被自动测试覆盖"？在这里按功能名查找。

附：三重定位自查清单

新增/修改一篇「hexo主题功能测试」系列文章时，检查以下三项：

快速判断：如果一个功能"只列了名字没说怎么验证"→ 缺 ①；"只列语法不给效果"→ 缺 ②；"没说怎么用或有歧义"→ 缺 ③。

附：测试体系速查表

参考&致谢

系列教程

全部文章RSS订阅

Hexo 主题功能测试系列

• Hexo主题功能测试-布局与页面篇 —— 页面布局、导航、侧边栏、卡片等结构功能
• Hexo主题功能测试-交互视觉篇 —— 代码高亮、图片灯箱、动画、明暗切换等交互
• Hexo主题功能测试-内容tag篇 —— note / tabs / timeline / label / button 等 tag 插件
• Hexo主题功能测试-Markdown语法篇 —— Markdown 渲染与扩展语法
• Hexo主题功能测试-自动化测试篇 —— 主题功能的自动化测试方案