plate 仓库的 slate-hyperscript Bun 测试迁移：从 Mocha fixture 到 bun test 一等公民

plate 仓库的 slate-hyperscript Bun 测试迁移从 Mocha fixture 到 bun test 一等公民【免费下载链接】plateRich-text editor with AI and shadcn/ui项目地址: https://gitcode.com/GitHub_Trending/pl/plate导读本文围绕 docs/plans/2026-04-16-slate-v2-slate-hyperscript-bun-migration.md 这份已完成的迁移计划完整还原 plate 仓库slate-v2 测试体系如何把slate-hyperscript包从旧的 Mocha fixture 测试框架整体迁移到根级 Bun 测试体系用一等公民的*.spec.tsx测试文件替代 fixture bank用本地 JSX helper 绕过 Bun 对自定义 pragma 路径的限制并用 scoped preload transform 作为最后一道桥接。读完本文你将掌握 Bun 测试体系下「测试入口替换、TSX pragma 兼容、preload 全局预置、tsconfig 与脚本重接」的完整实操路径以及这套模式在当前仓库中的真实落地形态。一、背景slate-hyperscript 与它的旧 Mocha 测试体系slate-hyperscript 是什么在 Slate 生态中slate-hyperscript是一套基于 JSX 语法构建 Slate 文档树的测试工具通过editor、element、text、cursor等标签把期望的编辑器状态直接写成声明式 JSX再编译为真实的 Slate 节点树从而让测试断言如选区位置、节点结构变得可读、可维护。在 plate 仓库中这一能力的核心实现位于 packages/test-utils/src/internals/hyperscript.ts它导出一个createHyperscript从源码结构看返回 JSX 函数配合 creators.ts 中的createAnchor、createCursor、createEditor、createElement、createFocus、createFragment、createSelection、createText以及 tokens.ts 的 token 解析共同构成测试侧书写 Slate 状态的声明式语言。旧方案Mocha fixture bank 动态 harness迁移前slate-hyperscript包的测试走的是传统 Mocha 链路包的测试入口是test/index.js只启动 Mocha与根级 Bun 测试体系完全割裂测试用例依托遗留的 fixture bank一批预置的文档/选区快照和动态 harness根据 fixture 动态生成断言逻辑的脚手架来运行由于 Mocha 不提供 Bun 的全局预置机制DOM 环境、断言匹配器等都需要在 harness 内部自建。这套体系的问题在于fixture bank 是数据 生成器的间接模式用例意图被埋藏在快照数据里而且它与仓库其他包已经迁到 Bun 的包使用两套不同的测试运行方式维护成本高、心智负担重。二、迁移目标与硬性约束迁移计划开篇明确了一组约束这决定了后续每一步的走向约束含义Keep only the rootbunfig.toml测试配置只保留仓库根级一份不再为单包维护独立 bunfigKeep thetest/directory name保持包内测试目录名为test/不因迁移改名No fake skips or suppressed tests不允许假跳过skip/todo糊弄或静默吞掉失败用例Do not broaden the change intoslateorslate-history迁移范围严格限定在slate-hyperscript包不顺手扩散到相邻包其中不扩散范围尤其值得注意在大型 monorepo 迁移中最容易失控的就是顺手把旁边的包也改了。这份计划把边界写死保证每次迁移的 diff 可审查、可回滚。三、现状诊断Findings迁移前团队做了四点评判这也是整个方案的技术依据当前包测试入口是 Mocha-onlytest/index.js只负责拉起 MochaBun 根本不会执行任何slate-hyperscript用例Bun 原生 TSX 不认 hyperscript pragma 路径这是整个迁移里最关键的坑。Bun 的 JSX 编译支持/** jsx */与jsxImportSource等机制但slate-hyperscript这类工具需要把 JSX 编译到自定义函数路径例如hyperscript模块的jsx导出Bun 在此场景下并不按预期 honor pragma 路径直接写 TSX 会编译失败遗留 fixture bank 与动态 harness 已被删除意味着旧资产不再需要兼容可以放手用一等公民 spec 重写剩余桥接只剩一个 scoped preload transformconfig/bun-test-setup.ts中有一段限定作用域的预置转换逻辑——它只对指定的 Bun spec 文件生效而不是像旧方案那样面向整个 fixture 语料库。scoped限定作用域是这套设计的关键词preload 全局预置本应影响所有测试文件但这里通过条件判断把副作用限制在slate-hyperscript的 spec 文件上避免污染其他包的测试。四、迁移步骤详解Plan计划共分 7 步从入口替换到脚本重接最终完成全链路切换第 1 步用 Bun spec 入口替换 Mocha 测试入口删除test/index.js的 Mocha 启动逻辑改为标准 Bun 测试入口。Bun 会直接发现并执行 spec 文件不再需要mocha作为包的测试运行器。第 2 步用一等公民 Bun spec 替换 fixture bank新增packages/slate-hyperscript/test/hyperscript.spec.tsx。这是一份**一等公民first-class**的 Bun 测试文件用例直接写在 spec 里用describe/it/expectBun 内建断言组织断言即用例、用例即文档取代了原来数据快照 动态生成的间接模式。从当前仓库的测试约定看这一步完全符合根级测试发现的规范tooling/config/test-suites.mjs 中TEST_FILE_PATTERNS明确包含packages/**/*.spec.{ts,tsx}即所有包内的*.spec.ts(x)文件都会被根级 Bun 测试流程自动收集。第 3 步新增本地 JSX helper新增packages/slate-hyperscript/test/jsx.ts。这正是为了解决上文提到的Bun TSX 不 honor hyperscript pragma 路径的问题与其依赖编译期 pragma 解析不如在测试文件里显式引入一个本地 JSX helper把editor.../editor之类的标签显式编译为对jsx函数的调用。这是把编译期魔法降级为显式函数调用的务实做法——可读性稍降但可预测性大幅提升。第 4 步重定向 scoped Bun preload transform把config/bun-test-setup.ts中原本指向旧 fixture 语料库的转换逻辑改为只针对新的hyperscript.spec.tsx生效。preload 在测试文件执行前运行见下文根级 bunfig.toml 的配置在这里完成 DOM 全局、断言匹配器等环境预置重定向目标后slate-hyperscript 的用例也享受与全仓库一致的测试环境但转换副作用依然被限定在包内。第 5 步重命名测试专用 tsconfig将config/tsconfig.bun-test.json重命名为config/tsconfig.test.json。命名的变化反映职责变化不再强调这是 Bun 专用的而是强调这是测试体系共用的。当前仓库的根级 bunfig.toml 正是这样引用的[test] # Preload scripts execute BEFORE any test file # Order matters: setup must come first for DOM globals preload [./tooling/config/bunTestSetup.ts] # Use test-specific tsconfig for path mappings (e.g., /registry/*) tsconfig ./tooling/config/tsconfig.test.json # Keep the inner loop quiet. Full pass spam is slower and useless. onlyFailures true而 tooling/config/tsconfig.test.json 继承了仓库根 tsconfig.json并补充了测试所需的路由映射/registry/*、/components/*、/lib/*等apps/www下的路径别名保证测试文件能正确解析 workspace 内部导入。第 6 步重接根级与包级测试脚本根级 package.json 中的测试脚本体系如下test→bun tooling/scripts/test-fast.mjs快速测试套件入口test:slow→bun tooling/scripts/test-slow.mjs、test:slowest→bun tooling/scripts/test-slowest.mjs慢速/最慢用例分层p:test→cd ${INIT_CWD:-.} bun test包级测试脚本模板各包通过plate-pkg p:test间接调用即 packages/slate/package.json 中test: plate-pkg p:test的形式。迁移后slate-hyperscript包走统一的bun test不再需要单独的 Mocha 脚本根级 tooling/scripts/test-fast.mjs 通过 tooling/config/test-suites.mjs 的 glob 规则自动纳入该包的*.spec.tsx。第 7 步验证见下文第六节的完整验证命令集。五、当前仓库的落地形态根级 Bun 测试基础设施迁移计划标注为status: completed。从当前仓库的实际代码看这套根级 Bun 测试体系已经全面落地并且正是第 4、5 步描述的那份 preload tsconfig 组合1. 唯一的根级 bunfig.toml根目录 bunfig.toml 是全仓库唯一保留的 Bun 测试配置满足Keep only the root bunfig.toml约束三个关键配置项preload指向./tooling/config/bunTestSetup.ts在任何测试文件执行前先运行注释特别强调顺序重要setup 必须先于 DOM 全局注册tsconfig指向./tooling/config/tsconfig.test.json为测试提供路径映射onlyFailures true只输出失败用例保持本地内循环安静全量通过的日志刷屏既慢又无用。2. scoped preload transformtooling/config/bunTestSetup.tstooling/config/bunTestSetup.ts 是迁移文档中所说scoped preload transform的现行实现它承担了所有测试文件的环境预置职责从happy-dom/global-registrator注册Happy-DOM 全局并禁用 iframe/脚本加载、把禁用文件加载当作成功处理保证document/window在任意测试模块顶层即可用将mock、spyOn挂到globalThis避免每个测试文件重复import { mock, spyOn } from bun:test用expect.extend(matchers)把testing-library/jest-dom的 DOM 断言注入 Bun 的expectafterEach(() cleanup())在每例测试后清理 React 渲染结果修正 Happy-DOM 的isContentEditable只读问题slate 测试工具需要主动设置该属性全局补齐TextEncoder、MessageChannel过滤已知的无害console.error/console.warn如 Vimeo 401、Unreachable code。这套预置同时服务全仓库所有包的测试印证了preload 在 Bun 中是全局生效、通过条件判断收窄作用域的设计思路。3. hyperscript 的现行源码实现作为测试语料的声明式书写层packages/test-utils/src/internals/hyperscript.ts 中可以看到与slate-hyperscript同源的实现细节DEFAULT_CREATORS把anchor/cursor/editor/element/focus/fragment/selection/text八个标签映射到 creators.ts 的工厂函数jsx函数处理属性与子节点的归一化kids kids.filter(Boolean).flat()最后调用creator(tagName, attrs, kids)normalizeElements则为自定义元素 shorthand 做校验非对象属性会抛出TypeError。这些逻辑正是迁移后hyperscript.spec.tsx 本地jsx.ts所依赖的运行时。六、完整验证命令集迁移计划在 Verification 一节列出了完整的验证命令这也是任何同类迁移的验收清单# 1. 安装依赖lockfile 与 workspace 同步 pnpm install # 2. 构建目标包turbo 按 filter 精确限定 pnpm turbo build --filter./packages/slate-hyperscript # 3. 目标包类型检查 pnpm turbo typecheck --filter./packages/slate-hyperscript # 4. 直接以 Bun 运行迁移后的 spec 文件单文件快速验证 bun test ./packages/slate-hyperscript/test/hyperscript.spec.tsx # 5. 根级 Bun 测试流程当前仓库对应 bun tooling/scripts/test-fast.mjs pnpm test:bun # 6. 根级完整测试快速 慢速分层 pnpm test # 7. 全仓库 lintbiome eslint pnpm lint各命令的分工可以这样理解第 2、3 步用 turbo 的--filter./packages/slate-hyperscript把构建与类型检查限定在目标包呼应不扩散到 slate / slate-history的约束第 4 步是迁移的最小可验证直接指定 spec 文件路径跑bun test若第 3 步的本地 JSX helper 或 pragma 处理有问题这一步会立刻暴露第 5、6 步验证迁移后的包能被根级测试流程自动发现并执行依赖packages/**/*.spec.{ts,tsx}的 glob 收集证明包已融入统一的 Bun 测试体系而非孤立运行第 7 步兜底代码质量。在当前仓库中第 4 步的等价做法可以替换为对任意单个 spec 文件运行bun test path根级 bunfig.toml 的 preload 与 tsconfig 会自动生效。七、经验总结这份迁移方案的通用价值pragma 兼容问题要正面解决而不是绕道Bun 对自定义 JSX pragma 路径支持不完善时本文方案选择显式本地 JSX helperjsx.ts而非全局魔改换来的是可预测的编译行为——这是迁移任何依赖 JSX 编译约定的库时都值得借鉴的取舍。scoped preload 是 monorepo 迁移的桥接利器全局 preload 天然有污染其他包的风险限定作用域的转换逻辑既能让目标包获得统一环境又不影响旁路包是渐进式迁移的关键手法。一等公民 spec 优于 fixture bank把数据快照 动态生成器重写为用例即文档的*.spec.tsx测试意图直接可读且天然符合TEST_FILE_PATTERNS的自动收集规则无需额外注册。约束即边界验收即闭环不假跳过、不扩散范围、目录名不变、只留根级 bunfig——这些约束让迁移的 diff 可审查、回归可定位配套的 7 条验证命令则覆盖了单包构建 → 单文件测试 → 根级全量 → lint的完整闭环。对 plate 仓库而言这份迁移是 slate-v2 测试体系全面 Bun 化的一个缩影包测试不再各自为政而是共享 bunfig.toml、tooling/config/bunTestSetup.ts 与 tooling/config/tsconfig.test.json 三件套由 tooling/scripts/test-fast.mjs 统一编排最终让slate-hyperscript从需要单独维护 harness 的边缘包变成开箱即测的一等公民。【免费下载链接】plateRich-text editor with AI and shadcn/ui项目地址: https://gitcode.com/GitHub_Trending/pl/plate创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考