Robot Framework#
| Author | Ville Purhonen |
| Contributors | Alena Galysheva |
| Last Updated | 19.03.2025 |
Robot Framework is a software testing and automation tool. It uses a keyword based syntax that is intended to be readable for non-technical people. In most cases keywords essentially work like function calls in predetermined libraries, but users can also define their own higher level keywords that perform a set of actions.
The Robot Framework homepage has links for user guides and keyword documentation for individual libraries, but this guide is meant to act as a quick start.
Basic installation and how to run .robot files#
Robot Framework is based on Python. In order to run .robot scripts, you need to have Python and pip package manager installed on your system.
As mentioned in the Robot Framework User Guide, it is strongly recommended to use virtual environments for Robot Framework installation.
From the guide:
Virtual environments have two main use cases:
- Install packages needed by different projects into their own environments. This avoids conflicts if projects need different versions of same packages.
- Avoid installing everything under the global Python installation. This is especially important on Linux where the global Python installation may be used by the distribution itself and messing it up can cause severe problems.
See Install packages in a virtual environment using pip and venv or Working With Robot Framework for instructions on how to set up a virtual environment and integrate it with Visual Studio Code IDE.
Robot Framework package can be installed via command line terminal like PowerShell or bash using the following command:
This gives access to the basic functionality of the framework.
If a robot script uses third party libraries, you also need to install them. One of the most common libraries used for web UI test automation in RF is SeleniumLibrary.
Selenium Library for Robot Framework can be installed with the following command:
The best practice for installing external libraries for Robot Framework is to find the package on PyPi and follow the installation instructions listed for the package. Setting up SeleniumLibrary requires additional steps like installation of browser drivers, see robotframework-seleniumlibrary package on PyPi for further instructions.
It's strongly recommended to use an IDE for development of Robot Framework tests like Visual Studio Code or Pycharm Community Edition.
You can run a Robot Framework script with the following command:
The command can also take additional arguments such as defining variables, determining log level and setting the directory for log files which are always automatically generated when running a test script.
Syntax#
Similar to Python, Robot Framework scripts use indents to indicate code blocks. Two or more whitespaces are used to separate a keyword from its parameters in the same row.
For example, SeleniumLibrary has the Open Browser keyword for opening a browser window with a parameter for the URL and another parameter for the browser. In practice, it looks something like this
where Open Browser is the keyword, vr.fi is the URL parameter and firefox is the browser parameter. Separation can be done by pressing space twice or tab once, the framework isn't too particular about it.
.robot file structure#
Robot scripts are divided into four different header sections with particular purposes. These sections are Settings, Variables, Keywords and Test Cases. Settings and Test Cases sections are mandatory to run the file. The headers are marked with three asterisks in the following way:
Settings section is at bare minimum used to define which libraries are being used. It can also contain documentation that is prompted when running the script and resource or variable files for test data.
Variables section contains user defined variables. These can have default default values, which can also be defined when running the script using the argument --variable name_of_variable:value.
Test Cases section contains the keywords that are executed when the script is run. The section has to contain at least one keyword so that script does something.
Keywords section contains user-defined keywords. It is generally useful to organize parts of a test under your own keyword when they are executed in same instance, such filling forms and pressing a button on a single page.
You can find the full list of sections available in .robot files here.
Simple example script#
In order to demonstrate how the framework operates, let's look at a simple working script. Travel.agileway.net is a simple site created as a testing environment.
We will write a script with one test and two test cases. The test itself will fill in the user credentials, click the sign in button and check if the Signed in! text appears. In the first test case we will attempt to login with wrong credentials, this test is supposed to fail. Then we will attempt with the correct credentials.
*** Settings ***
Documentation Attempt login with wrong and correct credentials.
Library SeleniumLibrary
*** Variables ***
${BASE_URL} https://travel.agileway.net/login # page to be tested
&{USER1} username=wronguser password=wrongpassword # dictionary variable
&{USER2} username=agileway password=testwise # another dictionary variable
*** Test Cases ***
Test with invalid credentials
Attempt Login ${USER1}[username] ${USER1}[password]
Test with valid credentials
Attempt Login ${USER2}[username] ${USER2}[password]
*** Keywords ***
Attempt Login
[Arguments] ${username} ${password}
[Setup] Open Browser ${BASE_URL} firefox
Input Text name=username ${username}
Input Password name=password ${password}
Click Element name=commit
Element Should Contain id=flash_notice Signed in!
[Teardown] Close Browser
Let us go through each row.
Settings marks the first header section. Under it the Documentation keyword has has explanatory text that is displayed on terminal when the script is run.
The library keyword determines which library is used for keywords. The keyword has the selected library as a parameter after two or more spaces, in this case we are using SeleniumLibrary.
Variables is the second header. Under it we have the three global variables. In the Robot Framework documentation it is recommended to write global variables with uppercase and local variables with lowercase, but it's just a convention.
The ${BASE_URL} is a scalar variable, which is denoted by the dollar sign. The sole parameter is the site URL, the page to be tested bit is just a comment.
Dictionary variables are denoted by the & sign, which is used for the USER1 and USER2 variables. On the parameters the dictionary uses the key=value syntax.
Test cases is the third header section. Rows under this section are individual test cases. If a test case in any keyword stage fails, the test case is marked as failed in the logs and the script moves to another test case by default. In this example we have two test cases, Test with invalid credentials and Test with valid credentials. They execute the same keyword with different parameters. In this case, the test with invalid credentials is supposed to fail, while the the one with valid credentials is supposed to pass.
Keywords is the last header. Under it we have our self-defined higher level keyword Attempt Login. Under the keyword title the rows to be implemented have to indented, similar to how Python operates when writing functions and whatnot.
The attempt login takes two arguments, which is defined in the next row. This means that every time this keyword is used you have to supply the username and password parameters.
Setup is a special keyword that determines the state before a test is done, in this case making a fresh browser session. Open Browser is a keyword in the Seleniumlibrary. It opens a browser window with a given url parameter with a parameter for the browser to be used.
Input Text is another SeleniumLibrary keyword. The first parameter is the html location identifier for the text field. The identifier can be found by exploring the site with browser inspect element feature, in this case the text field had a unique name property called username.
The second parameter is the text to be input into the field, we will use the username from the parameter input from invoking the keyword.
Input Password yet another SeleniumLibrary keyword. It is functionally identical to the Input Text one, but leaves less traces on the Robot Framework logging for security purposes.
Click Element is a SeleniumLibrary keyword that clicks a html element with the given locator parameter. In this case the commit button had unique name property.
Teardown is a keyword that is paired with setup. It is always performed even if the test fails at some stage. Close Browser closes the browser window opened by the Open Browser keyword. It too is a SeleniumLibrary keyword.
Command line options and logs#
While you can run robot scripts with just the robot <filename> command, it will lead to the folder with the file to be cluttered since Robot Framework will produce log files each time a script is run.
Therefore it is recommended to make a separate folder for output and use a command line option to determine the output folder.
Output folder is determined by -d <relative directory location> parameter, by default logs are output in the directory where the script is being run.
All command line options listed with the following command:
Every time a test script is executed, the framework produces log and report files in html format. This allows you to see step by step how the keywords are executed. Log level can be changed through command line options. SeleniumLibrary also automatically takes screenshots if the executed test fails. Due to this it is trivial to find the exact point of failure for each test. Below is an example of a log file produced by running the example script. Due to the first test case failing it takes an automatic screenshot from the failure stage.
