Harness 配置资产：本地验证与发布工作流

最小化模块化测试、沙盒隔离与晋升交付

工作流

工程化

xaringan

MathJax

Author

Harness 技术文档

Published

May 23, 2026

摘要

harness 中的可交付物是经本地验证的配置资产（如 js/mathjax/mathjax-config.js），而非测试产物、renv 或渲染输出。本文定义通用五阶段循环：Isolate → Specify → Verify → Promote → Publish，并强调模块化、分进程测试以避免多轮迭代中的 knitr hook 与会话状态污染。

MathJax 专项规程见 js/mathjax/test/xaringan-display-math-test-guide.md。

1. 进 Git vs 不进 Git

层级	提交到 GitHub	仅本地
可交付资产	`js/<asset>/` 下 canonical 文件	—
测试规程	`test/` 下指引、`modules/*.Rmd`、运行脚本	—
运行环境	文档中列出的包名与版本	`renv/`、全局 R 库
测试产物	—	`output/`、`libs/`、`*.html`、`TEST-LOG.md`

2. 五阶段工作流

flowchart TB
  isolate[Isolate 沙盒] --> specify[Specify 规程]
  specify --> verify[Verify L0/L1/L2]
  verify --> promote[Promote 晋升]
  promote --> publish[Publish 文档与Git]

Isolate — 在 js/<asset>/test/ 实验；renv/、output/ 写入 .gitignore；迭代只改 test 镜像，不动 canonical。
Specify — 中文或英文测试指引 + 用例矩阵 + 模块映射表；标明须配对使用的文件（若有）。
Verify — L0 单元 → L1 每模块独立 R 进程 → 可选 L2 冒烟；负向用例独立模块。
Promote — L1 必过项全绿后，同步更新 canonical 与 test 镜像。
Publish — 更新 docs/、index.qmd；Conventional Commit；不提交产物。

3. 三层测试（L0 / L1 / L2）

层级	目的	典型工具	render
L0	纯逻辑/字符串变换	`test-*.R` 脚本	否
L1	按关切拆分的最小集成	`run-module.R` → 新 R 进程	是
L2	发布前冒烟	`run-all-modules.R`	是

原则：L1 全模块通过即可晋升；L2 为可选复核。

4. 防污染 checklist

L1 使用 Rscript run-module.R，不在同一 RStudio 会话内连续 render 正负 deck
每模块输出到独立子目录（如 output/modules/<名>/）
负向用例单独 Rmd，不与正向合并
调试阶段只改 test/ 镜像，晋升前再同步 canonical
git status 无 output/、libs/、TEST-LOG.md

5. 目录约定（以 MathJax 为例）

js/mathjax/
├── mathjax-config.js       # canonical
├── wrap-display-math.R     # canonical（与 JS 配对）
├── index.qmd
└── test/                   # 沙盒（规程可提交，产物不提交）
    ├── modules/
    ├── js/                 # 镜像
    ├── Rscript/
    └── xaringan-display-math-test-guide.md

其它资产可复制：js/<name>/test/ + docs/<name>-*.qmd。模块 Rmd 建议对每个用例使用 (raw source) / (result view) 双幻灯片（见 MathJax 测试指引 §1.4）。

6. 与 Install-Harness 的关系

验证沙盒不通过 Install-Harness.ps1 分发。未来可为 canonical 资产新增 Profile；永不打包 test/output/。

摘要