Robot Framework 5.1 Beta 1 技术解读:多语言本地化、标签体系重构与关键字命名空间增强
Robot Framework 5.1 Beta 1 技术解读:多语言本地化、标签体系重构与关键字命名空间增强
Robot Framework 5.1 beta 1(发布于 2022 年 9 月 2 日)是 5.x 系列中一个具有里程碑意义的功能版本:它正式启动了框架的本地化(Localization)工作,同时带来了标签设置体系的重构、关键字命名空间改进、继续执行(continue-on-failure)模式的精细化控制以及 Python 3.11 官方支持。本文以官方发布说明 doc/releasenotes/rf-5.1b1.rst 为主体骨架,结合仓库源码与验收测试,逐一剖析这些新特性的用法、实现原理与迁移注意事项,帮助你在升级到 5.1 后正确使用新语法并规避破坏性变更。
安装与版本确认
5.1 作为功能版本,发布说明建议使用 pip 安装。若希望安装最新的可用预发布版本,运行:
pip install --pre --upgrade robotframework
若要精确安装本版本,则运行:
pip install robotframework==5.1b1
也可以从 PyPI 下载源码分发包后手动安装,更多安装方式参见仓库根目录的 INSTALL.rst。注意 5.1 的各个预览版本(alpha/beta)主要面向对翻译感兴趣的社区成员,用于提前验证本地化功能。
本地化:Robot Framework 的翻译能力初登场
本地化是 5.1 版本最核心的新特性(对应 issue #4096、#519、#4400)。它允许将数据文件中使用的各种标记(marker)翻译成其他语言,目前可翻译的内容包括:
- 表格头(headers),例如
Test Cases、Settings、Variables、Keywords; - 设置项(settings),例如
Documentation、Suite Setup、Test Tags; - BDD 前缀,即
Given/When/Then/And/But; - 布尔参数转换时使用的真/假字符串,例如
True/False。
未来的版本可能进一步允许翻译 IF、FOR 等语法、日志与报告内容、错误消息等。也就是说,5.1 的本地化只覆盖"数据标记"层面,不涉及执行期语法与输出。
通过命令行指定语言
在启动执行时使用 --language 命令行选项指定语言。该选项在 src/robot/run.py 与 src/robot/libdoc.py 中均有定义(Libdoc 中用于设置文档的默认语言)。对于 Robot Framework 内置支持的语言,可以直接使用语言代码或语言名称:
robot --language fi tests.robot # 芬兰语(代码)
robot --language Finnish tests.robot # 芬兰语(名称)
也可以创建自定义语言文件,并将其路径或模块名传给 --language:
robot --language MyLang.py tests.robot
如果需要同时支持多种语言,--language 可以重复使用多次:
robot --language de --language uk tests.robot
从源码看,src/robot/conf/settings.py 将 Language 选项映射为可重复收集的配置项,并在 src/robot/conf/settings.py 中惰性构造 Languages 实例;若语言无效则抛出 DataError。验收测试 atest/robot/parsing/translations.robot 也验证了传入无效语言 --lang bad 时进程返回码为 252、错误信息为 Invalid value for option '--language': Importing language file 'bad' failed。
在数据文件内部指定语言
除命令行外,还可以在数据文件第一个段落之前使用 language: <lang> 语法声明语言,其中 <lang> 是语言代码或名称。以下是一个使用芬兰语的示例:
language: fi
*** Asetukset ***
Dokumentaatio Example using Finnish.
由于技术原因,这种按文件指定的语言配置会影响后续被解析的文件。发布说明明确警告:该行为将来很可能改变,不应依赖它。正确做法是:要么在每个被解析的文件中都写上 language: <lang>,要么统一在命令行指定语言。仓库中的验收测试 atest/robot/parsing/translations.robot 甚至专门有一个用例 Per file configuration bleeds to other files,用来固化"按文件配置会外溢到其他文件"这一技术限制;而同文件 atest/robot/parsing/translations.robot 还验证了单文件多语言配置(many.robot)中芬兰语、泰语、乌克兰语标记可以共存,以及非法语言会报 Invalid language configuration 错误。
在 atest/testdata/parsing/translations/per_file_config/fi.robot 中可以找到一份完整的芬兰语数据文件示例,它覆盖了全部可翻译标记:
language: fi
*** Asetukset ***
Nimi Custom name
Dokumentaatio Suite documentation.
Metatiedot Metadata Value
Setin Alustus Suite Setup
Setin Alasajo Suite Teardown
Testin Alustus Test Setup
Testin Alasajo Test Teardown
Testin Malli Test Template
Testin Aikaraja 1 minute
Testin Tagit test tags
Avainsanan Tagit keyword tags
Kirjasto OperatingSystem
Resurssi ../finnish/resource.resource
Muuttujat ../../variables.py
*** Muuttujat ***
${VARIABLE} variable value
*** Testit ***
Test without settings
Nothing to see here
*** Avainsanat ***
Suite Setup
Directory Should Exist ${CURDIR}
对应地,atest/robot/parsing/translations.robot 中的 Validate Translations 关键字断言了这些芬兰语设置最终解析出的套件名、文档、元数据、Setup/Teardown、标签与超时值都与英文语义等价。
内置语言与自定义语言
5.1 beta 1 中,除默认的英语外,内置支持以下语言:
| 语言 | 代码 |
|---|---|
| 波斯尼亚语 | BS |
| 捷克语 | CS |
| 荷兰语 | NL |
| 芬兰语 | FI |
| 法语 | FR |
| 德语 | DE |
| 波兰语 | PL |
| 葡萄牙语 / 巴西葡萄牙语 | PT / PT-BR |
| 俄语 | RU |
| 简体中文 | ZH-CN |
| 西班牙语 | ES |
| 泰语 | TH |
| 乌克兰语 | UK |
这些翻译全部由社区贡献,协作平台为 Crowdin。当前仓库中的 src/robot/conf/languages.py 已经演进到包含更多语言(如意大利语、印地语、日语、韩语、繁体中文、土耳其语等,见 src/robot/conf/languages.py 起的各类),说明 5.1 后续版本持续扩充了语言支持。
自定义语言的实现原理:自定义语言本质上是一个 Python 模块,模块内定义一个或多个继承 Language 基类的类(见 src/robot/conf/languages.py)。Language 基类声明了全部可翻译的类属性:
- 各表格头:
settings_header、variables_header、test_cases_header、tasks_header、keywords_header、comments_header; - 各设置项:
library_setting、resource_setting、documentation_setting、metadata_setting、suite_setup_setting、test_setup_setting、test_tags_setting、task_tags_setting、keyword_tags_setting等; - BDD 前缀:
given_prefixes、when_prefixes、then_prefixes、and_prefixes、but_prefixes; - 布尔字符串:
true_strings、false_strings。
语言代码根据类名自动推导(src/robot/conf/languages.py):若类名为两个或更少字符则全小写作为代码,否则形如 pt-BR——取前两个字符小写、连字符、其余大写。语言名称取自类 docstring 的第一行(src/robot/conf/languages.py)。Language.from_name(src/robot/conf/languages.py)在解析 --language Finnish、--language fi 这类输入时,对名称做大小写、空格和连字符无关的归一化匹配——这也解释了验收测试中 --language fin-nish 能命中 Finnish 的原因。
Languages 类(src/robot/conf/languages.py)负责合并多个语言:_add_language 会把各语言的表头、设置、BDD 前缀、真/假字符串统一合并进 headers、settings、bdd_prefixes、true_strings、false_strings 字典/集合,并默认自动附加英语(add_english=True)。其中 bdd_prefix_regexp 属性(src/robot/conf/languages.py)把收集到的前缀编译成正则 (prefix1|prefix2)\s,并注明匹配不区分大小写——这与下文"BDD 前缀后必须跟空格"的破坏性变更直接相关。加载自定义语言模块由 Importer 完成,模块中所有 Language 的子类都会被实例化(src/robot/conf/languages.py)。
关键字与测试标签设置增强
5.1 对标签(Tags)设置体系做了一次重要重构,使"测试标签"与"关键字标签"的语义彻底分离。
新增 Keyword Tags 设置(#4373)
此前只能给测试用例设置标签,5.1 新增了 Keyword Tags 设置,可以为某个文件中的所有关键字统一设置标签。它可用于资源文件(resource file),也可用于测试用例文件和套件初始化文件(__init__.robot)。当用于初始化文件时,它只影响该文件内的关键字,不会向下传播到更低层级的套件。
*** Settings ***
Keyword Tags smoke regression
*** Keywords ***
My Keyword
Log message
Force Tags 更名为 Test Tags(#4368)
Force Tags 设置被更名为 Test Tags。更名的动机是让与测试相关的设置命名保持一致(Test Setup、Test Timeout、Test Tags……),并更好地与关键字标签设置区分开;一致的命名也方便翻译。旧名称 Force Tags 仍然可用,但将来会被弃用。当创建任务(Task,RPA 场景)时,可以使用 Task Tags 别名代替 Test Tags。
从词法层源码可以看到别名映射关系,src/robot/parsing/lexer/settings.py 中 Force Tags 与 Task Tags 都被归一化到 Test Tags,而 Keyword Tags 是独立条目;_lex_setting(src/robot/parsing/lexer/settings.py)把 Test Tags 映射为专门的 Token.TEST_TAGS 类型。解析模型层面,src/robot/parsing/model/statements.py 为 Test Tags、Default Tags、Keyword Tags 分别定义了语句类,说明它们在语法树中是不同的实体。各语言翻译中也统一出现了 test_tags_setting、task_tags_setting、keyword_tags_setting 三组属性(见 src/robot/conf/languages.py),印证了这一设计。
Default Tags 弃用与未来的 -tag 语法(#4374)
Default Tags 设置也将被弃用。它提供的"给部分而非全部测试设置标签"的功能,未来将通过配合 [Tags] 设置的 -tag 语法实现——用带连字符的标签表示"该测试不应获得标签 tag"。这一语法将来也能与新的 Keyword Tags 组合使用。因此,从 5.1 起,在 [Tags] 设置中使用以连字符开头的标签已开始被弃用(#4380);若确实需要字面量 -tag,可使用转义形式 \-tag。
关键字命名空间增强
私有关键字:robot:private 标签(#430)
现在可以在资源文件中给关键字添加 robot:private 标签,将其标记为私有:
*** Keywords ***
Internal Helper
[Tags] robot:private
Log This is private
如果该关键字被资源文件之外的关键字调用,运行时会发出警告;这类关键字还会被 Libdoc 生成的 HTML 库文档排除。实现上,src/robot/running/keywordimplementation.py 通过 self.tags.robot('private') 判断关键字是否私有;调用时 src/robot/running/context.py 的 warn_on_invalid_private_call 会比较调用方(父关键字)与私有关键字是否来自同一文件,否则发出警告 Keyword '...' is private and should only be called by keywords in the same file.;而 src/robot/running/namespace.py 的 _prioritize_same_file_or_public 在解析关键字时会优先选择同文件关键字,其次过滤掉私有关键字,从而保证命名解析的确定性。
robot: 前缀在框架中属于保留标签机制:Tags.robot() 方法(src/robot/model/tags.py)可以快速判断标签集合中是否包含 robot:<name> 形式的保留标签,其实现(src/robot/model/tags.py)在初始化时就把所有 robot: 开头的标签剥离前缀后存入 _reserved 元组——stop-on-failure、continue-on-failure 等保留标签也走同一套机制。
本地关键字优先于导入关键字(#4366)
如果某个资源文件中的关键字调用了另一个关键字,而调用方所在资源文件内部也存在同名关键字,那么将优先使用同文件内的本地关键字;此前这种情况会引发冲突。_prioritize_same_file_or_public(src/robot/running/namespace.py)正是这一逻辑的实现:它取出当前执行上下文中正在运行的父关键字(EXECUTION_CONTEXTS.current.user_keywords),比较 source 路径进行匹配。
一个正在被弃用的旧行为
如果关键字存在于调用方所在的资源文件中,但测试用例文件里存在同名关键字,那么测试用例文件中的关键字仍会像以前一样被优先使用。这一行为如今已被弃用:未来版本中,本地关键字将同样在这些场景下获得最高优先级。
按需禁用 continue-on-failure 模式
Robot Framework 通常在一个失败发生后停止执行关键字或测试用例,例外包括 Teardown、模板(template),以及显式启用了 continue-on-failure 模式的场景。此前该模式只能通过 robot:continue-on-failure 和 robot:recursive-continue-on-failure 标签开启;5.1 新增了对称的关闭能力(#4303):
robot:stop-on-failure:在当前层级禁用隐式或显式的 continue-on-failure 模式;robot:recursive-stop-on-failure:递归地在所有嵌套层级禁用。
这些标签的优先级逻辑在 src/robot/running/context.py 的 continue_on_failure() 方法中实现:它从当前执行栈(self.steps)逆向遍历父级关键字与测试用例,按顺序检查 stop-on-failure、continue-on-failure、recursive-stop-on-failure、recursive-continue-on-failure 四类保留标签,命中即返回对应布尔值。这也说明该机制天然支持"在某层关键字上递归关闭、在更深层再递归打开"这类精细控制。此外,发布说明中明确:即使 continue-on-failure 模式处于激活状态,失败的测试 Setup 仍会停止执行(#4404)。
监听器 API v2:控制结构获得更多上下文信息
使用监听器 API v2 时,start_keyword 和 end_keyword 方法不只用于关键字,也用于所有控制结构(如 IF、FOR、WHILE、TRY/EXCEPT 等)。此前这些方法收到的信息完全相同,5.1 起控制结构会附带更多上下文专属细节(#4335)。
这些附加属性的类型定义在 src/robot/api/interfaces.py 的 OptionalKeywordAttributes 中,其注释明确说明"这些属性随控制结构附带,例如 IF 结构包含 condition":
FOR/ITERATION:variables、flavor、values(RETURN也用values);WHILE和IF:condition;WHILE:limit;EXCEPT:patterns、pattern_type、variable。
基础的 StartKeywordAttributes(src/robot/api/interfaces.py)包含 type、kwname、libname、doc、args、assign、tags、source、lineno、status、starttime 等字段;EndKeywordAttributes(src/robot/api/interfaces.py)在基础上追加 endtime 与 elapsedtime。监听器方法签名见 src/robot/api/interfaces.py。
执行性能与 Python 版本支持
用户关键字执行性能提升(#4388、#4353)
5.1 降低了执行用户关键字(user keyword)时的开销,尤其是失败频繁的场景收益明显,例如使用 Wait Until Keyword Succeeds 或在 TRY/EXCEPT 循环中反复失败的情况。这得益于对执行路径的热点优化,相关解析性能也有提升。
Python 3.11 支持与 Python 3.6 弃用(#4401、#4295)
Robot Framework 5.1 官方支持即将发布的 Python 3.11;由于不兼容点不多,较早的 Python 版本也能正常工作。另一端,Python 3.6 已被弃用——5.1 及所有未来的 5.x 版本仍支持它,但 Robot Framework 6.0 将不再支持,建议用户尽早升级到更新的 Python 版本(Python 3.6 已于 2021 年 12 月停止维护)。
破坏性变更清单
升级到 5.1 需要留意以下行为变化:
- BDD 前缀后必须有空格(
#4379):Given/When/Then等前缀与关键字名之间必须有空格。这与bdd_prefix_regexp(src/robot/conf/languages.py)编译出的(prefixes)\s正则一致——前缀后必须紧跟空白字符才被识别为 BDD 前缀。 - Collections 库的字典关键字要求字典继承
Mapping(#4413):对传入值的类型校验更加严格。 Dictionary Should Contain Item不再预先将值转换为字符串再比较(#4408):值比较现在基于原始类型语义进行。- 嵌入式参数(embedded arguments)以变量传递时,变量值必须匹配自定义正则(
#4069):当使用嵌入式参数的关键字以变量方式传参时,变量值会与可能的自定义正则表达式进行匹配,不匹配将导致失败——这是比之前更严格的行为。 - Libdoc 生成的 XML/JSON 规格文件中"生成时间"格式变更(
#4262):统一为2022-05-27T19:07:15+00:00这种带时区的 ISO 8601 格式。此前 XML 规格使用2022-05-27T19:07:15Z(等价新格式),而 JSON 规格完全不包含时区信息。同时,该版本支持通过SOURCE_DATE_EPOCH环境变量生成可复现的(确定性)库文档——src/robot/libdocpkg/output.py 的get_generation_time()会优先读取该环境变量作为时间戳,并输出带 UTC 时区的 ISO 格式。
弃用项汇总
Force Tags与Default Tags设置(#4368):仍可用但已弃用,5.1 暂不产生可见的弃用警告,从 Robot Framework 6.0 开始将发出警告并最终移除;[Tags]设置中以连字符开头的标签(-tag)也已弃用(#4380),如需字面量请用\-tag。- 测试用例文件关键字优先于资源文件本地关键字(
#4366):当前行为保留但已弃用,未来本地关键字将始终拥有最高优先级。 WITH NAME让位于AS(#4371):给导入的库起别名时,WITH NAME将被重命名为AS,与 Python 的as保持一致,也与TRY/EXCEPT中已有的AS复用同一标记、简化语法、减轻翻译负担。5.1 中两者都可用,WITH NAME已弃用(6.0 起才会有可见警告)。词法层 src/robot/parsing/lexer/settings.py 和内置库实现 src/robot/libraries/BuiltIn.py 都已同时接受WITH NAME与AS。- 单数段落头(如
Test Case)(#4431):此前Test Cases与Test Case两种写法都被接受,现在单数形式已弃用,未来将移除支持;预计同样从 6.0 开始产生可见警告。 - Python 3.6(
#4295):5.x 仍支持,6.0 不再支持。
完整修复与增强列表
5.1 里程碑共包含 42 个 issue,下表按优先级整理了发布说明中的完整清单:
| ID | 类型 | 优先级 | 摘要 |
|---|---|---|---|
#4096 |
enhancement | critical | 数据中标记的多语言支持 |
#519 |
enhancement | critical | Given/When/Then 支持英语以外的语言 |
#4295 |
enhancement | high | 弃用 Python 3.6 |
#430 |
enhancement | high | 资源文件关键字可见性修饰符 |
#4303 |
enhancement | high | 用 robot:stop-on-failure / robot:recursive-stop-on-failure 禁用 continue-on-failure |
#4335 |
enhancement | high | 向 start/end_keyword 监听器方法传递更多控制结构信息 |
#4366 |
enhancement | high | 资源文件中本地关键字优先于导入关键字 |
#4368 |
enhancement | high | 新增 Test Tags 作为 Force Tags 的别名 |
#4373 |
enhancement | high | 用 Keyword Tags 设置为所有关键字添加标签 |
#4380 |
enhancement | high | 弃用 [Tags] 设置中以连字符开头的标签 |
#4388 |
enhancement | high | 提升用户关键字(尤其失败场景)的执行性能 |
#4400 |
enhancement | high | 允许翻译布尔参数转换中的 True/False 单词 |
#4401 |
enhancement | high | Python 3.11 兼容 |
#4351 |
bug | medium | Libdoc 在库参数扩展名匹配资源文件时给出错误提示 |
#4355 |
bug | medium | 可继续的失败会终止 WHILE 循环 |
#4357 |
bug | medium | 解析模型:无法用 from_params 创建 TRY / WHILE 语句 |
#4359 |
bug | medium | 解析模型:Variable.from_params 未正确处理列表值 |
#4364 |
bug | medium | @{list} 作为嵌入式参数在关键字接受 varargs 时不再展开 |
#4381 |
bug | medium | 解析错误被识别为 EmptyLines |
#4384 |
bug | medium | RPA 设置别名在套件初始化文件中不生效 |
#4387 |
bug | medium | Libdoc:修复已弃用关键字信息写入规格文件 |
#4408 |
bug | medium | Collections:Dictionary Should Contain Item 错误地在比较前将值转字符串 |
#4418 |
bug | medium | YAML 变量文件中列表内的字典未转换为 DotDict |
#4447 |
bug | medium | 求值修改求值命名空间(locals)的表达式会失败 |
#4069 |
enhancement | medium | 作为嵌入式参数的变量未与正则表达式匹配 |
#4262 |
enhancement | medium | 生成库文档时遵循 SOURCE_DATE_EPOCH 环境变量 |
#4312 |
enhancement | medium | 向 PyPI 添加项目 URL |
#4353 |
enhancement | medium | 解析性能增强 |
#4354 |
enhancement | medium | Rebot 合并套件时复制合并套件的文档与元数据 |
#4371 |
enhancement | medium | 库导入中新增 AS 作为 WITH NAME 的别名 |
#4379 |
enhancement | medium | 要求 Given/When/Then 前缀后有空格 |
#4398 |
enhancement | medium | Collections:Get From Dictionary 接受默认值 |
#4404 |
enhancement | medium | 文档化"即使 continue-on-failure 激活,失败的测试 Setup 也停止执行" |
#4413 |
enhancement | medium | Collections 字典相关关键字对接受值更严格 |
#4429 |
enhancement | medium | 允许为正则相关关键字传递显式 flags 参数 |
#4431 |
enhancement | medium | 弃用单数段落头 |
#4440 |
enhancement | medium | 允许将 None 用作自定义参数转换器以启用严格类型校验 |
#4349 |
bug | low | 用户指南:YAML 变量文件示例有误 |
#4358 |
bug | low | 用户指南:TRY/EXCEPT 示例错误 |
#4346 |
enhancement | low | 增强 --timestampoutputs 选项文档 |
#4372 |
enhancement | low | 文档化如何导入打包在 Python 包中的资源文件 |
#4394 |
bug | --- | --doc 或 --metadata 值匹配到已存在目录时报错 |
升级建议小结
- 若你的团队需要非英语数据文件,5.1 的
--language与language:语法已可投入使用;请始终在命令行指定语言,避免依赖"按文件配置会外溢"这一不稳定的技术限制。 - 关注标签设置的迁移:新项目直接用
Test Tags/Task Tags/Keyword Tags,避免使用Force Tags、Default Tags及[Tags]中以连字符开头的标签。 - 利用
robot:private将资源文件内部实现细节封装起来,并借助"本地关键字优先"规则收敛命名冲突。 - 需要临时关闭 continue-on-failure 时,用
robot:stop-on-failure/robot:recursive-stop-on-failure标签实现精确控制。 - 留意破坏性变更:BDD 前缀空格、Collections 字典行为、嵌入式参数正则匹配、Libdoc 时间格式等,按上文清单逐一排查存量套件。