CKEditor 4 回归测试实战:验证气球工具栏点击不破坏 Firefox 原生表格选区

原创2026-10-14 18:27:471,911 阅读
文章标签:前端UI组件

CKEditor 4 回归测试实战:验证气球工具栏点击不破坏 Firefox 原生表格选区

本篇技术指南以 CKEditor 4 仓库中 tests/core/selection/manual/tableselection.md 及其配套 HTML 手册测试为核心,深入讲解如何验证并回归"在 Firefox 中点击气球工具栏按钮后,表格单元格的本地选择(native table selection)保持不变"这一关键行为。读完本文,你将掌握该手册测试的完整操作流程、配套页面源码的实现细节,以及背后 tableselection 与 balloontoolbar 两个插件在选区层面的协作原理。

一、测试场景:一个表格选区 + 一个气球工具栏按钮

该手册测试针对 CKEditor 4.13.0 / 4.13.1 期间修复的回归缺陷 #3136 与 #3475。根据仓库 CHANGES.md 中 4.13.0 版本的修复记录:

#3136:[Firefox] 修复:点击 Balloon Toolbar 项会移除(表格的)本地选择。

在 Firefox 中,CKEditor 允许浏览器"原生"选中多个表格单元格(即浏览器本身提供的多单元格选区,带蓝色高亮),而不是像其他浏览器那样依赖 tableselection 插件模拟的"伪装选区"。历史 bug 表明:当用户用原生方式选中单元格后,再去点击悬停的气球工具栏(Balloon Toolbar)上的按钮,Firefox 会把选区丢失或改变。该手册测试的目的,就是反复验证点击气球工具栏按钮之后,编辑区内的选区仍然保持原样。

测试页面同时准备了 Classic(经典)编辑器与 Divarea 编辑器两种形态,要求对每个编辑器逐一执行相同的操作步骤。

二、手册测试文件逐段解读

手册测试文件为 tests/core/selection/manual/tableselection.md,全文很短,但信息密度很高,由 Bender 元数据与操作说明两部分构成。

2.1 Bender 元数据

@bender-tags: selection, 4.13.0, 4.13.1, bug, 3136, 3475
@bender-ui: collapsed
@bender-ckeditor-plugins: wysiwygarea, table, tabletools, toolbar
元数据 含义
@bender-tags 标记测试所属领域为 selection(选区),关联版本 4.13.0、4.13.1,类型为 bug,并绑定缺陷编号 3136、3475
@bender-ui: collapsed 声明这是 UI 手册测试,且测试 UI 初始为折叠状态(编辑器默认不展开渲染,减少干扰)
@bender-ckeditor-plugins 声明运行所需插件:wysiwygarea(可见编辑区)、table(表格)、tabletools(表格工具)、toolbar(工具栏)

值得注意:元数据声明了 tabletools,但没有声明 tableselection。这一点并非疏漏,而是刻意为之——本测试验证的是 Firefox 的原生表格选区,如果加载了 tableselection 插件,选区会被插件接管成"伪装选区",测试目标就变了(详见下文源码解析中 removePlugins: 'tableselection' 的配置)。

2.2 操作步骤与预期结果

## For each editors

1. Select few table cells, so that they have blue highlight.

	**Note:** for better visibility, all cells, in which there is selection, has cyan backgrund.
1. Press button in balloon toolbar.

## Expected

Selection in editor looks the same.

## Unexpected

Selection is changed.

对每个编辑器依次执行:

  1. 选中若干表格单元格,使其呈现蓝色高亮(即 Firefox 的原生表格选择视觉反馈)。
    • 附带说明:为了让选中状态更容易辨认,测试页面通过自定义 CSS 给所有"被选区覆盖的单元格"额外添加了青色(cyan)背景。
  2. 点击气球工具栏中的按钮(该工具栏会在鼠标悬停表格时出现)。

判定标准:

  • 预期(Expected):点击按钮后,编辑区内的选区与点击前完全一致。
  • 非预期(Unexpected):点击按钮后,选区发生了变化(丢失、收缩或转移到别处)。

三、配套 HTML 页面:复现缺陷的最小场景

手册测试的实体页面是 tests/core/selection/manual/tableselection.html,它把上面的操作步骤落地为一个可运行、可交互的复现环境。整个页面可拆解为四层。

3.1 两层编辑器实例

页面定义了 classic 与 divarea 两个容器,内容均为"Hello world + 一个 2 行 3 列的表格":

<h2>Classic Editor</h2>
<div id="classic">
	Hello world
	<table border=1>
		<tr><td>foo</td><td>foo</td><td>foo</td></tr>
		<tr><td>bar</td><td>bar</td><td>bar</td></tr>
	</table>
</div>

divarea 容器结构完全相同,用于覆盖"以 <div> 替代 <iframe> 承载编辑区"的另一种编辑器形态(对应 divarea 插件)。两套编辑器共享同一份 editorConfig,仅 divarea 额外追加 divarea 插件:

CKEDITOR.replace( 'classic', editorConfig );

CKEDITOR.replace( 'divarea', CKEDITOR.tools.object.merge( editorConfig, {
	extraPlugins: 'testplugin,divarea'
} ) );

3.2 关闭 tableselection,保留 Firefox 原生选区

var editorConfig =  {
	extraPlugins: 'testplugin',
	removePlugins: 'tableselection',
	// ...
};

removePlugins: 'tableselection' 是本测试的核心前提。查看 plugins/tableselection/plugin.js 的 isSupportedEnvironment 与初始化逻辑可以发现:tableselection 插件通过"伪装选区(fake selection)"为不支持原生表格选择的浏览器提供多单元格选择能力。而 Firefox 是少数自带原生表格选择的浏览器(这正是自动化测试中 CKEDITOR.env.gecko 判断存在的理由),因此本测试必须移除该插件,才能让 Firefox 走原生选择路径,从而验证 #3136 的修复。

3.3 青色高亮:把"被选区覆盖"可视化

CKEDITOR.addCss( '.selected { background-color: cyan; }' );

on: {
	selectionCheck: function( evt ) {
		var editor = evt.editor,
			editable = editor.editable(),
			selectedCells = CKEDITOR.plugins.tabletools.getSelectedCells( editor.getSelection() );

		CKEDITOR.tools.array.forEach( editable.find( 'td' ).toArray(), function( cell ) {
			cell.removeClass( 'selected' );
		} );

		CKEDITOR.tools.array.forEach( selectedCells, function( cell ) {
			cell.addClass( 'selected' );
		} );
	}
}

这里用到两个关键 API:

  • CKEDITOR.plugins.tabletools.getSelectedCells( selection ):位于 plugins/tabletools/plugin.js,是表格工具插件的公开方法(在第 1198 行被导出)。它遍历选区中的每个 Range,通过 CKEDITOR.dom.walker 的 moveOutOfCellGuard 守卫函数收集被选区覆盖的 td/th 单元格;对折叠选区则回退到 getCommonAncestor().getAscendant( { td: 1, th: 1 } ) 获取最近单元格。它还被 tableselection 插件在 onLoad 中直接复用(plugins/tableselection/plugin.js)。
  • selectionCheck 事件:编辑器每次选区检查后触发,测试在此事件中先清除所有 td 的 selected 类,再给"真正处于选区中"的单元格加上该类,从而渲染青色背景。

这一机制让测试人员不必依赖浏览器默认的蓝色高亮,就能肉眼确认"当前到底选中了哪些单元格",并在点击气球工具栏按钮后立即对比选区是否仍停留在同样的单元格集合上。

3.4 自定义 testplugin:挂载气球工具栏

页面定义了一个微型插件 testplugin,用于搭建复现 #3136 所需的 UI:

CKEDITOR.plugins.add( 'testplugin', {
	requires: 'balloontoolbar',
	icons: 'foo',
	init: function( editor ) {
		editor.addCommand( 'foo', { exec: function() {} } );
		editor.ui.addButton( 'foo', {
			label: 'foo',
			command: 'foo',
			toolbar: 'none,99'
		} );
	},
	afterInit: function( editor ) {
		editor.balloonToolbars.create( {
			buttons: 'foo',
			cssSelector: 'table'
		} );
	}
} );

要点拆解:

  • requires: 'balloontoolbar' 确保气球工具栏插件先于本插件加载,editor.balloonToolbars 管理器因此可用。
  • editor.addCommand( 'foo', ... ) 注册一个空命令 foo,editor.ui.addButton 将其渲染为工具栏按钮。命令体为空函数,说明本测试不关心按钮的功能,只关心"点击这个按钮会不会破坏选区"。
  • afterInit 中通过 editor.balloonToolbars.create() 创建工具栏上下文,cssSelector: 'table' 表示只要选区路径命中 table 元素就显示该工具栏。对照 plugins/balloontoolbar/plugin.js 中的上下文匹配逻辑(_matchRefresh 与 check),cssSelector 是比 refresh 回调更简单的匹配方式:任何位于表格内的选择都会命中上下文并弹出工具栏。

3.5 仅限 Firefox 运行

if ( !CKEDITOR.env.gecko ) {
	bender.ignore();
}

页面开头即判断 CKEDITOR.env.gecko,非 Firefox 直接 bender.ignore() 跳过。理由在自动化测试中有明确注释:"Only Firefox has native table selection."(只有 Firefox 拥有原生表格选择)。因此在其他浏览器上,即使 removePlugins: 'tableselection' 也无法进行多单元格选择,测试无从执行。

四、背后的插件机制:伪装选区如何与气球工具栏共存

4.1 tableselection 的鼠标事件链

当启用 tableselection 插件时,plugins/tableselection/plugin.js 在 contentDom 中为可编辑区挂载了一整套鼠标事件监听:

editable.attachListener( mouseHost, 'mousedown', fakeSelectionMouseHandler, null, evtInfo );
editable.attachListener( mouseHost, 'mousemove', fakeSelectionMouseHandler, null, evtInfo );
editable.attachListener( mouseHost, 'mouseup', fakeSelectionMouseHandler, null, evtInfo );

fakeSelectionMouseHandler(第 288 行起)负责整条"伪装选择"状态机:

  • mousedown:若左键按下且目标在表格内,置 fakeSelection.active = true,并临时在 CKEDITOR.document 上监听 mouseup(覆盖"鼠标在编辑器外释放"的场景,第 353-358 行)。
  • mousemove:fakeSelectByMouse 计算首尾单元格之间的全部单元格,调用 fakeSelectCells 为每个单元格生成"包住整格"的 Range 并 selectRanges,从而形成多 Range 的伪装选区;同时给单元格加上 cke_table-faked-selection 类(该样式定义见 plugins/tableselection/styles/tableselection.css,聚焦时呈蓝色 #0076cb 背景、cursor: cell 光标)。
  • mouseup:若选区结束在表格内或嵌套表格内,调用 restoreFakeSelection(第 168-178 行)重新按 cke_table-faked-selection 类重建选区,避免 Firefox 等浏览器在释放鼠标时把选区"弄乱"——这正是 #3136 修复思路的一部分。

4.2 气球工具栏与选区事件

plugins/balloontoolbar/plugin.js 中,工具栏上下文管理器监听编辑器的 selectionChange 并触发 _refresh()(第 590-605 行),进而调用 toolbar.refresh()(第 200-207 行)刷新各按钮的命令状态。点击工具栏按钮属于典型的"编辑器外交互",在 Firefox 旧版本中会触发编辑器失去焦点 / 选区重建,导致原生表格选区被丢弃;CKEditor 4.13.0 通过 #3136 修复让点击气球工具栏不再触碰原生表格选区。本手册测试正是这一修复的"人工冒烟测试"。

五、自动化测试作为对照证据

除手册测试外,仓库还提供了对应的自动化用例 tests/core/selection/tableselection.js,同样标注了 // (#3136)。它验证的是同一族问题的另一个侧面——编辑器重新获得焦点后 Range 必须原样恢复:

'test ranges are restored when editor is focused': function( editor, bot ) {
	// Only Firefox has native table selection.
	if ( !CKEDITOR.env.gecko ) {
		assert.ignore();
	}
	// ... 对每个 td 构造一个包住单元格的 Range,selectRanges 后:
	selectionContainer.focus();   // 焦点移出编辑器
	editor.focus();               // 焦点回到编辑器
	// 断言:重新获取的 Range 数量、startOffset/endOffset、startContainer/endContainer 与之前完全一致
}

测试通过 assertRange 逐项比对 Range 的偏移量与容器节点,确保 Firefox 中"失焦-聚焦"不会悄悄改动原生表格选区。这从自动化角度印证了手册测试"选区保持不变"的预期标准,二者构成"自动化 + 人工"的双重回归保障。

六、如何运行与判定

  1. 在仓库根目录确认 Bender 环境可用(项目根目录的 bender.js 与 bender-runner.config.json 定义了测试运行配置)。
  2. 启动 Bender 手册测试服务器,在浏览器中打开 tests/core/selection/manual/tableselection.html(仅需 Firefox,其他浏览器会被 bender.ignore() 跳过)。
  3. 对 Classic 与 Divarea 两个编辑器分别执行:
    • 用鼠标框选多个表格单元格,确认出现蓝色高亮且被选单元格呈青色背景;
    • 移动鼠标到表格上方,等待气球工具栏出现;
    • 点击工具栏中的按钮;
    • 观察选区:若单元格仍保持同样的青色高亮集合、蓝色选区未变化 → Expected(通过);若选区丢失、收缩或转移到其他位置 → Unexpected(缺陷复现)。

七、回归价值与适用范围

  • 该测试属于 UI 手册测试(manual test),依赖人工视觉判定,因为"选区是否被破坏"这类问题很难用纯 DOM 断言完全覆盖——这正是它与 tests/core/selection/tableselection.js 自动化用例互为补充的原因。
  • 测试仅在 Firefox(Gecko)下有效,因为只有 Firefox 具备原生表格选择;其他浏览器由 tableselection 插件的伪装选区接管,行为路径完全不同。
  • 若后续修改涉及 plugins/tableselection/plugin.js 的鼠标事件处理、plugins/balloontoolbar/plugin.js 的上下文刷新,或 plugins/tabletools/plugin.js 的 getSelectedCells,都应跑一遍本手册测试,确保"编辑器外 UI 交互不破坏表格选区"这一基础体验不回退。
登录后查看全文
ckeditor4