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:
*** Settings ***
Documentation Example robot that downloads a remote Excel file and opens it.
Library RPA.Excel.Files
Library RPA.HTTP
*** Tasks ***
Download an Excel file, open it, and close it
Download https://robotsparebinindustries.com/SalesData.xlsx overwrite=True
Open Workbook Data.xlsx
Close Workbook
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.
*** Tasks ***
Download an Excel file, open it, and close it
# This task executes these three keywords:
Download https://robotsparebinindustries.com/SalesData.xlsx overwrite=True
Open Workbook Data.xlsx
Close Workbook
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:
url: str,
target_file: str = None,
verify: Union[bool, str] = True,
force_new_session: bool = False,
overwrite: bool = False,
stream: bool = False
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:
*** Tasks ***
Download an Excel file
Download https://robotsparebinindustries.com/SalesData.xlsx
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:
*** Tasks ***
Download an Excel file
# These keyword calls are equivalent:
Download
... url=https://robotsparebinindustries.com/SalesData.xlsx
... overwrite=True
Download
... overwrite=True
... url=https://robotsparebinindustries.com/SalesData.xlsx
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.
*** Tasks ***
Download an Excel file
# Combining positional and named arguments:
Download
... https://robotsparebinindustries.com/SalesData.xlsx
... overwrite=True
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.
Example
Remove Files ${TEMPDIR}/f1.txt ${TEMPDIR}/f2.txt ${TEMPDIR}/f3.txt
@{paths} = Join Paths ${TEMPDIR} f1.txt f2.txt f3.txt f4.txt
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:
*** Keywords ***
Take a screenshot of the login page
Open Available Browser https://robotsparebinindustries.com/
Capture Page Screenshot
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:
*** Keywords ***
Take a screenshot of a web page
[Arguments] ${url}
Open Available Browser ${url}
Capture Page Screenshot
You can then call your keyword inside a task, or another keyword:
*** Tasks ***
Take screenshots
Take a screenshot of web page https://www.google.com
Take a screenshot of web page https://www.robocorp.com
You can also specify more than one argument, and default values:
*** Keywords ***
Perform a search on a search engine
[Arguments] ${search_url}=https://google.com/?q= ${search_term}=robocorp
Open Available Browser ${search_url}${search_term}
You could then call this keyword in your task like this:
*** Tasks ***
Search using different search engines
# No arguments passed, use the default, searching on Google for "robocorp":
Perform a search on a search engine
# Search for "rpa" on "duckduckgo":
Perform a search on a search engine https://duckduckgo.com/?q rpa
User keywords with return values
Just like library keywords, user keywords can have return values.
Add your return value after the RETURN
setting:
*** Keywords ***
Get page title of a web page
[Arguments] ${url}
Open Available Browser ${url}
${page_title}= Get Title
RETURN ${page_title}
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:
*** Tasks ***
Get page titles
${title1}= Get page title of a web page https://www.google.com
${title2}= Get page title of a web page https://www.robocorp.com
User keywords documentation
Using the [Documentation]
setting, you can add a description of what the keyword does:
*** Keywords ***
Get page title of a web page
[Documentation] Returns the title of the webpage found at the given URL.
[Arguments] ${url}
Open Available Browser ${url}
${page_title}= Get Title
RETURN ${page_title}
Further reading
You can learn more on these topics in the Robot Framework User Guide: