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.

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.

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 currently supports Python versions 2.5, 2.6, and 2.7. The plan is to support also Python 3 in the future, and Python 2.5 support will be dropped latest then. If you need Python 3 support earlier, you can use the un-official Python 3 port. If you need to use really old Python versions, Robot Framework 2.0 and 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 the pybot runner script executable on the command prompt.

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 implementations is out of the scope of these instructions, but you can find more information from http://java.com if needed.

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.

The minimum supported Jython version is 2.5 which requires Java 5 (a.k.a. Java 1.5) or newer. The forthcoming Jython 2.7 will require minimum Java 7, and that will also be the minimum for Robot Framework when support for Jython 2.5 is dropped in the future. Robot Framework 2.0 and 2.1 support Jython 2.2.

After installing Jython, you probably still want to configure PATH to make the jybot runner script executable on the command prompt.

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 the ipybot runner script executable on the command prompt.

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. The runner scripts themselves require the matching interpreter to be in the PATH and thus the interpreter installation directory must be added there too.

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.

Setting https_proxy

If you are planning to use pip for installation and are behind a proxy, you need to set the https_proxy environment variable. It is needed both when installing pip 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.

Package managers (e.g. pip)

The most popular 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, at least if they search packages from PyPI.

# Install the latest version
pip install robotframework

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

# Install a specific version
pip install robotframework==2.8.5

# Uninstall
pip uninstall robotframework

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

# Install the latest version even if it is a pre-release
pip install --pre robotframework

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 with names in format robotframework-<version>.win32.exe and robotframework-<version>.win-amd64.exe, respectively. Newer installers are on PyPI and Robot Framework 2.8.1 and older on the old Google Code 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.

Installing Robot Framework may require administrator privileges. In that case select Run as administrator from the context menu when starting the installer.

Standalone JAR distribution

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-2.8.5.jar mytests.txt
java -jar robotframework-2.8.5.jar --variable name:value mytests.txt

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-2.8.5.jar rebot output.xml
java -jar robotframework-2.8.5.jar libdoc MyLibrary list

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

Manual installation

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

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

Verifying installation

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

$ pybot --version
Robot Framework 2.8.5 (Python 2.7.3 on linux2)

$ rebot --version
Rebot 2.8.5 (Python 2.7.3 on linux2)

$ jybot --version
Robot Framework 2.8.5 (Jython 2.5.3 on java1.7.0_60)

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.

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 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 other interpreters, the scripts are typically either in Scripts 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.

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, for example, from 2.8.4 to 2.8.5. This typically works also when upgrading to a new major version, for example, from 2.8.5 to 2.9, 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

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

Runner scripts

Robot Framework has different runner scripts for executing test cases and for post-processing outputs based on earlier test results. In addition to that, these scripts are different depending on the interpreter that is used:

On UNIX-like operating systems such as Linux and OS X, the runner scripts are implemented using Python, and on Windows they are batch files. Regardless of the operating system, using any of these scripts requires that the appropriate interpreter is in PATH.

Direct entry points

In addition to the above runner scripts, it is possible to both run tests and post-process outputs by executing framework's entry points directly using a selected interpreter. It is possible to execute them as modules using Python's -m option and, if you know where the framework is installed, to run them as scripts. The entry points are listed on the following table using Python, and examples below illustrate using them also with other interpreters.

# 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

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.

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

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

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.

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.

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}

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

reStructuredText format

reStructuredText (reST) is an 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). reST documents are most often compiled to HTML, but also other output formats are supported.

Using reST with Robot Framework allows you to mix richly formatted documents and test data in a concise text format that is easy to work with using simple text editors, diff tools, and source control systems. In practice it combines many of the benefits of plain text and HTML formats.

When using reST files with Robot Framework, there are two ways to define the test data. Either you can use code blocks and define test cases in them using the plain text format or alternatively you can use tables exactly like you would with the HTML format.

.. code:: python

   def example_keyword():
       print 'Hello, world!'

.. code:: robotframework

   *** Test Cases ***
   Example Test
       Example Keyword

Example
-------

This text is outside code blocks and thus ignored.

.. code:: robotframework

   *** 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!

Also this text is outside code blocks and ignored. Above block used
the space separated plain text format and the block below uses the pipe
separated variant.

.. code:: robotframework

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

Example
-------

This text is outside tables and thus ignored.

============  ================  =======  =======
  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!
=============  ==================  ============  =============

Also this text is outside tables and ignored. Above tables are created
using the simple table syntax and the table below uses the grid table
approach.

+-------------+------------------------+------------+------------+
|   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.
• 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.

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.

Handling whitespace

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

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

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.

*** 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

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

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.

Mandatory 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

The named argument syntax makes using arguments with default values more flexible, and allows explicitly labeling what a certain argument value means. Technically named arguments work exactly like keyword arguments in Python.

Free keyword arguments

Robot Framework 2.8 added support for Python style free keyword arguments (**kwargs). What this means is that keywords can receive all arguments at the end of the keyword call that use the name=value syntax, and do not match any other arguments, as kwargs.

Free keyword arguments support variables similarly as named arguments. In practice that means that variables can be used both in names and values, but the escape sign must always be visible literally. For example, both foo=${bar} and ${foo}=${bar} are valid, as long as the variables that are used exist. An extra limitation is that free keyword argument names must always be strings. Support for variables in names is a new feature in Robot Framework 2.8.6, prior to that possible variables were left un-resolved.

Initially free keyword arguments only worked with Python based libraries, but Robot Framework 2.8.2 extended the support to the dynamic library API and Robot Framework 2.8.3 extended it further to Java based libraries and to the remote library interface. In other words, all libraries nowadays support kwargs. Unfortunately user keywords no not support them yet, but that support is planned for Robot Framework 2.9.

For a real life example of using kwargs, let's take a look at Run Process keyword in the Process library. It has a signature command, *arguments, **configuration, which means that it takes the command to execute, its arguments as variable number of arguments, and finally optional configuration parameters as free keyword arguments **configuration.

As the above example illustrates, using variables with free keyword arguments works exactly like when using the named argument syntax.

See Free keyword arguments (**kwargs) section under Creating test libraries for more information about using the kwargs syntax in your custom test libraries.

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.

When test case fails

A test case fails if any of the keyword it uses fails. Normally this means that execution of that test case is stopped, possible test teardown is executed, and then execution continues from the next test case. It is also possible to use special continuable failures if stopping test execution is not desired.

Error messages

The error message assigned to a failed test case is got directly from the failed keyword. Often the error message is created by the keyword itself, but some keywords allow configuring them.

In some circumstances, for example when continuable failures are used, a test case can fail multiple times. In that case the final error message is got by combining the individual errors. Very long error messages are automatically cut from the middle to keep reports easier to read. Full error messages are always visible in log file as a message of the failed keyword.

By default error messages are normal text, but starting from Robot Framework 2.8 they can contain HTML formatting. This is enabled by starting the error message with marker string *HTML*. This marker will be removed from the final error message shown in reports and logs. Using HTML in a custom message is shown in the second example below.

Basic usage

How a keyword accepting normal positional arguments can be used as a template is illustrated by the following example test cases. These two tests are functionally fully identical.

*** Test Cases **
Normal test case
    Example keyword    first argument    second argument

Templated test case
    [Template]    Example keyword
    first argument    second argument

As the example illustrates, it is possible to specify the template for an individual test case using the [Template] setting. An alternative approach is using the Test Template setting in the Setting table, in which case the template is applied for all test cases in that test case file. The [Template] setting overrides the possible template set in the Setting table, and an empty value for [Template] means that the test has no template even when Test Template is used. Starting from Robot Framework 2.5.6, it is also possible to use value NONE to indicate that a test has no template.

If a templated test case has multiple data rows in its body, the template is applied for all the rows one by one. This means that the same keyword is executed multiple times, once with data on each row. Templated tests are also special so that all the rounds are executed even if one or more of them fails. It is possible to use this kind of continue on failure mode with normal tests too, but with the templated tests the mode is on automatically.

*** Settings ***
Test Template    Example keyword

*** Test Cases ***
Templated test case
    first round 1     first round 2
    second round 1    second round 2
    third round 1     third round 2

Using arguments with default values or varargs, as well as using named arguments and free keyword arguments, work with templates exactly like they work otherwise. Using variables in arguments is also supported normally.

Templates with embedded arguments

Starting from Robot Framework 2.8.2, templates support a variation of the embedded argument syntax. With templates this syntax works so that if the template keyword has variables in its name, they are considered placeholders for arguments and replaced with the actual arguments used with the template. The resulting keyword is then used without positional arguments. This is best illustrated with an example:

*** Test Case ***
Normal test case with embedded arguments
    The result of 1 + 1 should be 2
    The result of 1 + 2 should be 3

Template with embedded arguments
    [Template]    The result of ${calculation} should be ${expected}
    1 + 1    2
    1 + 2    3

*** Keywords ***
The result of ${calculation} should be ${expected}
    ${result} =    Calculate    ${calculation}
    Should Be Equal    ${result}     ${expected}

When embedded arguments are used with templates, the number of arguments in the template keyword name must match the number of arguments it is used with. The argument names do not need to match the arguments of the original keyword, though, and it is also possible to use different arguments altogether:

*** Test Case ***
Different argument names
    [Template]    The result of ${foo} should be ${bar}
    1 + 1    2
    1 + 2    3

Only some arguments
    [Template]    The result of ${calculation} should be 3
    1 + 2
    4 - 1

New arguments
    [Template]    The ${meaning} of ${life} should be 42
    result    21 * 2

The main benefit of using embedded arguments with templates is that argument names are specified explicitly. When using normal arguments, the same effect can be achieved by naming the columns that contain arguments. This is illustrated by the data-driven style example in the next section.

Templates with for loops

If templates are used with for loops, the template is applied for all the steps inside the loop. The continue on failure mode is in use also in this case, which means that all the steps are executed with all the looped elements even if there are failures.

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) or Specification by Example.

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 or But 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. An initialization file name must always be of the format __init__.ext, where the extension must be one of the supported file formats (for example, __init__.robot or __init__.html). The name format is borrowed from Python, where files named in this manner denote that a directory is a module.

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. Variables and keywords created or imported in initialization files are not available in the lower level test suites. If you need to share variables or keywords, you can put them into resource files that can be imported both by initialization and test case files.

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. How to use different settings in the initialization files is explained below.

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.

Normal standard libraries

The available normal standard libraries are listed below with links to their documentations:

• BuiltIn
• Collections
• DateTime
• Dialogs
• OperatingSystem
• Process
• Screenshot
• String
• Telnet
• XML

Remote library

In addition to the normal standard libraries listed above, there is also Remote library that 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 this concept.

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.

Using list variables as scalars

It is possible to use list variables as scalar variables containing lists simply by replacing @ with $. This makes it possible to use list variables with list related keywords, for example, from BuiltIn and Collections libraries.

Notice that possible changes to the values of the list variable are not limited to the current variable scope. Because no new variable is created but instead the state of an existing variable is changed, all tests and keywords that see that variable will also see the changes. If this is a problem, Copy List keyword from the Collections library can be used to create a local copy of the variable.

Using list variables as scalars only works if there is no scalar variable with the same base name as the list variable has. In these cases the scalar variable has precedence and its value is used instead.

Using scalar variables as lists

Starting from Robot Framework 2.8, it is also possible to use scalar variables as list variables. If a scalar variable contains any list-like object, it can be used as a list variable by replacing $ with @. This is useful, for example, with for loops and when items in a scalar list needs to be used as a separate arguments for a keyword.

If a scalar variable contains any non-list object, for example a string or an integer, using it as a list variable fails. Exactly like when using lists variables as scalars, using a scalar variable as a list only works if there is no list variable with the same base name.

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 disadvantages are that values are always strings and they cannot be created dynamically. If either of these is a problem, variable files can be used instead.

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

The second example above shows how to set a predefined test case scope variable using BuiltIn Set Variable keyword. Same approach obviously works also with variables in user keyword scope. If all tests share same predefined variable, it is recommended to use variable table instead.

If a keyword returns a list, or any list-like object, it is also possible to assign the return value into several scalar variables and/or one list variable.

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 BuiltIn keywords as explained in the next section.

Using 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 insensitive.

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.

Starting from Robot Framework 2.7.4, there is also an empty list variable @{EMPTY}. Because it has no content, it basically vanishes when used somewhere in the test data. It is useful, for example, with test templates when the template keyword is used without arguments or when overriding list variables in different scopes. Modifying the value of @{EMPTY} is not possible.

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. Altering the value of these variables does not affect the original values, but some values can be changed dynamically using keywords from the BuiltIn library.

Suite related variables ${SUITE SOURCE}, ${SUITE NAME}, ${SUITE DOCUMENTATION} and ${SUITE METADATA} are available already when test libraries and variable files are imported, except to Robot Framework 2.8 and 2.8.1 where this support was broken. Possible variables in these automatic variables are not yet resolved at the import time, though.

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 using Set Test/Suite/Global Variable keywords 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.

Extended variable syntax

Extended variable syntax allows accessing attributes of an object assigned to a variable (for example, ${object.attribute}) and even calling its methods (for example, ${obj.getName()}). It works both with scalar and list variables, but is mainly useful with the former

Extended variable syntax is a powerful feature, but it should be used with care. Accessing attributes is normally not a problem, on the contrary, because one variable containing an object with 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 pretty complicated to understand. 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 name of the base variable is created. The body of the name consists of all the characters after the opening { until the first occurrence of a character that is not an alphanumeric character or a space. For example, base variables of ${OBJECT.name} and ${DICTIONARY[2]}) are OBJECT and DICTIONARY, respectively.
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 syntax works also when using scalar variables as lists. If, for example, an object assigned to a variable ${EXTENDED} has an attribute attribute that contains a list as a value, it can be used as a list variable @{EXTENDED.attribute}.

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 user 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 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 with user keywords

When creating user keywords, positional arguments are sufficient in most situations. It is, however, sometimes useful that keywords have default values for some or all of their arguments. Also user keywords support default values, 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. The default value can contain a variable created on suite or global scope.

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.

Varargs with user keywords

Sometimes even default values are not enough and there is a need for a keyword accepting variable number of arguments. User keywords support also this feature. 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/but 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.

Using [Return] setting

The most common case is that a user keyword returns one value and it is assigned to a scalar variable. When using the [Return] setting, this is done by having the return value in the next cell after the setting.

User keywords can also return several values, which can then be assigned into several scalar variables at once, to a list variable, or to scalar variables and a list variable. Several values can be returned simply by specifying those values in different cells after the [Return] setting.

Using special keywords to return

BuiltIn keywords Return From Keyword and Return From Keyword If allow returning from a user keyword conditionally in the middle of the keyword. Both of them also accept optional return values that are handled exactly like with the [Return] setting discussed above.

The first example below is functionally identical to the previous [Return] setting example. The second, and more advanced, example demonstrates returning conditionally inside a for loop.

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

--variablefile C:\\path\\variables.py

--variablefile "myvariables.py;argument:with:colons"
--variablefile C:\\path\\variables.py;D:\\data.xls

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() {
        anotherVariable = "another value";
    }
}