Project pages

The number one place to find more information about Robot Framework is the project web site at http://robotframework.org. This User Guide is naturally available there but you can also find more documentation, an issue tracker, downloads, source code and links to other related projects. Robot Framework is hosted on Google Code which provides excellent free services for open source projects.

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.

robotframework-commit

Automatically generated mails about commits to the version control system, build results, new and edited issues, and so on. Can be used to follow Robot Framework development.

Supported installation approaches

Robot Framework is implemented with Python and also runs on Jython (JVM) and IronPython (.NET) interpreters. Before installing the framework, an obvious precondition is installing the needed interpreters.

Different ways to install Robot Framework itself are listed below and explained more thoroughly in this chapter. All installation packages are available from http://downloads.robotframework.org.

Installing from source

You can get the source code either by downloading and extracting a source distribution or checking it out directly from version control system. After that you can install the framework by running python setup.py install command. This approach works on all operating systems and with all interpreters.

Using Windows installer

There are graphical installers for both 32 bit and 64 bit Windows systems.

Python package managers

Python package managers such as pip and easy_install make installation trivial.

Using One Click Installer

If you are using Windows XP and you do not have preconditions installed, One Click Installer can take care of installing everything.

Standalone JAR distribution

If running tests with Jython is enough, the easiest approach is downloading the standalone robotframework-<version>.jar that contains both Jython and Robot Framework.

Manual installation

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

Different entry points

# Run tests with Python by executing `robot.run` module.
python -m robot.run

# Run tests with Jython by running `robot/run.py` script.
jython path/to/robot/run.py

# Create reports/logs with IronPython by executing `robot.rebot` module.
ipy -m robot.rebot

# Create reports/logs with Python by running `robot/rebot.py` script.
python path/to/robot/rebot.py

$ pybot --version
Robot Framework 2.7 (Python 2.6.6 on linux2)

$ jybot --version
Robot Framework 2.7 (Jython 2.5.2 on java1.6.0_21)

Python installation

On most UNIX-like systems such as Linux and OSX you have Python installed by default. If you are on Windows or otherwise need to install Python yourself, your best 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.

Starting from Robot Framework 2.5, Python 2.5 is the minimum supported Python version. Earlier versions support also Python 2.3 and 2.4. Robot Framework is currently not compatible with Python 3.x versions.

Jython installation

Using test libraries implemented with Java or using Java tools internally requires running Robot Framework on Jython, which in turn requires Java Runtime Environment (JRE). 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.

Starting from Robot Framework 2.5, the minimum supported Jython version is 2.5 which requires Java 5 (a.k.a. Java 1.5) or newer. Earlier Robot Framework versions support also Jython 2.2.

IronPython installation

IronPython allows running Robot Framework on the .NET platform. Installation with IronPython is officially supported starting from Robot Framework 2.7. Only IronPython 2.7.x on .NET 4.0 series is officially supported and tested.

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

Setting 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 PATH. The runner scripts themselves require the matching interpreter to be in PATH, so the installation location must be added there too.

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

Installing from source

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.

# Installing with Python. Creates `pybot` and `rebot` scripts.
python setup.py install

# Installing with Jython. Creates `jybot` and `jyrebot` scripts.
jython setup.py install

# Installing with IronPython. Creates `ipybot` and `ipyrebot` scripts.
ipy setup.py install

Using Windows installer

There are separate graphical installers for 32 bit and 64 bit Windows systems. The former installer has name in format robotframework-<version>.win32.exe and the latter robotframework-<version>.win-amd64.exe, and both are available on the download page. Running the installer requires double-clicking it and following the simple instructions.

Windows installers always run on Python and create the standard pybot and rebot runner scripts. Unlike the other provided installers, these installers also automatically create jybot and ipybot scripts. To be able to use the created runner scripts, both the Scripts directory containing them and the appropriate interpreters need to be in PATH.

Python package managers

Python nowadays has various good package managers available for installing and otherwise managing Python packages. The most well known ones are easy_install and its successor pip. We highly recommend pip as it is more actively developed and has nice features such as uninstallation support.

Different package managers have different usage, but with pip and easy_install the basic usage is similar:

# Install the latest version
pip install robotframework
easy_install robotframework

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

# Install a specific version
pip install robotframework==2.7.1
easy_install robotframework==2.7.1

# Uninstall -- only supported by pip
pip uninstall robotframework

Using One Click Installer

The One Click Installer can install Robot Framework and its preconditions Python and Jython (optional). It also automatically puts Robot Framework runner scripts as well as Python and Jython executables into PATH.

The One Click Installer requires that you have downloaded all the required component installers separately and have them in the same directory with it. More detailed instructions and details about the supported installers are available on One Click Installer wiki page.

Standalone JAR distribution

Robot Framework is also distributed as a standalone Java archive that contains both Jython and Robot Framework and only requires Java 5 or newer as 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 Python.

The package is named robotframework-<version>.jar and it is available on the download page or as a Maven dependency. After downloading the package, you can execute tests with it like:

java -jar robotframework-2.7.jar mytests.txt
java -jar robotframework-2.7.jar --variable name:value mytests.txt

If you want to post-process outputs or use the built-in tools, you need to give the command name (e.g. rebot or libdoc) as the first argument to the JAR file:

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

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

Manual installation

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

1. Get the source code. All the code is in a directory (a module 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.
2. Copy the source code where you want to.
3. Create runner scripts you need or use the direct entry points with the interpreter of your choice.

Where files are installed

When an automatic installer is used, the Robot Framework 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, or when using easy_install in directory robotframework-<version>.py<version>.egg/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. On Windows and with other interpreters, the scripts are typically either in Scritps or bin directory under the interpreter installation directory.

Uninstallation

How to uninstall Robot Framework depends on the original installation method. Notice that if you have set PATH or configured your environment otherwise, you need to undo these changes separately.

python install.py uninstall

pip uninstall robotframework

Upgrading

When upgrading or downgrading Robot Framework, it is safe to install a new version over the existing when switching between two minor versions (e.g. from 2.7 to 2.7.1). This typically works also when upgrading to a new major version (e.g. from 2.6.3 to 2.7), but uninstalling the old version is always safer.

A very nice feature of pip package manager is that it automatically uninstalls old versions when upgrading. This happens both when changing to a specific version or when upgrading to the latest version:

pip install robotframework==2.7.1
pip install --upgrade robotframework

The custom install.py script included in the source distribution also supports re-installation that automatically removes the old installation first:

python install.py reinstall

Regardless on the version and installation method, you do not need to reinstall preconditions or set PATH environment variable again.

HTML format

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.

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

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

TSV format

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.

Plain text format

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 ( | ).

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.

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.

*** Settings ***
Library     OperatingSystem

*** Variables ***
${MESSAGE}  Hello, world!

*** Test Cases ***
My Test  [Documentation]  Example test
    Log         ${MESSAGE}
    My Keyword  /tmp

Another Test
    Should Be Equal  ${MESSAGE}  Hello, world!

*** Keywords ***
My Keyword  [Arguments]  ${path}
    Directory Should Exist  ${path}

| *Setting*  |     *Value*     |
| Library    | OperatingSystem |

| *Variable* |     *Value*     |
| ${MESSAGE} | Hello, world!   |

| *Test Case*  | *Action*        | *Argument*   |
| My Test      | [Documentation] | Example test |
|              | Log             | ${MESSAGE}   |
|              | My Keyword      | /tmp         |
| Another Test | Should Be Equal | ${MESSAGE}   | Hello, world!

| *Keyword*  |
| My Keyword | [Arguments] | ${path}
|            | Directory Should Exist | ${path}

| ${file count} = | Execute Command | ls -1 *.txt \| wc -l |
| Should Be Equal | ${file count}   | 42                   |

reStructuredText format

reStructuredText (reST) is a easy-to-read plain text markup syntax that is commonly used for documentation of Python projects (including Python itself, as well as this user guide). Using reST with Robot Framework allows you to mix richly formatted documents and tables that specify test data in a concise text format that is easy to work with using simple text editors, diff tools, and source control systems.

Tools to process reStructuredText are freely available as part of the docutils project, and there is a quick reference guide that shows the most common formatting constructs including the tables used by Robot Framework. Notice that Robot Framework converts test data in reST format internally to HTML before starting to actually parse it. The data must thus follow reST syntax strictly or otherwise processing it will not succeed.

In reST files, test data is defined in tables within the document, similar to the HTML format. Robot Framework identifies test data tables based on the text in the first cell and all content outside of the recognized table types is ignored.

An example of each of the four test data tables is shown below using the reST Simple Tables syntax. Note that \ or .. must be used to indicate an empty cell in the first column of the table:

============  ================  =======  =======
  Setting          Value         Value    Value
============  ================  =======  =======
Library       OperatingSystem
============  ================  =======  =======


============  ================  =======  =======
  Variable         Value         Value    Value
============  ================  =======  =======
${MESSAGE}    Hello, world!
============  ================  =======  =======


============  ===================  ============  =============
 Test Case          Action           Argument      Argument
============  ===================  ============  =============
My Test       [Documentation]      Example test
\             Log                  ${MESSAGE}
\             My Keyword           /tmp
\
Another Test  Should Be Equal      ${MESSAGE}    Hello, world!
============  ===================  ============  =============


============  ======================  ============  ==========
 Keyword            Action             Argument     Argument
============  ======================  ============  ==========
My Keyword    [Arguments]             ${path}
\             Directory Should Exist  ${path}
============  ======================  ============  ==========

Ignored data

When Robot Framework parses the test data, it ignores:

• 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.
• Data outside tables in HTML/reST and data before the first table in TSV.
• 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; you must add a backslash (\) to prevent such cells from being ignored.
• All single backslashes (\); they are used as an escape character.
• All characters following a hash mark (#), if 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.

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, or available to, for example, RIDE, place it to the documentation or other metadata of test cases or suites, or log with the Log or Comment keywords available from the BuiltIn library.

Escaping

The escape character for the Robot Framework parser is the backslash (\). The escape character can be used as follows:

• To escape special characters so that their literal values are used:
  • \${notvar} means a literal string ${notvar} that looks like a variable
  • \\ means a single backslash (for example, C:\\Temp)
  • \# means a literal hash (#) mark, even at the beginning of a cell
• To affect the parsing of whitespaces.
• To prevent ignoring empty cells at the end of a row in general and everywhere when using the plain text format. Another, and often clearer, possibility is using built-in variable ${EMPTY}.
• To escape pipe character when using the pipe and space separated format.
• To escape indented cells in for loops when using the plain text format.
• To prevent catenating documentation split into multiple rows with newlines.

Handling whitespace

Robot Framework handles whitespace, such as spaces, newlines and tabs, the same way as they are handled in HTML. This means that Robot Framework:

• Removes leading and trailing whitespace in all cells.
• Changes multiple consecutive spaces into single spaces.
• Converts all newlines and tabs into spaces.

To prevent Robot Framework from parsing data according to these rules, a backslash can be used:

• Before leading spaces, for example \ some text.
• Between consecutive spaces, for example text \ \ more text.
• After trailing spaces, for example some text \ \.
• As \n to create a newline, for example first line\n2nd line.
• As \t to create a tab character, for example text\tmore text.
• As \r to create a carriage return, for example text\rmore text.

Another, and often clearer, possibility for representing leading, trailing, or consecutive spaces is using built-in variable ${SPACE}. The extended variable syntax even allows syntax like ${SPACE * 8} which makes handling consecutive spaces very simple.

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 user 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.

All these syntaxes are 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 Case       Action           Argument      Argument    Argument
===========  ================  ==============  ==========  ==========
Example      [Documentation]   Documentation   for this    test case.
\            ...               This can get    quite       long...
\            [Tags]            t-1             t-2         t-3
\            ...               t-4             t-5
\            Do X              one             two         three
\            ...               four            five        six
\            ${var} =          Get X           1           2
\            ...               3               4           5
\            ...               6
===========  ================  ==============  ==========  ==========

+-----------+-------------------+---------------+------------+------------+
| Test Case |      Action       |   Argument    |  Argument  |  Argument  |
+===========+===================+===============+============+============+
| Example   | [Documentation]   | Documentation | for this   | test case. |
+-----------+-------------------+---------------+------------+------------+
|           | ...               | This can get  | quite      | long...    |
+-----------+-------------------+---------------+------------+------------+
|           | [Tags]            | t-1           | t-2        | t-3        |
+-----------+-------------------+---------------+------------+------------+
|           | ...               | t-4           | t-5        |            |
+-----------+-------------------+---------------+------------+------------+
|           | Do X              | one           | two        | three      |
+-----------+-------------------+---------------+------------+------------+
|           | ...               | four          | five       | six        |
+-----------+-------------------+---------------+------------+------------+
|           | ${var} =          | Get X         | 1          | 2          |
+-----------+-------------------+---------------+------------+------------+
|           | ...               | 3             | 4          | 5          |
+-----------+-------------------+---------------+------------+------------+
|           | ...               | 6             |            |            |
+-----------+-------------------+---------------+------------+------------+

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.

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. Have also synonyms [Precondition] and [Postcondition], respectively.

[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.

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. Have also synonyms Test Precondition and Test Postcondition, respectively.

Test Template

The default template keyword to use.

Test Timeout

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

Required arguments

Most keywords have a certain number of arguments that must always be given. In the keyword documentation this is denoted by specifying the argument names separated with a comma like first, second, third. The argument names actually do not matter in this case, except that they should explain what the argument does, but it is important to have exactly the same number of arguments as specified in the documentation. Using too few or too many arguments will result in an error.

The test below uses keywords Create Directory and Copy File from the OperatingSystem library. Their arguments are specified as path and source, destination which means that they take one and two arguments, respectively. The last keyword, No Operation from BuiltIn, takes no arguments.

Default values

Arguments often have default values which can either be given or not. In the documentation the default value is typically separated from the argument name with an equal sign like name=default value, but with keywords implemented using Java there may be multiple implementations of the same keyword with different arguments instead. It is possible that all the arguments have default values, but there cannot be any positional arguments after arguments with default values.

Using default values is illustrated by the example below that uses Create File keyword which has arguments path, content=, encoding=UTF-8. Trying to use it without any arguments or more than three arguments would not work.

Variable number of arguments

It is also possible to create keywords that accept any number of arguments. These arguments can be combined with mandatory arguments and arguments with default values, but the so called varargs are always the last ones. In the documentation they typically have an asterisk before the argument name like *varargs , but there are again differences with Java libraries.

Remove Files and Join Paths keywords used in the example below have arguments *paths and base, *parts, respectively. The former can be used with any number of arguments, but the latter requires at least one argument.

Named arguments

When a keyword accepts more than one argument with a default value, overriding only the last one using positional argument is not possible. For example, if a keyword having arguments arg1=a, arg2=b, arg3=c is used as in the test below, its arguments arg1 and arg2 both get an empty string as value instead of their default values.

To make giving only some of the arguments that expect default values easier, new named arguments syntax was added in Robot Framework 2.5. With this syntax the arguments that need to override their default values are given immediately after the required arguments in format argname=value. The arguments that should use defaults can be simply be left out. How this works in practice is illustrated by the example test below that uses the same keyword as the above example. In this example the arguments that are not specified will get their default values.

The named argument syntax can naturally be used with arguments accepting default values also when no arguments are left away. This can make argument meanings more clear than when only the value is shown. Naming the required arguments this way is not possible, though. Additionally, it is not possible to give first named arguments and then varargs.

The biggest limitation of the name arguments functionality is that it currently works only with user keywords and with library keywords implemented with Python that use either the static library API or the hybrid library API. It is possible that support for Java libraries and for the dynamic library API is added in the future. Until that it is possible to create user keywords that wrap the incompatible keywords.

The named argument syntax is used only when the part of the argument before the equal sign matches the name of an argument with a default value. This matching is started from the end of the given argument list and stopped when there is no match. In those rare cases when there are accidental matches, it is possible to use \ to escape this syntax like nomatch\=here.

The following example demonstrates using named arguments in different scenarios, including in test library imports.

Arguments embedded to keyword names

A totally different approach to specify arguments is embedding them into keyword names. This syntax is, at least currently, only supported by user keywords.

Keyword-driven style

Workflow tests, such as the Valid Login test described earlier, are constructed from several keywords and their possible arguments. Their normal structure is that first the system is taken into the initial state (Open Login Page in the Valid Login example), then something is done to the system (Input Name, Input Password, Submit Credentials), and finally it is verified that the system behaved as expected (Welcome Page Should Be Open).

Data-driven style

Another style to write test cases is the data-driven approach where test cases use only one higher-level keyword, normally created as a user keyword, that hides the actual test workflow. These tests are very useful when there is a need to test the same scenario with different input and/or output data. It would be possible to repeat the same keyword with every test, but the test template functionality allows specifying the keyword to use only once.

The above example has six separate tests, one for each invalid user/password combination, and the example below illustrates how to have only one test with all the combinations. When using test templates, all the rounds in a test are executed even if there are failures, so there is no real functional difference between these two styles. In the above example separate combinations are named so it is easier to see what they test, but having potentially large number of these tests may mess-up statistics. Which style to use depends on the context and personal preferences.

Behavior-driven style

It is also possible to write test cases as requirements that also non-technical project stakeholders must understand. These Executable Requirements are a corner stone of a process commonly called Acceptance Test Driven Development (ATDD).

One way to write these requirements/tests is Given-When-Then style popularized by Behavior Driven Development (BDD). When writing test cases in this style, the initial state is usually expressed with a keyword starting with word Given, the actions are described with keyword starting with When and the expectations with a keyword starting with Then. Keyword starting with And may be used if a step has more than one action.

Warning on invalid files

Normally files that do not have a valid test case table are silently ignored with a message written to the syslog. As of Robot Framework 2.5.5 it is possible to use a command line option --warnonskippedfiles, which turns the message into a warning shown in test execution errors.

Initialization files

A test suite created from a directory can have similar settings as a suite created from a test case file. Because a directory alone cannot have that kind of information, it must be placed into a special test suite initialization file. Initialization files have the same structure and syntax as test case files, except that they cannot have test case tables and not all settings are supported.

An initialization file name must always be of the format __init__.ext, where the extension must match one of the supported file formats (for example, __init__.html or __init__.txt). The name format is borrowed from Python, where files named in this manner denote that a directory is a module.

The main usage for initialization files is specifying test suite related settings similarly as in test case files, but setting some test case related settings is also possible. Variables and keywords created or imported in initialization files are not available in the lower level test suites, but resource files can be used if there is a need to share them.

How to use different settings in the initialization files:

Documentation, Metadata, Suite Setup, Suite Teardown

These test suite specific settings work the same way as in test case files.

Force Tags

Specified tags are unconditionally set to all test cases in all test case files this directory contains directly or recursively.

Test Setup, Test Teardown, Test Timeout

Set the default value for test setup/teardown or test timeout to all test cases this directory contains. Can be overridden on lower level. Support for defining test timeout in initialization files was added in Robot Framework 2.7.

Default Tags, Test Template

Not supported in initialization files.

Using Library setting

Test libraries are normally imported using the Library setting in the Setting table and having the library name in the subsequent column. The library name is case-sensitive (it is the name of the module or class implementing the library and must be exactly correct), but any spaces in it are ignored. With Python libraries in modules or Java libraries in packages, the full name including the module or package name must be used.

In those cases where the library needs arguments, they are listed in the columns after the library name. It is possible to use default values, variable number of arguments, and named arguments in test library imports similarly as with arguments to keywords. Both the library name and arguments can be set using variables.

It is possible to import test libraries in test case files, resource files and test suite initialization files. In all these cases, all the keywords in the imported library are available in that file. With resource files, those keywords are also available in other files using them.

Using Import Library keyword

Another possibility to take a test library into use is using the keyword Import Library from the BuiltIn library. This keyword takes the library name and possible arguments similarly as the Library setting. Keywords from the imported library are available in the test suite where the Import Library keyword was used. This approach is useful in cases where the library is not available when the test execution starts and only some other keywords make it available.

Library search path

The most common way to specify a test library to import is using its name, like it has been done in all the examples in this section. In these cases Robot Framework tries to find the class or module implementing the library from the library search path. Basically, this means that the library code and all its possible dependencies must be in PYTHONPATH or, when running tests on Jython, in a CLASSPATH. Setting the library search path is explained in a section of its own. Libraries can also set the search path automatically or have special instructions on how to do it. All standard libraries, for example, are in the library search path automatically.

The biggest benefit of this approach is that when the library search path has been configured, often using a custom start-up script, normal users do not need to think where libraries actually are installed. The drawback is that getting your own, possible very simple, libraries into the search path may require some additional configuration.

Using physical path to library

Another mechanism for specifying the library to import is using a path to it in the file system. This path is considered relative to the directory where current test data file is situated similarly as paths to resource and variable files. The main benefit of this approach is that there is no need to configure the library search path.

If the library is a file, the path to it must contain extension. For Python libraries the extension is naturally .py and for Java libraries it can either be .class or .java, but the class file must always be available. If Python library is implemented as a directory, the path to it must have a trailing forward slash (/). Following examples demonstrate these different usages.

A limitation of this approach is that libraries implemented as Python classes must be in a module with the same name as the class. Additionally, importing libraries distributed in JAR or ZIP packages is not possible with this mechanism.

BuiltIn library

The BuiltIn library provides a set of generic keywords needed often. It is imported automatically and thus always available. The provided keywords can be used, for example, for verifications (e.g. Should Be Equal, Should Contain), conversions (e.g. Convert To Integer) and for various other purposes (e.g. Log, Sleep, Run Keyword If, Set Global Variable).

The names of the keywords in the BuiltIn library have been renamed in Robot Framework version 1.8. All the old keywords still work, but the long names (the names visible in log files) of the keywords that are deprecated begin with DeprecatedBuiltIn. (for example, DeprecatedBuiltIn.Equals). It is highly recommended to use the new names of the keywords as the old versions will be removed altogether in the future.

For more information, see the BuiltIn library documentation.

OperatingSystem library

The OperatingSystem library enables various operating system related tasks to be performed in the system where Robot Framework is running. It can, among other things, execute commands (e.g. Run), create and remove files and directories (e.g. Create File, Remove Directory), check whether files or directories exists or contain something (e.g. File Should Exist, Directory Should Be Empty) and manipulate environment variables (e.g. Set Environment Variable).

The names of the keywords in the OperatingSystem library have been renamed in Robot Framework 1.8 similarly as the names of the BuiltIn keywords.

For more information, see the OperatingSystem library documentation.

Telnet library

The Telnet library makes it possible to connect to Telnet servers and execute commands on the opened connections.

For more information, see the Telnet library documentation.

Collections library

The Collections library provides a set of keywords for handling Python lists and dictionaries. This library has keywords, for example, for modifying and getting values from lists and dictionaries (e.g. Append To List, Get From Dictionary) and for verifying their contents (e.g. Lists Should Be Equal, Dictionary Should Contain Value).

For more information, see the Collections library documentation.

String library

The String library enables manipulating strings (e.g. Replace String With Regexp, Split To Lines) and verifying their contents (e.g. Should Be String).

For more information, see the String library documentation. This library is new in Robot Framework 2.1.

Dialogs library

The Dialogs library provides means for pausing the test execution and getting input from users. The dialogs are slightly different depending on are tests run on Python or Jython but they provide the same functionality.

For more information, see the Dialogs library documentation. This library is new in Robot Framework 2.1.

Screenshot library

The Screenshot library has keywords to capture and store screenshots of the whole desktop. This library is implemented with Java AWT APIs, so it can be used only when running Robot Framework on Jython.

For more information, see the Screenshot library documentation.

Remote library

The Remote library is totally different than the other standard libraries. It does not have any keywords of its own but it works as a proxy between Robot Framework and actual test library implementations. These libraries can be running on other machines than the core framework and can even be implemented using languages not supported by Robot Framework natively.

See separate Remote library interface section for more information about the concept. This library is new in Robot Framework 2.1.

Scalar variables

When scalar variables are used in the test data, they are replaced with the value they are assigned to. While scalar variables are most commonly used for simple strings, you can assign any objects, including lists, to them. The scalar variable syntax, for example ${NAME}, should be familiar to most users, as it is also used, for example, in shell scripts and Perl programming language.

The example below illustrates the usage of scalar variables. Assuming that the variables ${GREET} and ${NAME} are available and assigned to strings Hello and world, respectively, both the example test cases are equivalent.

When a scalar variable is used as the only value in a test data cell, the scalar variable is replaced with the value it has. The value may be any object. When a scalar variable is used in a test data cell with anything else (constant strings or other variables), its value is first converted into a Unicode string and then catenated to whatever is in that cell. Converting the value into a string means that the object's method __unicode__ (in Python, with __str__ as a fallback) or toString (in Java) is called.

The example below demonstrates the difference between having a variable in a cell alone or with other content. First, let us assume that we have a variable ${STR} set to a string Hello, world! and ${OBJ} set to an instance of the following Java object:

public class MyObj {

    public String toString() {
        return "Hi, tellus!";
    }
}

With these two variables set, we then have the following test data:

Finally, when this test data is executed, different keywords receive the arguments as explained below:

• KW 1 gets a string Hello, world!
• KW 2 gets an object stored to variable ${OBJ}
• KW 3 gets a string I said "Hello, world!"
• KW 4 gets a string You said "Hi, tellus!"

List variables

List variables are compound variables that can have several values assigned to them. In short, they are always lists and can contain an unlimited number of entries (also empty lists are possible). The main benefit of list variables is that they allow you to assign a name for a larger data set. While list variables normally contain only strings, other content is also possible.

When you use a list variable in test data, then the elements of the list are inserted as new cells in the test data. Thus, if the list variable contains two elements, the cell containing the list variable is turned into two cells with the content of the list variable. Note that cells with list variables should not contain other content. The list variable syntax, @{NAME}, is borrowed from Perl.

Assuming that the list variable @{USER} is set to the value ['robot','secret'], the following two test cases are equivalent.

Environment variables

Robot Framework allows using environment variables in the test data using the syntax %{ENV_VAR_NAME}. They are limited to string values.

Environment variables set in the operating system before the test execution are available during it, and it is possible to create new ones with the keyword Set Environment Variable or delete existing ones with the keyword Delete Environment Variable, both available in the OperatingSystem library. Because environment variables are global, environment variables set in one test case can be used in other test cases executed after it. However, changes to environment variables are not effective after the test execution.

Java system properties

When running tests with Jython, it is possible to access Java system properties using same syntax as environment variables. If an environment variable and a system property with same name exist, the environment variable will be used. Support for accessing Java system properties was added in Robot Framework 2.6.

Variable table

The most common source for variables are Variable tables in test case files and resource files. Variable tables are convenient, because they allow creating variables in the same place as the rest of the test data, and the needed syntax is very simple. Their main disadvantage is that they only enable assigning variables into strings or a list of strings. If other value types are needed, variable files are probably a better option.

Variable file

Variable files are the most powerful mechanism for creating different kind of variables. It is possible to assign variables to any object using them, and they also enable creating variables dynamically. The variable file syntax and taking variable files into use is explained in section Resource and variable files.

Setting variables in command line

Variables can be set from the command line either individually with the --variable (-v) option or using a variable file with the --variablefile (-V) option. Variables set from the command line are globally available for all executed test data files, and they also override possible variables with the same names in the Variable table and in variable files imported in the test data.

The syntax for setting individual variables is --variable name:value, where name is the name of the variable without ${} and value is its value. Several variables can be set by using this option several times. Only scalar variables can be set using this syntax and they can only get string values. Many special characters are difficult to represent in the command line, but they can be escaped with the --escape option.

--variable EXAMPLE:value
--variable HOST:localhost:7272 --variable USER:robot
--variable ESCAPED:Qquotes_and_spacesQ --escape quot:Q --escape space:_

In the examples above, variables are set so that

• ${EXAMPLE} gets the value value
• ${HOST} and ${USER} get the values localhost:7272 and robot
• ${ESCAPED} gets the value "quotes and spaces"

The basic syntax for taking variable files into use from the command line is --variablefile path/to/variables.py, and Taking variable files into use section has more details. What variables actually are created depends on what variables there are in the referenced variable file.

If both variable files and individual variables are given from the command line, the latter have higher priority.

Return values from keywords

Return values from keywords can also be set into variables. This allows communication between different keywords even in different test libraries. The syntax for a simple case is illustrated in the example below:

In the example above, the value returned by the Get X keyword is first set into the variable ${x} and then used by the Log keyword. This syntax works in all cases where a keywords returns something, and the variable is set to whatever value returned by the keyword. Having the equals sign = after the variable name is not obligatory, but recommended, because it makes the assignment more explicit.

If a keyword returns a list, it is also possible to assign the return value into several scalar variables and/or one list variable. Starting from Robot Framework 2.5 this works with all list-like objects, but prior to it only Python lists and tuples and Java arrays were supported.

Assuming that the keyword Get 3 returns a list [1, 2, 3], the following variables are created:

• ${scalar} with the value [1, 2, 3]
• ${a}, ${b} and ${c} with the values 1, 2, and 3, respectively
• ${first} with the value 1, and @{rest} with the value [2, 3]
• @{list} with the value [1, 2, 3]

Variables set in this manner are otherwise similar to any other variables, but they are available only within the scope of the test case or keyword where they are created. Thus it is not possible, for example, to set a variable in one test case and use it in another. This is because, in general, automated test cases should not depend on each other, and accidentally setting a variable that is used elsewhere could cause hard-to-debug errors. If there is a genuine need for setting a variable in one test case and using it in another, it is possible to use built-in keywords as explained in the next section.

Using built-in Set Test/Suite/Global Variable keywords

The BuiltIn library has keywords Set Test Variable, Set Suite Variable and Set Global Variable which can be used for setting variables dynamically during the test execution. If a variable already exists within the new scope, its value will be overwritten, and otherwise a new variable is created.

Variables set with Set Test Variable keyword are available everywhere within the scope of the currently executed test case. For example, if you set a variable in a user keyword, it is available both in the test case level and also in all other user keywords used in the current test. Other test cases will not see variables set with this keyword.

Variables set with Set Suite Variable keyword are available everywhere within the scope of the currently executed test suite. Setting variables with this keyword thus has the same effect as creating them using the Variable table in the test data file or importing them from variable files. Other test suites, including possible child test suites, will not see variables set with this keyword.

Variables set with Set Global Variable keyword are globally available in all test cases and suites executed after setting them. Setting variables with this keyword thus has the same effect as creating from the command line using the options --variable or --variablefile. Because this keyword can change variables everywhere, it should be used with care.

Operating-system variables

Built-in variables related to the operating system ease making the test data operating-system-agnostic.

Number variables

The variable syntax can be used for creating both integers and floating point numbers, as illustrated in the example below. This is useful when a keyword expects to get an actual number, and not a string that just looks like a number, as an argument.

Starting from Robot Framework 2.6, it is possible to create integers also from binary, octal, and hexadecimal values using 0b, 0o and 0x prefixes, respectively. The syntax is case insetive.

Boolean and None/null variables

Also Boolean values and Python None and Java null can be created using the variable syntax similarly as numbers.

These variables are case-insensitive, so for example ${True} and ${true} are equivalent. Additionally, ${None} and ${null} are synonyms, because when running tests on the Jython interpreter, Jython automatically converts None and null to the correct format when necessary.

Space and empty variables

It is possible to create spaces and empty strings using variables ${SPACE} and ${EMPTY}, respectively. These variables are useful, for example, when there would otherwise be a need to escape spaces or empty cells with a backslash. If more than one space is needed, it is possible to use the extended variable syntax like ${SPACE * 5}. In the following example, Should Be Equal keyword gets identical arguments but those using variables are easier to understand than those using backslashes.

Automatic variables

Some automatic variables can also be used in the test data. These variables can have different values during the test execution and some of them are not even available all the time.

Variable priorities

Variables from the command line

Variables set in the command line have the highest priority of all variables that can be set before the actual test execution starts. They override possible variables created in Variable tables in test case files, as well as in resource and variable files imported in the test data.

Individually set variables (--variable option) override the variables set using variable files (--variablefile option). If you specify same individual variable multiple times, the one specified last will override earlier ones. This allows setting default values for variables in a start-up script and overriding them from the command line. Notice, though, that if multiple variable files have same variables, the ones in the file specified first have the highest priority.

Variable table in a test case file

Variables created using the Variable table in a test case file are available for all the test cases in that file. These variables override possible variables with same names in imported resource and variable files.

Variables created in the variable tables are available in all other tables in the file where they are created. This means that they can be used also in the Setting table, for example, for importing more variables from resource and variable files.

Imported resource and variable files

Variables imported from the resource and variable files have the lowest priority of all variables created in the test data. Variables from resource files and variable files have the same priority. If several resource and/or variable file have same variables, the ones in the file imported first are taken into use.

If a resource file imports resource files or variable files, variables in its own Variable table have a higher priority than variables it imports. All these variables are available for files that import this resource file.

Note that variables imported from resource and variable files are not available in the Variable table of the file that imports them. This is due to the Variable table being processed before the Setting table where the resource files and variable files are imported.

Variables set during test execution

Variables set during the test execution either using return values from keywords or built-in keywords Set Test/Suite/Global Variable always override possible existing variables in the scope where they are set. In a sense they thus have the highest priority, but on the other hand they do not affect variables outside the scope they are defined.

Built-in variables

Built-in variables like ${TEMPDIR} and ${TEST_NAME} have the highest priority of all variables. They cannot be overridden using Variable table or from command line, but even they can be reset during the test execution. An exception to this rule are number variables, which are resolved dynamically if no variable is found otherwise. They can thus be overridden, but that is generally a bad idea. Additionally ${CURDIR} is special because it is replaced already during the test data processing time.

Variable scopes

Depending on where and how they are created, variables can have a global, test suite, test case or user keyword scope.

Global scope

Global variables are available everywhere in the test data. These variables are normally set from the command line with the --variable and --variablefile options, but it is also possible to create new global variables or change the existing ones with the BuiltIn keyword Set Global Variable anywhere in the test data. Additionally also built-in variables are global.

It is recommended to use capital letters with all global variables.

Test suite scope

Variables with the test suite scope are available anywhere in the test suite where they are defined or imported. They can be created in Variable tables, imported from resource and variable files, or set during the test execution using the BuiltIn keyword Set Suite Variable.

The test suite scope is not recursive, which means that variables available in a higher-level test suite are not available in lower-level suites. If necessary, resource and variable files can be used for sharing variables.

Since these variables can be considered global in the test suite where they are used, it is recommended to use capital letters also with them.

Test case scope

Variables created in test cases from the return values of keywords have a test case scope and they are available only in that test case. Another possibility to create them is using the BuiltIn keyword Set Test Variable anywhere in that particular test case. Test case variables are local and should use lower-case letters.

User keyword scope

User keywords get their own variables from arguments passed to them and return values from the keywords they use. Also these variables are local and should use lower-case letters.

Extended variable syntax

Extended variable syntax can be used with objects set into scalar variables. It allows accessing the attributes of the object (for example, ${obj.name} or ${obj.some_attr}), and even calling its methods (for example, ${obj.get_name()} or ${obj.getSomething('arg')}).

Extended variable syntax is a powerful feature, but it should be used with care. Accessing attributes is normally not a problem, on the contrary, as one variable with an object having several attributes is often better than having several variables. On the other hand, calling methods, especially when they are used with arguments, can make the test data complicated. If that happens, it is recommended to move the code into a test library.

The most common usages of extended variable syntax are illustrated in the example below. First assume that we have the following variable file and test case:

class MyObject:

    def __init__(self, name):
        self.name = name

    def eat(self, what):
        return '%s eats %s' % (self.name, what)

    def __str__(self):
        return self.name

OBJECT = MyObject('Robot')
DICTIONARY = { 1: 'one', 2: 'two', 3: 'three'}

When this test data is executed, the keywords get the arguments as explained below:

• KW 1 gets string Robot
• KW 2 gets string Robot eats Cucumber
• KW 3 gets string two

The extended variable syntax is evaluated in the following order:

1. The variable is searched using the full variable name. The extended variable syntax is evaluated only if no matching variable is found.
2. The real name of the base variable is created. The body of the name consists of all the characters after ${ until the first occurrence of a non-alphanumeric character or a space (for example, OBJECT in ${OBJECT.name} and DICTIONARY in ${DICTIONARY[2]}).
3. A variable matching the body is searched. If there is no match, an exception is raised and the test case fails.
4. The expression inside the curly brackets is evaluated as a Python expression, so that the base variable name is replaced with its value. If the evaluation fails because of an invalid syntax or that the queried attribute does not exist, an exception is raised and the test fails.
5. The whole extended variable is replaced with the value returned from the evaluation.

If the object that is used is implemented with Java, the extended variable syntax allows you to access attributes using so-called bean properties. In essence, this means that if you have an object with the getName method set into a variable ${OBJ}, then the syntax ${OBJ.name} is equivalent to but clearer than ${OBJ.getName()}. The Python object used in the previous example could thus be replaced with the following Java implementation:

public class MyObject:

    private String name;

    public MyObject(String name) {
        name = name;
    }

    public String getName() {
        return name;
    }

    public String eat(String what) {
        return name + " eats " + what;
    }

    public String toString() {
        return name;
    }
}

Many standard Python objects, including strings and numbers, have methods that can be used with the extended variable syntax either explicitly or implicitly. Sometimes this can be really useful and reduce the need for setting temporary variables, but it is also easy to overuse it and create really cryptic test data. Following examples show few pretty good usages.

Note that even though abs(number) is recommended over number.__abs__() in normal Python code, using ${abs(number)} does not work. This is because the variable name must be in the beginning of the extended syntax. Using __xxx__ methods in the test data like this is already a bit questionable, and it is normally better to move this kind of logic into test libraries.

Extended variable assignment

Starting from Robot Framework 2.7, it is possible to set attributes of objects stored to scalar variables using keyword return values and a variation of the extended variable syntax. Assuming we have variable ${OBJECT} from the previous examples, attributes could be set to it like in the example below.

The extended variable assignment syntax is evaluated using the following rules:

1. The assigned variable must be a scalar variable and have at least one dot. Otherwise the extended assignment syntax is not used and the variable is assigned normally.
2. If there exists a variable with the full name (e.g. ${OBJECT.name} in the example above) that variable will be assigned a new value and the extended syntax is not used.
3. The name of the base variable is created. The body of the name consists of all the characters between the opening ${ and the last dot, for example, OBJECT in ${OBJECT.name} and foo.bar in ${foo.bar.zap}. As the second example illustrates, the base name may contain normal extended variable syntax.
4. The name of the attribute to set is created by taking all the characters between the last dot and the closing }, for example, name in ${OBJECT.name}. If the name does not start with a letter or underscore and contain only these characters and numbers, the attribute is considered invalid and the extended syntax is not used. A new variable with the full name is created instead.
5. A variable matching the base name is searched. If no variable is found, the extended syntax is not used and, instead, a new variable is created using the full variable name.
6. If the found variable is a string or a number, the extended syntax is ignored and a new variable created using the full name. This is done because you cannot add new attributes to Python strings or numbers, and this way the new syntax is also less backwards-incompatible.
7. If all the previous rules match, the attribute is set to the base variable. If setting fails for any reason, an exception is raised and the test fails.

Variables inside variables

Variables are allowed also inside variables, and when this syntax is used, variables are resolved from the inside out. For example, if you have a variable ${var${x}}, then ${x} is resolved first. If it has the value name, the final value is then the value of the variable ${varname}. There can be several nested variables, but resolving the outermost fails, if any of them does not exist.

In the example below, Do X gets the value ${JOHN HOME} or ${JANE HOME}, depending on if Get Name returns john or jane. If it returns something else, resolving ${${name} HOME} fails.

Basic syntax

In many ways, the overall user keyword syntax is identical to the test case syntax. User keywords are created in keyword tables which differ from test case tables only by the name that is used to identify them. User keyword names are in the first column similarly as test cases names. Also user keywords are created from keywords, either from keywords in test libraries or other user keywords. Keyword names are normally in the second column, but when setting variables from keyword return values, they are in the subsequent columns.

Most user keywords take some arguments. This important feature is used already in the second example above, and it is explained in detail later in this section, similarly as user keyword return values.

User keywords can be created in test case files, resource files, and test suite initialization files. Keywords created in resource files are available for files using them, whereas other keywords are only available in the files where they are created.

Settings in the Keyword table

User keywords can have similar settings as test cases, and they have the same square bracket syntax separating them from keyword names. All available settings are listed below and explained later in this section.

[Documentation]

Used for setting a user keyword documentation.

[Arguments]

Specifies user keyword arguments.

[Return]

Specifies user keyword return values.

[Teardown]

Specify keyword teardown. Available from Robot Framework 2.6 onwards.

[Timeout]

Sets the possible user keyword timeout. Timeouts are discussed in a section of their own.

Positional arguments

The simplest way to specify arguments (apart from not having them at all) is using only positional arguments. In most cases, this is all that is needed.

The syntax is such that first the [Arguments] setting is given and then argument names are defined in the subsequent cells. Each argument is in its own cell, using the same syntax as with variables. The keyword must be used with as many arguments as there are argument names in its signature. The actual argument names do not matter to the framework, but from users' perspective they should should be as descriptive as possible. It is recommended to use lower-case letters in variable names, either as ${my_arg}, ${my arg} or ${myArg}.

Default values

Positional arguments are probably sufficient in most situations. However, sometimes it is useful to be able to have a keyword that takes a different number of arguments and has default values for those that are not given. User keywords also allow this, and the needed new syntax does not add very much to the already discussed basic syntax. In short, default values are added to arguments, so that first there is the equals sign (=) and then the value, for example ${arg}=default. There can be many arguments with defaults, but they all must be given after the normal positional arguments.

When a keyword accepts several arguments with default values and only some of them needs to be overridden, it is often handy to use the named arguments syntax. When this syntax is used with user keywords, the arguments are specified without the ${} decoration. For example, the second keyword above could be used like below and ${arg1} would still get its default value.

As all Pythonistas must have already noticed, the syntax for specifying default arguments is heavily inspired by Python syntax for function default values.

Variable number of arguments

Sometimes even default values are not enough and there is a need for a keyword accepting any number of arguments. User keywords support also this. All that is needed is having list variable such as @{varargs} as the last argument in the keyword signature. This syntax can be combined with the previously described positional arguments and default values, and at the end the list variable gets all the leftover arguments that do not match other arguments. The list variable can thus have any number of items, even zero.

Notice that if the last keyword above is used with more than one argument, the second argument ${opt} always gets the given value instead of the default value. This happens even if the given value is empty. The last example also illustrates how a variable number of arguments accepted by a user keyword can be used in a for loop. This combination of two rather advanced functions can sometimes be very useful.

Again, Pythonistas probably notice that the variable number of arguments syntax is very close to the one in Python.

Basic syntax

It has always been possible to use keywords like Select dog from list and Selects cat from list, but all such keywords must have been implemented separately. The idea of embedding arguments into the keyword name is that all you need is a keyword with name like Select ${animal} from list.

Keywords using embedded arguments cannot take any "normal" arguments (specified with [Arguments] setting) but otherwise they are created just like other user keywords. The arguments used in the name will naturally be available inside the keyword and they have different value depending on how the keyword is called. For example, ${animal} in the previous has value dog if the keyword is used like Select dog from list. Obviously it is not mandatory to use all these arguments inside the keyword, and they can thus be used as wildcards.

These kind of keywords are also used the same way as other keywords except that spaces and underscores are not ignored in their names. They are, however, case-insensitive like other keywords. For example, the keyword in the example above could be used like select x from list, but not like Select x fromlist.

Embedded arguments do not support default values or variable number of arguments like normal arguments do. Using variables when calling these keywords is possible but that can reduce readability. Notice also that embedded arguments only work with user keywords.

Embedded arguments matching too much

One tricky part in using embedded arguments is making sure that the values used when calling the keyword match the correct arguments. This is a problem especially if there are multiple arguments and characters separating them may also appear in the given values. For example, keyword Select ${city} ${team} does not work correctly if used with city containing too parts like Select Los Angeles Lakers.

An easy solution to this problem is quoting the arguments (e.g. Select "${city}" "${team}") and using the keyword in quoted format (e.g. Select "Los Angeles" "Lakers"). This approach is not enough to resolve all this kind of conflicts, though, but it is still highly recommended because it makes arguments stand out from rest of the keyword. A more powerful but also more complicated solution, using custom regular expressions when defining variables, is explained in the next section. Finally, if things get complicated, it might be a better idea to use normal positional arguments instead.

The problem of arguments matching too much occurs often when creating keywords that ignore given/when/then/and prefixes . For example, ${name} goes home matches Given Janne goes home so that ${name} gets value Given Janne. Quotes around the argument, like in "${name}" goes home, resolve this problem easily.

Using custom regular expressions

When keywords with embedded arguments are called, the values are matched internally using regular expressions (regexps for short). The default logic goes so that every argument in the name is replaced with a pattern .*? that basically matches any string. This logic works fairly well normally, but as just discussed above, sometimes keywords match more than intended. Quoting or otherwise separating arguments from the other text can help but, for example, the test below fails because keyword I execute "ls" with "-lh" matches both of the defined keywords.

A solution to this problem is using a custom regular expression that makes sure that the keyword matches only what it should in that particular context. To be able to use this feature, and to fully understand the examples in this section, you need to understand at least the basics of the regular expression syntax.

A custom embedded argument regular expression is defined after the base name of the argument so that the argument and the regexp are separated with a colon. For example, an argument that should match only numbers can be defined like ${arg:\d+}. Using custom regular expressions is illustrated by the examples below.

In the above example keyword I execute "ls" with "-lh" matches only I execute "${cmd}" with "${opts}". That is guaranteed because the custom regular expression [^"]+ in I execute "${cmd:[^"]}" means that a matching argument cannot contain any quotes. In this case there is no need to add custom regexps to the other I execute variant.

Behavior-driven development example

The biggest benefit of having arguments as part of the keyword name is that it makes it easier to use higher-level sentence-like keywords when writing test cases in behavior-driven style. The example below illustrates this. Notice also that prefixes Given, When and Then are left out of the keyword definitions.

Taking resource files into use

Resource files are imported using the Resource setting in the Settings table. The path to the resource file is given in the cell after the setting name.

If the path is given in an absolute format, it is used directly. In other cases, the resource file is first searched relatively to the directory where the importing file is located. If the file is not found there, it is then searched from the directories in PYTHONPATH. The path can contain variables, and it is recommended to use them to make paths system-independent (for example, ${RESOURCES}/login_resources.html or ${RESOURCE_PATH}). Additionally, slashes ("/") in the path are automatically changed to backslashes ("\") on Windows.

The user keywords and variables defined in a resource file are available in the file that takes that resource file into use. Similarly available are also all keywords and variables from the libraries, resource files and variable files imported by the said resource file.

Resource file structure

The higher-level structure of resource files is the same as that of test case files otherwise, but, of course, they cannot contain Test Case tables. Additionally, the Setting table in resource files can contain only import settings (Library, Resource, Variables) and Documentation. The Variable table and Keyword table are used exactly the same way as in test case files.

If several resource files have a user keyword with the same name, they must be used so that the keyword name is prefixed with the resource file name without the extension (for example, myresources.Some Keyword and common.Some Keyword). Moreover, if several resource files contain the same variable, the one that is imported first is taken into use.

Documenting resource files

Keywords created in a resource file can be documented using [Documentation] setting. Starting from Robot Framework 2.1 also the resource file itself can have Documentation in the Setting table similarly as test suites.

Both libdoc and RIDE use these documentations, and they are naturally available for anyone opening resource files. The first line of the documentation of a keyword is logged when it is run, but otherwise resource file documentations are ignored during the test execution.

Example resource file

Taking variable files into use

--variablefile myvariables.py
--variablefile path/variables.py
--variablefile /absolute/path/common.py
--variablefile taking_arguments.py:arg1:arg2

Creating variables directly

VARIABLE = "An example string"
ANOTHER_VARIABLE = "This is pretty easy!"
INTEGER = 42
STRINGS = ["one", "two", "kolme", "four"]
NUMBERS = [1, INTEGER, 3.14]

LIST__STRINGS = ["list", "of", "strings"]
LIST__MIXED = ["first value", -1.1, None, True]

from java.util import Hashtable

MAPPING = Hashtable()
MAPPING.put("one", 1)
MAPPING.put("two", 2)

MAPPING = {'one': 1, 'two': 2}

class MyObject:
    def __init__(self, name):
        self.name = name

OBJ1 = MyObject('John')
OBJ2 = MyObject('Jane')

import os
import random
import time

USER = os.getlogin()                # current login name
RANDOM_INT = random.randint(0, 10)  # random integer in range [0,10]
CURRENT_TIME = time.asctime()       # timestamp like 'Thu Apr  6 12:45:21 2006'
if time.localtime()[3] > 12:
    AFTERNOON = True
else:
    AFTERNOON = False

import math

def get_area(diameter):
    radius = diameter / 2
    area = math.pi * radius * radius
    return area

AREA1 = get_area(1)
AREA2 = get_area(2)

import math as _math

def _get_area(diameter):
    radius = diameter / 2.0
    area = _math.pi * radius * radius
    return area

AREA1 = _get_area(1)
AREA2 = _get_area(2)

import math

__all__ = ['AREA1', 'AREA2']

def get_area(diameter):
    radius = diameter / 2.0
    area = math.pi * radius * radius
    return area

AREA1 = get_area(1)
AREA2 = get_area(2)

Getting variables from a special function

An alternative approach for getting variables is having a special get_variables function (also camelCase syntax getVariables is possible) in a variable file. If such a function exists, Robot Framework calls it and expects to receive variables as a Python dictionary or a Java Map with variable names as keys and variable values as values. Variables are considered to be scalars, unless prefixed with LIST__, and values can contain anything. The example below is functionally identical to the first examples of creating variables directly above.

def get_variables():
    variables = {"VARIABLE ": "An example string",
                 "ANOTHER_VARIABLE": "This is pretty easy!",
                 "INTEGER": 42,
                 "STRINGS": ["one", "two", "kolme", "four"],
                 "NUMBERS": [1, 42, 3.14],
                 "LIST__STRINGS": ["list", "of", "strings"],
                 "LIST__MIXED": ["first value", -1.1, None, True]}
    return variables

get_variables can also take arguments, which facilitates changing what variables actually are created. Arguments to the function are set just as any other arguments for a Python function. When taking variable files into use in the test data, arguments are specified in cells after the path to the variable file, and in the command line they are separated from the path with a colon.

The dummy example below shows how to use arguments with variable files. In a more realistic example, the argument could be a path to an external text file or database where to read variables from.

variables1 = {'scalar': 'Scalar variable',
              'LIST__list': ['List','variable']}
variables2 = {'scalar' : 'Some other value',
              'LIST__list': ['Some','other','value'],
              'extra': 'variables1 does not have this at all'}

def get_variables(arg):
    if arg == 'one':
        return variables1
    else:
        return variables2

Implementing variable file as Python or Java class

Starting from Robot Framework 2.7, it is possible to implement variables files as Python or Java classes.

class StaticPythonExample(object):
    variable = 'value'
    LIST__list = [1, 2, 3]
    _not_variable = 'starts with an underscore'

    def __init__(self):
        self.another_variable = 'another value'

public class StaticJavaExample {
    public static String variable = "value";
    public static String[] LIST__list = {1, 2, 3};
    private String notVariable = "is private";
    public String anotherVariable;

    public StaticJavaExample(String arg1, String arg2) {
        anotherVariable = "another value";
    }
}

class DynamicPythonExample(object):

    def get_variables(self, *args):
        return {'dynamic variable': ' '.join(args)}

import java.util.Map;
import java.util.HashMap;

public class DynamicJavaExample {

    public Map<String, String> getVariables(String arg1, String arg2) {
        HashMap<String, String> variables = new HashMap<String, String>();
        variables.put("dynamic variable", arg1 + " " + arg2);
        return variables;
    }
}

Keyword scopes

When only a keyword name is used and there are several keywords with that name, Robot Framework attempts to determine which keyword has the highest priority based on its scope. The keyword's scope is determined on the basis of how the keyword in question is created:

1. Created as a user keyword in the same file where it is used. These keywords have the highest priority and they are always used, even if there are other keywords with the same name elsewhere.
2. Created in a resource file and imported either directly or indirectly from another resource file. This is the second-highest priority.
3. Created in an external test library. These keywords are used, if there are no user keywords with the same name. However, if there is a keyword with the same name in the standard library, a warning is displayed.
4. Created in a standard library. These keywords have the lowest priority.

Specifying a keyword explicitly

Scopes alone are not a sufficient solution, because there can be keywords with the same name in several libraries or resources, and thus, they provide a mechanism to use only the keyword of the highest priority. In such cases, it is possible to use the full name of the keyword, where the keyword name is prefixed with the name of the resource or library and a dot is a delimiter.

With library keywords, the long format means only using the format LibraryName.Keyword Name. For example, the keyword Run from the OperatingSystem library could be used as OperatingSystem.Run, even if there was another Run keyword somewhere else. If the library is in a module or package, the full module or package name must be used (for example, com.company.Library.Some Keyword). If a custom name is given to a library using the WITH NAME syntax, the specified name must be used also in the full keyword name.

Resource files are specified in the full keyword name, similarly as library names. The name of the resource is derived from the basename of the resource file without the file extension. For example, the keyword Example in a resource file myresources.html can be used as myresources.Example. Note that this syntax does not work, if several resource files have the same basename. In such cases, either the files or the keywords must be renamed. The full name of the keyword is case-, space- and underscore-insensitive, similarly as normal keyword names.

Specifying explicit priority between libraries and resources

If there are multiple conflicts between keywords, specifying all the keywords in the long format can be quite a lot work. Using the long format also makes it impossible to create dynamic test cases or user keywords that work differently depending on which libraries or resources are available. A solution to both of these problems is specifying the keyword priorities explicitly using the keyword Set Library Search Order from the BuiltIn library.

Note

Although the keyword has the word library in its name, it works also with resource files starting from Robot Framework 2.6.2. As discussed above, keywords in resources always have higher priority than keywords in libraries, though.

The Set Library Search Order accepts an ordered list or libraries and resources as arguments. When a keyword name in the test data matches multiple keywords, the first library or resource containing the keyword is selected and that keyword implementation used. If the keyword is not found from any of the specified libraries or resources, execution fails for conflict the same way as when the search order is not set.

For more information and examples, see the documentation of the keyword.

Test case timeout

The test case timeout can be set either by using the Test Timeout setting in the Setting table or the [Timeout] setting in the Test Case table. Test Timeout in the Setting table defines a default test timeout value for all the test cases in the test suite, whereas [Timeout] in the Test Case table applies a timeout to an individual test case and overrides the possible default value.

Using an empty [Timeout] means that the test has no timeout even when Test Timeout is used. Starting from Robot Framework 2.5.6, it is also possible to use value NONE for this purpose.

Regardless of where the test timeout is defined, the first cell after the setting name contains the duration of the timeout. The duration must be given in Robot Framework's time format, that is, either directly in seconds or in a format like 1 minute 30 seconds. It must be noted that there is always some overhead by the framework, and timeouts shorter than one second are thus not recommended.

The default error message displayed when a test timeout occurs is Test timeout <time> exceeded. It is also possible to use custom error messages, and these messages are written into the cells after the timeout duration. The message can be split into multiple cells, similarly as documentations. Both the timeout value and the error message may contain variables.

If there is a timeout, the keyword running is stopped at the expiration of the timeout and the test case fails. However, keywords executed as test teardown are not interrupted if a test timeout occurs, because they are normally engaged in important clean-up activities. If necessary, it is possible to interrupt also these keywords with user keyword timeouts.

User keyword timeout

A timeout can be set for a user keyword using the [Timeout] setting in the Keyword table. The syntax for setting it, including how timeout values and possible custom messages are given, is identical to the syntax used with test case timeouts. If no custom message is provided, the default error message Keyword timeout <time> exceeded is used if a timeout occurs.

A user keyword timeout is applicable during the execution of that user keyword. If the total time of the whole keyword is longer than the timeout value, the currently executed keyword is stopped. User keyword timeouts are applicable also during a test case teardown, whereas test timeouts are not.

If both the test case and some of its keywords (or several nested keywords) have a timeout, the active timeout is the one with the least time left.

Normal for loop

In a normal For loop, one variable is assigned from a list of values, one value per iteration. The syntax starts with :FOR, where colon is required to separate the syntax from normal keywords. The next cell contains the loop variable, the subsequent cell must have IN, and the final cells contain values over which to iterate.

The keywords used in the For loop are on the next rows and they must be indented one cell to the right. The For loop ends when the indentation returns back to normal or the table ends. Having nested For loops directly is not supported, but it is possible to use a user keyword inside a For loop and have another For loop there.

The For loop in Example 1 above is executed twice, so that first the loop variable ${animal} has the value cat and then dog. The loop consists of two Log keywords. In the second example, loop values are split into several rows and the loop is run altogether seven times.

*** Test Case ***
Example 1
    :FOR    ${animal}    IN    cat    dog
    \    Log    ${animal}
    \    Log    2nd keyword
    Log    Outside loop

For loops are most useful and also clearest when they are used with list variables. This is illustrated by the example below, where @{ELEMENTS} contains an arbitrarily long list of element names and keyword Start Element is used with all of them.

Using several loop variables

It is also possible to use several loop variables. The syntax is the same as with the normal For loop, but all loop variables are listed in the cells between :FOR and IN. There can be any number of loop variables, but the number of values must be evenly dividable by the number of variables.

This syntax naturally works both with and without list variables. In the former case, it is often possible to organize loop values below loop variables, as in the first part of the example below:

For in range

Earlier For loops always iterated over a sequence, and this is also the most common use case. Sometimes it is still convenient to have a For loop that is executed a certain number of times, and Robot Framework has a special FOR index IN RANGE limit syntax for this purpose. This syntax is derived from the similar Python idiom.

Similarly as other For loops, the For in range loop starts with :FOR and the loop variable is in the next cell. In this format there can be only one loop variable and it contains the current loop index. The next cell must contain IN RANGE and the subsequent cells loop limits.

In the simplest case, only the upper limit of the loop is specified. In this case, loop indexes start from zero and increase by one until, but excluding, the limit. It is also possible to give both the start and end limits. Then indexes start from the start limit, but increase similarly as in the simple case. Finally, it is possible to give also the step value that specifies the increment to use. If the step is negative, it is used as decrement.

Starting from Robot Framework 2.5.5, it is possible to use simple arithmetics such as addition and subtraction with the range limits. This is especially useful when the limits are specified with variables.

Exiting for loop

Normally for loop is executed until all the elements of the loop have been looped through or an error occurs and the test case or keyword fails. However sometimes execution of a for loop needs to be stopped before all elements of the loop have been gone through. BuiltIn keyword Exit For Loop can be used to exit the enclosing for loop.

Exit For Loop keyword can be used directly in a for loop or in a keyword that the for loop uses. In both cases the test execution continues after the for loop. If executed outside of a for loop, the test fails.

Exiting a for loop can also be initiated from a keyword in a test library by raising an exception with ROBOT_EXIT_FOR_LOOP attribute. Please see Stopping test execution for examples how to do this in Python and Java libraries.

Removing unnecessary keywords from outputs

For loops with multiple iterations often create lots of output and considerably increase the size of the generated output and log files. Starting from Robot Framework 2.7, it is possible to remove unnecessary keywords from the outputs using --RemoveKeywords FOR command line option.

Repeating single keyword

For loops can be excessive in situations where there is only a need to repeat a single keyword. In these cases it is often easier to use BuiltIn keyword Repeat Keyword. This keyword takes a keyword and how many times to repeat it as arguments. The times to repeat the keyword can have an optional postfix times or x to make the syntax easier to read.

Robot Framework also had a special syntax for repeating a single keyword. This syntax was deprecated in the 2.0.4 version in favor of Repeat Keyword and it was removed in the 2.5 version.