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

# 门禁层清单 —— 唯一权威（行序 = 执行顺序）
# 格式：ID<TAB>脚本文件<TAB>入口函数<TAB>描述
# 消费者：tools/tests/release-test.sh（source + 调用）、tools/tests/gen-tc-index.js（层清单）
L10	L10_smoke.sh	run_L10	发版前 SW 冒烟（远程测试域；--local 跳过）
L01	L01_build.sh	run_L01	构建验证
L02	L02_urls.sh	run_L02	URL 与链接完整性
L03_05	L03_05_static.sh	run_L03_05	静态资源与页面渲染（L3-L6）
L07	L07_core.sh	run_L07	核心功能
L08	L08_enhanced.sh	run_L08	增强功能
L09	L09_sw.sh	run_L09	Service Worker
L11	L11_integration.sh	run_L11	Playwright 集成
L12	L12_local.sh	run_L12	本地化资源 + 多语言一致性
L2i	L2i_seo.sh	run_L2i	SEO 结构化数据
L13	L13_units.sh	run_L13	全量单测门禁
L13a	L13a_cov.sh	run_L13a	覆盖率阈值
L14	L14_visual.sh	run_L14	视觉断言

cat tools/tests/layers/manifest

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

🔨 L1: 构建验证
  ✅ 构建成功 (hexo g Success)
  ✅ public/index.html 存在 (123456 字节)

tools/tests/release-test.sh          # L1 由其内部调用 cicd.sh -d 产出

🧪 L13: 全量单元/集成测试门禁（node tools/tests/*.test.js）
  ✅ 单测 unit-toc.test.js
  ✅ 单测 unit-search.test.js
  ✅ 单测 unit-css-architecture.test.sh（CSS 架构）

node tools/tests/unit/unit-toc.test.js   # 单跑其中一个，看它自己的输出

✅ 词云/去jQuery/防闪烁集成测试（PASS=8）
✅ 内容宽度统一测试（PASS=5）

node tools/tests/wordcloud.test.js

🎯 L14: 视觉断言（visual-assert）
  ✅ L14 layout-checks：18 项全部通过
  ✅ L14 dark-mode：4 项全部通过
  ⏱️  L14 总计：12 文件通过, 0 文件失败（299s）

node tools/visual-assert.js run --local tools/visual-assert/dark-mode.json

=============================================
 发版全量自动化测试 (target: https://blog.17lai.site)
=============================================
🔍 [preflight] 环境预检...
  ✅ 构建产物有效 (123456 字节)
  ✅ playwright 可用（NODE_PATH=/home/andy/.local/share/mise/installs/npm-playwright/1.56.0/lib/node_modules）
  ✅ _config.yml 未被污染
  ✅ 网络基址可达（HTTP 200）
✅ [preflight] 环境就绪
🔒 [preflight] 已获取门禁锁（PID 12345）

🌐 L10: 发版前 SW 冒烟（Vercel 测试域 blog2.17lai.site）
...
 测试结果: PASS=<N> FAIL=0
=============================================
🎉 全部通过！

tools/tests/release-test.sh

 ⏭️  已跳过 L10（远程 SW 冒烟）与 L11（playwright 集成）—— 本地迭代模式；
     发版门禁（不带 --local）会跑全量，L11 覆盖内容宽度/灯箱/懒加载/阅读模式等
 测试结果: PASS=<N> FAIL=0
🎉 全部通过！

tools/tests/release-test.sh --local

🔨 L1: 构建验证
  ✅ 跳过构建（--skip-build）
  ✅ 跳过产物验证（--skip-build）

tools/tests/release-test.sh --skip-build

🌐 L10: 发版前 SW 冒烟（Vercel 测试域 blog2.17lai.site）
  ⏭️ 跳过 L10（--local/--skip-l10：本地迭代不验证远程 SW）

tools/tests/release-test.sh --skip-l10

🔧 [preflight] 自动就绪环境...
  ✅ 容器已在运行
  ✅ 产物有效 (123456 字节)，跳过重建
🔍 [preflight] 复检环境...
✅ [preflight] 环境就绪

tools/tests/release-test.sh --prepare

🎯 L14: 视觉断言（visual-assert）
  ✅ L14 layout-checks：18 项全部通过
  ⏱️  L14 总计：12 文件通过, 0 文件失败（299s）

RUN_L14=1 tools/tests/release-test.sh --local

🎯 L14: 视觉断言（visual-assert）
  ⏭️  L14 视觉断言（SKIP_L14=1 → 强制跳过）

SKIP_L14=1 RUN_L14=1 tools/tests/release-test.sh

❌ [preflight] 门禁已在运行（PID 12345），拒绝并发启动
   锁文件：/tmp/opencode/gate.lock
   💡 如确认无其他门禁在跑，可手动删除：rm /tmp/opencode/gate.lock

tools/tests/release-test.sh --local   # 另开一个终端重复执行即可复现

❌ 本地服务器不可达（已尝试端口: 4000 4100）

  💡 修复命令（任选其一）：
     1. docker 生成: docker compose -f docker-compose.test.yml exec -T hexo bash -c 'tools/cicd.sh -d'
     2. 本机预览:    tools/test.sh server
     3. 恢复服务:    docker compose -f docker-compose.test.yml exec -T hexo bash -c 'pm2 restart all'

tools/tests/release-test.sh --local

 测试结果: PASS=<N> FAIL=2
=============================================
❌ 存在失败项，请检查！

tools/tests/release-test.sh        # exit code 1

🔨 L1: 构建验证
  ✅ 构建成功 (hexo g Success)
  ✅ public/index.html 存在 (123456 字节)

tools/tests/release-test.sh            # 不带 --skip-build 即跑 L1

✅ /archives/ → 200
✅ /categories/ → 200
✅ /tags/ → 200

curl -s -o /dev/null -w '%{http_code}\n' https://blog.17lai.site/archives/

✅ 搜索入口
✅ TOC 折叠配置（<实际配置值>，0=全部折叠）
✅ 暗色模式 CSS
✅ infinite-scroll 状态元素 + data-loading 文案 (<i18n 文案>)

curl -s https://blog.17lai.site/ | grep -o 'id="searchInput"' | head -1

✅ 单测 unit-wiki-helper.test.js
✅ 单测 search-integration.test.js（PASS=<N> FAIL=0）
✅ 教程文章结构门禁 check-tutorial-articles.js

node tools/tests/unit/unit-wiki-helper.test.js

✅ L14 homepage：<N> 项全部通过
⚠️  L14 nav-scrolled 第 1 次未通过（疑似负载抖动），重试一次…
✅ L14 nav-scrolled：<N> 项全部通过
⏱️  L14 总计：12 文件通过, 0 文件失败（312s）

node tools/visual-assert.js run --local tools/visual-assert/nav-scrolled.json

✅ TOC 折叠配置解析（collapseDepth=0 视为全部折叠）
✅ collapseDepth=6 视为全部展开
✅ 未配置时取默认值

结果: PASS=3 FAIL=0

node tools/tests/unit/unit-toc.test.js

结果: PASS=3 FAIL=0

结果: 5 通过, 0 失败

unit-i18n-core: 10 pass / 0 fail

grep -n 'console.log' tools/tests/unit/unit-toc.test.js | tail -2

结果: PASS

bash tools/tests/unit/unit-version.test.sh

ℹ all files      | 86.66 | 78.98 | 72.73 |

✅ node:test 单元测试 + 覆盖率达标（86.66/78.98/72.73）

node --test --experimental-test-coverage \
    --test-coverage-lines=85 --test-coverage-branches=77 --test-coverage-functions=70 \
    "tools/tests/unit/**/*.test.js"

# 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 断言）
utils.test.js             # 通用工具函数
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 补全 + 本地/网络图片尺寸读取）
infinite-scroll-aos.test.js # 无限滚动 + AOS 联动
unit-standalone.test.js   # 独立页排除法判定 + 语言前缀豁免（22 断言）
unit-i18n-helper.test.js  # t() helper（fallback_lang + 大小写容错，5 用例）

# 带外部依赖的集成（retry_match 包装，判据 PASS=N FAIL=0）
search-integration.test.js  # 搜索集成（Algolia 分页需真实 API）

# 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 双激活校验）

unit-i18n-core.test.js    # i18n 核心回落语义（resolveI18n 四级链 + cfg 防御，10 用例）
unit-sidebar-i18n.test.js # 侧栏 i18n 查表 + 回退链（当前→fallback→default→key，5 用例）
unit-sidebar-keys.test.js # 门禁校验器 sidebar-keys.js 行为（4 wiki × 9 语言覆盖，4 用例）
unit-encrypt.test.js      # 自研加密体系（AES-GCM + PBKDF2 闭环，9 用例）
unit-markmap-prune.test.js # markmap 无脑图页面资源拆除（6 用例）
unit-updated.test.js      # 「更新于」取 git 最后提交时间（4 用例）

unit-fontawesome.test.py  # FontAwesome 精简脚本（L13a 通配只收 .test.js，不含 .py）

⏳ 搜索集成 无输出（疑似超时），退避 1s 重试...
❌ 搜索集成 业务断言失败（真 bug）

tools/tests/release-test.sh --local   # 改动末尾 console.log 后复跑即可复现

✅ L2 搜索 通过

source tools/tests/lib/retry.sh
retry_run "L2 搜索" "node tools/tests/search-integration.test.js"

⏳ L2 搜索 第 1 次失败，退避 1s 重试...
⚠️  L2 搜索 第 2 次通过（前 1 次 flaky，需关注）

retry_run "L2 搜索" "node tools/tests/search-integration.test.js"

⏳ L2d 视频 第 1 次未通过，退避 1s 重试...
✅ L2d 视频 通过

retry_match "L2d 视频" "timeout 180 node tools/tests/videobg-integration.test.js" "0 失败|fail 0|失败, 0"

⚠️  L2d 视频 外部依赖不可用（降级 warn，非产品缺陷）
📄 日志: /tmp/opencode/test-L2d_视频.log

retry_match "L2d 视频" "timeout 180 node tools/tests/videobg-integration.test.js" "0 失败"

❌ L2d 视频 业务断言失败（真 bug）
📄 日志: /tmp/opencode/test-L2d_视频.log

retry_match "L2d 视频" "timeout 180 node tools/tests/videobg-integration.test.js" "0 失败"

✅ 页面无 JS 异常
✅ 无同源资源失败

node tools/tests/content-width.test.js    # 任一 playwright 测试的断言现场

❌ JS errors [ 'Failed to parse JSON from webpushr' ]

node tools/tests/effects-integration.test.js

jsErrors: []
sameOriginFailures: []

NODE_PATH=$(npm root) node tools/tests/lightbox.test.js

js:
  enable: true # minify-switch
css:
  enable: true # minify-switch
html:
  enable: true # minify-switch

grep -n 'minify-switch' _config.yml

.anchorjs-link {
  text-decoration: none !important;
  transition: opacity 0.2s ease-in-out;
}
.markdown-body h1:hover > .anchorjs-link,
h2:hover > .anchorjs-link,

tools/cicd.sh -d
head -c 200 public/css/main.css

.anchorjs-link{text-decoration:none!important;transition:opacity .2s ease-in-out}.markdown-body h1:hover>.anchorjs-link,...

tools/cicd.sh -t
head -c 200 public/css/main.css

🔍 [preflight] 环境预检...
  ✅ 构建产物有效 (123456 字节)
  ✅ playwright 可用（NODE_PATH=/home/andy/.local/share/mise/installs/npm-playwright/1.56.0/lib/node_modules）
  ✅ _config.yml 未被污染
  ✅ 网络基址可达（HTTP 200）
✅ [preflight] 环境就绪

tools/tests/release-test.sh --local

❌ 构建产物不存在（public/index.html）
💡 修复命令：docker compose -f docker-compose.test.yml exec -T hexo bash -c 'tools/cicd.sh -d'

tools/tests/release-test.sh --skip-build   # 跳过构建但产物不存在时即可见

⚠️  themes/matery/_config.yml 被构建污染（有未提交修改）
🔧 自动恢复：git -C themes/matery checkout -- _config.yml
✅ _config.yml 已自动恢复

tools/tests/release-test.sh --local

✓ 本地基址: http://localhost:4100（端口 4100）
  ✅ 已导出 TEST_BASE=http://localhost:4100 TEST_URL=http://localhost:4100

tools/tests/release-test.sh --local

# 未就绪时打印的 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'

结果: 18 通过, 0 失败

node tools/visual-assert.js run --local tools/visual-assert/layout-checks.json

✅ L14 layout-checks：18 项全部通过

node tools/visual-assert.js run --local tools/visual-assert/layout-checks.json

❌ L14 footer：<M> 失败（共 <N> 项）｜明细：❌ footer-margin 期望 24px 实际 16px  ❌ footer-padding ...

node tools/visual-assert.js run --local tools/visual-assert/footer.json

❌ L14 post-layout：超时或异常（exit 124）

L14_TIMEOUT=900 node tools/visual-assert.js run --local tools/visual-assert/layout-checks.json

layout-checks  reward-modal  search-modal  dark-mode  homepage  about
footer         404           i18n          tags       nav-scrolled  toc-expanded

📊 扫描结果：13 层 / 42 测试文件 / 3 lib 文件 / 284 断言 / 406 用例名
✅ TC 索引已写入（13 层 / 284 断言）

node tools/tests/gen-tc-index.js

✅ TC 索引与测试文件一致

node tools/tests/gen-tc-index.js --check

❌ TC 清单不一致（运行 node tools/tests/gen-tc-index.js 更新）

make tc-index-check

🔧 检测到 tools/tests/ 变更，重新生成 TC 清单...
✅ TC 索引已写入（13 层 / 284 断言）

git config core.hooksPath .githooks    # 新克隆执行一次

 测试结果: PASS=<N> FAIL=0
=============================================
🎉 全部通过！

tools/tests/release-test.sh

 ⚠️  本次门禁 flaky: 1 项（L14 nav-scrolled）
 测试结果: PASS=<N> FAIL=0
🎉 全部通过！

tools/tests/release-test.sh

 ⏭️  已跳过 L10（远程 SW 冒烟）与 L11（playwright 集成）—— 本地迭代模式；
 测试结果: PASS=<N> FAIL=0
🎉 全部通过！

tools/tests/release-test.sh --local

✅ should render expected element

结果: PASS=1 FAIL=0

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

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

✅ 单测 my-feature.test.js

# 在 tools/tests/layers/L13_units.sh 的 for 清单里追加文件名即可（unit/ 前缀自动判断）
    my-feature.test.js \

✅ my-interaction 通过

retry_match "my-interaction" "node tools/tests/my-interaction.test.js" "PASS=.*FAIL=0"   # 写进 layers/L11_integration.sh

 测试结果: PASS=<N> FAIL=0
🎉 全部通过！

tools/tests/release-test.sh --local

✅ TC 索引与测试文件一致

make tc-index

// 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);

// 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);
})();

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

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

❌ TC 清单不一致（运行 node tools/tests/gen-tc-index.js 更新）

node tools/tests/gen-tc-index.js --check

**移动端 LCP 4.6 s / 5.3 s 均远超 2.5 s 门槛**，与 Search Console「40 个 URL 的 LCP > 2.5s」的字段结论方向一致。

grep -n '移动端 LCP' docs/analysis/LCP-V2-BASELINE-2026-09-18.md

| 模式 | 页面 | LCP | FCP | TBT | CLS | 性能分 | LCP 元素 |

grep -n '| 模式 | 页面 | LCP' docs/analysis/LCP-V2-BASELINE-2026-09-18.md

- mobile LCP 两组分别为 **4.6/5.3 s**（§2.2）与 **3.7/3.6 s**（本组）——**运行间方差约 ±0.9 s**，与 mobile 节流下的固有噪声一致。**B 验收必须用多组采样的中位数，勿用单次值**。

grep -n '运行间方差' docs/analysis/LCP-V2-BASELINE-2026-09-18.md

🔨 L1: 构建验证
  ✅ 构建成功 (hexo g Success)
...
  ❌ 搜索入口

npm run clean && npm run build        # 或 tools/tests/release-test.sh --prepare

❌ /friends/ → 200 但页面无友链内容

rm -f db.json && npm run build        # 容器环境用 tools/cicd.sh -d（内置 clean）