Slate 浏览器测试框架落地实践slate-browser首个 Tranche 的分层车道构建实录【免费下载链接】plateRich-text editor with AI and shadcn/ui项目地址: https://gitcode.com/GitHub_Trending/pl/plate本文以计划文档 2026-04-03-slate-browser-first-tranche-plan.md 为主线完整还原 Plate 生态中slate-browser测试/证明proof车道从零搭建第一个可用 tranche 的过程包括 Bun 核心快速测试、Vitest browser 契约测试、Playwright 示例集成、Chromium CDP IME 四条车道如何同回合落地以及期间踩过的真实工程坑位PnP 污染、端口争抢、零宽字符归一化等。读完你既能照搬这套「分层测试框架」的脚本与命令拓扑也能理解编辑器领域「速度、保真度、覆盖率需要不同工具」这一设计哲学背后的源码级依据。一、背景为什么需要一个独立的slate-browser测试车道在 docs/slate-browser/overview.md 中这套测试框架有一个非常明确的立场「one runner to rule them all is a trap」——单一测试运行器通吃一切是一个陷阱。理由是编辑器的不同测试诉求天然冲突速度要求纯逻辑测试足够便宜可以高频运行保真度要求在真正测试浏览器行为时使用真实浏览器而不是 jsdom 模拟覆盖率要求 IME/组合输入、剪贴板、选区等浏览器专属行为有专门的车道。slate-browser这个名字本身就点出了缺口所在真正未解决的测试盲区是面向浏览器的编辑器行为而不是纯 core 语义。因此该文档体系被收纳在仓库的 docs/slate-browser 目录下并派生出一系列配套文档框架设计 framework-design.md、API 设计 api-design.md、证明车道矩阵 proof-lane-matrix.md 等。计划文档2026-04-03-slate-browser-first-tranche-plan.md就是这个体系的第一块实体在.tmp/slate-v2中构建第一个可工作的slate-browser包 tranche用最快的路径验证方向是否成立。二、Goal 与第一 Tranche 的交付形状2.1 目标按计划文档记录本 tranche 的目标是Bun承载核心快速测试Vitest browser承载小型 DOM/浏览器契约测试Playwright helpers承载示例/端到端e2e测试。三者共用同一个回合same turn落地形成「快、准、全」三条互补的车道雏形。2.2 First Tranche Shape首期交付清单计划文档给出了五个明确的交付物在packages/slate-browser下形成自包含的包一个使用全局describe/it的Bun 单元测试一个Vitest browser 契约测试一个Playwright helper 模块加一个微型示例集成测试一个Chromium-only 的 CDP IME helper加一个占位示例 IME 测试。这份清单对应了 framework-design.md 中「What To Build First」的前四条共享 Playwright helper打开示例、聚焦编辑器、断言选区、断言文本/HTML、从 Lexical 已验证模式复制的 CDP IME helper、一个 Chromium-only 的 placeholder 示例 IME 回归、一个覆盖 DOM 选区/placeholder 形状的浏览器契约车道。2.3 成功标准计划文档为这一 tranche 定义了三个可验证的成功标准三条车道在本回合全部跑通all three lanes run in this same turnAPI 形状与文档足够匹配足以验证方向正确搭建过程能暴露早期工具/运行时问题如有必要可据此触发方向 pivots转向。第三点非常关键这本质上是一次「低成本探针」——用最小的实现快速暴露工具链摩擦而不是等到大规模建设后才发现问题。三、分层车道架构哪种工具属于哪条车道slate-browser的核心不是选一个测试框架而是设计一套**分层layered**架构。根据 framework-design.md 与 overview.md推荐的分工如下层级 / 车道职责范围推荐工具Layer 0 核心快速测试模型语义、transforms、选区数学、投影逻辑、纯 helperBunLayer 1 浏览器契约测试DOM 翻译、选区桥接契约、placeholder DOM 形状、剪贴板 DOM 适配Vitest browser Playwright providerLayer 2 示例集成测试真实示例表面的工具栏流、选区手势、剪贴板流、跨功能回归PlaywrightLane A IME / 组合输入placeholder 敏感组合、空编辑器组合、提交后的选区、浏览器排序怪癖Playwright on Chromium CDPLane C 性能输入延迟、重渲染广度、组合/重组成本、超大文档操作Bun 基准脚本未来 Lane B Agent-Native人类能做但确定性脚本表达不好的动作复杂拖选、右键菜单、视觉校对dev-browser/agent-browser3.1 为什么 Layer 0 用 Bun 而不用 Vitestframework-design.md 给出了明确取舍Bun 在纯 TypeScript/单元车道上冷启动速度优势最大而这正是该车道最需要的浏览器保真度在这里无关紧要。但不要把 Bun 用于 contenteditable、DOM 选区、IME、剪贴板浏览器行为。当前仓库根 package.json 也印证了这一取向根级test脚本为bun tooling/scripts/test-fast.mjs包级p:test为cd ${INIT_CWD:-.} bun test说明 Bun 已是仓库纯逻辑测试的默认运行器。3.2 为什么 Layer 1 用 Vitest browser 而不是 Bun浏览器契约车道要的是「浏览器现实但不需要完整的示例应用编排」。Vitest 的优势在于成熟的项目拆分project split配置、browser 模式、Playwright provider 支持以及比 Bun 当前更完整的浏览器集成生态。这一判断的参考来源包括 edix 与 rich-textarea 的vitest.config.ts形态——它们是小仓库里做「快速浏览器契约测试」的最佳样板太浏览器化、jsdom 不够用又太小、不值得上重型 e2e 套件。3.3 为什么 IME 车道必须走真实浏览器 CDP这是整个框架最强烈的立场之一jsdom 的组合输入模拟是不可信的one fake jsdom composition test pretending it solved IME。IME 车道从 Lexical 的 e2e 组合测试中直接借鉴真实浏览器 CDP 方案——计划文档明确记录「do not try to reinvent IME testing in jsdom when Lexical already proved the right browser seam」。IME 测试不是「另一种 e2e 测试」而是配备专用 helper 的专门车道。四、2026-04-03首个 Tranche 的实施记录4.1 落地内容按计划文档进度日志首个 tranche 在 2026-04-03 完成在packages/slate-browser下创建第一个包 tranche实现带全局测试 API 的Bun 快速车道带 Playwright provider 的Vitest browser 车道Slate 本体中的共享 Playwright helper 模块一个使用共享 helper API 的微型示例集成测试一个Chromium CDP IME helper与一个占位示例 IME 测试。这五项与 First Tranche Shape 一一对应说明计划与执行完全闭合。4.2 新增的根脚本计划文档记录了以下根级脚本即test:slate-browser命令家族test:slate-browser总入口test:slate-browser:coreBun 核心车道test:slate-browser:domDOM 契约车道test:slate-browser:e2e示例集成车道test:slate-browser:imeIME 车道两条 Playwright 车道的本地固定端口变体local fixed-port variants后续在 2026-04-04-slate-browser-public-package-plan.md 中命令家族继续扩展出test:slate-browser:e2e:local、test:slate-browser:ime:local、test:slate-browser:anchors等最终形成 proof-lane-matrix.md 中那张完整的「哪个命令证明哪种真相」的答案表。4.3 早期问题与修复最有价值的实战部分计划文档如实记录了五个早期踩坑及修复方式这些是任何做编辑器测试框架的人都会遇到的真实摩擦Bun 运行时全局对象需要 TypeScript 支持通过bun-types/test-globals解决否则describe/it等全局 API 无法通过类型检查。helper API 必须尊重PLAYWRIGHT_BASE_URL说明 Playwright 车道支持通过环境变量指向外部或固定服务器而不是硬编码地址。仓库 Playwright 需要yarn exec playwright install chromium而不是临时用npx playwright install——保证浏览器二进制安装走仓库统一的依赖路径避免版本漂移。根 Yarn PnP 会污染嵌套的 npm/Vitest 包根脚本现在取消设置NODE_OPTIONS避免 PnP 注入影响 Vitest browser 车道。这正是计划文档中「support/slate-browser作为嵌套 npm 孤岛诞生于 Yarn PnP 摩擦」这句话的背景见 2026-04-04-slate-browser-public-package-plan.md。本地 Playwright 冒烟测试需要固定端口服务器 helper避免端口随机port roulette导致测试不稳定。这五点共同指向一个工程原则浏览器测试框架的难点往往不在断言逻辑而在工具链隔离依赖隔离、端口隔离、环境变量隔离。4.4 2026-04-03 验证证据计划文档给出的验收证据为bun test src/core yarn workspace slate-browser test PLAYWRIGHT_BASE_URLhttp://localhost:3200 yarn test:slate-browser:e2e PLAYWRIGHT_BASE_URLhttp://localhost:3200 yarn test:slate-browser:ime yarn build:rollup yarn lint:typescript外加「LSP diagnostics0on new TS files」新增 TS 文件零诊断。架构评审结论为APPROVE通过。五、2026-04-05 之后Public Package 计划与命令拓扑定型首个 tranche 通过后计划在 2026-04-04-slate-browser-public-package-plan.md 中继续推进把slate-browser从support/下的嵌套 npm 孤岛提升为packages/slate-browser正式 workspace 包并完成公共包形状公共 API 拆分为顶层纯/浏览器导出、slate-browser/core、slate-browser/browser、slate-browser/playwright四个子路径加入 Rollup 显式包构建列表并提供定向的build:slate-browser使 Playwright 消费方无需先跑完整仓库 rollup通过 YarnpackageExtensions修复 Vitest browser 车道在 PnP 下的运行剪贴板公共范围确定为copy()、copyPayload()、pasteText()、pasteHtml()强化 Playwright APIgetter 命名空间、selection 命名空间、精确 vs 包含的 HTML 断言、剪贴板断言 helper、更智能的openExample(...)readiness 选项。最终的命令拓扑在 proof-lane-matrix.md 中形成体系其中车道选择规则高度可用「helper API 还真实吗」→ 跑core/dom/selection「挂载后的编辑器还正常吗」→ 跑e2e「IME 还工作吗」→ 跑ime「annotation anchor 还稳定吗」→ 跑anchors「当前兼容性包络是什么」→ 跑test:replacement:compat:local六、2026-04-04第二个真实 Tranche 与后续切片计划文档在同一天2026-04-04记录了首个 tranche 之后的第一个真实后续切片内容是继续消化下一批 backlog空块empty-block在 placeholder 路径上的 IME 组合输入DOM 选区断言 fixture剪贴板契约 fixture持久化 annotation anchor 回归零宽zero-width形状 fixture共享 Playwright helper 断言。6.1 编辑前锚定的当前证据current evidence before editsIME 必须只走真实浏览器零宽选区必须双向归一化normalize both directions剪贴板语义与剪贴板 DOM 传输是两个不同的 seam即「复制了什么」与「通过什么 DOM 机制复制」要分开测试。6.2 诚实面对的两个失败计划文档明确记录了当时尚未解决的失败这种「如实记录失败」的做法本身即是工程质量的体现Playwright helper 冒烟测试在 placeholder 示例上断言了错误的初始 caret 位置通过当前 Playwright helper 的合成 HTML 粘贴无法证明真实粘贴行为且当时不会更新编辑器。6.3 落地的后续 tranche 细节针对上述失败与切片第二个 tranche 在.tmp/slate-v2中落地了以下内容assertSelection现在把 FEFF 零宽 DOM 偏移归一化回 Slate 偏移0assertDomSelection保持原始raw语义用于证明浏览器真的停留在 placeholder 路径的原生偏移1上——两条断言一「归一」一「原始」分别回答「Slate 语义上对不对」与「浏览器原生状态对不对」两个问题Vitest browser fixture 现在同时钉住 FEFF-backed 与br-only 两种零宽形状Playwright IME 在空块 placeholder 路径上的证明转为绿色剪贴板契约 fixture 从脆弱的 OS 剪贴板读取迁移到浏览器 DOM 传输用合成copy事件加捕获 payload 的方式验证helperselectAllInEditor(...)现在会先等待 selection 同步再执行选区敏感的 helper 断言Playwright helper DX 由 editor-first 的 harness 前置const editor await openExample(page, name); editor.focus(); editor.type(...); editor.press(...); editor.selectAll(); editor.assert.text/html/selection/domSelection/placeholderVisible; editor.clipboard.copy/copyPayload; editor.ime.enableKeyEvents/compose;现有的独立 helper 函数暂时保留为薄包装thin wrappers保证向后兼容的过渡期。6.4 显式当前状态持久化 annotation anchor 的覆盖现在被拆分到两处slate-react-v2中的挂载运行时断言加上一个专门的隐藏站点示例及 Playwright 浏览器回归。6.5 2026-04-04 验证证据yarn workspace slate-browser test PLAYWRIGHT_BASE_URLhttp://localhost:3200 yarn test:slate-browser:e2e PLAYWRIGHT_BASE_URLhttp://localhost:3200 yarn test:slate-browser:ime PLAYWRIGHT_BASE_URLhttp://localhost:3200 yarn test:slate-browser:clipboard PLAYWRIGHT_BASE_URLhttp://localhost:3200 yarn test:slate-browser:anchors yarn workspace slate-react-v2 test yarn build:rollup yarn lint:typescript注意车道的细化从首日的e2e/ime两条 Playwright 车道演进到clipboard、anchors等按风险类别拆分的专门车道——这正是 overview.md 中「Lanes are about specialized risk classes」车道是关于专门化的风险类别的具体化。七、当前仓库中的印证Playwright 与 Slate DOM 内部实现slate-browser包的实体实现位于独立的 slate-v2 仓库但当前 plate 仓库保留了两块可直接对照的印证物7.1packages/playwright从 Playwright 测试内操作 Plate 编辑器packages/playwright 是现成的 Playwright 插件包README 的定位即「Interact with a Plate editor from inside a Playwright test」。其源码结构提供了与slate-browser/playwright同思路的底层能力PlaywrightPlugin.ts把测试注入逻辑封装为 Plate 插件setSelection.ts 与 getSelection.ts选区写入/读取getEditable.ts、getDOMNodeByPath.ts、getNodeByPath.ts在 DOM 节点、Slate path、编辑器节点之间互转clickAtPath.ts、getTypeAtPath.ts按 path 执行点击与取类型。这与slate-browser的editor.assert.selection/domSelection是同一类「以 Slate 语义为第一公民的浏览器操作原语」。7.2packages/slate的 DOM 内部实现零宽选区问题的源码侧背景计划文档中反复出现的零宽FEFF /br选区归一化问题对应着 packages/slate/src/internal/dom-editor 下的一整套 DOM 桥接实现toSlatePoint.ts 与 toDOMPoint.tsDOM 点与 Slate 点的双向换算正是「FEFF 偏移归一化」逻辑的宿主isComposing.ts组合输入状态判定对应 IME 车道关注的核心状态insertData.ts 与 setFragmentData.ts剪贴板数据的读写 seam对应「剪贴板语义与剪贴板 DOM 传输是两个不同 seam」的判断toSlateRange.ts 与 toDOMRange.ts选区范围双向换算。这些内部模块就是 Layer 1DOM 契约测试与 Lane AIME要钉住的「一个 seam 一个契约」的实现本体。八、工程经验总结与可复用结论从这份计划文档可以提炼出几条放之四海皆准的编辑器测试框架经验不要迷信单一运行器。Bun 赢在纯逻辑车道的冷启动速度Vitest 赢在浏览器契约车道的生态成熟度Playwright 赢在真实浏览器行为CDP 赢在 IME 保真度——按车道选工具而不是按品牌选工具。让昂贵车道保持「小而稀有」纯单元测试便宜到可以常跑浏览器契约测试小于集成测试IME 测试数量少、信号高、默认仅 Chromium完整示例集成不是第一反馈线。覆盖率不是一个数字语义覆盖、DOM 桥接覆盖、浏览器交互覆盖、IME 覆盖、性能车道覆盖、未来的 agent-native 动作覆盖缺一不可缺任何一项框架就在「谎报覆盖率」。断言要区分「语义归一」与「原生原始」assertSelection归一化 FEFF 偏移、assertDomSelection保持原始两种断言各司其职才能同时证明「Slate 状态正确」与「浏览器真的处于某原生状态」。剪贴板测试要走浏览器 DOM 传输用合成copy事件加捕获 payload而不是依赖脆弱的 OS 剪贴板读取合成粘贴无法证明真实粘贴行为时必须如实记录。工具链隔离优先于断言逻辑PnP 污染取消NODE_OPTIONS、端口争抢固定端口服务器 helper、浏览器二进制安装yarn exec playwright install chromium——先把这些搞定测试稳定性才有基础。九、后续方向计划文档同时展望了后续演进空块 IME 组合、DOM 选区断言 fixture、剪贴板契约 fixture、持久化 annotation anchor 回归、零宽形状 fixture 已在第二 tranche 消化更远的路线包括test:slate-browser:cross跨浏览器、test:slate-browser:perf/accuracy性能与精度车道以及为「agent-native 车道」预留的扩展 seam——前提是确定性核心车道先稳定。这些后续切片的状态可继续跟踪 docs/slate-browser 目录下的 next-system-move.md、prioritized-backlog.md 等文档。一句话总结slate-browser首个 tranche 的价值不在于「又多了一个测试包」而在于用最小成本验证了一套「Bun 快、Vitest 准、Playwright 真、CDP 专」的分层车道架构并把过程中所有工具链摩擦与诚实失败完整沉淀为文档——这正是可被搜索引擎、Agent 与 LLM 高效复用的技术资产形态。【免费下载链接】plateRich-text editor with AI and shadcn/ui项目地址: https://gitcode.com/GitHub_Trending/pl/plate创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考