Keywords
Think of keywords in Robot Framework as functions in other programming languages.
To see a list of keyword libraries that are available on the Robocorp platform, check out the Robocorp Keyword Libraries documentation.
Consider this example script:
This script has one Task that we called Download an Excel file, open it, and close it
.
To accomplish the task, we call three keywords: Download
, Open Workbook
, and Close Workbook
.
Note that keywords within tasks need to be indented with spaces.
Keyword arguments
Keywords can accept zero or more arguments. You can read each keyword's documentation to find out which arguments it supports.
In our example task, when we call the Download
keyword, we are passing two arguments:
https://robotsparebinindustries.com/SalesData.xlsx
: the URL to download the file from.overwrite=True
: we are telling the keyword to overwrite the file if it exists already.
The Open Workbook
keyword needs one argument (the path of the Excel file to open).
The Close Workbook
one does not accept any arguments.
The keyword and each of the arguments need to be separated by spaces.
Positional arguments, named arguments, and default values
The Download
keyword, part of the RPA.HTTP
library, supports these arguments:
The arguments target_file
, verify
, force_new_session
, overwrite
and stream
all have a default value, represented by the value after the =
sign. For example, the keyword, by default, will not overwrite an existing file (overwrite: bool=False
). The url
argument does not have a default value, so it is required.
For each argument, we are also told which type of data it accepts (string values, boolean values).
In our example, we are interested in the url
and the overwrite
arguments. We want to make sure that the file is overwritten each time, so we have to override the default value (False
), with our own value (True
).
The order in which these arguments appear matters. We can call the keyword without specifying the name of the first argument (url
) like this:
And it will work since it is the first one on the list.
The arguments can also be called explicitly by name (named arguments). In this case, the order in which they appear does not matter:
The two styles are often combined. For example, here we are passing the first argument by position (url
), and the overwrite
argument by name, which allows us to leave all other arguments to their default values.
Variable number of arguments
It is also possible for a keyword to accept any number of arguments. These arguments, called varargs, can be combined with mandatory arguments and arguments with default values, but they are always given after them. In the keyword documentation, they are marked with an asterisk.
For example, the Remove Files
and Join Paths
keywords from the OperatingSystem library have the arguments *paths
and base, *parts
, respectively. The former can be used with any number of arguments, but the latter requires at least one argument.
Adding keywords to your robot script
You can add keywords to your script in two ways:
- Library keywords: Importing a library by adding it to your
*** Settings ***
section will allow you to use all keywords contained in the library. You can also create your own custom library. - User keywords: You can write your own keywords in a
*** Keywords ***
section in your script.
Creating user keywords
You can create a user keyword by combining existing keywords.
Create a *** Keywords ***
section in your script, choose a name for your keyword, and call any existing keywords you need in it:
You can then call your keyword inside a task or another keyword.
User keywords with arguments
To make the keyword more reusable, you can pass arguments to it by adding the [Arguments]
setting to the keyword:
You can then call your keyword inside a task, or another keyword:
You can also specify more than one argument, and default values:
You could then call this keyword in your task like this:
User keywords with return values
Just like library keywords, user keywords can have return values.
Add your return value after the RETURN
setting:
Note that we are assigning the result of the
Get Title
keyword to a variable, and then returning the variable.
You would then call the keyword in your task or another keyword like this:
User keywords documentation
Using the [Documentation]
setting, you can add a description of what the keyword does:
Further reading
You can learn more on these topics in the Robot Framework User Guide: