Plate 测试快慢车道治理实战docx 与 docx-io 包测试套件回归快速通道【免费下载链接】plateRich-text editor with AI and shadcn/ui项目地址: https://gitcode.com/GitHub_Trending/pl/platePlate 仓库维护着一套快速测试通道 / 慢速测试通道双车道体系默认pnpm test只跑快速套件凡是依赖真实 DOCX 文件、JSZip 打包或重型 fixture 的用例都被命名为*.slow.ts[x]挪入慢车道避免拖慢日常开发与 CI。本文以 2026-03-23-docx-fast-lane-reclaim.md 记录的一次快车道回收Fast Lane Reclaim任务为主线完整还原 docx 与 docx-io 两个包共 16 个纯函数测试套件如何从慢车道迁回快速通道以及哪些测试必须继续留在慢车道、背后基于什么判定标准。读完你将掌握 Plate 双车道测试体系的分流规则、迁移操作与验证命令能够为其他包重复这套快车道回收流程。背景Plate 的测试快慢车道分流机制Plate 的测试被拆分为两条互斥的车道其分流规则定义在 tooling/config/test-suites.mjs 中快速通道Fast Lane匹配TEST_FILE_PATTERNS即apps/**/*.spec.{ts,tsx}、packages/**/*.spec.{ts,tsx}、tooling/scripts/**/*.test.mjs由pnpm testbun tooling/scripts/test-fast.mjs执行慢速通道Slow Lane匹配TEST_SLOW_FILE_PATTERNS即apps/**/*.slow.{ts,tsx}、packages/**/*.slow.{ts,tsx}由pnpm test:slowbun tooling/scripts/test-slow.mjs执行。命名后缀即车道标识*.spec.ts是快车道*.slow.ts是慢车道。同目录下可以同时存在两份测试——慢车道版本通常被重命名为*.slow.ts从快车道摘除。快车道并非没有上限test-suites.mjs定义了硬性阈值与预警区阈值区分本地与 CICI 噪音更大因此放宽一档阈值本地CI单个用例慢速阈值FAST_TEST_SLOW_CASE_THRESHOLD_MS75ms90ms单文件总耗时慢速阈值FAST_TEST_SLOW_FILE_THRESHOLD_MS150ms180ms预警区用例阈值FAST_TEST_WARN_CASE_THRESHOLD_MS60ms75ms预警区文件阈值FAST_TEST_WARN_FILE_THRESHOLD_MS120ms150mspnpm test:slowesttooling/scripts/test-slowest.mjs会运行快车道套件、解析 JUnit 报告并自动按耗时排序一旦有用例/文件越过慢速阈值就输出错误并让 CI 失败提示把该 spec 移到*.slow.ts[x]。换句话说进入慢车道容易回来难——这也正是本次 docx 快车道回收任务的意义所在。任务目标把便宜的确定性测试从慢车道收回本次任务文档标题Docx Fast Lane Reclaim状态completed的目标非常聚焦把 docx 与 docx-io 两个包中便宜且确定性的 helper 级测试从*.slow.*迁回快速通道。所谓便宜且确定性从源码结构看是指这些测试只对纯函数做单元断言输入是字符串/HTML输出是可预测的结构化结果不读取磁盘 fixture、不构造 OOXML zip 包、不依赖真实 DOCX 样本。任务边界由 Constraints 明确约束不做新的覆盖率工作no new coverage work——只移动测试文件归属不新增测试不做运行时改动除非重命名测试暴露了真实 bugno runtime changes unless a renamed test exposes a real bug不虚假回收fixture-heavy 或 zip-heavy 的套件no fake reclaim of fixture-heavy or zip-heavy suites——依赖重型夹具的测试绝不假装它跑得快而硬塞回快车道。Scope16 个文件迁回快车道4 个文件继续留在慢车道迁回快车道的 16 个文件docx 包 docx-cleaner utils8 个均在 packages/docx/src/lib/docx-cleaner/utilscleanDocxImageElements.slow.ts→cleanDocxImageElements.spec.tscleanDocxListElementsToList.slow.ts→cleanDocxListElementsToList.spec.tsdocxListToList.slow.ts→docxListToList.spec.tsgetRtfImageHex.slow.ts→getRtfImageHex.spec.tsgetRtfImageMimeType.slow.ts→getRtfImageMimeType.spec.tsgetRtfImagesByType.slow.ts→getRtfImagesByType.spec.tsgetRtfImagesMap.slow.ts→getRtfImagesMap.spec.tsgetVShapeSpid.slow.ts→getVShapeSpid.spec.tsdocx-io 包8 个preprocessMammothHtml.slow.ts→preprocessMammothHtml.spec.ts位于 packages/docx-io/src/libcolor-conversion.spec.tsfont-family-conversion.spec.tsimage-dimensions.spec.tsimage-to-base64.spec.tslist.spec.tsunit-conversion.spec.tsurl.spec.ts继续留在慢车道的文件packages/docx/src/lib/docx-cleaner/cleanDocx.slow.tspackages/docx/src/lib/docx-cleaner/utils/getVShapes.slow.tspackages/docx-io/src/lib/internal/docx-document.slow.tspackages/docx-io/src/lib/internal/html-to-docx.slow.ts以及 app 与包内 fixture-heavy 的docx/docx-io集成测试文件为什么这 16 个文件配得上快车道判定一个测试能否迁回快车道核心看它是否为纯函数级、确定性、零重资产依赖的单元测试。逐一看这些被回收的用例即可印证docx-cleaner 的图片与列表清洗函数cleanDocxImageElements负责把 DOCX 转换 HTML 中的本地图片引用恢复为可用的src。其测试cleanDocxImageElements.spec.ts直接构造DOMParser解析出的img元素并断言三种典型行为保留外部 alt URL、用 RTF 中恢复出的 data URI 替换本地file:///引用、删除无法解析的本地图片。输入输出均为字符串/内存 DOM天然确定性。getRtfImagesMapgetRtfImagesMap.ts则是 RTF 图片索引的纯函数内部调用getRtfImagesByType(rtf, i, String.raw\shppict)与getRtfImagesByType(rtf, s, String.raw\shp)两类 RTF 图片声明以spid为键合并成映射。从源码结构看这类函数只做正则扫描与对象合并没有任何 IO属于典型的快车道候选。同一批的getRtfImageHex、getRtfImageMimeType、getRtfImagesByType、getVShapeSpid、cleanDocxListElementsToList、docxListToList同理——它们都在内存中对 RTF 字符串或 HTML 字符串做解析/清洗单测成本在毫秒级。docx-io 的纯工具函数docx-io 是导出 DOCXHTML → OOXML方向的包其 internal/utils 下被回收的七个工具测试同样是纯函数验证color-conversionRGB / HSL / 简写 hex 到 DOCX hex 格式的转换测试断言rgbRegex、hslRegex、hexRegex、hex3Regex的匹配行为如rgb(255, 0, 0)匹配而#FF0000不匹配以及各转换函数输出font-family-conversion、unit-conversion、url字符串与数值换算类纯逻辑image-dimensions、image-to-base64图片尺寸解析与 base64 编码list列表结构映射。这些测试共同特点是无fs读盘、无JSZip、无真实 DOCX 样本全部可在一个进程中并行跑完。preprocessMammothHtml一次带着 token 的纯函数迁移preprocessMammothHtml.ts 是 mammothDOCX → HTML输出后处理函数负责把注释从dl元素中提取出来、将comment-ref-{id}锚点替换为[[DOCX_COMMENT_REF:id]]这样的 token返回{ html, commentById, commentIds }三元组。整个处理只依赖DOMParser与正则属于确定性内存变换因此它的 spec 也完全适合快车道。哪些必须继续留在慢车道判定红线对照不虚假回收约束四类文件被明确排除在回收之外各自原因从源码中可以确认cleanDocx.slow.ts是 fixture-heavy 的典型cleanDocx.slow.ts 通过fs.readFileSync读取../docx-cleaner/__tests__/input/*.html与output/*.html成对夹具做全量对比断言如 whitespaces-1、whitespaces-2 等输入/输出样本测试过程中存在磁盘 IO 与较大 HTML 解析开销放回快车道必然超阈值getVShapes.slow.tsVML shape 提取涉及较重的 RTF/HTML 解析路径维持慢车道归属docx-document.slow.tsdocx-document.slow.ts 直接new JSZip()构造 OOXML zip 包并断言 relationships 的 OOXML 命名空间与自增 idzip 打包是典型的慢操作html-to-docx.slow.ts完整 HTML → DOCX 管线转换同样依赖 zip 与 OOXML 生成docx-io__tests__下的block_quotes.slow.tsx、headers.slow.tsx、inline_formatting.slow.tsx、links.slow.tsx、tables.slow.tsx这些是覆盖具体排版场景的集成用例属于app 与包内 fixture-heavy 集成文件保持慢车道。判定红线可以总结为只要测试路径里出现fs读夹具、JSZip打包、完整 DOCX 管线或多文件场景组合就一律不回收只有纯字符串/内存 DOM 的确定性单元测试才值得迁回快车道。验证流程回收后如何证明没有弄虚作假本次任务在Verification与Result中给出了完整的验证命令序列逐条说明其作用1. 定向验证被重命名的文件先用 bun 直接跑被回收的 16 个 spec确认重命名后测试仍全绿bun test packages/docx/src/lib/docx-cleaner/utils/cleanDocxImageElements.spec.ts packages/docx/src/lib/docx-cleaner/utils/cleanDocxListElementsToList.spec.ts packages/docx/src/lib/docx-cleaner/utils/docxListToList.spec.ts packages/docx/src/lib/docx-cleaner/utils/getRtfImageHex.spec.ts packages/docx/src/lib/docx-cleaner/utils/getRtfImageMimeType.spec.ts packages/docx/src/lib/docx-cleaner/utils/getRtfImagesByType.spec.ts packages/docx/src/lib/docx-cleaner/utils/getRtfImagesMap.spec.ts packages/docx/src/lib/docx-cleaner/utils/getVShapeSpid.spec.ts packages/docx-io/src/lib/preprocessMammothHtml.spec.ts packages/docx-io/src/lib/internal/utils/color-conversion.spec.ts packages/docx-io/src/lib/internal/utils/font-family-conversion.spec.ts packages/docx-io/src/lib/internal/utils/image-dimensions.spec.ts packages/docx-io/src/lib/internal/utils/image-to-base64.spec.ts packages/docx-io/src/lib/internal/utils/list.spec.ts packages/docx-io/src/lib/internal/utils/unit-conversion.spec.ts packages/docx-io/src/lib/internal/utils/url.spec.ts注意慢车道 runner 对显式路径做了./前缀归一化见 test-slow.mjs 的runFiles而快车道 runner 直接用原始路径所以定向跑的时候要把路径写成不带./的相对路径与上例一致。2. 性能画像确认回收后仍在阈值内pnpm test:profile -- --top 25 packages/docx packages/docx-iotest:profile对应bun tooling/scripts/test-slowest.mjs --profile它先执行快车道 runner 并输出 JUnit 报告再解析出 Top 25 慢用例与 Top 20 慢文件标记越过慢速阈值!与预警区~的条目。--profile只输出画像不使 CI 失败因此回收后先用它确认这 16 个文件的耗时确实落在快车道预算内这是没有虚假回收的直接证据。文档 Result 中同时记录了pnpm test:slowest -- --top 25 packages/docx packages/docx-io作为强校验版本。3. 慢车道回归确认遗留文件依然被正确收集pnpm test:slow -- packages/docx packages/docx-iotest:slow用TEST_SLOW_FILE_PATTERNS收集*.slow.{ts,tsx}文件回收后 docx 包内只剩cleanDocx.slow.ts、docx-io 包内只剩docx-document.slow.ts、html-to-docx.slow.ts与__tests__下的五个集成 slow 文件。这条命令确保慢车道仍能正常发现并执行它们而不是被意外丢在两条车道之间。4. 依赖与构建门禁pnpm install pnpm turbo build --filter./packages/docx --filter./packages/docx-io pnpm turbo typecheck --filter./packages/docx --filter./packages/docx-io pnpm lint:fix重命名只改测试文件不影响库代码但任务仍要求跑完依赖安装、turbo 构建与类型检查确认两个包对外产物不受影响pnpm lint:fixbiome check . --fix用于清理重命名过程可能引入的格式问题。双车道基础设施回收背后 runner 的实现细节理解回收任务还需要知道快车道 runner 的两个关键机制均可在 tooling/scripts/test-fast.mjs 中确认路径过滤逻辑runner 支持静态路径等于/前缀/包含匹配与动态 globisDynamicPattern两种过滤不带参数时默认跑全部*.spec.{ts,tsx}文件。因此pnpm test:profile -- --top 25 packages/docx packages/docx-io实际是把packages/docx、packages/docx-io作为前缀过滤器只对该目录树内的快车道文件做画像。mock 隔离与 JUnit 合并runner 会静态分析测试文件及其本地导入链中是否出现mock.module(通过LOCAL_IMPORT_PATTERN正则递归解析相对导入凡是依赖mock.module的 spec 被单独隔离成批次运行isolated-{index}其余共享批次运行使用--reporterjunit --reporter-outfile时多个批次的 JUnit XML 会被合并成单个testsuites报告。这正是test-slowest能对全部快车道用例做耗时统计的基础。这套机制意味着测试归属*.spec.ts/*.slow.ts直接决定其在流水线中的执行频率与性能门禁。快车道每次pnpm test与 CI 都会跑慢车道只在test:slow/test:all中跑。因此像 docx/docx-io 这样被高频改动的包把廉价的确定性单测从慢车道回收回来能显著降低日常验证的等待成本——这正是Fast Lane Reclaim的价值所在。任务结果总结本次快车道回收最终落地为16 个*.slow.ts测试文件重命名为*.spec.ts迁回快车道docx 8 个、docx-io 8 个全部通过定向bun test验证4 个 fixture-heavy / zip-heavy 测试文件cleanDocx.slow.ts、getVShapes.slow.ts、docx-document.slow.ts、html-to-docx.slow.ts及 docx-io 的集成 slow 文件继续留在慢车道未做任何虚假回收通过test:profile画像确认回收后文件耗时落在快车道阈值内并通过test:slow、pnpm install、turbo build/typecheck、lint:fix全部门禁。如果要在其他包复制这套流程操作顺序是先用pnpm test:profile -- --top 25 包路径找出候选纯函数、无磁盘夹具、无 zip 依赖、确定性输出把其 spec 从*.slow.ts重命名为*.spec.ts定向跑一遍确认全绿再跑 profile 确认耗时在阈值内最后补跑慢车道回归与构建/类型检查门禁。【免费下载链接】plateRich-text editor with AI and shadcn/ui项目地址: https://gitcode.com/GitHub_Trending/pl/plate创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考