Plate 项目 Slate Browser E2E 测试面拓宽：为 read-only、shadow-dom、iframe、plaintext 建立专用浏览器验证通道

Plate 项目 Slate Browser E2E 测试面拓宽：为 read-only、shadow-dom、iframe、plaintext 建立专用浏览器验证通道

【免费下载链接】plateRich-text editor with AI and shadcn/ui项目地址: https://gitcode.com/GitHub_Trending/pl/plate

本文基于 docs/plans/2026-04-09-slate-browser-e2e-surface-widening.md 展开，介绍 Plate（富文本编辑器）仓库中slate-browser专项测试通道的一次"测试面拓宽"：把read-only与shadow-dom等此前只在替换矩阵（replacement matrix）中间接证明的浏览器专属场景，正式提升为专用 current-example 浏览器 E2E 测试；同时新增iframe、plaintext的专用浏览器测试，并同步拓宽test:slate-browser:e2e/test:slate-browser:e2e:local两条命令的覆盖面。读完本文，你将掌握该计划的动机、测试分组方式、逐条可复现的验证命令，以及其背后的分层测试框架与 proof-lane 证据体系。

一、背景：为什么浏览器专属场景需要"专用车道"

1.1 slate-browser 分层测试框架的立场

在 Plate 仓库的测试体系中，slate-browser是一个"专家型测试/证明通道"（specialist testing/proof lane），其设计立场明确反对"一个 runner 打天下"：速度、保真度（fidelity）与覆盖率各自需要不同的工具组合。相关总览见 docs/slate-browser/overview.md。

该框架将测试划分为三层加若干专用通道：

• Layer 0（Core Fast Tests）：纯模型、transform、selection、projection 语义，走快速包级 runner；
• Layer 1（DOM Contract Tests）：DOM 翻译、选区数学、占位符形态、剪贴板 DOM 适配等单缝（seam）级别的浏览器契约测试；
• Layer 2（Example Integration Tests）：在真实 example 挂载之后断言编辑器行为，使用 Playwright；
• 专用通道：IME/Composition（Lane A）、Agent-Native（Lane B）、Performance（Lane C）。

本计划所拓宽的test:slate-browser:e2e与test:slate-browser:e2e:local正是 Layer 2 的载体，同时与 IME、anchors、replacement 等专用通道并行存在、互不混淆。

1.2 车道矩阵（Proof-Lane Matrix）的职责划分

proof-lane-matrix.md 的核心作用是一张"证据地图"——回答"哪条命令证明哪种真相"。与本次拓宽直接相关的两条 example lane：

• yarn test:slate-browser:e2e负责：broad v2 example integration matrix、在已证明的 v2 example 上的结构性浏览器真相、面向 broad current example suite 的 dedicated current-example proof；且明确排除IME 专用车道、anchors 车道与 replacement matrix 车道；
• yarn test:slate-browser:e2e:local负责：在全新本地服务器上运行同一矩阵，是"同一轮改动后首选的自检命令"（same-turn gut-check），同样承载 broad current example suite 的本地证明。

lane 选择规则非常直白：问"挂载后的编辑器是否仍然行为正确"就用e2e；问"IME 是否仍然工作"就用ime；问"注解 anchors 是否稳定"就用anchors；问"当前兼容性范围是什么"就用test:replacement:compat:local。

1.3 本计划的动机：从"矩阵证明"升级为"专用证明"

计划的目标部分（Goal）写得很清楚：

Bringread-onlyandshadow-dominto the dedicated current-example browser lane instead of only proving them through the replacement matrix.

即：read-only与shadow-dom此前只通过 replacement matrix（跨仓库兼容性矩阵）被间接证明，而 replacement matrix 属于另一类证据（"当前兼容性范围"），并不等同于"挂载后编辑器行为正确"的结构性浏览器证明。本次拓宽的目的，就是让这类浏览器专属场景进入 dedicated current-example browser lane，获得第一手的真实浏览器证据。

二、Result：四类场景进入专用浏览器测试

计划的结果部分（Result）记录了本次实际落地的四项产出：

1. 为以下四类场景新增了专用浏览器测试：
   • read-only（只读模式）
   • shadow-dom（Shadow DOM 容器）
   • iframe（iframe 内嵌）
   • plaintext（纯文本模式）
2. 拓宽了test:slate-browser:e2e与test:slate-browser:e2e:local，使其承载上述 example 以及更广的 current example suite；
3. 保持 proof-lane matrix 与拓宽后的 current-example e2e lane 保持对齐。

这四类场景的共同点是"渲染/宿主环境边界"：

• read-only：编辑器的只读渲染路径，涉及contentEditable行为、选区与光标策略的关闭，以及占位符、装饰等在只读下的表现；
• shadow-dom：编辑器挂载进 Shadow DOM 时，DOM 查找、事件穿透、选区计算等行为与常规 DOM 树的差异；
• iframe：编辑器嵌入 iframe 时跨 document/window 边界的渲染与事件行为；
• plaintext：纯文本渲染路径，与富文本结构树形成对照。

它们难以在 jsdom 中真实表达，正是"浏览器行为必须在真实浏览器中验证"这一框架原则的典型样本。仓库中apps/www/src/registry/examples/目录（如editor-disabled.tsx、editable-voids-demo.tsx、iframe-value.tsx等，见 apps/www/src/registry/examples）即为这类 current example 的注册示例来源，是 e2e 车道所挂载的"真实产品表面"。

三、验证命令逐条解析

计划中给出了三条可复现的验证命令，全部通过scripts/run-slate-browser-local.sh辅助脚本在本地固定端口上启动服务器并执行 Playwright 测试（该脚本位于 slate-browser 执行环境，负责"固定端口本地服务器"以避免端口随机冲突——这是 first tranche 期间明确记录过的早期问题）。

3.1 命令一：read-only + shadow-dom 分组

bash ./scripts/run-slate-browser-local.sh 3100 /examples/read-only "yarn build:slate-browser:playwright && yarn exec playwright test playwright/integration/examples/read-only.test.ts playwright/integration/examples/shadow-dom.test.ts --project=chromium --workers=1"

参数拆解：

参数	值	含义
端口	3100	本地服务器的固定端口
起始示例	/examples/read-only	服务器以 read-only 示例为起始页面
执行命令	yarn build:slate-browser:playwright && yarn exec playwright test ...	先构建 Playwright 侧产物，再运行指定测试

其中：

• yarn build:slate-browser:playwright：构建slate-browser的 Playwright 相关入口（在 overview.md 的 canonical root commands 中有记录）；
• yarn exec playwright test playwright/integration/examples/read-only.test.ts playwright/integration/examples/shadow-dom.test.ts：显式指定两个测试文件，说明read-only 与 shadow-dom 在同一分组内成对验证；
• --project=chromium --workers=1：仅跑 Chromium 项目、串行执行，保证确定性并降低资源竞争。

3.2 命令二：iframe + plaintext 分组

bash ./scripts/run-slate-browser-local.sh 3100 /examples/plaintext "yarn build:slate-browser:playwright && yarn exec playwright test playwright/integration/examples/iframe.test.ts playwright/integration/examples/plaintext.test.ts --project=chromium --workers=1"

参数拆解：

参数	值	含义
端口	3100	同一固定端口
起始示例	/examples/plaintext	服务器以 plaintext 示例为起始页面
执行命令	yarn build:slate-browser:playwright && yarn exec playwright test ...	构建后运行 iframe 与 plaintext 两个测试文件

iframe 与 plaintext 成对验证，起始页面切换为/examples/plaintext。两条命令共用端口3100，属于"同一服务器、两次不同分组定向测试"的组织方式；这体现了"专用小分组 + 整体大矩阵"的双层验证策略：先用窄分组快速定位，再跑整体矩阵做回归。

3.3 命令三：整体拓宽后的本地矩阵

yarn test:slate-browser:e2e:local

这条命令是拓宽后的整体本地 e2e 车道——按照 proof-lane-matrix.md 的定义，它在全新本地服务器上运行与test:slate-browser:e2e相同的矩阵，是改动 example 行为后的首选同轮自检命令。据 slate-v2 草案台账（docs/slate-v2-draft/true-slate-rc-proof-ledger.md）的记录，拓宽后的该车道曾在 Chromium 下覆盖 79 条 current example suite 测试行并整体通过，与本文计划"carry those examples and the broader current example suite"的目标相互印证。

四、仓库源码层面的支撑证据

4.1 Playwright helper 模块：e2e 测试的地基

当前仓库中packages/playwright（见 packages/playwright/src）是这一体系的浏览器测试辅助包，提供了供 e2e 断言使用的基础能力：

• PlaywrightPlugin.ts：Playwright 适配的 Plate 插件入口；
• getEditable.ts/getDOMNodeByPath.ts/getNodeByPath.ts：在真实 DOM 中定位编辑器节点；
• getSelection.ts/setSelection.ts/clickAtPath.ts/getTypeAtPath.ts：选区读取、设置与光标/输入定位；
• usePlaywrightAdapter.tsx：React 侧的适配钩子，使测试能驱动挂载后的编辑器实例。

这些 helper 构成"editor-first harness"风格 API 的基础（如openExample(page, name)后执行editor.focus()、editor.type(...)、editor.assert.text/html/selection等，详见 2026-04-03-slate-browser-first-tranche-plan.md 的进度记录）。本次拓宽新增的 read-only、shadow-dom、iframe、plaintext 测试，正是建立在这样的统一 helper 之上，从而能对"真实浏览器中的真实示例"做结构化断言。

4.2 测试框架的演进痕迹

从 first tranche 计划（2026-04-03-slate-browser-first-tranche-plan.md）可以还原本次拓宽的来龙去脉：

• 第一批（2026-04-03）建立了test:slate-browser系列根命令与 Playwright 帮助模块，并明确--project=chromium与固定端口服务器的必要性；
• 第二批（2026-04-04）强化了 helper API（assertSelection对 FEFF 零宽字符的归一化、selectAllInEditor(...)等待选区同步、剪贴板断言从 OS 剪贴板迁移到浏览器 DOM 传输等）；
• 到 2026-04-09 本次计划，则把浏览器专属场景（read-only、shadow-dom、iframe、plaintext）正式纳入 dedicated current-example lane。

可以推断，read-only与shadow-dom此前的主要证据来源是 replacement matrix（跨仓库兼容性矩阵），其证明的是"兼容性范围"而非"挂载后行为"，这正是本次拓宽要补齐的缺口。

4.3 对齐关系：拓宽车道与矩阵文档

计划强调"kept the proof-lane matrix aligned with the widened current-example e2e lane"，即拓宽代码车道的同时，proof-lane-matrix.md 中yarn test:slate-browser:e2e与yarn test:slate-browser:e2e:local的职责描述也要同步更新。这遵循了框架的"迁移审查规则"（Migration Review Rule，见 overview.md）：一条浏览器车道发生变化时，验收标准不是"以前存在同名文件"，而是"概念仍然存在、证明归属明确记录在矩阵文档中、并在维护者 diff 故事中说明"。

五、实践要点与复现指引

1. 先跑窄分组、再跑整体矩阵：改动涉及 read-only/shadow-dom 相关行为时，先执行命令一；涉及 iframe/plaintext 时，先执行命令二；最后统一跑yarn test:slate-browser:e2e:local做全量回归。
2. 注意构建前置：两条定向命令都先执行yarn build:slate-browser:playwright，修改了 Playwright 侧源码后不要跳过构建步骤。
3. 固定端口与串行执行：--project=chromium --workers=1与固定端口3100是保证本地确定性、避免端口随机与并行资源竞争的关键参数。
4. 车道选择不要串味：按照 proof-lane-matrix.md 的 lane 选择规则，浏览器行为问题归 e2e、IME 问题归 ime、兼容性范围问题归 replacement，三者互不替代。

六、小结

2026-04-09-slate-browser-e2e-surface-widening是一次典型的"证明面拓宽"：它把 read-only、shadow-dom 从替换矩阵的间接证明提升为专用 current-example 浏览器证明，并顺带为 iframe、plaintext 建立专用浏览器测试；同时通过同步拓宽test:slate-browser:e2e/test:slate-browser:e2e:local与保持 proof-lane matrix 对齐，确保整个证据体系自洽。对读者而言，这套"分层框架 + 车道矩阵 + 定向验证命令"的组合，既是 Plate 仓库测试基建的缩影，也是一份可直接复用的浏览器 E2E 组织范式：哪些场景需要真实浏览器证明、由哪条命令证明、如何用固定端口小分组快速定位、如何用整体矩阵兜底回归——一条命令即可回答。

【免费下载链接】plateRich-text editor with AI and shadcn/ui项目地址: https://gitcode.com/GitHub_Trending/pl/plate