WeMD 测试体系揭秘:70+ 用例如何守住「复制到公众号」高风险链路

原创2026-10-22 10:25:001,430 阅读

WeMD 测试体系揭秘:70+ 用例如何守住「复制到公众号」高风险链路

WeMD 是一款更优雅的 Markdown 公众号编辑器,把 Markdown 排版成主题化文章后一键复制到微信。为了让这条「复制到公众号」的核心链路稳定可靠,项目围绕它部署了 170 多个测试用例、覆盖 20 余个测试文件,从 CSS 变量展开、公式降级到剪贴板兜底全都有回归保护,本文带你拆解这套 vitest 测试体系是如何工作的。

WeMD微信公众号编辑器界面:左侧Markdown编辑,右侧实时预览,一键复制到公众号

为什么「复制到公众号」是全项目风险最高的链路

微信公众号编辑器不接受任何源码粘贴,只认「富文本 + 内联样式」。这意味着 WeMD 的复制流程要同时跨过好几道坎:

  • CSS 会被清洗:微信不认 var(--xxx) 这类 CSS 变量,不认 counter() 伪元素,样式必须提前展开成具体值
  • 标签会被过滤:<input> 复选框会被直接删除,得换成 emoji
  • 渲染依赖要自保:数学公式(KaTeX/MathJax)、Mermaid 图表在微信里无法二次渲染,得提前转成 SVG
  • 剪贴板本身不可靠:不同浏览器、不同操作系统下 execCommand("copy") 行为差异巨大

项目贡献指南 CONTRIBUTING.md 里写得很直白:

复制到公众号、Markdown 渲染、主题、图床、文件系统和 Electron IPC 都是高风险链路,改动时需要补充对应测试。

而整条复制链路的总入口,就是 apps/web/src/services/wechatCopyService.ts 中的 copyToWechat() 函数。

测试基建:用 vitest + jsdom 模拟一个「真浏览器」

Web 端测试基于 vitest 4 + jsdom 环境,核心配置在 apps/web/vitest.config.ts:

  • environment: "jsdom":让测试拥有真实的 DOM,可以直接操作 HTML 容器
  • globals: true:describe / it / expect 免导入
  • alias:把 @wemd/core 直指 packages/core/src/index.ts,测试跑的是核心包源码而非构建产物

jsdom 天生缺一些浏览器 API,apps/web/src/test/setup.ts 统一补齐了 matchMedia、ResizeObserver 两个桩,并在每个用例后自动 cleanup() 清理 DOM——这保证了 700+ 用例之间互不污染。

170 个用例:复制链路测试矩阵

围绕复制链路,apps/web/src/__tests__/services/ 目录下的测试文件按「风险点」一文件一主题拆分,主力用例分布大致如下:

测试文件 用例数 守护的风险点
wechatCopyNormalizer.test.ts 24 根容器归一化:背景画布、内边距迁移、长代码换行
wechatCopyCssIntegration.test.ts 19 完整管线跑通后样式是否正确内联、var() 是否清零
cssVariableExpander.test.ts 17 CSS 变量展开:链式引用、循环引用、注释内大括号
wechatCopyService.test.ts 13 剪贴板策略选择与多级降级链
htmlCopyService.test.ts 12 「复制 HTML」链路的样式净化
wechatCopyTransport.test.ts 10 原生选区序列化:execCommand 返回 true 但实际未写入时继续兜底
wechatCopyMathCompat.integration.test.ts 9 高危公式转 SVG、MathJax 卡死时整体失败而非复制坏内容
wechatCounterCompat.test.ts 7 counter() 章节编号伪元素物化为真实节点
wechatMermaidSvgText.test.ts 7 Mermaid 图中长中文标签折行、子图标题
wechatCodeBlockCompat.test.ts 4 多行代码结构化换行,保留缩进与空行
wechatCopyTable.integration.test.ts 2 表格自动换行偏好写入最终 HTML

再算上核心包的 30 个 wechatDarkMode.test.ts(深色模式色彩转换)以及属性语法、Mac Bar 布局等集成测试,复制链相关用例轻松超过 170 个——标题里的「70+」其实是保守说法。

把踩过的坑写成「保险单」:issue 编号回归测试

细读测试名会发现一个有意思的习惯:用例直接以线上 issue 编号命名。比如:

  • propagates #wemd background-color to child blocks after normalization (#52)
  • 复制 Issue #90 的多行代码时使用结构化换行
  • 源码注释里还记着 #91(微信不转存 45×13 的小尺寸 data URI)和 #102(五个公式的完整复制)的修复决策

每个曾经翻过车的场景,都固化成了带编号的永久回归测试:只要再改复制链路,这些历史 bug 想复发就得先「死」在这些用例上。对普通用户来说,这就是「以前修好的 bug 不会莫名其妙回来」的保障。

双层防线:单元测试守纯函数,集成测试守全管线

这套体系还刻意分了两层:

单元测试——守纯函数边界。 像 expandCSSVariables() 这类函数被喂了 17 种刁钻输入:变量链式引用、循环引用、注释里藏着分号和大括号、data: URI 里出现的 {}……全部逐条断言。

集成测试——守端到端管线。 文件名带 integration 的用例(如 wechatCopyCssIntegration.test.ts)会调用真实的 Markdown 解析器 + processHtml() 走完整流程,验证「四款场景化主题的关键样式内联进最终剪贴板 HTML」这类只有全管线才能暴露的问题。

剪贴板策略也有专门的降级链测试:execCommand 失败 → Electron 剪贴板桥 → 原生 Clipboard API,任一环节挂掉都有下一层接住,且 Windows 下特意优先走与手动复制一致的选区链路(见 wechatCopyService.test.ts)。

自己动手:一键跑完全量测试

在仓库根目录,直接运行:

pnpm test

它会通过 turbo 依次执行所有子包的 test:ci。也可以按包单独跑:

pnpm --filter @wemd/web test -- --run
pnpm --filter @wemd/core test -- --run
pnpm --filter wemd-electron test

Web 端还贴心地提供 pnpm --filter @wemd/web test:ui(vitest 可视化界面)和 test:ui-acceptance 脚本,把编辑器交互相关的验收用例单独打了一组,方便快速回归 UI 改动。

图床上传同样在「测试监控区」

顺带一提,图床上传链路也有集成测试把关:autoCompressImage.test.ts 覆盖了「小图不压缩、超限先压缩再上传、分辨率超上限直接拒绝」等 8 种边界,imageUploadFlow.integration.test.ts 则验证上传前的完整决策。下图就是仓库 apps/server/uploads/ 目录里一张真实走过上传链路的示例图片。

WeMD图床上传链路中的示例图片:经过服务端上传目录的JPG文件

写在最后

WeMD 的测试哲学可以浓缩为一句话:把「复制到公众号」这条高风险链路拆成一个个可独立验证的风险点,再让每个风险点都有专属用例盯着。 114 个测试文件、774 个用例遍布 Web 端、核心包和 Electron 端,其中复制链路独占 170 余席——下次当你点击「复制到公众号」按钮时,背后正是这支「用例守夜队」在值岗。

登录后查看全文
WeMD