Robot Framework 5.1 alpha 2 新特性详解:本地化、标签体系重构与执行控制增强
Robot Framework 5.1 alpha 2 新特性详解:本地化、标签体系重构与执行控制增强
本文基于仓库内发布说明 doc/releasenotes/rf-5.1a2.rst,结合 src/robot 源码实现展开。Robot Framework 5.1 alpha 2 是 5.1 系列的第二个 alpha 版本,于 2022 年 7 月 21 日发布,标志着 Robot Framework 正式启动本地化(localization)工作,同时引入了标签(Tags)体系重构、关键字命名空间增强、continue-on-failure 模式可控关闭、Python 3.11 支持以及用户关键字执行性能优化等多项能力。读完本文,你将掌握
--language本地化选项的用法与自定义语言文件的写法、新旧标签设置的迁移路径、robot:private与robot:stop-on-failure等保留标签的实战应用,并了解 5.1 引入的向后不兼容变更与弃用特性。
一、版本概览与安装方式
Robot Framework 5.1 是一个新特性版本,其 alpha 系列版本尤其面向对翻译感兴趣的社区成员。5.1 alpha 2 版本聚焦于为正式版铺路的本地化基础设施,同时也带来了上述其他增强。该版本所有已提交的修复与增强均可在 issue tracker 的 5.1 里程碑中查看。
如果你已安装 pip,可以通过以下命令安装最新可用版本(含预发布版本):
pip install --pre --upgrade robotframework
若需要精确定位本版本,使用:
pip install robotframework==5.1a2
也可以从 PyPI 下载源码分发包手动安装。其他安装方式参见仓库根目录的 INSTALL.rst。
二、本地化(Localization):5.1 的核心新特性
本地化是 5.1 启动的长期工程。它首先让数据文件中的各类标记(marker)可以被翻译,包括:
- 数据文件中的表头(如
Test Cases、Settings、Variables、Keywords、Comments); - 设置项名称(如
Documentation、Suite Setup、Test Timeout等); - BDD 场景中使用的
Given/When/Then前缀。
在 5.1 规划中,还计划允许翻译布尔参数转换中使用的 True 和 False 单词;未来版本可能进一步允许翻译 IF、FOR 等语法、日志与报告内容以及错误消息。
2.1 --language 命令行选项
语言在启动执行时通过 --language 命令行选项指定。对于 Robot Framework 开箱即支持的语言,直接使用语言代码即可:
robot --language fi tests.robot
对于其他语言,可以创建自定义语言文件并使用:
robot --language MyLang.py tests.robot
该选项的完整定义位于 src/robot/run.py:lang 可以是内置语言的名称或代码,也可以是自定义语言文件的路径或模块名。robot rebot 同样支持该选项(见 src/robot/rebot.py),robot libdoc 也引入了语言支持(见 src/robot/libdoc.py)。
注意:
--language选项支持重复使用(选项后的*表示可多次指定),多语言可叠加生效,例如同时启用英语与目标语言进行补充。
2.2 内置语言列表
Robot Framework 5.1 alpha 2 在英语(默认自动支持)之外,内置支持以下社区翻译的语言:
| 语言 | 代码 |
|---|---|
| 捷克语 | CS |
| 荷兰语 | NL |
| 芬兰语 | FI |
| 法语 | FR |
| 德语 | DE |
| 波兰语 | PL |
| 葡萄牙语 / 巴西葡萄牙语 | PT / PT-BR |
| 简体中文 | ZH-CN |
| 西班牙语 | ES |
| 泰语 | TH |
这些翻译全部由社区贡献,官方在 5.1 正式版发布前仍欢迎更多社区翻译,协作平台为 Crowdin。仓库源码中除上述语言外,还进一步实现了 Bosnian(Bs)、Ukrainian(Uk)、Russian(Ru)、Chinese Traditional(ZhTw)、Turkish(Tr)等语言类,完整定义见 src/robot/conf/languages.py。
2.3 语言文件的结构与自定义语言
从源码结构看,本地化体系以 src/robot/conf/languages.py 为核心,由两个类构成:
Languages:语言容器,负责存储多种语言并统一合并翻译结果。它支持通过语言代码、语言名称、语言模块路径或Language实例来注册语言(add_language方法),并自动去重。所有语言可共同贡献表头(headers)、设置(settings)、BDD 前缀(bdd_prefixes)以及真假值字符串(true_strings/false_strings),例如英文的True/Yes/On与False/No/Off会被不同语言对应的翻译扩充。Language:所有语言定义(如En、Fi、De、ZhCn等)的基类。每个语言子类通过类属性声明各表头与设置项的本土化名称,并通过given_prefixes/when_prefixes/then_prefixes/and_prefixes/but_prefixes声明 BDD 前缀。语言代码由类名推导:类名两个字符以内直接小写(如fi),更长则转换为xx-YY形式(如ZhCn→zh-CN)。
自定义语言文件本质上就是一个 Python 模块,模块内定义 Language 的子类并覆写上述类属性。Languages._import_language_module 会导入该模块并加载其中所有 Language 子类实例,因此即使一个文件定义多种语言也能一并加载。
2.4 本地化的验证
仓库的验收测试 atest/robot/parsing/translations.robot 展示了多种调用方式:
--language fi运行芬兰语测试数据(parsing/translations/finnish/tests.robot);--language fin-nish --rpa:语言匹配对大小写与空格不敏感、忽略连字符(fin-nish等价于Finnish),并可结合--rpa任务模式;--lang(--language的短别名)配合自定义语言文件路径custom/custom.py;-P参数将自定义语言目录加入模块搜索路径后按模块名加载。
这些测试数据位于 atest/testdata/parsing/translations,其中包含自定义语言文件的具体写法,可作为编写自定义语言文件时的参考范例。
三、标签设置增强:Keyword Tags 与 Test Tags
5.1 对标签设置做了两处重要调整:新增按文件批量设置关键字标签的 Keyword Tags,并将 Force Tags 更名为 Test Tags。
3.1 新增 Keyword Tags 设置
现在可以使用新的 Keyword Tags 设置为某个文件中的所有关键字统一打标签。它适用于资源文件(resource file),也适用于测试用例初始化文件与套件初始化文件(suite initialization files)。当在初始化文件中使用时,它只影响该文件内的关键字,不会向下传播到更低层级的套件。
示例(资源文件 mykeywords.resource):
*** Settings ***
Keyword Tags regression
*** Keywords ***
Login
Log logging in
此后该资源文件中所有关键字(此处 Login)都会自动获得 regression 标签。Keyword Tags 设置项的解析实现在 src/robot/parsing/lexer/settings.py 与 src/robot/parsing/model/statements.py 中,运行期的标签合并逻辑位于 src/robot/running/builder/transformers.py。
3.2 Force Tags 更名为 Test Tags
Force Tags 设置被更名为 Test Tags,动机是让测试相关的设置命名更一致(Test Setup、Test Timeout、Test Tags……),同时更好地区分“测试标签”与“关键字标签”两组设置,统一的命名也降低了翻译难度。在创建任务(RPA 任务模式)时,可以使用 Task Tags 作为 Test Tags 的别名。
*** Settings ***
Test Tags smoke regression
旧的 Force Tags 设置仍然可用,但会在未来被弃用。
3.3 Default Tags 走向弃用与 -tag 语法规划
为简化标签设置,Default Tags 设置同样进入弃用轨道。它所提供的“仅部分测试获得某些标签”能力,未来将由 [Tags] 设置配合 -tag 语法实现——用 -tag 表示“该测试不应获得标签 tag”。该语法未来也能与新的 Keyword Tags 组合使用。由于这一规划,[Tags] 设置中以连字符开头的标签(如 -tag)即被视为弃用用法;若确需字面量标签值,使用转义形式 \-tag。
四、关键字命名空间增强
4.1 资源文件私有关键字:robot:private
现在可以给资源文件中的关键字打上 robot:private 标签,将其标记为私有。私有关键字的约束为:
- 若被该资源文件之外的关键字调用,会产生警告;
- 这类关键字会被 Libdoc 生成的 HTML 库文档排除。
私有关键字的过滤逻辑体现在 Libdoc 的模型层:Keyword.to_dictionary 与 to_json 均接受 include_private 参数(见 src/robot/libdocpkg/model.py),HTML 输出默认 include_private=False(见 src/robot/libdocpkg/htmlwriter.py),JSON 输出则记录 private 标志(见 src/robot/libdocpkg/jsonbuilder.py)。相关验收测试见 atest/robot/keywords/private.robot 及 atest/testdata/keywords/private.resource 等文件。
4.2 本地关键字优先于导入的关键字
在 5.1 中,如果某个关键字与其调用者位于同一个资源文件中,那么即使另一个资源文件中存在同名关键字,也会优先使用本地资源文件中的关键字(此前这种情况会引发命名冲突)。这解决了资源文件间同名关键字的优先级问题。
不过,如果测试用例文件(test case file)中存在同名关键字,当前行为仍是测试用例文件中的关键字优先——这与以往一致。但该行为已被标记为弃用,未来(5.2 起)本地关键字将拥有最高优先级。
五、可禁用 continue-on-failure 模式
Robot Framework 默认在出现失败时停止执行关键字或测试用例,例外情况包括 teardown、模板以及显式开启 continue-on-failure 模式的场景(通过 robot:continue-on-failure 或 robot:recursive-continue-on-failure 标签)。5.1 新增了反向控制能力:
robot:stop-on-failure:在当前层级禁用(隐式或显式的)continue-on-failure 模式;robot:recursive-stop-on-failure:在当前层级及其所有子层级禁用。
其底层逻辑位于 src/robot/running/context.py 的 continue_on_failure 方法:执行上下文从当前执行栈由内向外遍历父级用户关键字与测试,stop-on-failure 与 recursive-stop-on-failure 的检查优先级高于对应的 continue 标签——即最近一层若出现 robot:stop-on-failure,立即返回 False(停止继续执行);只有最近的 continue 标签与之匹配时才返回 True;若一路都没有命中任何标签,则回退到 default 参数或 teardown 状态的默认行为。这种实现保证了“就近显式控制”与“递归控制”可以叠加使用、互不干扰。
此外,5.1 还补充了文档说明:即使 continue-on-failure 模式激活,失败的测试 setup 依然会停止执行。
六、Python 版本支持变化
Robot Framework 5.1 正式支持即将发布的 Python 3.11。由于不兼容点不多,早期版本也能在 Python 3.11 上较正常地工作。
同时,Python 3.6 已被弃用(其官方支持已在 2021 年 12 月结束):5.1 及所有后续 5.x 版本仍支持 Python 3.6,但 Robot Framework 6.0 将不再支持。官方建议用户尽早升级到更新版本的 Python。
七、用户关键字执行性能优化
5.1 显著降低了执行用户关键字的额外开销(overhead),尤其在用户关键字频繁失败时效果明显,例如使用 Wait Until Keyword Succeeds 或在 TRY/EXCEPT 循环中反复调用关键字时。该项优化由社区贡献的拉取请求实现,属于 5.1 对高频失败场景的针对性性能改进。
八、向后不兼容的变更
5.1 alpha 2 包含以下不兼容变更,升级时需特别注意:
- BDD 前缀后必须跟空格:
Given/When/Then前缀与关键字名称之间必须存在空格,此前允许紧邻写法的场景(如GivenLogin)将不再合法。从源码实现看,Languages.bdd_prefix_regexp构造的正则要求前缀后匹配\s(空白字符),正是这一约束的落地(见 src/robot/conf/languages.py)。 - Collections 库字典相关关键字要求继承
Mapping:Collections库中与字典相关的关键字现在要求传入的字典对象继承collections.abc.Mapping。 Dictionary Should Contain Item不再进行字符串化比较:该关键字不再先把待比较的值转换为字符串再比较,比较行为更精确。- Libdoc 规格文件生成时间格式变更:XML 与 JSON 规格文件中的生成时间统一为
2022-05-27T19:07:15+00:00格式。XML 规格此前为2022-05-27T19:07:15Z(与新格式等价),JSON 规格此前完全不含时区信息(格式为2022-05-27 19:07:15)。
九、弃用特性汇总
9.1 Force Tags 与 Default Tags 设置
如前所述,Test Tags 已取代 Force Tags,Default Tags 计划整体移除。两者当前仍可用但视为已弃用:目前尚无可视化的弃用警告,自 Robot Framework 6.0 起会发出警告,并最终移除这些设置。同时,[Tags] 设置中以连字符开头的标签(-tag)也已弃用,字面量需求请使用 \-tag 转义。
9.2 Python 3.6
Python 3.6 在 2021 年 12 月达到生命周期终点。Robot Framework 5.1 及全部 5.x 仍支持,6.0 起移除。
9.3 测试用例文件关键字对资源文件本地关键字的优先权
测试用例文件中的关键字当前始终具有最高优先级,即使资源文件中的本地关键字与其同名。该行为将在 5.2 改变为“本地关键字始终优先”,当前行为已弃用。
9.4 WITH NAME 更名为 AS
给导入库起别名时使用的 WITH NAME 标记将更名为 AS,动机是与 Python 的 as 语法保持一致;TRY/EXCEPT 已经使用 AS,复用同一标记与内部 token 可简化语法,同时减少标记种类也有利于后续翻译工作(不过这些标记当前尚不可翻译)。5.1 中 AS 与 WITH NAME 均可用于设置库别名,WITH NAME 视为弃用,但可视化的弃用警告同样推迟到 6.0 才发出。
十、完整修复与增强列表
以下是 5.1 alpha 2 的全部 32 个 issue 汇总,按类型、优先级与加入的 alpha 版本列出:
| ID | 类型 | 优先级 | 概要 | 加入版本 |
|---|---|---|---|---|
| #4096 | enhancement | critical | 数据中标记的多语言支持 | alpha 1 |
| #519 | enhancement | critical | Given/When/Then 支持英语以外的语言 | alpha 1 |
| #4295 | enhancement | high | 弃用 Python 3.6 | alpha 1 |
| #430 | enhancement | high | 资源文件关键字可见性修饰符 | alpha 1 |
| #4303 | enhancement | high | 支持用 robot:stop-on-failure 与 robot:recursive-stop-on-failure 禁用 continue-on-failure |
alpha 1 |
| #4366 | enhancement | high | 资源文件中本地关键字优先于导入关键字 | alpha 1 |
| #4368 | enhancement | high | 新增 Test Tags 作为 Force Tags 的别名 |
alpha 1 |
| #4373 | enhancement | high | 支持用 Keyword Tags 设置为所有关键字打标签 |
alpha 1 |
| #4380 | enhancement | high | 弃用 [Tags] 设置中 -tag 形式的标签 |
alpha 1 |
| #4388 | enhancement | high | 提升用户关键字执行性能(尤其失败场景) | alpha 1 |
| #4401 | enhancement | high | Python 3.11 兼容性 | alpha 1 |
| #4351 | bug | medium | Libdoc 在库参数扩展名匹配资源文件时给出错误提示 | alpha 1 |
| #4355 | bug | medium | 可继续的失败会终止 WHILE 循环 | alpha 1 |
| #4357 | bug | medium | 解析模型:无法用 from_params 创建 TRY、WHILE 语句 |
alpha 1 |
| #4359 | bug | medium | 解析模型:Variable.from_params 未正确处理列表值 |
alpha 1 |
| #4381 | bug | medium | 解析错误被识别为 EmptyLines | alpha 1 |
| #4384 | bug | medium | RPA 设置的别名在套件初始化文件中不生效 | alpha 1 |
| #4387 | bug | medium | Libdoc:修复规格文件中弃用关键字信息的存储 | alpha 1 |
| #4408 | bug | medium | Collections:Dictionary Should Contain Item 比较前错误地转字符串 |
alpha 1 |
| #4262 | enhancement | medium | 生成库文档时遵循 SOURCE_DATE_EPOCH 环境变量 |
alpha 1 |
| #4312 | enhancement | medium | 在 PyPI 添加项目 URL | alpha 1 |
| #4353 | enhancement | medium | 解析性能增强 | alpha 1 |
| #4371 | enhancement | medium | 库导入中为 WITH NAME 添加 AS 别名 |
alpha 1 |
| #4379 | enhancement | medium | 要求 Given/When/Then 前缀后必须有空格 | alpha 1 |
| #4398 | enhancement | medium | Collections:Get From Dictionary 支持默认值参数 |
alpha 1 |
| #4404 | enhancement | medium | 文档化:continue-on-failure 模式下失败的测试 setup 仍会停止执行 | alpha 1 |
| #4413 | enhancement | medium | Collections 字典相关关键字更严格地限定可接受的值 | alpha 1 |
| #4349 | bug | low | 用户指南:YAML 变量文件示例有误 | alpha 1 |
| #4358 | bug | low | 用户指南:TRY/EXCEPT 相关示例有误 | alpha 1 |
| #4346 | enhancement | low | 增强 --timestampoutputs 选项的文档 |
alpha 1 |
| #4372 | enhancement | low | 文档化如何导入打包进 Python 包的资源文件 | alpha 1 |
| #4394 | bug | --- | --doc 或 --metadata 值匹配到已有目录时报错 |
alpha 1 |
从发布说明可见,5.1 alpha 2 的所有 32 个 issue 均已在 alpha 1 阶段合入,alpha 2 的重点在于围绕本地化收集更多社区反馈与翻译。其中 SOURCE_DATE_EPOCH 支持(#4262)保证了 Libdoc 生成的库文档具备可复现构建能力——通过该环境变量固定生成时间戳,从而让每次构建产出的文档字节级一致。
十一、升级与迁移建议
结合以上变更,从 5.0 升级到 5.1 时的实操建议如下:
- BDD 写法:检查所有
Given/When/Then前缀后的空格,GivenLogin这类写法需要改为Given Login。 - 标签设置迁移:将
Force Tags逐步替换为Test Tags(RPA 任务场景用Task Tags);Default Tags的用法关注后续-tag语法的发布;避免在[Tags]中直接书写-开头的字面量标签。 - 库别名写法:将
Library XXX WITH NAME YYY迁移为Library XXX AS YYY。 - Collections 字典断言:
Dictionary Should Contain Item不再做字符串转换,比较逻辑需按新语义复核。 - Python 版本:为 Python 3.6 环境规划升级,避免被 6.0 阻断。
- 试用本地化:运行
robot --language fi tests.robot或加载自定义语言文件体验多语言数据文件,并关注后续对True/False及语法的翻译扩展。