Robot Framework（十八） 支持工具

5支持工具

5.1库文档工具（libdoc）

libdoc是一种用于为HTML和XML格式的测试库和资源文件生成关键字文档的工具。前一种格式适用于人类，后者适用于RIDE和其他工具。Libdoc也没有很少的特殊命令来显示控制台上的库或资源信息。

可以创建文档：

• 使用普通静态库API 用Python或Java实现的测试库，
• 使用动态API测试库，包括远程库和
• 资源文件。

此外，可以使用 之前由libdoc创建的XML规范作为输入。

libdoc内置于Robot Framework中，并自2.7版开始自动包含在安装中。对于早期版本，您需要单独下载libdoc.py脚本。这些版本之间的命令行用法略有变化，但文档语法仍然相同。

5.1.1一般用法

概要

python -m robot.libdoc [options] library_or_resource output_file
python -m robot.libdoc [options] library_or_resource list|show|version [names]

选项

-f, --format <html|xml>
	指定是否生成HTML或XML输出。如果未使用此选项，则从输出文件的扩展名获取格式。
-N, --name <newname>
	设置记录的库或资源的名称。
-V, --version <newversion>
	设置记录的库或资源的版本。
-P, --pythonpath <path>
	与运行测试时类似的搜索库和资源的其他位置。
-E, --escape <what:with>
	转义在控制台中有问题的字符。 要转义的字符的名称是什么，with是用它来转义它的字符串。可用的转义列在--help 输出中。
-h, --help	打印此帮助。

指定库或资源文件

Python库和带有名称或路径的动态库

在记录使用Python实现的库或使用动态库API的库时，可以通过仅使用库名称或库源代码的路径来指定库。在前一种情况下，使用库搜索路径搜索库 ，其名称必须与Robot Framework测试数据中的格式相同。

如果这些库在导入时需要参数，则必须使用两个冒号（如MyLibrary :: arg1 :: arg2）将参数与库名称或路径连接起来 。如果参数更改了库提供的关键字或以其他方式更改其文档，那么使用 --name选项也可以相应地更改库名称。

带有路径的Java库

可以通过提供包含库实现的源代码文件的路径来指定使用普通库API实现的Java测试库。此外，必须在执行libdoc时从CLASSPATH中找到tools.jar，它是Java JDK发行版的一部分 。请注意，生成Java库的文档仅适用于Jython。

带路径的资源文件

必须始终使用路径指定资源文件。如果路径不存在，则与执行测试用例时类似，也会从PYTHONPATH中的所有目录中搜索资源文件。

创建文档

在以HTML或XML格式创建文档时，必须将输出文件指定为库/资源名称或路径之后的第二个参数。输出格式从扩展名自动获取，但也可以使用--format选项设置。

例子：

python -m robot.libdoc OperatingSystem OperatingSystem.html
python -m robot.libdoc --name MyLibrary Remote::http://10.0.0.42:8270 MyLibrary.html
python -m robot.libdoc test/resource.html doc/resource_doc.html
jython -m robot.libdoc --version 1.0 MyJavaLibrary.java MyJavaLibrary.xml

在控制台上查看信息

libdoc有三个特殊命令来显示控制台上的信息。使用这些命令代替输出文件的名称，它们也可以使用其他参数。

名单

列出库/资源包含的关键字的名称。可以限制为通过将可选模式作为参数传递来仅显示某些关键字。如果其名称包含给定模式，则列出关键字。

节目

显示库/资源文档。可以限制为通过将名称作为参数传递来仅显示某些关键字。如果其名称与任何给定名称匹配，则显示关键字。特殊参数介绍将仅显示库介绍和导入部分。

版

显示库版本

列表和显示的可选模式是大小写和空间不敏感的。两者都接受*和？作为通配符。

例子：

python -m robot.libdoc Dialogs list
python -m robot.libdoc Selenium2Library list browser
python -m robot.libdoc Remote::10.0.0.42:8270 show
python -m robot.libdoc Dialogs show PauseExecution execute*
python -m robot.libdoc Selenium2Library show intro
python -m robot.libdoc Selenium2Library version

替代执行

尽管libdoc仅在上面的概要中与Python一起使用，但它也适用于Jython和IronPython。在记录Java库时，实际上需要Jython。在概要中，libdoc作为已安装的模块（python -m robot.libdoc）执行，但它也可以作为脚本运行：

python path/robot/libdoc.py [options] arguments

如果您已完成手动安装， 或者只是在系统中的某个位置安装了包含源代码的robot目录，则执行脚本非常有用。

5.1.2编写文档

本指南的其他部分将详细介绍如何创建测试库和资源文件。

Python库

Python库的文档只是作为库类的doc字符串和实现关键字的方法编写的。方法文档的第一行被视为关键字的简短文档（例如，在生成的HTML文档中用作链接中的工具提示），因此它应该尽可能地描述，但不能太长。

下面的简单示例说明了如何编写文档，例如标准库提供了更实际的示例。有关Python文档字符串的更多信息，请参阅PEP-257。

class ExampleLib:
    """Library for demo purposes.

    This library is only used in an example and it doesn't do anything useful.
    """

    def my_keyword(self):
        """Does nothing."""
        pass

    def your_keyword(self, arg):
        """Takes one argument and *does nothing* with it.

        Example:
        | Your Keyword | xxx |
        | Your Keyword | yyy |
        """
        pass

注意

如果要在Python库的文档中使用非ASCII字符，则必须使用UTF-8作为源代码编码，或者将docstrings创建为Unicode。

Java库

在为普通Java库编写文档时，应该使用编写Javadoc的约定。该文档是基于源文件中的Javadoc生成的。例如，以下简单示例与早期Python示例具有完全相同的文档（和功能）。

/**
 * Library for demo purposes.
 *
 * This library is only used in an example and it doesn't do anything useful.
 */
public class ExampleLib {

    /**
     * Does nothing.
     */
    public void myKeyword() {
    }

    /**
     * Takes one argument and *does nothing* with it.
     *
     * Example:
     * | Your Keyword | xxx |
     * | Your Keyword | yyy |
     */
    public void yourKeyword(String arg) {
    }
}

动态库

为了能够为动态库生成有意义的文档，库必须使用get_keyword_arguments和get_keyword_documentation 方法（或使用它们的camelCase变体getKeywordArguments 和getKeywordDocumentation）返回关键字参数名称和文档 。库还可以通过特殊的__intro__和 __init__值支持通用库文档到get_keyword_documentation方法。

有关如何创建这些方法的详细信息，请参阅动态库API部分。

导入部分

将基于其初始化方法创建有关如何导入库的单独部分。对于Python库，如果它有 __init__ 方法除了self之外还接受参数，则会显示其文档和参数。对于Java库，如果它具有接受参数的公共构造函数，则会显示其所有公共构造函数。

class TestLibrary:

    def __init__(self, mode='default')
        """Creates new TestLibrary. `mode` argument is used to determine mode."""
        self.mode = mode

    def some_keyword(self, arg):
        if self.mode == 'secret':
             # ...

资源文件文档

资源文件中的关键字可以使用 [Documentation]设置生成文档，libdoc也使用此文档 。文档的第一行（直到第一行  n）被认为是与测试库类似的简短文档。

另外，资源文件本身可以有文档中设置表中记录了整个资源文件。

资源文件中的可能变量未记录。

示例资源文件

设置	值	值
文档	用于演示目的的资源文件。 n
...	此资源仅用于示例	它没有做任何有用的事情。

关键词	行动	争论	争论
我的关键字	[文档]	什么也没做
	没有操作
你的关键字	[参数]	$ {} ARG
	[文档]	采用一个参数，*不执行任何操作*。 n	例如： n | 你的关键字| xxx | n | 你的关键字| yyy | n
	没有操作

示例资源文件

Setting	Value	Value
Documentation	Resource file for demo purposes.
...	This resource is only used in an example	and it doesn't do anything useful.

Keyword	Action	Argument	Argument
My Keyword	[Documentation]	Does nothing
	No Operation
Your Keyword	[Arguments]	${arg}
	[Documentation]	Takes one argument and *does nothing* with it.	Example: | Your Keyword | xxx | | Your Keyword | yyy |
	No Operation

文档语法

通用格式规则

该文档是根据Robot Framework的文档格式规则生成的。最重要的功能是使用* bold *和_italic_进行格式化 ，将URL自动转换为可点击链接，以及使用竖线字符创建表格和预格式化块（对示例有用）的可能性。

特殊格式和内部链接

libdoc还支持带有反引号字符`的关键字名称和参数的特殊格式。更重要的是，此语法还会自动创建指向库中其他关键字的内部链接。例如，以下简单Python库的文档将具有从Log Messages到Log Message的链接，并且`message`和 `level`将被特殊格式化。

def log_message(message, level="INFO"):
    """Writes given message to log using specified log level.

    `message` can be any object. Valid values for `level` are "INFO" (default),
    "DEBUG" and "TRACE".
    """
    print "*%s* %s" % (level, message)

def log_messages(message1, message2, level="INFO"):
    """Writes given messages to log using specified log level.

    See `Log Message` keyword for more information about valid values
    for `level`.
    """
    log_message(message1, level)
    log_message(message2, level)

此外，使用`introduction`或`library introduction`，不区分大小写，在生成的文档的开头生成库引入的链接。类似地，`imported` 或`library imports`生成一个指向导入部分的链接。

所有标准库都使用关键字之间的内部链接，因此它们的文档（和源代码）可以作为一个更现实的示例。

关键词的论点

libdoc自动处理关键字的参数，以便为库中的方法或资源文件中的用户关键字指定的参数列在单独的列中。显示用户关键字参数时不带$ {}或@ {}，以使参数看起来相同，无论关键字来自哪里。

5.2测试数据文档工具（testdoc）

testdoc是基于Robot Framework测试数据生成高级文档的工具。创建的文档采用HTML格式，包括ach测试套件和测试用例的名称，文档和其他元数据，以及顶级关键字及其参数。

testdoc内置于Robot Framework中，并从2.7版开始自动包含在安装中。对于早期版本，您需要单独下载testdoc.py脚本。这些版本之间的命令行用法略有变化。

5.2.1一般用法

概要

python -m robot.testdoc [options] data_sources output_file

选项

-T, --title <title>
	设置生成的文档的标题。标题中的下划线转换为空格。默认标题是顶级套件的名称。
-N, --name <name>
	覆盖顶级测试套件的名称。
-D, --doc <doc>
	覆盖顶级测试套件的文档。
-M, --metadata <name:value>
	设置/覆盖顶级测试套件的免费元数据。
-G, --settag <tag>
	将给定标记设置为所有测试用例。
-t, --test <name>
	按名称包括测试。
-s, --suite <name>
	按名称包括套房。
-i, --include <tag>
	包括标签测试。
-e, --exclude <tag>
	按标签排除测试。
-h, --help	在控制台中打印此帮助。

除了--title之外的所有选项都具有与执行测试用例时相同选项具有的完全相同的语义。

5.2.2生成文档

数据可以作为单个文件，目录或多个文件和目录提供。在所有这些情况下，最后一个参数必须是写入输出的文件。

Testdoc适用于Robot Framework支持的所有解释器（Python，Jython和IronPython）。它可以像python -m robot.testdoc一样安装，也可以 像python path / robot / testdoc.py这样的脚本执行。

例子：

python -m robot.testdoc my_test.html testdoc.html
jython -m robot.testdoc --name smoke_tests --include smoke path/to/my_tests smoke.html
ipy path/to/robot/testdoc.py first_suite.txt second_suite.txt output.html

5.3测试数据清理工具（整洁）

tidy是一个清理和更改Robot Framework测试数据文件格式的工具。它内置于Robot Framework中，并从2.7版开始自动包含在安装中。

默认情况下，工具的输出将写入标准输出流，但也可以重定向到文件。或者，可以使用--inplace或--recursive选项就地修改文件。

5.3.1一般用法

概要

python -m robot.tidy [options] inputfile
python -m robot.tidy [options] inputfile > outputfile
python -m robot.tidy --inplace [options] inputfile [more input files]
python -m robot.tidy --recursive [options] directory

选项

-i, --inplace	整理给定文件，以便覆盖（或删除，如果格式更改）原始文件。使用此选项时，可以提供多个输入文件。例子： python -m robot.tidy --inplace tests.html python -m robot.tidy --inplace --format txt * .html
-r, --recursive
	递归处理给定目录。与使用--inplace 选项时类似，处理目录中的文件。
-f, --format <txt|html|tsv>
	输出文件格式。如果省略，则使用输入文件的格式。
-p, --use-pipes
	使用管道符（|）作为txt格式的单元格分隔符。
-h, --help	显示此帮助。

替代执行

虽然在上面的概要中，整洁仅用于Python，但它也适用于Jython和IronPython。在概要中，整理是作为已安装的模块（python -m robot.tidy）执行的，但它也可以作为脚本运行：

python path/robot/tidy.py [options] arguments

如果您已完成手动安装， 或者只是在系统中的某个位置安装了包含源代码的robot目录，则执行脚本非常有用。

输出编码

所有输出文件都使用UTF-8编码编写。写入控制台的输出使用当前控制台编码。

5.3.2清理测试数据

使用HTML编辑器创建的测试用例文件或手工编写的测试用例文件可以使用整齐进行标准化。整洁总是写出一致的标题，设置的一致顺序，以及单元格和表格之间一致的空白量。

例子：

python -m robot.tidy messed_up_tests.html > cleaned_tests.html
python -m robot.tidy --inplace tests.txt

5.3.3更改测试数据格式

Robot Framework支持HTML，TSV和TXT格式的测试数据，整洁， 使得格式之间的变化变得微不足道。输入格式始终根据输入文件的扩展名确定。可以使用--format选项设置输出格式。

例子：

python -m robot.tidy --format tsv tests_in_html.html > tests_in_tsv.tsv
python -m robot.tidy --format txt --recursive mytests

5.4随机器人框架分发的其他工具

下面列出的工具包含在Robot Framework项目中，但与内置工具libdoc，testdoc和tidy不同，它们需要单独安装。工具名称链接到Wiki页面，其中包含工具文档和用于下载的工具本身。

risto.py

生成有关测试执行的历史统计信息的图表。

fixml.py

用于修复损坏的输出文件的工具。

times2csv.py

以CSV格式生成有关套件，测试和关键字的开始，结束和已用时间信息

statuschecker.py

用于验证测试用例状态和消息以及关键字日志消息的工具符合预期

robotdiff.py

用于显示基于输出文件的不同测试运行之间差异的工具 。

fileviewer.py

实现UNIX 尾部功能的图形工具。专门用于查看调试文件。

一键安装程序

用于在Windows XP计算机上安装Robot Framework及其前提条件的工具。

5.5外部工具

外部工具是作为单独的项目开发的。下面列出了一些比较成熟的工具，但由于新工具经常被引入，因此列表并非详尽无遗。要在此处列出您的工具，请使用邮件列表联系开发人员。

骑

RIDE是一个用于编辑测试数据的独立工具。它有助于创建，编辑和维护Robot Framework测试数据。

mabot

用于报告手动测试执行结果的独立工具。它可以存储和报告手动测试用例以及自动化Robot Framework测试用例。

JavalibCore

通过提供在运行时解析可用关键字的几种动态方法，提供有助于创建更大的Java测试库的集合基类

RemoteApplications

一个代理测试库，可以将在不同JVM上运行的应用程序作为Robot Framework进行测试，包括Java Webstart应用程序。

詹金斯插件

Jenkins的插件，一个流行的持续集成服务器，用于收集和发布Robot Framework测试结果。

Maven插件

Maven构建工具的Robot Framework插件。

Ant插件

Ant构建工具的Robot Framework插件。

机器人模

机器人框架的Emacs模式。

robotframework-VIM

使用Robot框架进行开发的Vim插件

Robot.tmbundle

Robot Framework的TextMate包。