Robot Framework 5.1 新特性全解析:多语言本地化、关键字标签与命名空间增强实战指南
Robot Framework 5.1 新特性全解析:多语言本地化、关键字标签与命名空间增强实战指南
Robot Framework 5.1 alpha 1 是 5.1 系列的首个预览版本,于 2022 年 7 月 15 日发布,其核心使命是启动官方本地化(Localization)工作,同时带来关键字标签体系、关键字命名空间、执行控制标签、Python 3.11 兼容与用户关键字性能优化等一系列增强。本文以 rf-5.1a1.rst 发布说明为骨架,深入 src/robot 源码与 atest/robot 验收测试,带你逐项掌握 --language 多语言用法、Keyword Tags/Test Tags 新设置、robot:private 私有关键字、robot:stop-on-failure 控制标签等新能力,并理解其底层实现原理。
安装与版本定位
5.1 alpha 1 面向对翻译感兴趣的开发者,是一个预览版本。使用 pip 安装最新可用(含预发布)版本:
pip install --pre --upgrade robotframework
如需精确安装此版本:
pip install robotframework==5.1a1
也可以从 PyPI 下载源码发行包手动安装,更详细的安装方式见仓库根目录的 INSTALL.rst。
核心增强一:本地化(Localization)
5.1 通过允许翻译数据文件中使用的各种标记(marker)来启动本地化工作,这是本次发布最重要的主题(对应 issue #4096 与 #519)。
可以翻译的内容
- 数据文件的表头(headers):如
Test Cases、Settings、Keywords、Variables、Comments等; - 设置项名称(settings):如
Documentation、Test Setup、Library、Resource等; - BDD 前缀
Given/When/Then:包括And、But在内。
计划中还将支持翻译 Boolean 参数转换中的 True/False 词汇(issue #4400),未来的版本可能继续支持翻译 IF、FOR 等语法关键字、日志与报告内容以及错误消息。
指定语言的方式
通过命令行选项 --language 指定。对于内置语言,直接用语言代码即可:
robot --language fi tests.robot
对于自定义语言,可以创建自定义语言文件并像导入模块一样使用:
robot --language MyLang.py tests.robot
内置语言列表
5.1 alpha 1 除默认支持的英语外,内置了以下社区贡献的语言:
| 语言 | 代码 |
|---|---|
| 捷克语 Czech | cs |
| 荷兰语 Dutch | nl |
| 芬兰语 Finnish | fi |
| 法语 French | fr |
| 德语 German | de |
| 葡萄牙语 Portuguese | pt |
| 巴西葡萄牙语 Brazilian Portuguese | ptbr |
源码级实现:Languages 与 Language 类
本地化功能的底层实现在 src/robot/conf/languages.py:
Language是语言定义的基类,通过类名派生语言代码(如类Fi→ 代码fi,类PtBr→ 代码pt-BR),通过类 docstring 第一行派生语言名称。子类只需声明settings_header、library_setting、given_prefixes、true_strings等类属性即可完成整套翻译;Languages类负责合并多种语言:headers、settings、bdd_prefixes、true_strings、false_strings会被统一汇总(_add_language方法,languages.py),因此可以同时指定多个语言;- BDD 前缀会被编译成正则表达式:
bdd_prefix_regexp属性将前缀拼接为(prefixes)\s并忽略大小写匹配(languages.py),这对应 5.1 中"Given/When/Then前缀后必须跟空格"的不兼容变更; - 自定义语言文件会被当作 Python 模块导入,从中收集所有
Language子类(_import_language_module,languages.py)。
在配置层面,RobotSettings 将 --language 解析到 Language 选项(settings.py),并提供惰性求值的 languages 属性(settings.py)。
示例:创建一个 MyLang.py 自定义语言文件,继承 Language 并覆盖目标属性即可,例如:
from robot.conf.languages import Language
class MyLang(Language):
"""My Language"""
settings_header = 'Asetukset'
given_prefixes = ['Oletetaan']
# 其余属性同理,可参考 src/robot/conf/languages.py 中 Fi 类的完整定义
实测验证
验收测试中已有大量多语言用例(如 atest/robot/parsing/translations.robot),并且仓库在 5.1 之后还陆续加入了 Bosnian、Thai、Polish、Ukrainian、Spanish、Russian、简体中文(zh_CN)、繁体中文(zh_TW)、土耳其语等语言类(src/robot/conf/languages.py),说明该机制具备良好的扩展性。
核心增强二:关键字与测试标签的设置增强
新增 Keyword Tags 设置
现在可以为某个文件中的所有关键字统一设置标签,对应 issue #4373:
*** Settings ***
Keyword Tags smoke regression
该设置在资源文件(.resource/.robot)、测试用例初始化文件和套件初始化文件(__init__.robot)中均可用;在初始化文件中使用时,只影响该文件内的关键字,不会向下传播到更低层级的套件。
在词法分析层面,Keyword Tags 已被注册为合法的设置 token(src/robot/parsing/lexer/settings.py),并对应 KEYWORD_TAGS 语句模型(src/robot/parsing/model/statements.py)。Libdoc 相关的验收测试(如 atest/robot/libdoc/resource_file.robot)会验证 Keyword Tags 是否被正确收集到关键字文档中。
Force Tags 更名为 Test Tags
为了让测试相关设置命名更一致(Test Setup、Test Timeout、Test Tags 等),并更好地区分测试标签与关键字标签,Force Tags 被重命名为 Test Tags(issue #4368):
*** Settings ***
Test Tags smoke
旧的 Force Tags 仍然可用,但已被标记为"未来将弃用"。创建 RPA 任务时,可以使用 Task Tags 作为 Test Tags 的别名。词法分析器中 Task Tags、Force Tags 都会被统一归一化为 Test Tags token(src/robot/parsing/lexer/settings.py)。
Default Tags 的弃用计划
Default Tags 设置(为部分测试设置标签)将同样被弃用。未来将引入 [Tags] 设置配合 -tag 语法,表示"该测试不应获得标签 tag",该语法也计划与新的 Keyword Tags 组合使用(issue #4374)。因此从 5.1 起,在 [Tags] 中使用以连字符开头的标签(如 -tag)被视为弃用;如果确实需要字面量值,请使用转义形式 \-tag(issue #4380)。
注意:Test Tags、Keyword Tags 这些新名称本身也已被纳入本地化体系(src/robot/conf/languages.py),这正是"统一命名便于翻译"这一动机的体现。
核心增强三:关键字命名空间(Namespaces)增强
资源文件私有关键字:robot:private
现在可以在资源文件中将关键字标记为私有,方法是为其添加 robot:private 标签(issue #430):
*** Keywords ***
Internal Helper
[Tags] robot:private
Log This is private
效果:
- 跨文件使用警告:如果该关键字被资源文件之外的代码调用,会发出警告;
- Libdoc 排除:私有关键字不会出现在 Libdoc 生成的 HTML 库文档中。
源码证据:
- 关键字实现通过
tags.robot('private')判断私有性(src/robot/running/keywordimplementation.py); - 执行时通过
context.warn_on_invalid_private_call发出警告(src/robot/running/userkeywordrunner.py,实现于 src/robot/running/context.py); - 命名空间解析时会优先选择非私有关键字(src/robot/running/namespace.py);
- Libdoc 侧,私有信息会写入 spec 的 JSON/XML 输出(src/robot/libdocpkg/jsonbuilder.py、src/robot/libdocpkg/xmlwriter.py),HTML 文档默认
include_private=False(src/robot/libdocpkg/htmlwriter.py)。
验收测试覆盖了私有关键字在资源文件文档中的行为(如 atest/robot/libdoc/resource_file.robot)。
本地关键字优先于导入的关键字
当某个资源文件中的关键字调用另一个同名关键字时,同文件内的本地关键字优先,即使其他资源文件中存在同名关键字(issue #4366)。此前这种情况会引发冲突。其实现位于命名空间的 _prioritize_same_file_or_public 方法:当调用者存在父源文件时,优先选择 source 与调用者相同的候选关键字(src/robot/running/namespace.py)。
一个已知的弃用行为
如果关键字存在于其使用者的同一资源文件中,但同时测试用例文件中也有同名关键字,目前仍是测试用例文件中的关键字优先(历史行为)。但该行为在 5.1 中已被弃用,未来(5.2 起)本地关键字将拥有最高优先级。
核心增强四:禁用 continue-on-failure 模式
Robot Framework 通常在失败时停止执行当前关键字或测试,例外情况包括 teardown、模板以及通过 robot:continue-on-failure 或 robot:recursive-continue-on-failure 标签显式开启的继续失败模式。5.1 新增了两个标签(issue #4303),用于在需要时禁用隐式或显式的继续失败模式:
*** Test Cases ***
My Test
[Tags] robot:recursive-stop-on-failure
Keyword 1
Keyword 2
| 标签 | 作用 |
|---|---|
robot:stop-on-failure |
在标记的元素本身处停止(非递归) |
robot:recursive-stop-on-failure |
在标记的元素及其所有嵌套关键字中停止 |
实现位于 continue_on_failure 方法:它会逆序遍历当前调用栈的父级(用户关键字与测试),stop-on-failure/recursive-stop-on-failure 标签优先于对应的 continue 标签被检查并返回 False(src/robot/running/context.py)。
同时 5.1 还明确文档化:即使 continue-on-failure 模式处于激活状态,失败的测试 setup 仍会停止执行(issue #4404)。
核心增强五:Python 3.11 支持与 Python 3.6 弃用
5.1 官方支持即将发布的 Python 3.11(issue #4401),且不兼容性问题不大,早期版本在 3.11 上也能正常运转。与此同时,Python 3.6 被弃用:它已于 2021 年 12 月到达生命周期终点,5.1 及所有未来 RF 5.x 仍支持它,但 Robot Framework 6.0 将不再支持 Python 3.6(issue #4295),官方建议用户尽早升级到更新版本。
核心增强六:用户关键字执行性能优化
5.1 降低了用户关键字执行的额外开销(overhead),尤其在用户关键字频繁失败的场景下差异明显,例如配合 Wait Until Keyword Succeeds 使用,或在 TRY/EXCEPT 循环中。该优化来自社区 PR(issue #4353/#4388),此外解析性能也有增强(issue #4353 中同时包含 parsing 性能改进)。
向后不兼容变更
5.1 引入了以下不兼容变更,升级时需注意:
- BDD 前缀后必须跟空格:
Given/When/Then前缀(含本地化后的前缀)后必须紧跟空格(issue #4379)。这对应bdd_prefix_regexp中(prefixes)\s的正则要求(src/robot/conf/languages.py); Dictionary Should Contain Item不再做字符串转换:Collections 库中该关键字不再在比较前将值转换为字符串(issue #4408);- Libdoc spec 文件的生成时间格式变更:XML 与 JSON spec 文件中的生成时间统一为带时区格式
2022-05-27T19:07:15+00:00。旧 XML 格式...Z与新格式等价;旧 JSON 格式2022-05-27 19:07:15不含时区信息(issue #4262)。该变更同时支持通过SOURCE_DATE_EPOCH环境变量生成确定性(deterministic)文档(src/robot/libdocpkg/output.py),用于可复现构建场景。
已弃用特性汇总
| 特性 | 弃用说明 | 替代方案 |
|---|---|---|
Force Tags |
仍可用,6.0 起发出可见弃用警告,最终移除 | 使用 Test Tags(任务场景用 Task Tags) |
Default Tags |
同上 | 未来的 [Tags] + -tag 语法 |
[Tags] 中以 - 开头的字面量标签 |
弃用 | 转义为 \-tag |
| Python 3.6 | 5.x 仍支持,6.0 移除 | 升级 Python |
| 测试用例文件关键字优先于资源文件本地关键字 | 5.2 起本地关键字优先 | 将本地关键字放在资源文件中 |
WITH NAME(库导入别名) |
仍可用,6.0 起警告 | 使用 AS |
其中 WITH NAME 别名标记在 5.1 中引入了新的 AS 写法(issue #4371)。动机是与 Python 的 as 保持一致,且 AS 已用于 TRY/EXCEPT,复用同一标记可以减少内部 token 种类,也有助于降低后续翻译成本:
*** Settings ***
Library Collections AS Col
5.1 中 AS 与 WITH NAME 均可用于为导入的库设置别名。
附带修复与其他增强
5.1 alpha 1 共包含 31 个 issue,除上述主要内容外还包括:
- Libdoc 相关:库参数扩展名与资源文件冲突时给出更准确的错误消息(#4351);修复 spec 文件中弃用关键字信息的存储(#4387);
- 解析模型:
TRY/WHILE语句的from_params创建支持(#4357);Variable.from_params对列表值处理修复(#4359);解析错误被误识别为EmptyLines的修复(#4381); - 执行相关:continuable failures 终止
WHILE循环的修复(#4355);套件初始化文件中 RPA 设置别名失效的修复(#4384); - Collections 库:
Get From Dictionary支持默认值参数(#4398); - PyPI 元数据:为 PyPI 添加项目 URL(#4312);
- 文档改进:修正 YAML 变量文件示例(#4349)、
TRY/EXCEPT示例(#4358)、增强--timestampoutputs文档(#4346)、说明如何导入打包进 Python 包中的资源文件(#4372); - 其他:修复
--doc或--metadata值与已有目录同名时报错的问题(#4394)。
结语
Robot Framework 5.1 以本地化为旗帜,为数据文件、BDD 前缀乃至未来的布尔字面量铺平了多语言道路;同时通过 Keyword Tags、Test Tags 重构了标签设置体系,以 robot:private 和本地关键字优先规则重塑了资源文件命名空间语义,并以 robot:stop-on-failure 系列标签补齐了失败控制的最后一块拼图。理解这些新机制不仅能让你在 5.1 上写出更规范、更易维护的测试数据,也能为跟踪后续 5.x 系列的演进打下基础。若想深入了解每个特性背后的完整实现,可以直接研读 src/robot/conf/languages.py、src/robot/running/context.py 与 src/robot/running/namespace.py,并对照 atest/robot/parsing/translations.robot 等验收测试验证行为。