TinyMCE 测试框架 mcagar 全解析:从 CHANGELOG 版本演化到 BDD 与 Pipeline 测试 API 实战

原创2026-09-21 19:28:571,896 阅读
文章标签:富文本UI组件前端插件系统

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):使用 agar Cursors 的 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):使用 agar ApproxStructure 对内容做结构化断言。
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 的浏览器端验证,例如:

六、关键实现原理小结

  1. 编辑器生命周期:TinyHooks(BDD)与 TinyLoader(Pipeline)殊途同归,最终都汇聚到 Loader.ts 的 setup:创建目标元素 → 检测/加载 tinymce → tinymce.init → 等待 SkinLoaded → 暴露 editor()。11.0.0 起初始化异常会被 Promise.resolve(...).catch(onFailure) 捕获并以失败回调上报。
  2. UI 定位:所有 UI 操作都以 getUiRoot(ShadowDOM 感知的内容容器)为根进行 UiFinder 查找,这是 8.3.0 引入的能力;工具栏/菜单则通过 getThemeSelectors() 中的主题选择器在编辑器容器内定位。
  3. 键盘模拟:内容区与 UI 区的键盘事件分别委托给 agar Keyboard.activeKeydown(TinyDom.document(editor), ...) 与 Keyboard.activeKeydown(getUiDoc(editor), ...),即 11.0.0 所描述的“现代键盘模拟辅助函数”。
  4. 兼容性边界: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 的组合,足以覆盖绝大部分编辑器交互测试场景。

登录后查看全文
tinymce