Robot Framework 新版教程 - 输出文件
(Robot Framework 7.x 教程, Part 17)
输出文件
测试执行时会创建多个输出文件，它们都以某种方式与测试结果相关。本节讨论会创建哪些输出文件、如何配置它们的创建位置，以及如何调整它们的内容。
不同的输出文件
本节解释可以创建哪些不同的输出文件，以及如何配置它们的创建位置。输出文件通过命令行选项配置，这些选项以相关输出文件的路径作为参数。特殊值 NONE（不区分大小写）可用于禁止创建某个输出文件。
输出目录
所有输出文件都可以使用绝对路径来设置，在这种情况下它们将创建在指定位置；其他情况下，路径被视为相对于输出目录的相对路径。默认的输出目录是执行启动时所在的目录，但可以通过 --outputdir (-d) 选项来修改。该选项设置的路径同样是相对于执行目录的，当然也可以给定绝对路径。无论单个输出文件的路径如何获得，如果其父目录不存在，都会自动创建。
输出文件（Output file）
输出文件以机器可读的 XML 或 JSON 格式包含所有执行结果。日志文件、报告文件和 xUnit 文件通常基于输出文件生成，它们还可以通过 Rebot 进行合并和其他后处理。各种外部工具也会处理输出文件以便展示详细的执行信息。
提示： 在测试执行过程中生成报告文件和 xUnit 文件不需要在执行后处理输出文件。因此，运行测试时禁用日志文件生成可以节省内存。
命令行选项 --output (-o) 决定输出文件的创建路径。该路径相对于输出目录，执行测试时的默认值为 output.xml。使用 Rebot 后处理输出时，除非显式使用 --output 选项，否则不会创建新的输出文件。
可以通过对 --output 选项使用特殊值 NONE 来禁用输出文件。如果不需要任何输出，应使用 --output NONE --report NONE --log NONE 显式禁用所有输出。
XML 输出格式
输出文件默认使用 XML 格式创建。XML 输出格式在 result.xsd schema 文件中有文档说明。
JSON 输出格式
Robot Framework 也支持 JSON 输出，如果输出文件扩展名为 .json，将自动使用该格式。JSON 输出格式在 result.json schema 文件中有文档说明。
注意： 从 Robot Framework 7.2 开始，执行期间支持 JSON 输出文件。Rebot 从 Robot Framework 7.0 起就可以基于 XML 输出文件创建 JSON 输出文件。
旧版 XML 格式
Robot Framework 7.0 对 XML 输出文件格式进行了一些不向后兼容的更改。为了使新版 Robot Framework 能够与尚未更新以支持新格式的外部工具配合使用，提供了 --legacyoutput 选项，该选项生成与 Robot Framework 6.x 及更早版本兼容的输出文件。Robot Framework 本身可以处理旧格式和新格式的输出文件。
我们希望外部工具能够尽快更新，但我们计划至少在 Robot Framework 8.0 之前继续支持此选项。如果你遇到不兼容的工具，请通知工具开发者相关更改。
日志文件
日志文件以 HTML 格式包含已执行测试用例的详细信息。它们具有层级结构，展示测试套件、测试用例和关键字的详细信息。在需要详细调查测试结果时，几乎总是需要日志文件。尽管日志文件也包含统计信息，但报告文件更适合获取更高层次的概览。
命令行选项 --log (-l) 决定日志文件的创建位置。除非使用特殊值 NONE，否则日志文件总是会被创建，其默认名称为 log.html。
报告文件
报告文件以 HTML 格式包含测试执行结果的概览。它们包含基于 tag 和已执行测试套件的统计信息，以及所有已执行测试用例的列表。当同时生成报告和日志时，报告中包含指向日志文件的链接，便于导航到更详细的信息。从报告中可以轻松查看整体的测试执行状态，因为当所有测试通过时其背景色为绿色，而当任何测试失败时为亮红色。背景色也可能是黄色，这表示所有测试都被跳过了。
命令行选项 --report (-r) 决定报告文件的创建位置。与日志文件类似，除非使用 NONE 作为值，否则报告文件总是会被创建，其默认名称为 report.html。
xUnit 兼容结果文件
xUnit 结果文件以 xUnit 兼容的 XML 格式包含测试执行摘要。因此这些文件可以作为能理解 xUnit 报告的外部工具的输入。例如，Jenkins 持续集成服务器支持基于 xUnit 兼容结果生成统计信息。
提示： Jenkins 还有一个单独的 Robot Framework 插件。
除非显式使用命令行选项 --xunit (-x)，否则不会创建 xUnit 输出文件。该选项需要一个相对于输出目录的生成 xUnit 文件路径作为值。
xUnit 输出文件在 Robot Framework 5.0 中进行了大幅修改。它们现在为每个套件包含单独的 <testsuite> 元素，<testsuite> 元素具有 timestamp 属性，并且套件文档和元数据以 <property> 元素存储。
调试文件
调试文件是在测试执行过程中写入的纯文本文件。从测试库获得的所有消息都会写入其中，同时还包括关于已启动和已结束的测试套件、测试用例和关键字的信息。调试文件可用于监控测试执行。可以使用例如单独的 fileviewer.py 工具来实现这一点，或者在类 UNIX 系统中，简单地使用 tail -f 命令即可。
除非显式使用命令行选项 --debugfile (-b)，否则不会创建调试文件。
为输出文件添加时间戳
所有由 Robot Framework 自身生成的输出文件都可以通过 --timestampoutputs (-T) 选项自动添加时间戳。使用此选项时，格式为 YYYYMMDD-hhmmss 的时间戳会放置在每个文件的扩展名和基本名称之间。例如，下面的命令会创建类似 output-20080604-163225.xml 和 mylog-20080604-163225.html 这样的输出文件：
robot --timestampoutputs --log mylog.html --report NONE tests.robot
设置标题
日志文件和报告文件的默认标题是通过在顶层测试套件的名称前加上 Test Log 或 Test Report 来生成的。可以通过命令行选项 --logtitle 和 --reporttitle 分别指定自定义标题。
示例：
robot --logtitle "Smoke Test Log" --reporttitle "Smoke Test Report" --include smoke my_tests/
注意： 在 Robot Framework 3.1 之前，给定标题中的下划线会被转换为空格。现在需要像上面的示例一样对空格进行转义或加引号。
设置背景颜色
默认情况下，报告文件在有失败时显示红色背景，在有通过测试（可能还有一些被跳过的测试）时显示绿色背景，在所有测试被跳过或没有运行任何测试时显示黄色背景。可以使用 --reportbackground 命令行选项来自定义这些颜色，该选项接受两个或三个以冒号分隔的颜色作为参数：
--reportbackground blue:red
--reportbackground blue:red:orange
--reportbackground #00E:#E00
如果指定两种颜色，第一种将替代默认的绿色（通过）颜色，第二种替代默认的红色（失败）颜色。例如，这允许使用蓝色替代绿色，以便色盲人群更容易区分背景颜色。
如果指定三种颜色，前两种的含义与之前相同，最后一种替代默认的黄色（跳过）颜色。
指定的颜色用作 body 元素的 background CSS 属性的值。该值按原样使用，可以是 HTML 颜色名称（如 red）、十六进制值（如 #f00 或 #ff0000）或 RGB 值（如 rgb(255,0,0)）。默认的绿色、红色和黄色分别使用十六进制值 #9e9、#f66 和 #fed84f 指定。
日志级别
可用的日志级别
日志文件中的消息可以具有不同的日志级别。一些消息由 Robot Framework 自身写入，但已执行的关键字也可以使用不同级别记录信息。可用的日志级别有：
FAIL
: 当关键字失败时使用。只能由 Robot Framework 自身使用。
ERROR
: 用于显示错误。错误会显示在控制台以及日志文件的 Test Execution Errors 部分，但不会影响测试用例的状态。不过，如果启用了 --exitonerror 选项，错误将停止整个执行。
WARN
: 用于显示警告。警告会显示在控制台以及日志文件的 Test Execution Errors 部分，但不会影响测试用例的状态。
INFO
: 普通消息的默认级别。默认情况下，低于此级别的消息不会在日志文件中显示。
DEBUG
: 用于调试目的。例如，在记录库内部行为时很有用。当关键字失败时，会自动使用此级别记录一个 traceback，显示代码中发生故障的位置。
TRACE
: 更详细的调试级别。关键字参数和返回值会自动使用此级别记录。
设置日志级别
默认情况下，低于 INFO 级别的日志消息不会被记录，但可以通过命令行选项 --loglevel (-L) 来更改此阈值。该选项接受任何可用的日志级别作为参数，该级别将成为新的阈值级别。也可以使用特殊值 NONE 来完全禁用日志记录。
也可以在使用 Rebot 后处理输出时使用 --loglevel 选项。例如，这允许先以 TRACE 级别运行测试，之后再以 INFO 级别生成更小的日志文件用于日常查看。默认情况下，执行期间包含的所有消息在使用 Rebot 时也会包含。执行期间被忽略的消息无法恢复。
另一种更改日志级别的方式是在测试数据中使用 BuiltIn 关键字 Set Log Level。它接受与 --loglevel 选项相同的参数，并且返回旧的级别，以便之后可以恢复它，例如在 test teardown 中。
可见日志级别
如果日志文件包含 DEBUG 或 TRACE 级别的消息，右上角会显示一个可见日志级别下拉菜单。这允许用户从视图中移除低于所选级别的消息。在以 TRACE 级别运行测试时，这特别有用。
默认情况下，下拉菜单将设置为日志文件中的最低级别，以便显示所有消息。可以通过 --loglevel 选项更改默认的可见日志级别，方法是在正常日志级别之后用冒号分隔给出默认值：
--loglevel DEBUG:INFO
在上面的示例中，测试以 DEBUG 级别运行，但日志文件中的默认可见级别为 INFO。
拆分日志
通常日志文件只是一个单独的 HTML 文件。当测试用例数量增加时，文件大小可能会增长到在浏览器中打开不方便甚至无法打开的程度。因此，可以使用 --splitlog 选项将日志的部分内容拆分到外部文件中，这些文件在需要时会透明地加载到浏览器中。
拆分日志的主要好处是各个日志部分足够小，即使测试数据量非常大，打开和浏览日志文件也是可能的。一个小缺点是日志文件占用的总体大小会增加。
从技术上讲，与每个测试用例相关的测试数据会保存到与主日志文件相同文件夹中的 JavaScript 文件中。这些文件的名称类似于 log-42.js，其中 log 是主日志文件的基本名称，42 是递增的索引。
JavaScript 文件保存到与日志文件本身相同的目录中。默认是公共的输出目录，但可以通过 --log 命令行选项更改。
注意： 复制日志文件时，需要同时复制所有
log-*.js文件，否则部分信息将缺失。
配置统计信息
有多个命令行选项可用于配置和调整不同输出文件中 Statistics by Tag、Statistics by Suite 和 Test Details by Tag 表格的内容。所有这些选项在执行测试用例和后处理输出时都有效。
配置显示的套件统计
当执行较深的套件结构时，在 Statistics by Suite 表格中显示所有测试套件层级可能会使表格难以阅读。默认情况下显示所有套件，但可以通过命令行选项 --suitestatlevel 控制，该选项接受要显示的套件层级作为参数：
--suitestatlevel 3
包含和排除 tag 统计
当使用很多 tag 时，Statistics by Tag 表格可能会变得相当拥挤。如果发生这种情况，可以使用命令行选项 --tagstatinclude 和 --tagstatexclude 来选择显示哪些 tag，用法类似于 --include 和 --exclude 用于选择测试用例：
--tagstatinclude some-tag --tagstatinclude another-tag
--tagstatexclude owner-*
--tagstatinclude prefix-* --tagstatexclude prefix-13
生成组合 tag 统计
命令行选项 --tagstatcombine 可用于生成将多个 tag 的统计信息合并在一起的聚合 tag。组合 tag 使用 tag 模式指定，其中 * 和 ? 作为通配符，AND、OR 和 NOT 运算符可用于将单个 tag 或模式组合在一起。
以下示例展示了使用不同模式创建组合 tag 统计，下图显示了结果 Statistics by Tag 表格的一个片段：
--tagstatcombine owner-*
--tagstatcombine smokeANDmytag
--tagstatcombine smokeNOTowner-janne*
如上例所示，添加的组合统计的名称默认只是给定的模式。如果这不够好，可以在模式之后用冒号（:）分隔给出自定义名称：
--tagstatcombine "prio1ORprio2:High priority tests"
注意： 在 Robot Framework 3.1 之前，自定义名称中的下划线会被转换为空格。现在需要像上面的示例一样对空格进行转义或加引号。
从 tag 名称创建链接
可以通过使用命令行选项 --tagstatlink 向 Statistics by Tag 表格添加外部链接。该选项的参数格式为 tag:link:name，其中 tag 指定要分配链接的 tag，link 是要创建的链接，name 是给链接指定的名称。
tag 可以是单个 tag，但更常见的是简单模式，其中 * 匹配任意内容，? 匹配任意单个字符。当 tag 是模式时，通配符的匹配结果可以在 link 和 title 中使用语法 %N，其中 "N" 是从 1 开始的匹配索引。
以下示例展示了此选项的用法，下图显示了使用这些选项执行示例测试数据时，结果 Statistics by Tag 表格的一个片段：
--tagstatlink mytag:http://www.google.com:Google
--tagstatlink example-bug-*:http://example.com
--tagstatlink owner-*:mailto:%1@domain.com?subject=Acceptance_Tests:Send_Mail
为 tag 添加文档
可以通过命令行选项 --tagdoc 为 tag 指定文档，该选项接受格式为 tag:doc 的参数。tag 是要分配文档的 tag 名称，也可以是匹配多个 tag 的简单模式。doc 是分配的文档内容。
给定的文档在 Test Details by Tag 表格中与匹配的 tag 一起显示，并在 Statistics by Tag 表格中作为这些 tag 的工具提示显示。如果一个 tag 获得多个文档，它们会组合在一起并以 & 符号分隔。
示例：
--tagdoc mytag:Example
--tagdoc "regression:See http://example.com/info.html"
--tagdoc "owner-*:Original author"
注意： 在 Robot Framework 3.1 之前，文档中的下划线会被转换为空格。现在需要像上面的示例一样对空格进行转义或加引号。
移除和扁平化关键字
输出文件的大部分内容来自关键字及其日志消息。在创建更高层次的报告时，日志文件可能根本不需要，在这种情况下关键字及其消息只是不必要地占用空间。日志文件本身也可能变得过大，特别是当它们包含 FOR 循环或其他重复执行某些关键字的结构时。
在这些情况下，可以使用命令行选项 --removekeywords 和 --flattenkeywords 来处置或扁平化不必要的关键字。它们可以在执行测试用例时和后处理输出时使用。在执行期间使用时，它们只影响日志文件，不影响 XML 输出文件。使用 rebot 时，它们同时影响日志和可能生成的新输出 XML 文件。
移除关键字
--removekeywords 选项完全移除关键字及其消息。它具有以下操作模式，可以多次使用以启用多种模式。包含错误或警告的关键字不会被移除，除非使用 ALL 模式。
ALL
: 无条件地从所有关键字中移除数据。
PASSED
: 从通过的测试用例中移除关键字数据。在大多数情况下，使用此选项创建的日志文件包含足够的信息来调查可能的失败。
FOR
: 从 FOR 循环中移除除最后一次外的所有通过的迭代。
WHILE
: 从 WHILE 循环中移除除最后一次外的所有通过的迭代。
WUKS
: 移除 BuiltIn 关键字 Wait Until Keyword Succeeds 内部除最后一个外的所有失败关键字。
NAME:<pattern>
: 无论关键字状态如何，从所有匹配给定模式的关键字中移除数据。模式与关键字的完整名称匹配，包含可能的库或资源文件名前缀，如 MyLibrary.Keyword Name。模式不区分大小写、空格和下划线，并且支持使用 *、? 和 [] 作为通配符的简单模式。
TAG:<pattern>
: 从 tag 匹配给定模式的关键字中移除数据。tag 不区分大小写和空格，可以使用 tag 模式指定，其中 *、? 和 [] 作为通配符，AND、OR 和 NOT 运算符可用于将单个 tag 或模式组合在一起。可以同时用于库关键字 tag 和用户关键字 tag。
示例：
rebot --removekeywords all --output removed.xml output.xml
robot --removekeywords passed --removekeywords for tests.robot
robot --removekeywords name:HugeKeyword --removekeywords name:resource.* tests.robot
robot --removekeywords tag:huge tests.robot
移除关键字是在解析输出文件并基于它生成内部模型之后完成的。因此它不像扁平化关键字那样能有效减少内存使用。
扁平化关键字
--flattenkeywords 选项会扁平化匹配的关键字。实际上这意味着匹配的关键字会递归地获取其子关键字的所有日志消息，而子关键字本身则被丢弃。扁平化支持以下模式：
FOR
: 完全扁平化 FOR 循环。
WHILE
: 完全扁平化 WHILE 循环。
ITERATION
: 扁平化单个 FOR 和 WHILE 循环迭代。
FORITEM
: ITERATION 的已弃用别名。
NAME:<pattern>
: 扁平化匹配给定模式的关键字。模式匹配规则与使用 NAME:<pattern> 模式移除关键字时相同。
TAG:<pattern>
: 扁平化 tag 匹配给定模式的关键字。模式匹配规则与使用 TAG:<pattern> 模式移除关键字时相同。
示例：
robot --flattenkeywords name:HugeKeyword --flattenkeywords name:resource.* tests.robot
rebot --flattenkeywords foritem --output flattened.xml original.xml
扁平化关键字在输出文件最初被解析时就已完成。这可以节省大量内存，特别是对于深度嵌套的关键字结构。
在执行期间扁平化关键字
从 Robot Framework 6.1 开始，可以在执行期间启用关键字扁平化。这只能在用户关键字级别通过将保留 tag robot:flatten 定义为关键字 tag 来实现。使用此 tag 的效果与上一节描述的命令行选项类似，例如，具有该 tag 的关键字下方的所有内容（日志消息除外）都会被移除。一个重要区别是，在这种情况下，被移除的内容根本不会写入输出文件，因此之后无法访问。
*** Keywords ***
Example
[Tags] robot:flatten
Log 关键字和循环会被移除，但日志消息会被保留。
FOR ${i} IN RANGE 1 101
Log Iteration ${i}/100.
END
自动展开关键字
通过的关键字在日志文件中默认是折叠的。因此它们包含的信息在你展开之前是不可见的。如果某些关键字包含应在打开日志文件时就可见的重要信息，可以使用 --expandkeywords 选项将关键字设置为在日志文件中自动展开，类似于失败的关键字。展开支持以下模式：
NAME:<pattern>
: 展开匹配给定模式的关键字。模式匹配规则与使用 NAME:<pattern> 模式移除关键字时相同。
TAG:<pattern>
: 展开 tag 匹配给定模式的关键字。模式匹配规则与使用 TAG:<pattern> 模式移除关键字时相同。
如果需要展开匹配不同名称或模式的关键字，可以多次使用 --expandkeywords。
示例：
robot --expandkeywords name:SeleniumLibrary.CapturePageScreenshot tests.robot
rebot --expandkeywords tag:example --expandkeywords tag:another output.xml
注意：
--expandkeywords选项是 Robot Framework 3.2 中新增的。
设置执行的开始和结束时间
使用 Rebot 合并输出时，可以使用 --starttime 和 --endtime 选项分别设置合并后测试套件的开始和结束时间。这很方便，因为默认情况下合并的套件没有这些值。当同时给出开始和结束时间时，经过时间也会基于它们计算。否则，经过时间通过将子测试套件的经过时间相加来获得。
也可以在使用 Rebot 处理单个套件时使用上述选项设置开始和结束时间。对单个输出使用这些选项总是会影响套件的经过时间。
时间必须以 YYYY-MM-DD hh:mm:ss.mil 格式的时间戳给出，其中所有分隔符都是可选的，从毫秒到小时的部分都可以省略。例如，2008-06-11 17:59:20.495 等同于 20080611-175920.495 和 20080611175920495，单独的 20080611 也可以。
示例：
rebot --starttime 20080611-17:59:20.495 output1.xml output2.xml
rebot --starttime 20080611-175920 --endtime 20080611-180242 *.xml
rebot --starttime 20110302-1317 --endtime 20110302-11418 myoutput.xml
限制报告中的错误消息长度
如果测试用例失败并且错误消息很长，报告中显示的消息会自动从中间截断以保持报告的可读性。默认情况下超过 40 行的消息会被截断，但可以通过 --maxerrorlines 命令行选项来配置。该选项的最小值为 10，也可以使用特殊值 NONE 来显示完整消息。
完整的错误消息始终可以在日志文件中作为失败关键字的消息查看。
注意：
--maxerrorlines选项是 Robot Framework 3.1 中新增的。
以编程方式修改结果
如果提供的内置功能不足以修改结果，Robot Framework 允许以编程方式进行自定义修改。这通过创建一个模型修改器并使用 --prerebotmodifier 选项激活它来实现。
此功能的工作方式与可以通过 --prerunmodifier 选项启用的以编程方式修改测试数据几乎完全相同。明显的区别是，这次修改器操作的是结果模型，而不是运行模型。例如，以下修改器将所有执行时间超过允许时间的通过测试标记为失败：
from robot.api import SuiteVisitor
class ExecutionTimeChecker(SuiteVisitor):
def __init__(self, max_seconds: float):
self.max_milliseconds = max_seconds * 1000
def visit_test(self, test):
if test.status == 'PASS' and test.elapsedtime > self.max_milliseconds:
test.status = 'FAIL'
test.message = 'Test execution took too long.'
如果上述修改器保存在文件 ExecutionTimeChecker.py 中，可以如下使用：
# 运行测试时将修改器指定为路径。最大时间为 42 秒。
robot --prerebotmodifier path/to/ExecutionTimeChecker.py:42 tests.robot
# 使用 Rebot 时将修改器指定为名称。最大时间为 3.14 秒。
# ExecutionTimeChecker.py 必须在模块搜索路径中。
rebot --prerebotmodifier ExecutionTimeChecker:3.14 output.xml
如果需要多个模型修改器，可以多次使用 --prerebotmodifier 选项指定。执行测试时，可以同时使用 --prerunmodifier 和 --prerebotmodifier 选项。
系统日志
Robot Framework 有自己的纯文本系统日志，其中记录以下信息：
- 已处理和已跳过的测试数据文件
- 已导入的测试库、资源文件和变量文件
- 已执行的测试套件和测试用例
- 已创建的输出
通常用户不需要这些信息，但在调查测试库或 Robot Framework 自身的问题时可能很有用。默认不创建系统日志，但可以通过设置环境变量 ROBOT_SYSLOG_FILE 使其包含指向所选文件的路径来启用。
系统日志具有与普通日志文件相同的日志级别，但用 ERROR 级别替代了 FAIL。阈值级别可以使用 ROBOT_SYSLOG_LEVEL 环境变量更改，如下例所示。意外的错误和警告除了写入控制台和普通日志文件外，还会写入系统日志。
#!/bin/bash
export ROBOT_SYSLOG_FILE=/tmp/syslog.txt
export ROBOT_SYSLOG_LEVEL=DEBUG
robot --name Syslog_example path/to/tests