TinyMCE 测试框架 mcagar 全解析:从 CHANGELOG 版本演化到 BDD 与 Pipeline 测试 API 实战
TinyMCE 测试框架 mcagar 全解析:从 CHANGELOG 版本演化到 BDD 与 Pipeline 测试 API 实战
mcagar(@ephox/mcagar)是 TinyMCE 官方针对 tinymce 封装 agar(@ephox/agar)测试基础设施而成的专用测试模块,仅由一组 TypeScript 模块组成,服务于 TinyMCE 编辑器及其插件的浏览器端自动化测试。本文以 modules/mcagar/CHANGELOG.md 的版本演化为主线,结合 README.md、BDD 测试文档 与 Pipeline 测试文档 的 API 说明,并深入 modules/mcagar/src/main/ts/ephox/mcagar 源码验证实现细节,帮助你全面掌握 mcagar 的安装、BDD 风格测试、旧式 Pipeline 风格测试、测试运行方式,以及每个 API 背后的设计意图。
一、mcagar 是什么:定位与安装
模块定位
mcagar 本质上是 TinyMCE 对 agar 测试框架的“二次封装层”。它本身不是独立的测试运行器,而是提供了一组与 TinyMCE 编辑器交互的高层测试模块:创建编辑器、注入内容、模拟键盘与鼠标事件、操作 UI(工具栏、菜单、对话框)、设置选区、断言内容与选区等。从源码入口 Main.ts 可以看到,它统一导出了两套 API:
- BDD 风格模块:
TinyAssertions、TinyHooks、TinySelections、TinyContentActions、TinyState、TinyUiActions,适合 Mocha 等 BDD 测试框架; - Pipeline 风格模块:
TinyLoader、TinyApis、TinyActions、TinyUi、TinyScenarios、TinyDom、RemoteTinyLoader、ActionChains、ApiChains、UiChains,基于 agar 的 Step/Chain 机制构建执行流水线。
根据 README.md 的约定:只有 api 包内的模块允许被其他项目使用,其余模块(如 loader/、selection/)均属于实现细节,不应直接引用。
安装方式
mcagar 以 npm 包 @ephox/mcagar 发布:
npm install @ephox/mcagar
开发环境安装则需要使用 bun,因为 package.json 中使用了 npm 不支持的包别名(package aliasing)。其依赖包括 @ephox/agar、@ephox/katamari、@ephox/sand、@ephox/sugar 以及属性测试库 fast-check,peerDependencies 要求 tinymce >= 4.0.0。
二、CHANGELOG 主线:mcagar 能力演化图谱
CHANGELOG.md 采用 Keep a Changelog 格式、遵循语义化版本(Semantic Versioning),记录了从 7.0.0 到 11.0.0 的完整演进。这张“版本地图”直接映射了 TinyMCE 主版本的迭代节奏,下面逐版本梳理其核心变更。
| 版本 | 日期 | 类型 | 核心变更 | 关联问题 |
|---|---|---|---|---|
| 7.0.0 | 2021-08-26 | Added | assertContent 新增可选 args 参数;新增 TinyContentActions.trueClick / trueClickOn |
TINY-3388 / TINY-7399 |
| 7.0.0 | 2021-08-26 | Changed | 升级 Katamari 8.0(与 7.0 不兼容);TinyMCE 不再被 import,改为从 node_modules 或全局变量加载 |
— |
| 7.0.2 | 2021-09-08 | Fixed | TinyHooks 的 setup 模块在 TinyMCE 加载完成前被错误执行 |
TINY-7957 |
| 8.0.0 | 2022-03-03 | Added | EditorTypes.Selection 新增 getSel();TinySelections 新增 setRawSelection() |
— |
| 8.0.0 | 2022-03-03 | Improved | API 适配 TinyMCE 6 的 options API | — |
| 8.0.0 | 2022-03-03 | Deprecated | setSetting / deleteSetting 废弃,改为 setOption / unsetOption |
— |
| 8.0.0 | 2022-03-03 | Removed | 移除 IE 与旧版 Edge 支持 | — |
| 8.1.0 | 2022-09-08 | Changed | TinyMCE 6.2 新增的 promotion 选项默认设为 false |
— |
| 8.2.0 | 2022-11-23 | Added | TinyContentActions 新增 pWaitForEventToStopFiring |
— |
| 8.3.0 | 2023-03-15 | Added | 从 TinyUiActions 暴露 getUiRoot,支持 ShadowDOM |
TINY-9226 |
| 8.4.0 | 2023-06-12 | Added | 新增 TinyState 模块(编辑器状态的事务性函数) |
— |
| 9.0.0 | 2023-11-22 | Changed | 升级 agar 至最新 major | TINY-10275 |
| 9.0.0 | 2023-11-22 | Fixed | TinyState.withNoneditableRootEditor(Async) 改用 setEditableRoot API 而非直接操作 DOM |
TINY-10304 |
| 10.0.0 | 2024-02-29 | Changed | 许可证改为 GPL v2 或更高版本 | TINY-10578 |
| 11.0.0 | 2026-03-27 | Added | 引入现代键盘模拟辅助函数 | TINY-8724 |
| 11.0.0 | 2026-03-27 | Removed | 移除仅旧浏览器需要的回退代码 | TINY-11093 |
| 11.0.0 | 2026-03-27 | Fixed | Loader 捕获 tinymce.init 抛出的错误并上报给调用方 |
TINY-12536 |
从版本脉络看设计演进
加载策略的转变(7.0.0):早期 mcagar 直接 import TinyMCE,7.0.0 起改为优先使用全局 tinymce,不存在时再从 node_modules 加载。对应实现位于 Loader.ts:当 Global.tinymce 为空时,通过 loadScript(detectTinymceBaseUrl(settings) + '/tinymce.js') 动态注入 <script> 标签。
对齐 TinyMCE 6 的 options API(8.0.0):TinyMCE 6 将旧的 settings API 重构为 options API,mcagar 同步废弃 setSetting/deleteSetting,替换为 setOption/unsetOption(对应 Options.ts)。
ShadowDOM 支持(8.3.0):getUiRoot 从 TinyUiActions 导出后,UI 查找与点击便能定位到 ShadowDOM 内部的内容容器。从源码看,getUiRoot 基于 SugarShadowDom.getContentContainer(getUiDoc(editor)) 实现(见 TinyUiActions.ts)。
状态管理模块化(8.4.0 / 9.0.0):TinyState 提供 withNoneditableRootEditor 与异步版本 withNoneditableRootEditorAsync。9.0.0 的修复是重要拐点——此前通过直接 DOM 突变来切换可编辑根,现在改用官方 editor.setEditableRoot(state) API(见 TinyState.ts),且要求 TinyMCE >= 6.5。
测试框架现代化(11.0.0):引入“现代键盘模拟辅助函数”(agar Keyboard 模块的 activeKeydown/activeKeypress/activeKeystroke 等,见 TinyContentActions.ts);同时 Loader 的 tinymce.init 调用被包裹进 Promise.resolve(...).catch(onFailure) 与 try/catch,初始化阶段的任何异常都会上报给测试调用方(见 Loader.ts)。
三、BDD 测试 API 实战
BDD 模块适合 Mocha 等行为驱动测试。核心思路:用 TinyHooks 在套件级初始化编辑器,用 TinyContentActions/TinyUiActions 驱动交互,用 TinySelections 设置选区,用 TinyAssertions 断言结果。
TinyHooks:套件级编辑器初始化
TinyHooks 注册 before/after 钩子完成编辑器的创建与清理。注意:编辑器每个 suite 只初始化一次,而非每个测试一次,因此测试间需要自行关闭对话框或重置状态。可用函数:
bddSetup(settings, setupModules?, focusOnInit?):最常用的标准初始化;bddSetupLight(settings, setupModules?, focusOnInit?):默认不渲染menubar、toolbar、statusbar,加速不需要 UI 的测试;bddSetupFromElement(settings, setupElement, setupModules?, focusOnInit?):使用自定义元素初始化,需返回{ element, teardown }形式的回调;bddSetupInShadowRoot(settings, setupModules?, focusOnInit?):在 ShadowRoot 内初始化,返回对象额外提供shadowRoot()查询函数。
自定义插件测试示例(来自 bdd.md):
import { TinyHooks } from '@ephox/mcagar';
import { Editor } from 'tinymce';
import { Plugin } from '../../main/ts/Plugin';
describe('My Custom Plugin', () => {
const hook = TinyHooks.bddSetup<Editor>({
plugins: 'customplugin',
toolbar: 'custom',
customplugin_setting: true
}, [ Plugin ]);
it('should include a custom toolbar button', () => {
const editor = hook.editor();
// 断言编辑器渲染了自定义工具栏按钮
...
});
});
从源码 TinyHooks.ts 可以看到:bddSetupLight 实质是向 settings 合并 { toolbar: '', menubar: false, statusbar: false };bddSetup 在 before 中将 Mocha 默认的 2 秒超时放宽到 10 秒(慢网络下初始化可能超时),并在编辑器 SkinLoaded 事件后回调 done()。第三个参数 hookOptions 既可以是布尔值(兼容旧版 focusOnInit 语义)也可以是 { focusOnInit, fastAnimations } 对象——fastAnimations 会注入一段 CSS 将 sliding sidebar 的过渡时长压缩到 0.01s 以加速测试(见 TinyHooks.ts)。
TinyContentActions:内容区交互
针对编辑器内容区域(editable body)的辅助函数,基于 agar 的 Keyboard/Mouse 模块实现:
| 函数 | 说明 |
|---|---|
keydown(editor, keyCode, modifiers?) |
对内容区聚焦元素模拟 keydown |
keyup(editor, keyCode, modifiers?) |
模拟 keyup |
keypress(editor, keyCode, modifiers?) |
模拟 keypress |
keystroke(editor, keyCode, modifiers?) |
依次模拟 keydown + keypress + keyup |
type(editor, content) |
逐字符模拟输入指定内容 |
trueClick(editor) |
在内容区执行一次“真实”鼠标点击 |
trueClickOn(editor, selector) |
对内容区匹配选择器的元素执行真实点击 |
pWaitForEventToStopFiring(editor, eventName, timing) |
等待某事件停止触发(8.2.0 新增) |
pWaitForEventToStopFiring 的实现思路(见 TinyContentActions.ts):监听指定事件,若在 timing.delay 毫秒内不再触发则认为停止并 resolve;若累计超过 timing.timeout 毫秒仍在触发则 reject 并输出超时信息。它常用于断言防抖类逻辑(如输入后自动保存、搜索替换的实时高亮)。
TinyUiActions:UI 层交互
针对编辑器 UI(工具栏、菜单、对话框)的辅助函数,全部经由 getUiRoot 定位 UI 根节点:
对话框操作:submitDialog(点击 Save)、cancelDialog(点击 Cancel)、closeDialog(点击 X)、pWaitForDialog(等待对话框可见)。三个点击函数都支持可选 dialogSelector 参数,默认使用主题选择器 getThemeSelectors().dialogSelector(见 TinyUiActions.ts)。
键盘操作:keydown/keyup/keypress/keystroke/type,与内容区版本签名一致,但事件目标是 UI 文档(getUiDoc)。
鼠标与等待操作:clickOnMenu、clickOnToolbar、clickOnUi(按 CSS 选择器点击)、tapOnToolbar(触摸事件)、pTriggerContextMenu(targetSelector, menuSelector)(触发上下文菜单并等待菜单弹出)、pWaitForPopup(等待元素可见)、pWaitForUi(等待元素存在于 DOM,不要求可见)。
对话框交互完整示例:
it('should open a dialog when clicking a toolbar button', async () => {
const editor = hook.editor();
TinyUiActions.clickOnToolbar(editor, 'button[aria-label="My Button"]');
await TinyUiActions.pWaitForDialog(editor);
TinyUiActions.closeDialog(editor);
});
TinySelections:选区控制
该模块的核心概念是 element path:从根元素开始、由子节点下标组成的一维数字数组。例如文档 bdd.md 中的表格:
<table>
<tbody>
<tr>
<td>Cell 1</td>
<td>Cell 2</td>
<td>Cell 3</td>
</tr>
<tr>
<td>Cell 4</td>
<td>Cell 5</td>
<td>Cell 6</td>
</tr>
</tbody>
</table>
Cell 6 文本节点的 path 为 [ 0, 1, 2, 0 ],即 [ tbody, 第2个 tr, 第3个 td, text ]。
可用函数:
setCursor(editor, path, offset):在指定 path 与偏移处设置折叠选区;setSelection(editor, startPath, startOffset, endPath, endOffset):设置跨字符/跨元素的选区;setSelectionFrom(editor, spec):使用 agarCursors的CursorSpec | RangeSpec规格设置选区;select(editor, selector, path):选择内容中的元素(如图片);setRawSelection(editor, startPath, startOffset, endPath, endOffset):绕过所有 TinyMCE API,直接用selection.removeAllRanges()+addRange()写入原生 Range(8.0.0 新增,见 TinySelections.ts)。
默认情况下 setSelection 系列在设置选区后会触发 editor.nodeChanged(),可通过第五个参数 fireNodeChange = false 关闭,用于模拟不触发 nodeChanged 的选区变更场景。
it('should set the selection inside a paragraph', () => {
const editor = hook.editor();
editor.setContent('<p>Content</p>');
TinySelections.setSelection(editor, [ 0 ], 3, [ 0 ], 7); // 选中段落中的 "tent"
});
it('should set the selection around an image', () => {
const editor = hook.editor();
editor.setContent('<p><img src="..."></p>');
TinySelections.select(editor, 'img', []);
});
TinyAssertions:内容与选区断言
内容断言:
assertContent(editor, expected, args?):通过editor.getContent(args)获取净化后的内容并断言(args参数自 7.0.0 起支持,可传入如{ format: 'text' });assertRawContent(editor, expected):直接断言editor.getBody().innerHTML的原始 HTML,适合断言 bogus br 等仅编辑期存在的内容;assertContentPresence(editor, { selector: count }):断言内容中匹配指定 CSS 选择器的元素数量;assertContentStructure(editor, structAssert):使用 agarApproxStructure对内容做结构化断言。
it('should check the editor structure', () => {
const editor = hook.editor();
editor.setContent('<p class="red">Content</p>');
TinyAssertions.assertContentPresence(editor, { 'p': 1 });
TinyAssertions.assertContentStructure(editor, ApproxStructure.build((s, str, arr) => {
return s.element('body', {
children: [
s.element('p', {
classes: [ arr.has('red') ],
children: [
s.text(str.is('Content'))
]
})
]
});
}));
});
选区断言:assertCursor(editor, path, offset) 断言折叠选区位置;assertSelection(editor, startPath, startOffset, endPath, endOffset) 断言范围选区。其实现通过 Cursors.calculateOne 按 path 计算出预期节点,再与实际 selection.getRng() 的 start/end 容器逐一比对,失败时输出预期/实际 path 的 JSON 对比(见 TinyAssertions.ts)。
TinyState:编辑器状态的事务性操作
TinyState 是 8.4.0 引入的模块,提供“进入状态 → 执行测试 → 恢复状态”的事务模式:
withNoneditableRootEditor(editor, f):将编辑器根设为不可编辑,执行f(editor),再恢复可编辑;withNoneditableRootEditorAsync(editor, f):异步版本,await f(editor)后恢复。
自 9.0.0 起二者统一调用 editor.setEditableRoot(state)(需 TinyMCE >= 6.5),彻底取代了早期直接操作 DOM 的实现(见 TinyState.ts),因此测试行为与真实运行时完全一致。
四、Pipeline(旧式)测试 API 概览
Pipeline 风格是 mcagar 自带的内部测试框架,基于 agar 的 Step 与 Chain 构建动作流水线。根据 README.md,该语法“正在逐步移除并最终将被弃用”,新测试应优先采用 BDD 风格。其主要模块(详见 pipelines.md):
- TinyLoader:创建带指定 settings 的编辑器测试环境。核心逻辑在 Loader.ts:自动生成
tiny-loader-*随机 id 的 textarea/div 目标元素(inline 模式用 div),注入promotion: false与license_key: 'gpl'等默认配置,等待SkinLoaded后回调;测试结束后执行tinymce.remove()并清理残留的.mce-notification、.mce-window、#mce-modal-block等 DOM 元素。 - TinyApis:获取/设置/断言内容与选区、聚焦编辑器、触发 nodeChanged 的 Step/Chain 集合。
- TinyActions:向编辑器 UI 与可编辑区域模拟按键事件的 Step 集合。
- TinyUi:点击工具栏、菜单、通用 UI,等待 UI 部件,触发上下文菜单的 Step/Chain 集合。
- TinyScenarios:
Scenario= 初始内容 + 选区,基于 agar 的生成器与fast-check结构生成随机内容与选区,用于属性测试(property-based testing)。 - TinyDom:创建节点与选区 Range 所需内部结构的工具模块。
- RemoteTinyLoader / ActionChains / ApiChains / UiChains:远程加载器与链式操作辅助。
五、运行测试
在 mcagar 模块目录下使用 bun run test 即可通过 bedrock 运行测试(见 package.json 的 scripts)。默认命令为:
bun run test
注意:该命令仅在 Chrome 上运行(bedrock-auto -b chrome-headless),且需要安装 chromedriver。若要测试其他浏览器,可直接使用 bedrock 工具(bedrock -d src/test/ts,对应 bun run test-manual)自行指定浏览器。
mcagar 自身的测试覆盖了上述所有 API 的浏览器端验证,例如:
- TinyLoaderTest.ts 与 TinyLoaderErrorTest.ts:验证 Loader 初始化及 11.0.0 引入的错误捕获行为;
- TinySelectionTest.ts 与 SelectionTest.ts:验证选区设置/断言;
- TinySetAndDeleteSettingTest.ts:验证
setOption/unsetOption迁移后的行为; - McagarTutorialTest.ts 与 ScenarioTutorialTest.ts:作为 BDD 与 Scenario 的入门教程用例。
六、关键实现原理小结
- 编辑器生命周期:
TinyHooks(BDD)与TinyLoader(Pipeline)殊途同归,最终都汇聚到 Loader.ts 的setup:创建目标元素 → 检测/加载 tinymce →tinymce.init→ 等待SkinLoaded→ 暴露editor()。11.0.0 起初始化异常会被Promise.resolve(...).catch(onFailure)捕获并以失败回调上报。 - UI 定位:所有 UI 操作都以
getUiRoot(ShadowDOM 感知的内容容器)为根进行UiFinder查找,这是 8.3.0 引入的能力;工具栏/菜单则通过getThemeSelectors()中的主题选择器在编辑器容器内定位。 - 键盘模拟:内容区与 UI 区的键盘事件分别委托给 agar
Keyboard.activeKeydown(TinyDom.document(editor), ...)与Keyboard.activeKeydown(getUiDoc(editor), ...),即 11.0.0 所描述的“现代键盘模拟辅助函数”。 - 兼容性边界:8.0.0 移除 IE/旧 Edge 支持、11.0.0 移除仅旧浏览器需要的回退代码,与 TinyMCE 整体放弃旧浏览器(TINY-11093)的路线一致;10.0.0 起许可证为 GPL-2.0-or-later。
理解 mcagar 的版本演化,等于同时理解了 TinyMCE 测试体系的演进方向:从 Pipeline 流水线逐步过渡到 BDD 风格、全面拥抱 ShadowDOM 与现代键盘事件、以官方 API 取代 DOM 直操作,并在每次 major 升级中同步清理旧浏览器包袱。对插件开发者而言,bddSetup + TinyContentActions + TinyUiActions + TinyAssertions 的组合,足以覆盖绝大部分编辑器交互测试场景。