Robot Framework User Guide

• Enables easy-to-use tabular syntax for creating test cases in a uniform way.

  使用易于使用的表格语法以统一方式创建测试用例。

• Provides ability to create reusable higher-level keywords from the existing keywords.

  可以根据已有的关键词创建可重用更高层次的关键词。

• Provides easy-to-read result reports and logs in HTML format.

  以 HTML 格式提供易读的结果报告和日志。

• Is platform and application independent.

  独立于平台和应用程序。

• Provides a command line interface and XML based output files for integration into existing build infrastructure (continuous integration systems).

  提供可用于集成到已有构建设施（持续集成系统）的命令行接口和基于 XML 的输出文件。

• Provides support for Selenium for web testing, Java GUI testing, running processes, Telnet, SSH, and so on.

  支持用于 web 测试的 Selenium，Java GUI 测试，运行程序，Telnet，SSH 等。

• Supports creating data-driven test cases.

  支持创建数据驱动的测试用例。

• Has built-in support for variables, practical particularly for testing in different environments.

  内建支持变量，对测试不同环境特别有用。

• Provides tagging to categorize and select test cases to be executed.

  提供的标签可用于分类和选择要执行的测试用例。

• Enables easy integration with source control: test suites are just files and directories that can be versioned with the production code.

  易于集成到源码控制：测试套件是文件和目录，可以和生产代码一起版本控制。

• Provides test-case and test-suite -level setup and teardown.

  提供测试用例和测试套件级别的 setup 和 teardown。

• The modular architecture supports creating tests even for applications with several diverse interfaces.

  即使应用程序有多个不同接口，模块化架构支持创建测试用例。

Robot Framework is a generic, application and technology independent framework. It has a highly modular architecture illustrated in the diagram below.

Robot Framework 是一个通用的，独立于应用程序和技术的框架。它有一个如下图所示的高度模块化的架构。

The test data is in simple, easy-to-edit tabular format. When Robot Framework is started, it processes the test data, executes test cases and generates logs and reports. The core framework does not know anything about the target under test, and the interaction with it is handled by test libraries. Libraries can either use application interfaces directly or use lower level test tools as drivers.

测试数据是简单的，易于编辑的表格形式。Robot Framework 启动后，它处理测试数据，执行测试用例，并生成日志和报告。核心框架不知道任何被测试目标，通过测试库与其交互。库能直接使用应用接口，也可以使用低水平的测试工具作为驱动。

Following screenshots show examples of the test data and created reports and logs.

下面的截图是测试数据和创建报告和日志的例子。

Project pages

The number one place to find more information about Robot Framework and the rich ecosystem around it is http://robotframework.org. Robot Framework itself is hosted on GitHub.

Mailing lists

There are several Robot Framework mailing lists where to ask and search for more information. The mailing list archives are open for everyone (including the search engines) and everyone can also join these lists freely. Only list members can send mails, though, and to prevent spam new users are moderated which means that it might take a little time before your first message goes through. Do not be afraid to send question to mailing lists but remember How To Ask Questions The Smart Way.

• robotframework-users

  General discussion about all Robot Framework related issues. Questions and problems can be sent to this list. Used also for information sharing for all users.

• robotframework-announce

  An announcements-only mailing list where only moderators can send messages. All announcements are sent also to the robotframework-users mailing list so there is no need to join both lists.

• robotframework-devel

  Discussion about Robot Framework development.

Robot Framework is implemented with Python and supports also Jython (JVM) and IronPython (.NET). Before installing the framework, an obvious precondition is installing at least one of these interpreters.

Robot Framework 使用 Python 实现，也支持 Jython（JVM）和 IronPython（.NET）。安装 Framework 之前，一个明显的前提是至少安装这些解释器中的一个。

Different ways to install Robot Framework itself are listed below and explained more thoroughly in the subsequent sections.

下面列出了安装 Robot Framework 的不同方法，随后的章节中进行更加彻底的解释。

• Installing with pip（使用 pip 安装）

  Using pip is the recommended way to install Robot Framework. As the standard Python package manager it is included in the latest Python, Jython and IronPython versions. If you already have pip available, you can simply execute:

  推荐使用 pip 安装 Robot Frame。作为标准 Python 包管理器包含在最新版本的 Python，Jython 和 IronPython 版本中。如果已有可用的 pip，可以简单执行：

  pip install robotframework
  

• Installing from source

  This approach works regardless the operating system and the Python interpreter used. You can get the source code either by downloading a source distribution from PyPI and extracting it, or by cloning the GitHub repository .

• Standalone JAR distribution

  If running tests with Jython is enough, the easiest approach is downloading the standalone robotframework-<version>.jar from Maven central. The JAR distribution contains both Jython and Robot Framework and thus only requires having Java installed.

• Manual installation

  If you have special needs and nothing else works, you can always do a custom manual installation.

Note

Prior to Robot Framework 3.0, there were also separate Windows installers for 32bit and 64bit Python versions. Because Python 2.7.9 and newer contain pip on Windows and Python 3 would have needed two more installers, it was decided that Windows installers are not created anymore. The recommend installation approach also on Windows is using pip.

Robot Frame 3.0 之前，针对 32 位和 64 位 Python 有单独的 Windows 安装包。由于 Python 2.7.9 及更新版本在 window 上包含 pip，而 Python 3 需要两个额外的安装包，这决定了不再需要 Windows 安装包。Windows 上推荐使用 pip 进行安装。

Robot Framework is supported on Python (both Python 2 and Python 3), Jython (JVM) and IronPython (.NET) and runs also on PyPy. The interpreter you want to use should be installed before installing the framework itself.

Robot Framework 支持 Python (both Python 2 and Python 3), Jython (JVM) and IronPython (.NET)，可以运行于 PyPy。想要使用的解释器应该在框架之前安装。

Which interpreter to use depends on the needed test libraries and test environment in general. Some libraries use tools or modules that only work with Python, while others may use Java tools that require Jython or need .NET and thus IronPython. There are also many tools and libraries that run fine with all interpreters.

一般来说使用哪个编译器取决于所需的测试库和测试环境。一些库使用的工具或模块值使用 python，另一些可能使用 java 工具就需要 Jython，或者使用.NET 需要 IronPython。也有很多工具或库和所有的编译器很好的工作。

If you do not have special needs or just want to try out the framework, it is recommended to use Python. It is the most mature implementation, considerably faster than Jython or IronPython (especially start-up time is faster), and also readily available on most UNIX-like operating systems. Another good alternative is using the standalone JAR distribution that only has Java as a precondition.

如果没有特殊需求，只是想尝试 framework，推荐使用 Python。它是最成熟的实现，速度大大快于 Jython 或 IronPython（特别是启动时间更短），在大部分类 Unix 操作系统上都可用。另一个不错的选择是使用只要求 Java 作为前提的标准 JAR 发行版。

Python 2 vs Python 3

Python 2 and Python 3 are mostly the same language, but they are not fully compatible with each others. The main difference is that in Python 3 all strings are Unicode while in Python 2 strings are bytes by default, but there are also several other backwards incompatible changes. The last Python 2 release is Python 2.7 that was released in 2010 and will be supported until 2020. See Should I use Python 2 or 3? for more information about the differences, which version to use, how to write code that works with both versions, and so on.

Python2 和 Python3 基本上是同一种语言，但它们之间并不完全兼容。主要区别在于 Python3 中所有字符串都是 Unicode，而 Python 2 默认情况下字符串是字节类型，但也有一些向后不见荣的更改。最新的 Python2 发布是 2010 年发布的 Python2.7，将会支持到 2020 年。查看 Should I use Python 2 or 3?了解更多关于差异，应该选用哪个版本，如何编写两个版本都可用的代码等等。

Robot Framework 3.0 is the first Robot Framework version to support Python 3. It supports also Python 2, and the plan is to continue Python 2 support as long as Python 2 itself is officially supported. We hope that authors of the libraries and tools in the wider Robot Framework ecosystem also start looking at Python 3 support now that the core framework supports it.

Robot Framework 3.0 是第一个支持 Python 3 的 Robot Framework 版本。它也支持 Python 2，计划继续支持 Python 2 直到官方支持结束。我们希望更广泛的 Robot Framework 生态系统中的库和工具的作者开始关注 Python 3 支持，现在核心框架已经支持它。

Python installation

On most UNIX-like systems such as Linux and OS X you have Python installed by default. If you are on Windows or otherwise need to install Python yourself, a good place to start is http://python.org. There you can download a suitable installer and get more information about the installation process and Python in general.

Robot Framework 3.0 supports Python 2.6, 2.7, 3.3 and newer, but the plan is to drop Python 2.6 support in RF 3.1. If you need to use older versions, Robot Framework 2.5-2.8 support Python 2.5 and Robot Framework 2.0-2.1 support Python 2.3 and 2.4.

On Windows it is recommended to install Python to all users and to run the installer as an administrator. Additionally, environment variable PYTHONCASEOK must not be set.

After installing Python, you probably still want to configure PATH to make Python itself as well as the robot and rebot runner scripts executable on the command line.

Tip

Latest Python Windows installers allow setting PATH as part of the installation. This is disabled by default, but Add python.exe to Path can be enabled on the Customize Python screen.

Jython installation

Using test libraries implemented with Java or that use Java tools internally requires running Robot Framework on Jython, which in turn requires Java Runtime Environment (JRE) or Java Development Kit (JDK). Installing either of these Java distributions is out of the scope of these instructions, but you can find more information, for example, from http://java.com.

Installing Jython is a fairly easy procedure, and the first step is getting an installer from http://jython.org. The installer is an executable JAR package, which you can run from the command line like java -jar jython_installer-<version>.jar. Depending on the system configuration, it may also be possible to just double-click the installer.

Robot Framework 3.0 supports Jython 2.7 which requires Java 7 or newer. If older Jython or Java versions are needed, Robot Framework 2.5-2.8 support Jython 2.5 (requires Java 5 or newer) and Robot Framework 2.0-2.1 support Jython 2.2.

After installing Jython, you probably still want to configure PATH to make Jython itself as well as the robot and rebot runner scripts executable on the command line.

IronPython installation

IronPython allows running Robot Framework on the .NET platform and interacting with C# and other .NET languages and APIs. Only IronPython 2.7 is supported.

When using IronPython, an additional dependency is installing elementtree module 1.2.7 preview release. This is required because the elementtree module distributed with IronPython is broken. You can install the package by downloading the source distribution, unzipping it, and running ipy setup.py install on the command prompt in the created directory.

After installing IronPython, you probably still want to configure PATH to make IronPython itself as well as the robot and rebot runner scripts executable on the command line.

Configuring PATH

The PATH environment variable lists locations where commands executed in a system are searched from. To make using Robot Framework easier from the command prompt, it is recommended to add the locations where the runner scripts are installed into the PATH. It is also often useful to have the interpreter itself in the PATH to make executing it easy.

When using Python on UNIX-like machines both Python itself and scripts installed with should be automatically in the PATH and no extra actions needed. On Windows and with other interpreters the PATH must be configured separately.

Tip

Latest Python Windows installers allow setting PATH as part of the installation. This is disabled by default, but Add python.exe to Path can be enabled on the Customize Python screen. It will add both the Python installation directory and the Scripts directory to the PATH.

What directories to add to PATH

What directories you need to add to the PATH depends on the interpreter and the operating system. The first location is the installation directory of the interpreter (e.g. C:\Python27) and the other is the location where scripts are installed with that interpreter. Both Python and IronPython install scripts to Scripts directory under the installation directory on Windows (e.g. C:\Python27\Scripts) and Jython uses bin directory regardless the operating system (e.g. C:\jython2.7.0\bin).

Notice that the Scripts and bin directories may not be created as part of the interpreter installation, but only later when Robot Framework or some other third party module is installed.

Setting PATH on Windows

On Windows you can configure PATH by following the steps below. Notice that the exact setting names may be different on different Windows versions, but the basic approach should still be the same.

• Open Control Panel > System > Advanced > Environment Variables. There are User variables and System variables, and the difference between them is that user variables affect only the current users, whereas system variables affect all users.
• To edit an existing PATH value, select Edit and add ;<InstallationDir>;<ScriptsDir> at the end of the value (e.g. ;C:\Python27;C:\Python27\Scripts). Note that the semicolons (;) are important as they separate the different entries. To add a new PATH value, select New and set both the name and the value, this time without the leading semicolon.
• Exit the dialog with Ok to save the changes.
• Start a new command prompt for the changes to take effect.

Notice that if you have multiple Python versions installed, the executed robot or rebot runner script will always use the one that is first in the PATH regardless under what Python version that script is installed. To avoid that, you can always execute the installed robot module directly like C:\Python27\python.exe -m robot.

Notice also that you should not add quotes around directories you add into the PATH (e.g. "C:\Python27\Scripts"). Quotes can cause problems with Python programs and they are not needed in this context even if the directory path would contain spaces.

Setting PATH on UNIX-like systems

On UNIX-like systems you typically need to edit either some system wide or user specific configuration file. Which file to edit and how depends on the system, and you need to consult your operating system documentation for more details.

Setting https_proxy

If you are installing with pip and are behind a proxy, you need to set the https_proxy environment variable. It is needed both when installing pip itself and when using it to install Robot Framework and other Python packages.

How to set the https_proxy depends on the operating system similarly as configuring PATH. The value of this variable must be an URL of the proxy, for example, http://10.0.0.42:8080.

The standard Python package manager is pip, but there are also other alternatives such as Buildout and easy_install. These instructions only cover using pip, but other package managers ought be able to install Robot Framework as well.

标准 Python 包管理器是 pip，但也有其他选择比如 Buildout 和 easy_install。这些说明哪个只针对使用 pip，但其他包管理器也应该能够安装 Robot Framework。

Latest Python, Jython and IronPython versions contain pip bundled in. Which versions contain it and how to possibly activate it is discussed in sections below. See pip project pages if for latest installation instructions if you need to install it.

最新的 Python, Jython and IronPython 版本捆绑了 pip。下面的章节讨论了哪个版本包含以及如果启用。参见需要安装 pip 参见 pip project pages 上面最新的安装指南。

Note

Only Robot Framework 2.7 and newer can be installed using pip. If you need an older version, you must use other installation approaches.

只有 Robot Framework 2.7 及最更新版本能够使用 pip 安装，如果需要旧版本，应该使用其他方法安装。

Installing pip for Python

Starting from Python 2.7.9, the standard Windows installer by default installs and activates pip. Assuming you also have configured PATH and possibly set https_proxy, you can run pip install robotframework right after Python installation.

从 Python 2.7.9 开始，标准 Windows 安装其默认安装和启用 pip。假设你已经配置了 PATH 和可能设置的 https_proxy，安装好 Python 之后就可运行 pip 安装 robotframework。

Outside Windows and with older Python versions you need to install pip yourself. You may be able to do it using system package managers like Apt or Yum on Linux, but you can always use the manual installation instructions found from the pip project pages.

除了 Windows 和使用 python 旧版本，需要自己安装 pip。linux 上可能需要使用系统包管理器比如 Apt 或者 Yum，反仍然可以使用从 pip proejct 的手动安装指南。

If you have multiple Python versions with pip installed, the version that is used when the pip command is executed depends on which pip is first in the PATH. An alternative is executing the pip module using the selected Python version directly:

如果有多个 Python 版本都安装了 pip，当执行 pip 命令时使用的版本取决于 PATH 中出现的第一个 pip。另一个是直接使用选中的 Pyhon 版本执行 pip 模块。

python -m pip install robotframework
python3 -m pip install robotframework

Installing pip for Jython

Jython 2.7 contain pip bundled in, but it needs to be activated before using it by running the following command:

jython -m ensurepip

Jython installs its pip into <JythonInstallation>/bin directory. Does running pip install robotframework actually use it or possibly some other pip version depends on which pip is first in the PATH. An alternative is executing the pip module using Jython directly:

jython -m pip install robotframework

Installing pip for IronPython

IronPython contains bundled pip starting from version 2.7.5. Similarly as with Jython, it needs to be activated first:

ipy -X:Frames -m ensurepip

Notice that with IronPython -X:Frames command line option is needed both when activating and when using pip.

IronPython installs pip into <IronPythonInstallation>/Scripts directory. Does running pip install robotframework actually use it or possibly some other pip version depends on which pip is first in the PATH. An alternative is executing the pip module using IronPython directly:

ipy -X:Frames -m pip install robotframework

IronPython versions prior to 2.7.5 do not officially support pip.

Using pip

Once you have pip installed, and have set https_proxy is you are behind a proxy, using it on the command line is very easy. The easiest way to use pip is letting it find and download packages it installs from the Python Package Index (PyPI), but it can also install packages downloaded from the PyPI separately. The most common usages are shown below and pip documentation has more information and examples.

# Install the latest version
pip install robotframework

# Upgrade to the latest version
pip install --upgrade robotframework

# Install a specific version
pip install robotframework==2.9.2

# Install separately downloaded package (no network connection needed)
pip install robotframework-3.0.tar.gz

# Uninstall
pip uninstall robotframework

Notice that pip 1.4 and newer will only install stable releases by default. If you want to install an alpha, beta or release candidate, you need to either specify the version explicitly or use the –pre option:

# Install 3.0 beta 1
pip install robotframework==3.0b1

# Upgrade to the latest version even if it is a pre-release
pip install --pre --upgrade robotframework

This installation method can be used on any operating system with any of the supported interpreters. Installing from source can sound a bit scary, but the procedure is actually pretty straightforward.

Getting source code

You typically get the source by downloading a source distribution package in .tar.gz format. Newer packages are available on PyPI, but Robot Framework 2.8.1 and older can be found from the old Google Code download page. Once you have downloaded the package, you need to extract it somewhere and, as a result, you get a directory named robotframework-<version>. The directory contains the source code and scripts needed for installing it.

An alternative approach for getting the source code is cloning project's GitHub repository directly. By default you will get the latest code, but you can easily switch to different released versions or other tags.

Installation

Robot Framework is installed from source using Python's standard setup.py script. The script is in the directory containing the sources and you can run it from the command line using any of the supported interpreters:

python setup.py install
jython setup.py install
ipy setup.py install

The setup.py script accepts several arguments allowing, for example, installation into a non-default location that does not require administrative rights. It is also used for creating different distribution packages. Run python setup.py –help for more details.

Robot Framework is also distributed as a standalone Java archive that contains both Jython and Robot Framework and only requires Java a dependency. It is an easy way to get everything in one package that requires no installation, but has a downside that it does not work with the normal Python interpreter.

The package is named robotframework-<version>.jar and it is available on the Maven central. After downloading the package, you can execute tests with it like:

java -jar robotframework-3.0.jar mytests.robot
java -jar robotframework-3.0.jar --variable name:value mytests.robot

If you want to post-process outputs using Rebot or use other built-in supporting tools, you need to give the command name rebot, libdoc, testdoc or tidy as the first argument to the JAR file:

java -jar robotframework-3.0.jar rebot output.xml
java -jar robotframework-3.0.jar libdoc MyLibrary list

For more information about the different commands, execute the JAR without arguments.

In addition to the Python standard library and Robot Framework modules, the standalone JAR versions starting from 2.9.2 also contain the PyYAML dependency needed to handle yaml variable files.

If you do not want to use any automatic way of installing Robot Framework, you can always install it manually following these steps:

Get the source code. All the code is in a directory (a package in Python) called robot. If you have a source distribution or a version control checkout, you can find it from the src directory, but you can also get it from an earlier installation.

Copy the source code where you want to.

Decide how to run tests.

After a successful installation, you should be able to execute the created runner scripts with –version option and get both Robot Framework and interpreter versions as a result:

成功安装之后，应该能够使用–version 选项执行创建的运行脚本，得到如下有关 Robot Framework 和解释器的版本：

$ robot --version
Robot Framework 3.0 (Python 2.7.10 on linux2)

$ rebot --version
Rebot 3.0 (Python 2.7.10 on linux2)

If running the runner scripts fails with a message saying that the command is not found or recognized, a good first step is double-checking the PATH configuration. If that does not help, it is a good idea to re-read relevant sections from these instructions before searching help from the Internet or as asking help on robotframework-users mailing list or elsewhere.

如果运行脚本执行失败，提示消息说命令没有找到或不识别，最好检查一下 PATH 配置。如果这没有帮助，从网上搜索帮助或者在 robotframework 用户邮件列表或其他什么地方寻求帮助前重读一下这些说明中的相关章节是个好主意。

*Where files are installed*（文件安装在哪里了？）

When an automatic installer is used, Robot Framework source code is copied into a directory containing external Python modules. On UNIX-like operating systems where Python is pre-installed the location of this directory varies. If you have installed the interpreter yourself, it is normally Lib/site-packages under the interpreter installation directory, for example, C:\Python27\Lib\site-packages. The actual Robot Framework code is in a directory named robot.

当使用自动安装，Robot Framework 源码被拷贝到外部 Python 模块所在的目录。在类 Unix 操作系统中，这个目录根据 Python 预安装的目录有所不同。如果自己安装了解释器，通常是解释器安装目录下的 Lib/site-packages，例如 C:\Python27\Lib\site-packages。Robot Framework 的实际代码放在名为 robot 的目录中。

Robot Framework runner scripts are created and copied into another platform-specific location. When using Python on UNIX-like systems, they normally go to /usr/bin or /usr/local/bin. On Windows and with Jython and IronPython, the scripts are typically either in Scripts or bin directory under the interpreter installation directory.

创建 Robot Framework 运行脚本，并将其拷贝到另一个平台的特定位置。在类 Unix 操作系统中使用 Python，通常是/usr/bin or /usr/local/bin。安装 Jython 或者 IronPython 的 Windows 中，这些脚本通常在解释器安装目录下的 Scripts 或者 bin 目录。

The easiest way to uninstall Robot Framework is using pip:

卸载 Robot Framework 最简单的方式是使用 pip：

pip uninstall robotframework

A nice feature in pip is that it can uninstall packages even if they are installed from the source. If you do not have pip available or have done a manual installation to a custom location, you need to find where files are installed and remove them manually.

即使从源码安装，也可以通过 pip 卸载，这挺不错的。如果没有可用的 pip，或者手动安装到自定义位置，需要找到文件位置并手动删除它们。

If you have set PATH or configured the environment otherwise, you need to undo those changes separately.

如果有设置 PATH 或者配置环境变量，需要单独撤销这些变化。

If you are using pip, upgrading to a new version required either using the –upgrade option or specifying the version to use explicitly:

如果使用 pip，升级到新版本需要使用 –upgrade 选项或者显示指定要使用的版本：

pip install --upgrade robotframework
pip install robotframework==2.9.2

When using pip, it automatically uninstalls previous versions before installation. If you are installing from source, it should be safe to just install over an existing installation. If you encounter problems, uninstallation before installation may help.

When upgrading Robot Framework, there is always a change that the new version contains backwards incompatible changes affecting existing tests or test infrastructure. Such changes are very rare in minor versions like 2.8.7 or 2.9.2, but more common in major versions like 2.9 and 3.0. Backwards incompatible changes and deprecated features are explained in the release notes, and it is a good idea to study them especially when upgrading to a new major version.

Using robot and rebot scripts

使用 robot 和 robot 脚本

Starting from Robot Framework 3.0, tests are executed using the robot script and results post-processed with the rebot script:

启动 Robot Framework 3.0，使用 robot 脚本执行测试和后期处理结果：

robot tests.robot
rebot output.xml

Both of these scripts are installed as part of the normal installation and can be executed directly from the command line if PATH is set correctly. They are implemented using Python except on Windows where they are batch files.

这两个脚本作为正常安装的一部分，如果正确设置 PATH，可以直接命令行执行。它们用 Python 实现，Windows 上是批处理文件。

Older Robot Framework versions do not have the robot script and the rebot script is installed only with Python. Instead they have interpreter specific scripts pybot, jybot and ipybot for test execution and jyrebot and ipyrebot for post-processing outputs. These scripts still work, but they will be deprecated and removed in the future.

旧的 Robot Framework 版本没有 robot 脚本，这些脚本只随 Python 安装。相反，它们有编译器特定脚本 pybot，jybot 和 ipybot 用来执行测试，jyrebot 和 ipyrebot 用来后期处理输出，这些脚本仍然工作，但将来可能会弃用或删除。

Executing installed robot module

执行安装的 robot 模块

An alternative way to run tests is executing the installed robot module or its sub module robot.run directly using Python's -m command line option. This is especially useful if Robot Framework is used with multiple Python versions:

另一种运行测试的方法是执行安装的 robot 模块或使用 Python 的 -m 命令行参数直接执行它的 robot.run 字模块。如果使用多个 Python 版本执行 Robt Framework 这很有用。

python -m robot tests.robot
python3 -m robot.run tests.robot
jython -m robot tests.robot
/opt/jython/jython -m robot tests.robot

The support for python -m robot approach is a new feature in Robot Framework 3.0, but the older versions support python -m robot.run. The latter must also be used with Python 2.6.

支持 python -m robot 方法是 Robt Framework 3.0 的新功能，但旧版本支持 python -m robot.run。后者必须配合 Python 2.6 使用。

Post-processing outputs using the same approach works too, but the module to run is robot.rebot:

后期处理输出使用相同的方法工作，但运行的模块是 robot.rebot：

python -m robot.rebot output.xml

Executing installed robot directory

执行安装的 robot 目录

If you know where Robot Framework is installed, you can also execute the installed robot directory or run.py file inside it directly:

如果知道 Robot Framework 安装目录，可以直接执行安装 robot 的目录或其中的 run.py：

python path/to/robot/ tests.robot
jython path/to/robot/run.py tests.robot

Running the directory is a new feature in Robot Framework 3.0, but the older versions support running the robot/run.py file.

执行目录是 Robot Framework 3.0 的新功能，但旧版本支持运行 robot/run.py 文件。

Post-processing outputs using the robot/rebot.py file works the same way too:

可以用同样的方式使用 robot/reobot.py 处理后期输出：

#+BEGIN_SRC sh python path/to/robot/rebot.py output.xml

Executing Robot Framework this way is especially handy if you have done a manual installation.

如果手动安装，这种方式执行 Robot Framework 尤其方便。

The hierarchical structure for arranging test cases is built as follows:

安排测试用例的层次结构可以如下构建：

• Test cases are created in test case files.

  在测试用例中文件中创建测试用例。

• A test case file automatically creates a test suite containing the test cases in that file.

  测试用例文件自动创建包含该文件中的测试用例测试套件。

• A directory containing test case files forms a higher-level test suite. Such a test suite directory has suites created from test case files as its sub test suites.

  包含测试用例文件的目录是更高级别的测试套件。测试用例文件中创建的测试套件作为这种测试套件目录子测试套件。

• A test suite directory can also contain other test suite directories, and this hierarchical structure can be as deeply nested as needed.

  测试套件目录可以包含其他测试套件目录，这种层次的结构可以按照需要任意嵌套。

• Test suite directories can have a special initialization file.

  测试套件目录可以有一个特殊的初始化文件。

In addition to this, there are:

除此之外，还有：

• Test libraries containing the lowest-level keywords.

  测试库包含最低级别的关键词。

• Resource files with variables and higher-level user keywords.

  资源文件有变量和更高级别的用户关键词。

• Variable files to provide more flexible ways to create variables than resource files.

  变量文件提供比资源文件更灵活的方式创建变量。

Robot Framework test data is defined in tabular format, using either hypertext markup language (HTML), tab-separated values (TSV), plain text, or reStructuredText (reST) formats. The details of these formats, as well as the main benefits and problems with them, are explained in the subsequent sections. Which format to use depends on the context, but the plain text format is recommended if there are no special needs.

Robot Framework 使用表格形式定义测试数据，可以使用超文本标记语言（HTML），制表符分割值（TSV），纯文本，或者 reStructuredText(reST)格式。随后的部分会解释这些格式的细节，主要优点和问题。使用哪种格式依赖于上下文，但如果没有特殊需要推荐使用纯文本格式。

Robot Framework selects a parser for the test data based on the file extension. The extension is case-insensitive, and the recognized extensions are .html, .htm and .xhtml for HTML, .tsv for TSV, .txt and special .robot for plain text, and .rst and .rest for reStructuredText.

Robot Framework 基于文件扩展名为测试数据选择解释器。扩展名不区分大小写，可识别的扩展名是.html, .htm and .xhtml for HTML, .tsv for TSV, .txt and special .robot for plain text, and .rst and .rest for reStructuredText。

Different test data templates are available for HTML and TSV formats to make it easier to get started writing tests.

HTML 和 TSV 格式有各自的测试数据模板，可以更容易开始编写测试。

Note

The special .robot extension with plain text files is supported starting from Robot Framework 2.7.6.

纯文本使用的特殊的.robot 扩展从 Robot Framework 2.7.6。

HTML format

HTML files support formatting and free text around tables. This makes it possible to add additional information into test case files and allows creating test case files that look like formal test specifications. The main problem with HTML format is that editing these files using normal text editors is not that easy. Another problem is that HTML does not work as well with version control systems because the diffs resulting from changes contain HTML syntax in addition to changes to the actual test data.

In HTML files, the test data is defined in separate tables (see the example below). Robot Framework recognizes these test data tables based on the text in their first cell. Everything outside recognized tables is ignored. #+caption：using the HTML format

Editing test data

Test data in HTML files can be edited with whichever editor you prefer, but a graphic editor, where you can actually see the tables, is recommended. RIDE can read and write HTML files, but unfortunately it loses all HTML formatting and also possible data outside test case tables.

Encoding and entity references

HTML entity references (for example, &auml;) are supported. Additionally, any encoding can be used, assuming that it is specified in the data file. Normal HTML files must use the META element as in the example below:

<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">

XHTML files should use the XML preamble as in this example:

<?xml version="1.0" encoding="Big5"?>

If no encoding is specified, Robot Framework uses ISO-8859-1 by default.

TSV format

TSV files can be edited in spreadsheet programs and, because the syntax is so simple, they are easy to generate programmatically. They are also pretty easy to edit using normal text editors and they work well in version control, but the plain text format is even better suited for these purposes.

The TSV format can be used in Robot Framework's test data for all the same purposes as HTML. In a TSV file, all the data is in one large table. Test data tables are recognized from one or more asterisks (*), followed by a normal table name and an optional closing asterisks. Everything before the first recognized table is ignored similarly as data outside tables in HTML data.

Editing test data

You can create and edit TSV files in any spreadsheet program, such as Microsoft Excel. Select the tab-separated format when you save the file and remember to set the file extension to .tsv. It is also a good idea to turn all automatic corrections off and configure the tool to treat all values in the file as plain text.

TSV files are relatively easy to edit with any text editor, especially if the editor supports visually separating tabs from spaces. The TSV format is also supported by RIDE.

Robot Framework parses TSV data by first splitting all the content into rows and then rows into cells on the basis of the tabular characters. Spreadsheet programs sometimes surround cells with quotes (for example, "my value") and Robot Framework removes them. Possible quotes inside the data are doubled (for example, "my ""quoted"" value") and also this is handled correctly. If you are using a spreadsheet program to create TSV data, you should not need to pay attention to this, but if you create data programmatically, you have to follow the same quoting conventions as spreadsheets.

Encoding

TSV files are always expected to use UTF-8 encoding. Because ASCII is a subset of UTF-8, plain ASCII is naturally supported too.

Plain text format

纯文本格式

The plain texts format is very easy to edit using any text editor and they also work very well in version control. Because of these benefits it has became the most used data format with Robot Framework.

纯文本格式可以用任何编辑器很容易的编辑，也很容易进行版本控制。由于这些优点，它成了 Robot Framework 最常用的数据格式。

The plain text format is technically otherwise similar to the TSV format but the separator between the cells is different. The TSV format uses tabs, but in the plain text format you can use either two or more spaces or a pipe character surrounded with spaces (|).

纯文本格式技术和 TSV 格式类似，但分隔符不同。TSV 使用制表符，但纯文本格式使用两个或更多空格，或者空格包围的管道符（|）。

The test data tables must have one or more asterisk before their names similarly as in the TSV format. Otherwise asterisks and possible spaces in the table header are ignored so, for example, * Settings * and *Settings work the same way. Also similarly as in the TSV format, everything before the first table is ignored.

和 TSV 格式一样，测试数据表名前必须有一个或更多星号。表头的中其他星号和可能的空格将会忽略，例如*** Settings * and *Settings 以相同的方式工作。和 TSV 格式类似，第一个表格前的所有东西将会忽略。

In plain text files tabs are automatically converted to two spaces. This allows using a single tab as a separator similarly as in the TSV format. Notice, however, that in the plain text format multiple tabs are considered to be a single separator whereas in the TSV format every tab would be a separator.

纯文本文件中制表符自动转换为两个空格。类似 TSV 格式，这允许使用一个制表符作为分隔符。不过，请注意，纯文本格式中多个制表符被当作单个分隔符，而 TSV 格式中，每个制表符都是一个制表符。

Space separated format

空格分割格式

The number of spaces used as separator can vary, as long as there are at least two spaces, and it is thus possible to align the data nicely. This is a clear benefit over editing the TSV format in a text editor because with TSV the alignment cannot be controlled.

作为分隔符的空格数量各有不同，只要至少有两个空格，因而可以很好看的对其数据。相比 TSV 格式，在文本编辑器中这是很明显的优势，因为 TSV 对齐不能控制。

Test data is structured in four types of tables listed below. These test data tables are identified by the first cell of the table. Recognized table names are Settings, Variables, Test Cases, and Keywords. Matching is case-insensitive and also singular variants like Setting and Test Case are accepted.

测试数据按照下面列出的四种类型的表格组织。这些测试数据通过表格的第一个元素区别。可识别的表名是 Settings, Variables, Test Cases, and Keywords。匹配不去分大小写，也接受奇怪的变体比如 Setting 和 Test Case。

#+caption：Different test data tables

Ignored data

忽略的数据

When Robot Framework parses the test data, it ignores:

当 Robot Framework 分析测试数据时，它忽略：

• All tables that do not start with a recognized table name in the first cell.

  第一个表格不是可识别表名的所有表格。

• Everything else on the first row of a table apart from the first cell.

  表格第一行中除了第一个单元格的其他数据。

• All data before the first table. If the data format allows data between tables, also that is ignored.

  第一个表格前的所有数据。如果数据格式允许在表格之间有数据，这些数据也会被忽略。

• All empty rows, which means these kinds of rows can be used to make the tables more readable.

  所有空行，这些空行为了让表更具可读性。

• All empty cells at the end of rows, unless they are escaped.

  行末尾所有的单元格，除非它们被转义。

• All single backslashes (\) when not used for escaping.

  所有不用于转义的单个发斜杠。

• All characters following the hash character (#), when it is the first character of a cell. This means that hash marks can be used to enter comments in the test data.

  如果#是单元格的第一个字符，忽略其后的所有字符。这意味着#可用于在测试数据中输入注释。

• All formatting in the HTML/reST test data.

  HTML/reST 测试数据中所有格式。

When Robot Framework ignores some data, this data is not available in any resulting reports and, additionally, most tools used with Robot Framework also ignore them. To add information that is visible in Robot Framework outputs, place it to the documentation or other metadata of test cases or suites, or log it with the BuiltIn keywords Log or Comment.

当 Robot Framework 忽略一些数据，这些数据不会用在任何结果报告中，此外，大多数配合 Robot Framework 使用的工具也会忽略它们。为了添加在 Robot Framework 输出中可见的信息，将它们放在文档或其他测试用例或套件的元数据中，或者使用内建关键词 Log 或 Comment。

Handling whitespace

处理空白符

Robot Framework handles whitespace the same way as they are handled in HTML source code:

Robot Framework 处理空白符的方式和在 HTML 源码中处理空白符方式相同：

• Newlines, carriage returns, and tabs are converted to spaces.

  换行，回车，制表符转换为空格。

• Leading and trailing whitespace in all cells is ignored.

  忽略单元格中首部和尾部的空白符。

• Multiple consecutive spaces are collapsed into a single space.

  多个连续的空格将被折叠为单个空格。

In addition to that, non-breaking spaces are replaced with normal spaces. This is done to avoid hard-to-debug errors when a non-breaking space is accidentally used instead of a normal space.

除此之外，没有换行的空格将替换为普通空格。这么做是为了避免难以调试的错误，因为偶尔会使用不换行的空格而不是普通的空格。

If leading, trailing, or consecutive spaces are needed, they must be escaped. Newlines, carriage returns, tabs, and non-breaking spaces can be created using escape sequences \n, \r, \t, and \xA0 respectively.

如果首部，尾部和连续空格是必要的，它们必须被转义。换行，回车，制表符，或没有换行的空格可以相应的通过\n, \r, \t, and \xA0 创建。

Escaping

转义

The escape character in Robot Framework test data is the backslash (\) and additionally built-in variables ${EMPTY} and ${SPACE} can often be used for escaping. Different escaping mechanisms are discussed in the sections below.

Robot Framework 测试数据中的转义字符是反斜杠（\），另外的内置变量${EMPTY} 和 ${SPACE}经常用于进行转义。下面的章节将讨论不同的转义机制。

Escaping special characters

转义特殊字符

The backslash character can be used to escape special characters so that their literal values are used.

反斜杠字符可以用转义特殊字符，这样就可以使用它们的字面值。

#+caption：Escaping special characters

Forming escape sequences

组织转义序列

The backslash character also allows creating special escape sequences that are recognized as characters that would otherwise be hard or impossible to create in the test data.

转义字符还允许创建特殊转义序列，这些转义序列为在测试数据中很难或不可能创建的字符。

Escape sequences

Note

All strings created in the test data, including characters like \x02, are Unicode and must be explicitly converted to byte strings if needed. This can be done, for example, using Convert To Bytes or Encode String To Bytes keywords in BuiltIn and String libraries, respectively, or with something like str(value) or value.encode('UTF-8') in Python code.

测试数据中创建的所有的字符串，包括类似\x02 的字符，是 unicode，如果有需要必须显示转为字节字符串。这可以使用内建的字符串库转为字节或编码字符串为字节，在 Python 代码中相应的库诶有使用 str(value)或 value.encode('UTF-8')。

Note

If invalid hexadecimal values are used with \x, \u or \U escapes, the end result is the original value without the backslash character. For example, \xAX (not hex) and \U00110000 (too large value) result with xAX and U00110000, respectively. This behavior may change in the future, though.

如果和\x, \u or \U 一起使用的是无效的十六进制值，最后的结果是没有反斜杠的原始数值。例如，\xAX (非十六进制) and \U00110000（过大）相应的结果是 xAX and U00110000。尽管将来这种行为可能会改变。

Note

Built-in variable ${\n} can be used if operating system dependent line terminator is needed (\r\n on Windows and \n elsewhere).

如果需要和操作系统有关的行结束符（Windows 上是\r\n，其他是\n），可以使用内建变量${\n}。

Note

Possible un-escaped whitespace character after the \n is ignored. This means that two lines\nhere and two lines\n here are equivalent. The motivation for this is to allow wrapping long lines containing newlines when using the HTML format, but the same logic is used also with other formats. An exception to this rule is that the whitespace character is not ignored inside the extended variable syntax.

忽略\n 之后可能的未转义的空白字符。这意味着 two lines\nhere 等同于 two lines\n here。这样做是为了当使用 HTML 格式是，允许包含换行符的较长的行，但相同的逻辑也可用于其他格式。该规则的一个例外的是扩展变量语法内的空白字符不会忽略。

Note

\x, \u and \U escape sequences are new in Robot Framework 2.8.2.

\x, \u and \U 转义序列是在 Robot Framework 2.8.2 中新出现的。

Prevent ignoring empty cells

禁止忽略空单元格

If empty values are needed as arguments for keywords or otherwise, they often need to be escaped to prevent them from being ignored. Empty trailing cells must be escaped regardless of the test data format, and when using the space separated format all empty values must be escaped.

如果需要空值作为关键词或其他，经常需要将其转义避免被忽略。不管何种测试数据格式，结尾的空单元格必须被转义，当使用空格分割格式所有空值都必须转义。

Empty cells can be escaped either with the backslash character or with built-in variable ${EMPTY}. The latter is typically recommended as it is easier to understand. An exception to this recommendation is escaping the indented cells in for loops with a backslash when using the space separated format. All these cases are illustrated in the following examples first in HTML and then in the space separated plain text format:

空单元格可以使用反斜杠字符或内建变量${EMPTY}转义。由于更易理解，通常推荐使用后者。这种推荐的例外是当使用空格分割格式时，在循环使用反斜杠转义缩进的单元格。

=*** Test Cases ***=
Using backslash
    Do Something    first arg    \
Using ${EMPTY}
    Do Something    first arg    ${EMPTY}
Non-trailing empty
    Do Something    ${EMPTY}     second arg    # Escaping needed in space separated format
For loop
    :FOR    ${var}    IN    @{VALUES}
    \    Log    ${var}                         # Escaping needed here too

Prevent ignoring spaces

禁止忽略空格

Because leading, trailing, and consecutive spaces in cells are ignored, they need to be escaped if they are needed as arguments to keywords or otherwise. Similarly as when preventing ignoring empty cells, it is possible to do that either using the backslash character or using built-in variable ${SPACE}.

因为单元格中忽略开头，结尾和连续空格，如果它们作为关键词的参数或其他需要被转义。与阻止转义空单元格类似，可以使用反斜杠字符或内建变量${SPACE}进行转义。

Escaping spaces examples

As the above examples show, using the ${SPACE} variable often makes the test data easier to understand. It is especially handy in combination with the extended variable syntax when more than one space is needed.

正如上面显示的例子，使用${SPACE}通常使测试数据更容易理解。当需要多余一个空格时和扩展变量语法配合特别方便。

Dividing test data to several rows

将测试数据分割为几行

If there is more data than readily fits a row, it possible to use ellipsis (…) to continue the previous line. In test case and keyword tables, the ellipsis must be preceded by at least one empty cell. In settings and variable tables, it can be placed directly under the setting or variable name. In all tables, all empty cells before the ellipsis are ignored.

如果如何一行的数据超过预期，使用省略号（…）继续前一行。在测试用例和关键词表格中。省略号将被预处理为至少一个空白单元格。在设置和变量表格中，可直接置于在设置和变量名下。在所有表格中，忽略省略号前所有空单元格。

Additionally, values of settings that take only one value (mainly documentations) can be split to several columns. These values will be then catenated together with spaces when the test data is parsed. Starting from Robot Framework 2.7, documentation and test suite metadata split into multiple rows will be catenated together with newlines.

此外，只需要一个值的设置（主要是记录）的取值可以分割为几列。当分析测试数据时这些值将与空格相加。从 Robot Framework 2.7 开始，分割为多行的记录和测试套件元数据将与换行相加。

All the syntax discussed above is illustrated in the following examples. In the first three tables test data has not been split, and the following three illustrate how fewer columns are needed after splitting the data to several rows.

上面讨论的语法在下面的例子中应用。前三个表中没有分割测试数据，后面三个例子说明了将数据分割为多行之后需要更少的列。

Test data that has not been split

Test data split to several rows

Basic syntax

基本语法

Test cases are constructed in test case tables from the available keywords. Keywords can be imported from test libraries or resource files, or created in the keyword table of the test case file itself.

测试用例通过可用的关键词在测试用例表中构造。关键词可以从测试库或者资源文件中导入，或在测试文件本身的关键词表中创建。

The first column in the test case table contains test case names. A test case starts from the row with something in this column and continues to the next test case name or to the end of the table. It is an error to have something between the table headers and the first test.

测试用例表的第一列包含测试用例名字。测试用例开始于包含该列的行，直到下个测试用例名字或该用例表结束。在表头和第一个测试之间有任何东西都是错误的。

The second column normally has keyword names. An exception to this rule is setting variables from keyword return values, when the second and possibly also the subsequent columns contain variable names and a keyword name is located after them. In either case, columns after the keyword name contain possible arguments to the specified keyword.

第二列通常有关键词名字。该规则例外是从关键词的返回值设置变量，第二列以及其后可能存在的列包含变量名字，最后是关键词。这种情况下，关键词名字后面的列可能是该关键词可能的参数。

=*** Test Cases ***=
Valid Login
    Open Login Page
    Input Username    demo
    Input Password    mode
    Submit Credentials
    Welcome Page Should Be Open

Setting Variables
    Do Something    first argument    second argument
    ${value} =    Get Some Value
    Should Be Equal    ${value}    Expected value

Settings in the Test Case table

测试用例表中的设置

Test cases can also have their own settings. Setting names are always in the second column, where keywords normally are, and their values are in the subsequent columns. Setting names have square brackets around them to distinguish them from keywords. The available settings are listed below and explained later in this section.

测试用例可以有自己的设置。测试名字总是放在第二列，该列通常是关键词，它们的取值位于随后的列中。设置名字必须被方括号包围

• [Documentation]

  Used for specifying a test case documentation.

  用来指定测试用例的文档说明。

• [Tags]

  Used for tagging test cases.

  用来标记测试用例。

• [Setup], [Teardown]

  Specify test setup and teardown.

  指定测试的 setup 和 teardown。

• [Template]

  Specifies the template keyword to use. The test itself will contain only data to use as arguments to that keyword.

  指定使用的板关键词。测试本身将只包含该关键词使用的数据。

• [Timeout]

  Used for setting a test case timeout. Timeouts are discussed in their own section.

  设置测试用例的超时时间。超时将在相关的章节谈论。

Example test case with settings:

包含设置的测试用例如下：

=*** Test Cases ***=
Test With Settings
    [Documentation]    Another dummy test
    [Tags]    dummy    owner-johndoe
    Log    Hello, world!

Test case related settings in the Setting table

设置表格中测试用例相关的设置

The Setting table can have the following test case related settings. These settings are mainly default values for the test case specific settings listed earlier.

设置表中可以有如下测试现相关的设置。这些设置主要是前面列出的测试用例的具体设置的默认值。

• Force Tags, Default Tags

  强制标签，默认标签

  The forced and default values for tags.

• Test Setup, Test Teardown

  The default values for test setup and teardown.

• Test Template

  测试模板

  The default template keyword to use.

  使用的默认模板关键词。

• Test Timeout

  The default value for test case timeout. Timeouts are discussed in their own section.

  测试用例超时的默认值。后面章节将会讨论超时。

The earlier examples have already demonstrated keywords taking different arguments, and this section discusses this important functionality more thoroughly. How to actually implement user keywords and library keywords with different arguments is discussed in separate sections.

前面的例子已经证明了关键词可以取不同的参数，本章节更加深入的讨论这个关键的功能。单独的部分讨论了如何使用实现带不同参数的用户关键词和库关键词。

Keywords can accept zero or more arguments, and some arguments may have default values. What arguments a keyword accepts depends on its implementation, and typically the best place to search this information is keyword's documentation. In the examples in this section the documentation is expected to be generated using the Libdoc tool, but the same information is available on documentation generated by generic documentation tools such as javadoc.

关键词可以接受零个或更多参数，一些参数可以有默认值。关键词接受何参数取决于实现，通常最好在关键词的文档中搜寻该信息。本节中例子的文档将使用 Libdoc 工具生成，但同样的信息也可能通用文档工具，比如 javadoc，生成的文档中。

The test case name comes directly from the Test Case table: it is exactly what is entered into the test case column. Test cases in one test suite should have unique names. Pertaining to this, you can also use the automatic variable ${TEST_NAME} within the test itself to refer to the test name. It is available whenever a test is being executed, including all user keywords, as well as the test setup and the test teardown.

测试用例名字直接来自 Test Case 表：就是测试用例列中输入的内容。测试套件中的测试用例应该有唯一的名字。为了说明这个，可以使用测试本身的自动变量${TEST_NAME}引用测试名字。当执行测试的时候它是可用的，还有所有用户关键词，测试 setup 和测试 teardown。

The [Documentation] setting allows you to set a free documentation for a test case. That text is shown in the command line output, as well as the resulting test logs and test reports. It is possible to use simple HTML formatting in documentation and variables can be used to make the documentation dynamic.

[Documentation]设置允许为测试用例设置自由的文档。文本内容将显示在命令行输出上，以及由此产生的日志和报告中。在文档和变量中可以使用 HTML 格式，可用于动态生成文档。

If documentation is split into multiple columns, cells in one row are concatenated together with spaces. This is mainly be useful when using the HTML format and columns are narrow. If documentation is split into multiple rows, the created documentation lines themselves are concatenated using newlines. Newlines are not added if a line already ends with a newline or an escaping backslash.

如果文档分为多列，每行单元格使用空格连接。这对于使用 HTML 格式 narrow 列的时候有用。如果文档分割为多行，它们滋生创建的文档使用换行符连接。如果一行行尾已经使用换行符或转义反斜杠，就不会添加换行。

=*** Test Cases ***=
Simple
    [Documentation]    Simple documentation
    No Operation

Formatting
    [Documentation]    *This is bold*, _this is italic_  and here is a link: http://robotframework.org
    No Operation

Variables
    [Documentation]    Executed at ${HOST} by ${USER}
    No Operation

Splitting
    [Documentation]    This documentation    is split    into multiple columns
    No Operation

Many lines
    [Documentation]    Here we have
    ...                an automatic newline
    No Operation

It is important that test cases have clear and descriptive names, and in that case they normally do not need any documentation. If the logic of the test case needs documenting, it is often a sign that keywords in the test case need better names and they are to be enhanced, instead of adding extra documentation. Finally, metadata, such as the environment and user information in the last example above, is often better specified using tags.

重要的是测试用例有明确的和描述型的名字，这种情况下它们通常不需要任何文档。如果测试用例的逻辑需要文档，通常这表明测试用例中的关键词需要更好的名字，需要被加强，包括添加额外文档。最后，元数据，比如上面最后一个列子中的环境变量和用户信息通常使用标签更好的指定。

Using tags in Robot Framework is a simple, yet powerful mechanism for classifying test cases. Tags are free text and they can be used at least for the following purposes:

在 Robot Framework 中使用标签很简单，这也是对测试用例进行分类的强大工具。tag 是任意文本，至少可用于一下目的：

• Tags are shown in test reports, logs and, of course, in the test data, so they provide metadata to test cases.

  标签可以显示在测试报告，日志，当然还有测试数据中，所以它们提供测试用例的元数据。

• Statistics about test cases (total, passed, failed are automatically collected based on tags).

  统计测试测试用例信息（总数，通过，失败，基于标签自动搜集）

• With tags, you can include or exclude test cases to be executed.

  使用标签，可以指定执行包含或排除的测试用例。

• With tags, you can specify which test cases are considered critical.

  使用标签，可以指定哪些测试用例是关键的。

In this section it is only explained how to set tags for test cases, and different ways to do it are listed below. These approaches can naturally be used together.

本章节中直接是如何为测试用例设置标签，以及下面所列的不同的设置方式。这些方法可以自然的一起使用。

• Force Tags in the Setting table

  Setting 表中的强制标签

  All test cases in a test case file with this setting always get specified tags. If it is used in the test suite initialization file, all test cases in sub test suites get these tags.

  测试用例文件中使用该设置的所有测试用例总是获得指定标签。如果测试套件初始化文件中使用，子测试套件中所有的测试用例都会获得这些标签。

• Default Tags in the Setting table

  Setting 表中的默认标签。

  Test cases that do not have a [Tags] setting of their own get these tags. Default tags are not supported in test suite initialization files.

  自身没有[Tags]设定的测试用例将会使用这些标签。默认标签不支持谓语测试套件初始化文件中。

• [Tags] in the Test Case table

  测试用例表中[Tags]

  A test case always gets these tags. Additionally, it does not get the possible tags specified with Default Tags, so it is possible to override the Default Tags by using empty value. It is also possible to use value NONE to override default tags.

  测试用例总会得到这些标签。此外，不会获得默认标签指定的可能的标签。所以可以使用空值覆盖默认标签的值。可以使用 NONE 覆盖默认标签。

• –settag command line option

  –settag 命令行选项

  All executed test cases get tags set with this option in addition to tags they got elsewhere.

  除了其他地方的标签，所有执行的测试用例获得使用该选项设置的标签。

• Set Tags, Remove Tags, Fail and Pass Execution keywords

  Set Tags, Remove Tags, Fail and Pass Execution 关键词

  These BuiltIn keywords can be used to manipulate tags dynamically during the test execution.

  这些 BuiltIn 关键词可以用动态维护测试执行时的标签。

Tags are free text, but they are normalized so that they are converted to lowercase and all spaces are removed. If a test case gets the same tag several times, other occurrences than the first one are removed. Tags can be created using variables, assuming that those variables exist.

标签是任意文本，但它们是标准化的，所以它们转换为小写，移除了所有空格。如果测试用例几次获得相同的标签，其他发生在第一次之后的将被移除。可以使用变量创建标签，假设存在这些变量。

=*** Settings ***=
Force Tags      req-42
Default Tags    owner-john    smoke

=*** Variables ***=
${HOST}         10.0.1.42

=*** Test Cases ***=
No own tags
    [Documentation]    This test has tags owner-john, smoke and req-42.
    No Operation

With own tags
    [Documentation]    This test has tags not_ready, owner-mrx and req-42.
    [Tags]    owner-mrx    not_ready
    No Operation

Own tags with variables
    [Documentation]    This test has tags host-10.0.1.42 and req-42.
    [Tags]    host-${HOST}
    No Operation

Empty own tags
    [Documentation]    This test has only tag req-42.
    [Tags]
    No Operation

Set Tags and Remove Tags Keywords
    [Documentation]    This test has tags mytag and owner-john.
    Set Tags    mytag
    Remove Tags    smoke    req-*

Robot Framework has similar test setup and teardown functionality as many other test automation frameworks. In short, a test setup is something that is executed before a test case, and a test teardown is executed after a test case. In Robot Framework setups and teardowns are just normal keywords with possible arguments.

和其他很多自动化测试框架一样，Robot Framework 也有测试设置和清楚功能。简而言之，测试设置就是在执行测试用例之前所做的事情，测试清楚是测试用例之后所做的事情。Robot Framework 中测试设置和清理只是可能带有参数的正常关键词。

Setup and teardown are always a single keyword. If they need to take care of multiple separate tasks, it is possible to create higher-level user keywords for that purpose. An alternative solution is executing multiple keywords using the BuiltIn keyword Run Keywords.

Setup 和 teardown 总是单个关键字。如果它们需要考虑多个安顿的任务，可使用用户关键词创建更高级别的用户关键词。执行多个关键词的另一个解决方案是使用 BuiltIn 关键字 Run。

The test teardown is special in two ways. First of all, it is executed also when a test case fails, so it can be used for clean-up activities that must be done regardless of the test case status. In addition, all the keywords in the teardown are also executed even if one of them fails. This continue on failure functionality can be used also with normal keywords, but inside teardowns it is on by default.

test teardown 在两方面是特殊的。首先，当测试用例失败时也会执行，所以，它可以用于不管测试用例状态是什么都需要做的清理活动。除此之外，teardown 中的所有关键字都会执行，即使它们其中的某一个失败了，这种失败情况下仍会继续继续的功能可以用普通关键，但在 teardown 内部是默认启用的。

The easiest way to specify a setup or a teardown for test cases in a test case file is using the Test Setup and Test Teardown settings in the Setting table. Individual test cases can also have their own setup or teardown. They are defined with the [Setup] or [Teardown] settings in the test case table and they override possible Test Setup and Test Teardown settings. Having no keyword after a [Setup] or [Teardown] setting means having no setup or teardown. It is also possible to use value NONE to indicate that a test has no setup/teardown.

为一个测试用例指定 setup 和 teardown 最简单的方法是在 Setting 表中使用 Test Setup 和 Test Teardown。单独的测试用例还可以有自己的 setup 和 teardown。在测试用例表中使用[Setup] or [Teardown]定义设置，它们可能会覆盖 Test Setup and Test Teardown 设置。[Setup] or [Teardown]之后没有关键字意味着没有 setup 或 teardown。使用值 NONE 指示一个测试没有 setup/teardown 也是可能的。

=*** Settings ***=
Test Setup       Open Application    App A
Test Teardown    Close Application

=*** Test Cases ***=
Default values
    [Documentation]    Setup and teardown from setting table
    Do Something

Overridden setup
    [Documentation]    Own setup, teardown from setting table
    [Setup]    Open Application    App B
    Do Something

No teardown
    [Documentation]    Default setup, no teardown at all
    Do Something
    [Teardown]

No teardown 2
    [Documentation]    Setup and teardown can be disabled also with special value NONE
    Do Something
    [Teardown]    NONE

Using variables
    [Documentation]    Setup and teardown specified using variables
    [Setup]    ${SETUP}
    Do Something
    [Teardown]    ${TEARDOWN}

The name of the keyword to be executed as a setup or a teardown can be a variable. This facilitates having different setups or teardowns in different environments by giving the keyword name as a variable from the command line.

作为 setup 或 teardown 执行的关键词的名字可以是变量。这个功能有助于根据不同的环境设置不同的 setups 或 teardowns，而作为变量的关键词名字可以来自命令行。

Note

Test suites can have a setup and teardown of their own. A suite setup is executed before any test cases or sub test suites in that test suite, and similarly a suite teardown is executed after them.

测试套件可以有自己的 setup 和 teardown。测试套件的 setup 在套件中任何测试用例或子测试套件之前执行，类似的测试套件 teardown 在它们之后执行。

Test templates convert normal keyword-driven test cases into data-driven tests. Whereas the body of a keyword-driven test case is constructed from keywords and their possible arguments, test cases with template contain only the arguments for the template keyword. Instead of repeating the same keyword multiple times per test and/or with all tests in a file, it is possible to use it only per test or just once per file.

Template keywords can accept both normal positional and named arguments, as well as arguments embedded to the keyword name. Unlike with other settings, it is not possible to define a template using a variable.

There are several different ways in which test cases may be written. Test cases that describe some kind of workflow may be written either in keyword-driven or behavior-driven style. Data-driven style can be used to test the same workflow with varying input data.