Robot Framework architecture

Test case file

Reports and logs

Project pages

The number one place to find more information about Robot Frameworkand the rich ecosystem around it ishttp://robotframework.org.Robot Framework itself is hosted onGitHub.

Mailing lists

There are several Robot Framework mailing lists where to ask andsearch for more information. The mailing list archives are open foreveryone (including the search engines) and everyone can also jointhese lists freely. Only list members can send mails, though, and toprevent spam new users are moderated which means that it might take alittle time before your first message goes through. Do not be afraidto send question to mailing lists but rememberHow To Ask QuestionsThe Smart Way.

robotframework-users

General discussion about all Robot Framework relatedissues. Questions and problems can be sent to this list. Used alsofor information sharing for all users.

robotframework-announce

An announcements-only mailing list where only moderators can sendmessages. All announcements are sent also to therobotframework-users mailing list so there is no need to join bothlists.

robotframework-devel

Discussion about Robot Framework development.

Installing Python on Linux

On Linux you should have suitable Python installation withpip availableby default. If not, you need to consult your distributions documentationto learn how to install them. This is also true if you want to use some otherPython version than the one provided by your distribution by default.

To check what Python version you have installed, you can runpython --versioncommand in a terminal:

$python--versionPython3.10.13

Notice that if your distribution provides also older Python 2, runningpythonmay use that. To use Python 3, you can usepython3 command or even more versionspecific command likepython3.8. You need to use these version specific variantsalso if you have multiple Python 3 versions installed and need to pinpoint whichone to use:

$python3.11--versionPython3.11.7$python3.12--versionPython3.12.1

Installing Robot Framework directly under the system provided Pythonhas a risk that possible problems can affect the whole Python installationused also by the operating system itself. NowadaysLinux distributions typically useuser installs by default to avoid suchproblems, but users can also themselves decide to usevirtual environments.

Installing Python on Windows

On Windows Python is not available by default, but it is easy to install.The recommended way to install it is using the official Windows installers availableathttp://python.org. For other alternatives, such as installing from theMicrosoft Store, see theofficial Python documentation.

When installing Python on Windows, it is recommended to add Python toPATHto make it and tools like pip and Robot Framework easier to execute fromthe command line. When using theofficial installer, you just needto select theAdd Python 3.x to PATH checkbox on the first dialog.

To make sure Python installation has been successful and Python has beenadded toPATH, you can open the command prompt and executepython --version:

C:\>python --versionPython 3.10.9

If you install multiple Python versions on Windows, the version that is usedwhen you executepython is the one first inPATH. If you need to use others,the easiest way is using thepy launcher:

C:\>py --versionPython 3.10.9C:\>py -3.12 --versionPython 3.12.1

Installing Python on macOS

MacOS does not provide Python 3 compatible Python version by default, so itneeds to be installed separately. The recommended approach is using the officialmacOS installers available athttp://python.org. If you are using a packagemanager likeHomebrew, installing Python via it ispossible as well.

You can validate Python installation on macOS usingpython --version like onother operating systems.

PyPy installation

PyPy is an alternative Python implementation. Its main advantage over thestandard Python implementation is that it can be faster and use less memory,but this depends on the context where and how it is used. If execution speedis important, at least testing PyPy is probably a good idea.

Installing PyPy is a straightforward procedure and you can find both installersand installation instructions athttp://pypy.org. To validate that PyPy installationwas successful, runpypy --version orpypy3 --version.

ConfiguringPATH

ThePATH environment variable lists directories where commands executed ina system are searched from. To make using Python,pip and Robot Framework easierfrom the command line, it is recommended to add the Python installation directoryas well as the directory where commands likepip androbot are installedintoPATH.

When using Python on Linux or macOS, Python and tools installed with it should beautomatically inPATH. If you nevertheless need to updatePATH, youtypically need to edit some system wide or user specific configuration file.Which file to edit and how depends on the operating system and you need toconsult its documentation for more details.

On Windows the easiest way to make surePATH is configured correctly issetting theAdd Python 3.x to PATH checkbox whenrunning the installer.To manually modifyPATH on Windows, follow these steps:

1. FindEnvironment Variables underSettings. There are variables affectingthe whole system and variables affecting only the current user. Modifyingthe former will require admin rights, but modifying the latter is typicallyenough.
2. SelectPATH (often written likePath) and clickEdit. If you areediting user variables andPATH does not exist, clickNew instead.
3. Add both the Python installation directory and theScripts directoryunder the installation directory intoPATH.
4. Exit the dialog withOk to save the changes.
5. Start a new command prompt for the changes to take effect.

Runningpip command

Typically you use pip by running thepip command, but on Linux you may needto usepip3 or even more Python version specific variant likepip3.8instead. When runningpip or any of its variants, the pip version that isfound first inPATH will be used. If you have multiple Python versionsinstalled, you may need to pinpoint which exact version you want to use.This is typically easiest done by runningpython -m pip and substitutingpython with the Python version you want to use.

To make sure you have pip available, you can runpip --version or equivalent.

Examples on Linux:

$pip--versionpip23.2.1from...(python3.10)$python3.12-mpip--versionpip23.3.1from...(python3.12)

Examples on Windows:

C:\> pip --versionpip 23.2.1 from ... (python 3.10)C:\> py -m 3.12 -m pip --versionpip 23.3.2 from ... (python 3.12)

In the subsequent sections pip is always run using thepip command. You mayneed to use some of the other approaches explained above in your environment.

Installing and uninstalling Robot Framework

The easiest way to use pip is by letting it find and download packages itinstalls from thePython Package Index (PyPI), but it can also installpackages downloaded from the PyPI separately. The most common usages areshown below andpip documentation has more information and examples.

# Install the latest version (does not upgrade)pipinstallrobotframework# Upgrade to the latest stable versionpipinstall--upgraderobotframework# Upgrade to the latest version even if it is a pre-releasepipinstall--upgrade--prerobotframework# Install a specific versionpipinstallrobotframework==7.0# Install separately downloaded package (no network connection needed)pipinstallrobotframework-7.0-py3-none-any.whl# Install latest (possibly unreleased) code directly from GitHubpipinstallhttps://github.com/robotframework/robotframework/archive/master.zip# Uninstallpipuninstallrobotframework

Note

Section headers can belocalized. See theTranslations appendix forsupported translations.

Space separated format

When Robot Framework parses data, it first splits the data to lines and thenlines to tokens such as keywords and arguments. When using the spaceseparated format, the separator between tokens is two or more spaces oralternatively one or more tab characters. In addition to the normal ASCIIspace, any Unicode character considered to be a space (e.g. no-break space)works as a separator. The number of spaces used as separator can vary, aslong as there are at least two, making it possible to align the data nicelyin settings and elsewhere when it makes the data easier to understand.

*** Settings ***DocumentationExample using the space separated format.LibraryOperatingSystem*** Variables ***${MESSAGE}Hello, world!*** Test Cases ***My Test    [Documentation]Example test.Log    ${MESSAGE}My Keyword    ${CURDIR}Another TestShould Be Equal    ${MESSAGE}Hello, world!*** Keywords ***My Keyword    [Arguments]    ${path}Directory Should Exist    ${path}

Because tabs and consecutive spaces are considered separators, they mustbe escaped if they are needed in keyword arguments or elsewherein the actual data. It is possible to use special escape syntax like\t for tab and\xA0 for no-break space as well asbuilt-in variables${SPACE} and${EMPTY}. See theEscaping section for details.

Pipe separated format

The biggest problem of the space delimited format is that visuallyseparating keywords from arguments can be tricky. This is a problemespecially if keywords take a lot of arguments and/or argumentscontain spaces. In such cases the pipe delimited variant canwork better because it makes the separator more visible.

One file can contain both space separated and pipe separated lines.Pipe separated lines are recognized by the mandatory leading pipe character,but the pipe at the end of the line is optional. There must always be atleast one space or tab on both sides of the pipe except at the beginning andat the end of the line. There is no need to align the pipes, but that oftenmakes the data easier to read.

|*** Settings ***   ||Documentation      |Example using the pipe separated format.|Library            |OperatingSystem|*** Variables ***  || ${MESSAGE}         |Hello, world!|*** Test Cases *** |                 |               ||My Test            | [Documentation] |Example test. ||                    |Log             | ${MESSAGE}    ||                    |My Keyword      | ${CURDIR}     ||Another Test       |Should Be Equal | ${MESSAGE}    |Hello, world!|*** Keywords ***   |                        |         ||My Keyword         | [Arguments]            | ${path} ||                    |Directory Should Exist | ${path} |

When using the pipe separated format, consecutive spaces or tabs insidearguments do not need to be escaped. Similarly empty columns do not needto be escaped exceptif they are at the end. Possible pipes surrounded byspaces in the actual test data must be escaped with a backslash, though:

|*** 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 thatis commonly used for documentation of Python projects, including Python itselfas well as this User Guide. reST documents are most often compiled to HTML,but also other output formats are supported. Using reST with Robot Frameworkallows you to mix richly formatted documents and test data in a concise textformat that is easy to work with using simple text editors, diff tools, andsource control systems.

When using Robot Framework with reStructuredText files, normal Robot Frameworkdata is embedded to so called code blocks. In standard reST code blocks aremarked using thecode directive, but Robot Framework supports alsocode-block orsourcecode directives used by theSphinx tool.

reStructuredText example------------------------This text is outside code blocks and thus ignored...code::robotframework*** Settings ***DocumentationExample using the reStructuredText format.LibraryOperatingSystem*** Variables ***${MESSAGE}Hello, world!*** Test Cases ***My Test    [Documentation]Example test.Log    ${MESSAGE}My Keyword    ${CURDIR}Another TestShould Be Equal    ${MESSAGE}Hello, world!Also this text is outside code blocks and ignored. Code blocks notcontaining Robot Framework data are ignored as well...code::robotframework# Both space and pipe separated formats are supported.|*** Keywords ***  |                        |         ||My Keyword        | [Arguments]            | ${path} ||                   |Directory Should Exist | ${path} |..code::python# This code block is ignored.defexample():print('Hello, world!')

Robot Framework supports reStructuredText files using.robot.rst,.rst and.rest extensions. To avoid parsing unrelatedreStructuredText files, only files with the.robot.rst extensionare parsed by default when executing a directory. Parsing files withother extensionscan be enabled by using either--parseincludeor--extension option.

When Robot Framework parses reStructuredText files, errors below levelSEVERE are ignored to avoid noise about possible non-standard directivesand other such markup. This may hide also real errors, but they can be seenwhen processing files using reStructuredText tooling normally.

JSON format

Robot Framework supports data also in theJSON format. This format is designedmore for tool developers than for regular Robot Framework users and it is notmeant to be edited manually. Its most important use cases are:

• Transferring data between processes and machines. A suite can be convertedto JSON in one machine and recreated somewhere else.
• Saving a suite, possibly a nested suite, constructed from normal Robot Frameworkdata into a single JSON file that is faster to parse.
• Alternative data format for external tools generating tests or tasks.

fromrobot.runningimportTestSuite# Create suite based on data on the file system.suite=TestSuite.from_file_system('/path/to/data')# Get JSON data as a string.data=suite.to_json()# Save JSON data to a file with custom indentation.suite.to_json('data.rbt',indent=2)

fromrobot.runningimportTestSuite# Create suite from JSON data in a file.suite=TestSuite.from_json('data.rbt')# Create suite from a JSON string.suite=TestSuite.from_json('{"name": "Suite", "tests": [{"name": "Test"}]}')# Execute suite. Notice that log and report needs to be created separately.suite.run(output='example.xml')

fromrobot.runningimportTestSuite# Create a suite, adjust source and convert to JSON.suite=TestSuite.from_file_system('/path/to/data')suite.adjust_source(relative_to='/path/to')suite.to_json('data.rbt')# Recreate suite elsewhere and adjust source accordingly.suite=TestSuite.from_json('data.rbt')suite.adjust_source(root='/new/path/to')

Ignored data

When Robot Framework parses the test data files, it ignores:

• All data before the firsttest data section.
• Data in theComments section.
• All empty rows.
• All empty cells at the end of rows when using thepipe separated format.
• All single backslashes (\) when not used forescaping.
• All characters following the hash character (#), when it is the firstcharacter of a cell. This means that hash marks can be used to entercomments in the test data.

When Robot Framework ignores some data, this data is not available inany resulting reports and, additionally, most tools used with RobotFramework also ignore them. To add information that is visible inRobot Framework outputs, place it to the documentation or other metadata oftest cases or suites, or log it with theBuiltIn keywordsLog orComment.

Escaping

The escape character in Robot Framework test data is the backslash(\) and additionallybuilt-in variables${EMPTY} and${SPACE}can often be used for escaping. Different escaping mechanisms arediscussed in the sections below.

*** Test Cases ***Using backslashDo Somethingfirst arg\Do Something\second argUsing${EMPTY}Do Somethingfirst arg    ${EMPTY}Do Something    ${EMPTY}second arg

|*** Test Cases *** |              |           |            ||Using backslash    |Do Something |first arg |\          ||                    |Do Something |           |second arg ||                    |              |           |            ||Using${EMPTY}     |Do Something |first arg | ${EMPTY}   ||                    |Do Something |           |second arg |

Dividing data to several rows

If there is more data than readily fits a row, it is possible to split itand start continuing rows with ellipsis (...). Ellipses can be indentedto match the indentation of the starting row and they must always be followedby the normal test data separator.

In most places split lines have exact same semantics as lines that are notsplit. Exceptions to this rule aresuite,test andkeyword documentationas wellsuite metadata. With them split values are automaticallyjoined together with the newline character to ease creating multilinevalues.

The... syntax allows also splitting variables in theVariable section.When long scalar variables (e.g.${STRING}) are split to multiple rows,the final value is got by concatenating the rows together. The separator isa space by default, but that can be changed by starting the value withSEPARATOR=<sep>.

Splitting lines is illustrated in the following two examples containingexactly same data without and with splitting.

*** Settings ***DocumentationHere we have documentation for this suite.\nDocumentation is often quite long.\n\nIt can also contain multiple paragraphs.Test Tagstest tag 1test tag 2test tag 3test tag 4test tag 5*** Variables ***${STRING}This is a long string. It has multiple sentences. It does not have newlines.${MULTILINE}This is a long multiline string.\nThis is the second line.\nThis is the third and the last line.@{LIST}thislistisquitelonganditems in it can also be long&{DICT}first=This value is pretty long.second=This value is even longer. It has two sentences.*** Test Cases ***Example    [Tags]youprobablydonothavethismanytagsinreallifeDo Xfirst argumentsecond argumentthird argumentfourth argumentfifth argumentsixth argument    ${var} =Get Xfirst argument passed to this keyword is pretty longsecond argument passed to this keyword is long too

*** Settings ***DocumentationHere we have documentation for this suite....Documentation is often quite long.......It can also contain multiple paragraphs.Test Tagstest tag 1test tag 2test tag 3...test tag 4test tag 5*** Variables ***${STRING}This is a long string....It has multiple sentences....It does not have newlines.${MULTILINE}SEPARATOR=\n...This is a long multiline string....This is the second line....This is the third and the last line.@{LIST}thislistisquitelongand...items in it can also be long&{DICT}first=This value is pretty long....second=This value is even longer. It has two sentences.*** Test Cases ***Example    [Tags]youprobablydonothavethismany    ...tagsinreallifeDo Xfirst argumentsecond argumentthird argument    ...fourth argumentfifth argumentsixth argument    ${var} =Get X    ...first argument passed to this keyword is pretty long    ...second argument passed to this keyword is long too

Enabling languages

robot --language Finnish testit.robotrobot --language pt --language ptbr testes.robot

robot --language Custom.py tests.robotrobot --language MyLang tests.robot

Language: Finnish*** Asetukset ***Dokumentaatio        Example using Finnish.

Built-in languages

The following languages are supported out-of-the-box. Click the language nameto see the actual translations:

• Arabic (ar)
• Bulgarian (bg)
• Bosnian (bs)
• Czech (cs)
• German (de)
• Spanish (es)
• Finnish (fi)
• French (fr)
• Hindi (hi)
• Italian (it)
• Japanese (ja)
• Korean (ko)
• Dutch (nl)
• Polish (pl)
• Portuguese (pt)
• Brazilian Portuguese (pt-BR)
• Romanian (ro)
• Russian (ru)
• Swedish (sv)
• Thai (th)
• Turkish (tr)
• Ukrainian (uk)
• Vietnamese (vi)
• Chinese Simplified (zh-CN)
• Chinese Traditional (zh-TW)

All these translations have been provided by the awesome Robot Frameworkcommunity. If a language you are interested in is not included, you canconsidercontributing it!

Custom language files

If a language you would need is not available as a built-in language, or youwant to create a totally custom language for some specific need, you can easilycreate a custom language file. Language files are Python files that containone or more language definitions that are all loaded when the language fileis taken into use. Language definitions are created by extending therobot.api.Language base class and overriding class attributes as needed:

fromrobot.apiimportLanguageclassExample(Language):test_cases_header='Validations'tags_setting='Labels'given_prefixes=['Assuming']true_strings=['OK','\N{THUMBS UP SIGN}']

Assuming the above code would be in fileexample.py, a path to thatfile or just the module nameexample could be used when the language fileisactivated.

The above example adds only some of the possible translations. That is finebecause English is automatically enabled anyway. Most values must be specifiedas strings, but BDD prefixes and true/false strings allow more than one valueand must be given as lists. For more examples, see Robot Framework's internallanguages module that contains theLanguage class as well as all built-inlanguage definitions.

Contributing translations

If you want to add translation for a new language or enhance existing, headtoCrowdin that we use for collaboration. For more details, see theseparateLocalization project, and for questions and free discussion jointhe#localization channel on ourSlack.

Basic syntax

Test cases are constructed in test case sections from the availablekeywords. Keywords can be imported fromtest libraries orresourcefiles, or created in thekeyword section of the test case fileitself.

The first column in the test case section contains test case names. Atest case starts from the row with something in this column andcontinues to the next test case name or to the end of the section. It isan error to have something between the section headers and the firsttest.

The second column normally has keyword names. An exception to this ruleissetting variables from keyword return values, when the second andpossibly also the subsequent columns contain variable names and a keywordname is located after them. In either case, columns after the keyword namecontain possible arguments to the specified keyword.

*** Test Cases ***Valid LoginOpen Login PageInput UsernamedemoInput PasswordmodeSubmit CredentialsWelcome Page Should Be OpenSetting VariablesDo Somethingfirst argumentsecond argument    ${value} =Get Some ValueShould Be Equal    ${value}Expected value

Settings in the Test Case section

Test cases can also have their own settings. Setting names are alwaysin the second column, where keywords normally are, and their valuesare in the subsequent columns. Setting names have square brackets aroundthem to distinguish them from keywords. The available settings are listedbelow and explained later in this section.

[Documentation]

Used for specifying atest case documentation.

[Setup],[Teardown]

Specifytest setup and teardown.

[Tags]

Used fortagging test cases.

[Template]

Specifies thetemplate keyword to use. The test itself will contain onlydata to use as arguments to that keyword.

[Timeout]

Used for setting atest case timeout.Timeouts are discussed intheir own section.

Example test case with settings:

*** Test Cases ***Test With Settings    [Documentation]Another dummy test    [Tags]dummyowner-johndoeLogHello, world!

Test case related settings in the Setting section

The Setting section can have the following test case relatedsettings. These settings are mainly default values for thetest case specific settings listed earlier.

Test Setup,Test Teardown

The default values fortest setup and teardown.

Test Tags

Tags all tests in the suite will get in addition to their possible own tags.

Test Template

The defaulttemplate keyword to use.

Test Timeout

The default value fortest case timeout.Timeouts are discussed intheir own section.

Positional arguments

Most keywords have a certain number of arguments that must always begiven. In the keyword documentation this is denoted by specifying theargument names separated with a comma likefirst, second,third. The argument names actually do not matter in this case, exceptthat they should explain what the argument does, but it is importantto have exactly the same number of arguments as specified in thedocumentation. Using too few or too many arguments will result in anerror.

The test below uses keywordsCreate Directory andCopyFile from theOperatingSystem library. Their arguments arespecified aspath andsource, destination, which meansthat they take one and two arguments, respectively. The last keyword,No Operation fromBuiltIn, takes no arguments.

*** Test Cases ***ExampleCreate Directory    ${TEMPDIR}/stuffCopy File    ${CURDIR}/file.txt    ${TEMPDIR}/stuffNo Operation

Default values

Arguments often have default values which can either be given ornot. In the documentation the default value is typically separatedfrom the argument name with an equal sign likename=defaultvalue. It is possible that all the arguments have defaultvalues, but there cannot be any positional arguments after argumentswith default values.

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

*** Test Cases ***ExampleCreate File    ${TEMPDIR}/empty.txtCreate File    ${TEMPDIR}/utf-8.txtHyvä esimerkkiCreate File    ${TEMPDIR}/iso-8859-1.txtHyvä esimerkkiISO-8859-1

Variable number of arguments

It is also possible that a keyword accepts any number of arguments.These so calledvarargs can be combined with mandatory argumentsand arguments with default values, but they are always given afterthem. In the documentation they have an asterisk before the argumentname like*varargs.

For example,Remove Files andJoin Paths keywords fromtheOperatingSystem library have arguments*paths andbase, *parts,respectively. The former can be used with any number of arguments, butthe latter requires at least one argument.

*** Test Cases ***ExampleRemove Files    ${TEMPDIR}/f1.txt    ${TEMPDIR}/f2.txt    ${TEMPDIR}/f3.txt    @{paths} =Join Paths    ${TEMPDIR}f1.txtf2.txtf3.txtf4.txt

Named arguments

The named argument syntax makes using arguments withdefault values moreflexible, and allows explicitly labeling what a certain argument value means.Technically named arguments work exactly likekeyword arguments in Python.

*** Test Cases ***ExampleRun Programshell=True# This will not come as a named argument to Run Process*** Keywords ***Run Program    [Arguments]    @{args}Run Processprogram.py    @{args}# Named arguments are not recognized from inside @{args}

*** Settings ***LibraryTelnetprompt=$default_log_level=DEBUG*** Test Cases ***ExampleOpen connection10.0.0.42port=${PORT}alias=exampleList filesoptions=-lhList filespath=/tmpoptions=-l*** Keywords ***List files    [Arguments]    ${path}=.    ${options}=Execute commandls${options}${path}

Free named arguments

Robot Framework supportsfree named arguments, often also calledfreekeyword arguments orkwargs, similarly asPython supports **kwargs.What this means is that a keyword can receive all arguments that usethenamed argument syntax (name=value) and do not match any argumentsspecified in the signature of the keyword.

Free named arguments are supported by same keyword types thannormal namedarguments. How keywords specify that they accept free named argumentsdepends on the keyword type. For example,Python based keywords simply use**kwargs anduser keywords use&{kwargs}.

Free named arguments support variables similarly asnamed arguments. In practice that means that variablescan be used both in names and values, but the escape sign must always bevisible literally. For example, bothfoo=${bar} and${foo}=${bar} arevalid, as long as the variables that are used exist. An extra limitation isthat free argument names must always be strings.

*** Test Cases ***Free Named ArgumentsRun Processprogram.pyarg1arg2cwd=/home/userRun Processprogram.pyargumentshell=Trueenv=${ENVIRON}

*** Test Cases ***Free Named ArgumentsRun Programarg1arg2cwd=/home/userRun Programargumentshell=Trueenv=${ENVIRON}*** Keywords ***Run Program    [Arguments]    @{args}    &{config}Run Processprogram.py    @{args}    &{config}

Named-only arguments

Starting from Robot Framework 3.1, keywords can accept argument that mustalways be named using thenamed argument syntax. If, for example,a keyword would accept a single named-only argumentexample, it wouldalways need to be used likeexample=value and using justvalue wouldnot work. This syntax is inspired by thekeyword-only argumentssyntax supported by Python 3.

For most parts named-only arguments work the same way asnamed arguments.The main difference is that libraries implemented with Python 2 usingthestatic library APIdo not support this syntax.

As an example of using thenamed-only arguments with user keywords, hereis a variation of theRun Program in the abovefree named argumentexamples that only supports configuringshell:

*** Test Cases ***Named-only ArgumentsRun Programarg1arg2# 'shell' is False (default)Run Programargumentshell=True# 'shell' is True*** Keywords ***Run Program    [Arguments]    @{args}    ${shell}=FalseRun Processprogram.py    @{args}shell=${shell}

Arguments embedded to keyword names

A totally different approach to specify arguments is embedding theminto keyword names. This syntax is supported by bothtest library keywordsanduser keywords.

When test case fails

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

Error messages

The error message assigned to a failed test case is got directly from thefailed keyword. Often the error message is created by the keyword itself, butsome 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 messageis got by combining the individual errors. Very long error messages areautomatically cut from the middle to keepreports easier to read, butfull error messages are always visible inlog files as messages ofthe failed keywords.

By default error messages are normal text, butthey cancontain HTML formatting. Thisis enabled by starting the error message with marker string*HTML*.This marker will be removed from the final error message shown in reportsand logs. Using HTML in a custom message is shown in the second example below.

*** Test Cases ***Normal ErrorFailThis is a rather boring example...HTML Error    ${number} =Get NumberShould Be Equal    ${number}42*HTML* Number is not my <b>MAGIC</b> number.

*** Variables ***${MAX AMOUNT}      ${5000000}*** Test Cases ***Amount cannot be larger than${MAX AMOUNT}# ...

*** Test Cases ***Simple    [Documentation]Simple and short documentation.No OperationMultiple lines    [Documentation]First row of the documentation.    ...    ...Documentation continues here. These rows form    ...a paragraph when shown in HTML outputs.No OperationFormatting    [Documentation]    ...This list has:    ...- *bold*    ...- _italics_    ...- link: http://robotframework.orgNo OperationVariables    [Documentation]Executed at${HOST} by${USER}No Operation

*** Settings ***Test Tagsrequirement: 42smoke*** Variables ***${HOST}10.0.1.42*** Test Cases ***No own tags    [Documentation]Test has tags 'requirement: 42' and 'smoke'.No OperationOwn tags    [Documentation]Test has tags 'requirement: 42', 'smoke' and 'not ready'.    [Tags]not readyNo OperationOwn tags with variable    [Documentation]Test has tags 'requirement: 42', 'smoke' and 'host: 10.0.1.42'.    [Tags]host:${HOST}No OperationRemove common tag    [Documentation]Test has only tag 'requirement: 42'.    [Tags]-smokeNo OperationRemove common tag using a pattern    [Documentation]Test has only tag 'smoke'.    [Tags]-requirement: *No OperationSet Tags and Remove Tags keywords    [Documentation]This test has tags 'smoke', 'example' and 'another'.Set TagsexampleanotherRemove Tagsrequirement: *

Note

TheTest Tags setting is new in Robot Framework 6.0.Earlier versions supportForce Tags andDefault Tagssettings discussed in the next section.

Note

The-tag syntax for removing tags using the[Tags] settingis new in Robot Framework 7.0.

Deprecation ofForce Tags andDefault Tags

Prior to Robot Framework 6.0, tags could be specified to tests in the Setting sectionusing two different settings:

Force Tags

All tests unconditionally get these tags. This is exactly the same asTest Tags nowadays.

Default Tags

All tests get these tags by default. If a test has[Tags],it will not get these tags.

Both of these settings still work, but they are considered deprecated.A visible deprecation warning will be added in the future, most likelyin Robot Framework 8.0, and eventually these settings will be removed.Tools likeTidy can be used to ease transition.

UpdatingForce Tags requires only renaming it toTest Tags.TheDefault Tags setting will be removed altogether, but the-tagfunctionality introduced in Robot Framework 7.0 provides same underlyingfunctionality. The following examples demonstrate the needed changes.

Old syntax:

*** Settings ***Force TagsallDefault Tagsdefault*** Test Cases ***Common only    [Documentation]Test has tags 'all' and 'default'.No OperationNo default    [Documentation]Test has only tag 'all'.    [Tags]No OperationOwn and no default    [Documentation]Test has tags 'all' and 'own'.    [Tags]ownNo Operation

New syntax:

*** Settings ***Test Tagsalldefault*** Test Cases ***Common only    [Documentation]Test has tags 'all' and 'default'.No OperationNo default    [Documentation]Test has only tag 'all'.    [Tags]-defaultNo OperationOwn and no default    [Documentation]Test has tags 'all' and 'own'.    [Tags]own-defaultNo Operation

Reserved tags

Users are generally free to use whatever tags that work in their context.There are, however, certain tags that have a predefined meaning for RobotFramework itself, and using them for other purposes can have unexpectedresults. All special tags Robot Framework has and will have in the futurehave therobot: prefix. To avoid problems, users should thus not use anytag with this prefixes unless actually activating the special functionality.The current reserved tags are listed below, but more such tags are likelyto be added in the future.

robot:continue-on-failure androbot:recursive-continue-on-failure

Used forenabling the continue-on-failure mode.

robot:stop-on-failure androbot:recursive-stop-on-failure

Used fordisabling the continue-on-failure mode.

robot:exit-on-failure

Stop the whole execution if atest with this tag fails.

robot:skip-on-failure

Mark test to beskipped if it fails.

robot:skip

Mark test to beunconditionally skipped.

robot:exclude

Mark test to beunconditionally excluded.

robot:private

Mark keyword to beprivate.

robot:no-dry-run

Mark keyword not to be executed in thedry run mode.

robot:exit

Added to tests automatically whenexecution is stopped gracefully.

robot:flatten

Enableflattening keyword during execution time.

As of RobotFramework 4.1, reserved tags are suppressed by default intag statistics. They will be shown when they are explicitlyincluded via the--tagstatinclude robot:* command line option.

*** Settings ***Test SetupOpen ApplicationApp ATest TeardownClose Application*** Test Cases ***Default values    [Documentation]Setup and teardown from setting sectionDo SomethingOverridden setup    [Documentation]Own setup, teardown from setting section    [Setup]Open ApplicationApp BDo SomethingNo teardown    [Documentation]Default setup, no teardown at allDo Something    [Teardown]No teardown 2    [Documentation]Setup and teardown can be disabled also with special value NONEDo Something    [Teardown]NONEUsing variables    [Documentation]Setup and teardown specified using variables    [Setup]    ${SETUP}Do Something    [Teardown]    ${TEARDOWN}

Note

Test suites can have a setup and teardown of theirown. A suite setup is executed before any test cases or sub testsuites in that test suite, and similarly a suite teardown isexecuted after them.

Basic usage

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

*** Test Cases ***Normal test caseExample keywordfirst argumentsecond argumentTemplated test case    [Template]Example keywordfirst argumentsecond argument

As the example illustrates, it is possible to specify thetemplate for an individual test case using the[Template]setting. An alternative approach is using theTest Templatesetting in the Setting section, in which case the template is appliedfor all test cases in that test case file. The[Template]setting overrides the possible template set in the Setting section, andan empty value for[Template] means that the test has notemplate even whenTest Template is used. It is also possibleto use valueNONE to indicate that a test has no template.

Using keywords withdefault values or acceptingvariable number of arguments,as well as usingnamed arguments andfree named arguments, work with templatesexactly like they work otherwise. Usingvariables in arguments is alsosupported normally.

Templates with multiple iterations

If a templated test case has multiple data rows in its body, the templateis applied for all the rows one by one. Thismeans that the same keyword is executed multiple times, once with dataon each row.

*** Settings ***Test TemplateExample keyword*** Test Cases ***Templated test casefirst round 1first round 2second round 1second round 2third round 1third round 2

Templated tests are special so that all iterations are executed even if oneor more of them is failed or skipped. The aggregated result of a templatedtest with multiple iterations is:

• FAIL if any of the iterations failed.
• PASS if there were no failures and at least one iteration passed.
• SKIP if all iterations were skipped.

Templates with embedded arguments

Templates support a variation oftheembedded argument syntax. With templates this syntax works sothat if the template keyword has variables in its name, they are consideredplaceholders for arguments and replaced with the actual argumentsused with the template. The resulting keyword is then used without positionalarguments. This is best illustrated with an example:

*** Test Cases ***Normal test case with embedded argumentsThe result of 1 + 1 should be 2The result of 1 + 2 should be 3Template with embedded arguments    [Template]The result of${calculation} should be${expected}1 + 121 + 23*** 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 inthe 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 Cases ***Different argument names    [Template]The result of${foo} should be${bar}1 + 121 + 23Only some arguments    [Template]The result of${calculation} should be 31 + 24 - 1New arguments    [Template]The${meaning} of${life} should be 42result21 * 2

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

Templates withFOR loops

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

*** Test Cases ***Template with FOR loop    [Template]Example keywordFOR    ${item}IN    @{ITEMS}        ${item}2nd argENDFOR    ${index}IN RANGE421st arg    ${index}END

Templates withIF/ELSE structures

IF/ELSE structures can be also used together with templates.This can be useful, for example, when used together withFOR loops tofilter executed arguments.

*** Test Cases ***Template with FOR and IF    [Template]Example keywordFOR    ${item}IN    @{ITEMS}IF  ${item} < 5            ${item}2nd argENDEND

Keyword-driven style

Workflow tests, such as theValid Login test describedearlier, are constructed from several keywords and their possiblearguments. Their normal structure is that first the system is takeninto the initial state (Open Login Page in theValidLogin example), then something is done to the system (InputName,Input Password,Submit Credentials), andfinally it is verified that the system behaved as expected(Welcome Page Should Be Open).

Data-driven style

Another style to write test cases is thedata-driven approach wheretest cases use only one higher-level keyword, often created as auser keyword, that hides the actual test workflow. These tests arevery useful when there is a need to test the same scenario withdifferent input and/or output data. It would be possible to repeat thesame keyword with every test, but thetest template functionalityallows specifying the keyword to use only once.

*** Settings ***Test TemplateLogin with invalid credentials should fail*** Test Cases ***USERNAMEPASSWORDInvalid User Nameinvalid          ${VALID PASSWORD}Invalid Password                  ${VALID USER}invalidInvalid User Name and PasswordinvalidinvalidEmpty User Name                   ${EMPTY}         ${VALID PASSWORD}Empty Password                    ${VALID USER}    ${EMPTY}Empty User Name and Password      ${EMPTY}         ${EMPTY}

The above example has six separate tests, one for each invaliduser/password combination, and the example below illustrates how tohave only one test with all the combinations. When usingtesttemplates, all the rounds in a test are executed even if there arefailures, so there is no real functional difference between these twostyles. In the above example separate combinations are named so it iseasier to see what they test, but having potentially large number ofthese tests may mess-up statistics. Which style to use depends on thecontext and personal preferences.

*** Test Cases ***Invalid Password    [Template]Login with invalid credentials should failinvalid          ${VALID PASSWORD}    ${VALID USER}invalidinvalidwhatever    ${EMPTY}         ${VALID PASSWORD}    ${VALID USER}    ${EMPTY}    ${EMPTY}         ${EMPTY}

Behavior-driven style

It is also possible to write test cases as requirements that also non-technicalproject stakeholders must understand. Theseexecutable requirements are acorner stone of a process commonly calledAcceptance Test Driven Development(ATDD) orSpecification by Example.

One way to write these requirements/tests isGiven-When-Then stylepopularized byBehavior Driven Development (BDD). When writing test cases inthis style, the initial state is usually expressed with a keyword starting withwordGiven, the actions are described with keyword starting withWhen and the expectations with a keyword starting withThen.Keyword starting withAnd orBut may be used if a step has morethan one action.

*** Test Cases ***Valid LoginGivenlogin page is openWhenvalid username and password are insertedandcredentials are submittedThenwelcome page should be open

*** Tasks ***Process invoiceRead information from PDFValidate informationSubmit information to backend systemValidate information is visible in web UI

Note

Setting names are case-insensitive, but the format used above is recommended.

Suite initialization files

A test suite created from a directory can have similar settings as a suitecreated from a test case file. Because a directory alone cannot have thatkind of information, it must be placed into a special test suite initializationfile. An initialization file name must always be of the format__init__.ext, where the extension must be one of thesupportedfile formats (typically__init__.robot).The name format is borrowed from Python, where files named in this mannerdenote that a directory is a module.

Starting from Robot Framework 6.1, it is also possible to define a suiteinitialization file for automatically created suite when starting the testexecution by giving multiplepaths.

Initialization files have the same structure and syntax as test case files,except that they cannot have test case sections and not all settings aresupported. Variables and keywords created or imported in initialization filesare not available in the lower level test suites. If you need to sharevariables or keywords, you can put them intoresource files that can beimported both by initialization and test case files.

The main usage for initialization files is specifying test suite relatedsettings similarly as insuite files, but setting sometest caserelated settings is also possible. How to use different settings in theinitialization files is explained below.

Name,Documentation,Metadata,Suite Setup,Suite Teardown

These suite specific settings work the same way in suite initialization filesas in suite files.

Test Tags

Specified tags are unconditionally set to all tests in all suite filesthis directory contains, recursively. New in Robot Framework 6.1. ThedeprecatedForce Tags needs to be used with older versions.

Test Setup,Test Teardown,Test Timeout

Set the default value for test setup/teardown or test timeout to all testcases this directory contains. Can be overridden on lower level.Notice that keywords used as setups and teardowns must be available intest case files where tests using them are. Defining keywords in theinitialization file itself is not enough.

Task Setup,Task Teardown,Task Tags,Task Timeout

Aliases forTest Setup,Test Teardown,Test TagsandTest Timeout, respectively, that can be used whencreating tasks, not tests.

Default Tags,Test Template

Not supported in initialization files.

*** Settings ***DocumentationExample suiteSuite SetupDo Something    ${MESSAGE}Test TagsexampleLibrarySomeLibrary*** Variables ***${MESSAGE}Hello, world!*** Keywords ***Do Something    [Arguments]    ${args}Some Keyword    ${arg}Another Keyword

*** Settings ***NameCustom suite name

*** Settings ***DocumentationAn example suite documentation with *some* _formatting_....Long documentation can be split into multiple lines.

*** Settings ***MetadataVersion2.0MetadataRobot Frameworkhttp://robotframework.orgMetadataPlatform           ${PLATFORM}MetadataLonger Value...Longer metadata values can be split into multiple...rows. Also *simple* _formatting_ is supported.

UsingLibrary setting

Libraries are normally imported in the Settings section using theLibrary setting with the library name or path as its value.Unlike most of the other data, the library name or pathis both case- and space-sensitive. If a library is in a package,the full name including the package name must be used.

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

*** Settings ***LibraryOperatingSystemLibrarypath/to/MyLibrary.pyLibrarymy.package.TestLibraryLibraryLibraryAcceptingArgumentsarg1arg2Library    ${LIBRARY}

It is possible to import test libraries insuite files,resource files andsuite initialization files. In all thesecases, all the keywords in the imported library are available in thatfile. With resource files, those keywords are also available in otherfiles using them.

UsingImport Library keyword

Another possibility to take a test library into use is using thekeywordImport Library from theBuiltIn library. This keywordtakes the library name or path and possible arguments similarly as theLibrary setting. Keywords from the imported library areavailable in the test suite where theImport Library keyword wasused. This approach is useful in cases where the library is notavailable when the test execution starts and only some other keywordsmake it available.

*** Test Cases ***ExampleDo SomethingImport LibraryMyLibraryarg1arg2KW From MyLibrary

Using library name

The most common way to specify a test library to import is using its name.In these cases Robot Framework tries to find the class or moduleimplementing the library from themodule search path. Libraries thatare installed somehow ought to be in the module search path automatically,but with other libraries the search path may need to be configured separately.

*** Settings ***LibraryOperatingSystemLibraryCustomLibrarypossibleargumentsLibrarylibrarymodule.LibraryClass

The biggest benefit of this approach is that when the module searchpath has been configured, often using a customstart-up script,normal users do not need to think where libraries actually areinstalled. The drawback is that getting your own, possiblevery simple, libraries into the search path may require someadditional configuration.

Using physical path to library

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

If the library is a file, the path to it must contain extension,i.e..py. If a library is implementedas a directory, the path to it must have a trailing forward slash (/)if the path is relative. With absolute paths the trailing slash is optional.Following examples demonstrate these different usages.

*** Settings ***LibraryPythonLibrary.pyLibraryrelative/path/PythonDirLib/possibleargumentsLibrary    ${RESOURCES}/Example.py

*** Settings ***Librarypackagename.TestLibASTestLibLibrary    ${LIBRARY}ASMyName

*** Settings ***LibrarySomeLibrarylocalhost1234ASLocalLibLibrarySomeLibraryserver.domain8080ASRemoteLib*** Test Cases ***ExampleLocalLib.Some Keywordsome argsecond argRemoteLib.Some Keywordanother argwhateverLocalLib.Another Keyword

Note

Prior to Robot Framework 6.0 the marker to use when giving a custom nameto a library wasWITH NAME instead ofAS. The old syntax continuesto work, but it is considered deprecated and will eventually be removed.

Normal standard libraries

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

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

Remote library

In addition to the normal standard libraries listed above, there isalsoRemote library that is totally different than the other standardlibraries. It does not have any keywords of its own but it works as aproxy between Robot Framework and actual test library implementations.These libraries can be running on other machines than the coreframework and can even be implemented using languages not supported byRobot Framework natively.

See separateRemote library interface section for more informationabout this concept.

Scalar variable syntax

The most common way to use variables in Robot Framework test data is usingthe scalar variable syntax like${var}. When this syntax is used, thevariable name is replaced with its value as-is. Most of the time variablevalues are strings, but variables can contain any object, including numbers,lists, dictionaries, or even custom objects.

The example below illustrates the usage of scalar variables. Assumingthat the variables${GREET} and${NAME} are availableand assigned to stringsHello andworld, respectively,these two example test cases are equivalent:

*** Test Cases ***ConstantsLogHelloLogHello, world!!VariablesLog    ${GREET}Log    ${GREET},${NAME}!!

When a scalar variable is used alone without any text or other variablesaround it, like in${GREET} above, the variable is replaced withits value as-is and the value can be any object. If the variable is not usedalone, like${GREER}, ${NAME}!! above, its value is first converted intoa string and then concatenated with the other data.

The example below demonstrates the difference between having avariable in alone or with other content. First, let us assumethat we have a variable${STR} set to a stringHello,world! and${OBJ} set to an instance of the following Pythonobject:

classMyObj:def__str__(self):return"Hi, terra!"

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

*** Test Cases ***ObjectsKW 1    ${STR}KW 2    ${OBJ}KW 3I said "${STR}"KW 4You said "${OBJ}"

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

• KW 1 gets a stringHello, world!
• KW 2 gets an object stored to variable${OBJ}
• KW 3 gets a stringI said "Hello, world!"
• KW 4 gets a stringYou said "Hi, terra!"

*** Test Cases ***Bytes alone    [Documentation]Keyword gets bytes '\x00\x01'.Keyword    ${a}Bytes concatenated with bytes    [Documentation]Keyword gets bytes '\x00\x01a\xe4'.Keyword    ${a}${b}Bytes concatenated with others    [Documentation]Keyword gets string '=\x00\x01a\xe4='.Keyword=${a}${b}=

List variable syntax

When a variable is used as a scalar like${EXAMPLE}, its value is beused as-is. If a variable value is a list or list-like, it is also possibleto use it as a list variable like@{EXAMPLE}. In this case the list is expandedand individual items are passed in as separate arguments.

This is easiest to explain with an example. Assuming that a variable${USER}contains a list with two itemsrobot andsecret, the first two of these testsare equivalent:

*** Test Cases ***ConstantsLoginrobotsecretList variableLogin    @{USER}List as scalarKeyword    ${USER}

The third test above illustrates that a variable containing a list can be usedalso as a scalar. In that test the keyword gets the whole list as a single argument.

Starting from Robot Framework 4.0, list expansion can be used in combination withlist item access making these usages possible:

*** Test Cases ***Nested container    ${nested} =Evaluate[['a', 'b', 'c'], {'key': ['x', 'y']}]Log Many    @{nested}[0]# Logs 'a', 'b' and 'c'.Log Many    @{nested}[1][key]# Logs 'x' and 'y'.Slice    ${items} =Create ListfirstsecondthirdLog Many    @{items}[1:]# Logs 'second' and  'third'.

*** Test Cases ***ExampleKeyword    @{LIST}moreargsKeyword    ${SCALAR}    @{LIST}constantKeyword    @{LIST}    @{ANOTHER}    @{ONE MORE}

*** Settings ***LibraryExampleLibrary      @{LIB ARGS}# This worksLibrary         ${LIBRARY}          @{LIB ARGS}# This worksLibrary         @{LIBRARY AND ARGS}# This does not workSuite SetupSome Keyword        @{KW ARGS}# This worksSuite Setup     ${KEYWORD}          @{KW ARGS}# This worksSuite Setup     @{KEYWORD AND ARGS}# This does not workTest Tags       @{TAGS}# This works

Dictionary variable syntax

As discussed above, a variable containing a list can be used as alistvariable to pass list items to a keyword as individual arguments.Similarly, a variable containing a Python dictionary or a dictionary-likeobject can be used as a dictionary variable like&{EXAMPLE}. In practicethis means that the dictionary is expanded and individual items are passed asnamed arguments to the keyword. Assuming that a variable&{USER} has avalue{'name': 'robot', 'password': 'secret'}, the first two test casesbelow are equivalent:

*** Test Cases ***ConstantsLoginname=robotpassword=secretDictionary variableLogin    &{USER}Dictionary as scalarKeyword    ${USER}

The third test above illustrates that a variable containing a dictionary can be usedalso as a scalar. In that test the keyword gets the whole dictionary as a single argument.

Starting from Robot Framework 4.0, dictionary expansion can be used in combination withdictionary item access making usages like&{nested}[key] possible.

*** Test Cases ***ExampleKeyword    &{DICT}named=argKeywordpositional    @{LIST}    &{DICT}Keyword    &{DICT}    &{ANOTHER}    &{ONE MORE}

*** Settings ***LibraryExampleLibrary    &{LIB ARGS}Suite SetupSome Keyword      &{KW ARGS}named=arg

Accessing list and dictionary items

It is possible to access items of subscriptable variables, e.g. lists and dictionaries,using special syntax like${var}[item] or${var}[nested][item].Starting from Robot Framework 4.0, it is also possible to use item access together withlist expansion anddictionary expansion by using syntax@{var}[item] and&{var}[item], respectively.

*** Test Cases ***Positive indexLogin    ${USER}[0]    ${USER}[1]Title Should BeWelcome${USER}[0]!Negative indexKeyword    ${SEQUENCE}[-1]Index defined as variableKeyword    ${SEQUENCE}[${INDEX}]

*** Test Cases ***Start indexKeyword    ${SEQUENCE}[1:]End indexKeyword    ${SEQUENCE}[:4]Start and endKeyword    ${SEQUENCE}[2:-1]StepKeyword    ${SEQUENCE}[::2]Keyword    ${SEQUENCE}[1:-1:10]

*** Test Cases ***Dictionary variable itemLogin    ${USER}[name]    ${USER}[password]Title Should BeWelcome${USER}[name]!Key defined as variableLog Many    ${DICT}[${KEY}]    ${DICT}[${42}]Attribute accessLogin    ${USER.name}    ${USER.password}Title Should BeWelcome${USER.name}!

*** Test Cases ***Nested item accessShould Be Equal    ${DATA}[0][name]RobotShould Be Equal    ${DATA}[1][id]      ${2}

Environment variables

Robot Framework allows using environment variables in the test data usingthe syntax%{ENV_VAR_NAME}. They are limited to string values. It ispossible to specify a default value, that is used if the environmentvariable does not exists, by separating the variable name and the defaultvalue with an equal sign like%{ENV_VAR_NAME=default value}.

Environment variables set in the operating system before the test execution areavailable during it, and it is possible to create new ones with the keywordSet Environment Variable or delete existing ones with thekeywordDelete Environment Variable, both available in theOperatingSystem library. Because environment variables are global,environment variables set in one test case can be used in other testcases executed after it. However, changes to environment variables arenot effective after the test execution.

*** Test Cases ***Environment variablesLogCurrent user:%{USER}Run    %{JAVA_HOME}${/}javacEnvironment variable with defaultSet Port    %{APPLICATION_PORT=8080}

Variable section

The most common source for variables are Variable sections insuite filesandresource files. Variable sections are convenient, because theyallow creating variables in the same place as the rest of the testdata, and the needed syntax is very simple. Their main disadvantage is thatvariables cannot be created dynamically. If that is a problem,variable filescan be used instead.

*** Variables ***${NAME}Robot Framework${VERSION}2.0${ROBOT}        ${NAME}${VERSION}

*** Variables ***${NAME} =Robot Framework${VERSION} =2.0

*** Variables ***${EXAMPLE}This value is joined...together with a space.${MULTILINE}First line....Second line....Third line....separator=\n

*** Variables ***${MULTILINE}SEPARATOR=\n...First line....Second line....Third line.

*** Variables ***@{NAMES}MattiTeppo@{NAMES2}       @{NAMES}Seppo@{NOTHING}@{MANY}onetwothreefour...fivesixseven

*** Variables ***&{USER 1}name=Mattiaddress=xxxphone=123&{USER 2}name=Teppoaddress=yyyphone=456&{MANY}first=1second=${2}         ${3}=third&{EVEN MORE}    &{MANY}first=overrideempty=...=emptykey\=here=value

*** Variables ***${X}Y${${X}}Z# Name is created based on '${X}'.*** Test Cases ***Dynamically created nameShould Be Equal    ${Y}Z

Using variable files

Variable files are the most powerful mechanism for creating differentkind of variables. It is possible to assign variables to any objectusing them, and they also enable creating variables dynamically. Thevariable file syntax and taking variable files into use is explainedin sectionResource and variable files.

Command line variables

Variables can be set from the command line either individually withthe--variable (-v) option or using the aforementioned variable fileswith the--variablefile (-V) option. Variables set from the command lineare globally available for all executed test data files, and they alsooverride possible variables with the same names in the Variable section and invariable files imported in the Setting section.

The syntax for setting individual variables is--variable name:value,wherename is the name of the variable without the${} decoration andvalueis its value. Several variables can be set by using this option several times.

--variableEXAMPLE:value--variableHOST:localhost:7272--variableUSER:robot

In the examples above, variables are set so that:

• ${EXAMPLE} gets valuevalue, and
• ${HOST} and${USER} get valueslocalhost:7272 androbot, respectively.

The basic syntax for takingvariable files into use from the command line is--variablefile path/to/variables.py and theTaking variable files intouse section explains this more thoroughly. What variables actually are createddepends 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 havehigher priority.

Return values from keywords

Return values from keywords can also be assigned into variables. Thisallows communication between different keywords even in different librariesby passing created variables forward as arguments to other keywords.

Variables set in this manner are otherwise similar to any othervariables, but they are available only in thelocal scopewhere they are created. Thus it is not possible, for example, to seta variable like this in one test case and use it in another. This isbecause, in general, automated test cases should not depend on eachother, and accidentally setting a variable that is used elsewherecould cause hard-to-debug errors. If there is a genuine need forsetting a variable in one test case and using it in another, it ispossible to use theVAR syntax orSet Test/Suite/Global Variable keywordsas explained in the subsequent sections.

*** Test Cases ***Returning    ${x} =Get Xan argumentLogWe got${x}!

*** Test Cases ***List assigned to scalar variable    ${list} =Create ListfirstsecondthirdLength Should Be    ${list}3Log Many    @{list}

*** Test Cases ***List item assignment    ${list} =Create Listonetwothreefour    ${list}[0] =Set Variablefirst    ${list}[${1}] =Set Variablesecond    ${list}[2:3] =Create Listthird    ${list}[-1] =Set VariablelastLog Many           @{list}# Logs 'first', 'second', 'third' and 'last'Dictionary item assignment    ${dict} =Create Dictionaryfirst_name=unknown    ${dict}[first_name] =Set VariableJohn    ${dict}[last_name] =Set VariableDoeLog                      ${dictionary}# Logs {'first_name': 'John', 'last_name': 'Doe'}

*** Test Cases ***Dynamically created name    ${x} =Set Variabley    ${${x}} =Set Variablez# Name is created based on '${x}'.Should Be Equal    ${y}z

*** Test Cases ***Assign to list variable    @{list} =Create ListfirstsecondthirdLength Should Be    ${list}3Log Many    @{list}

*** Test Cases ***Assign to dictionary variable    &{dict} =Create Dictionaryfirst=1second=${2}    ${3}=thirdLength Should Be    ${dict}3Do Something    &{dict}Log    ${dict.first}

*** Test Cases ***Assign multiple    ${a}    ${b}    ${c} =Get Three    ${first}    @{rest} =Get Three    @{before}    ${last} =Get Three    ${begin}    @{middle}    ${end} =Get Three

--maxassignlength1000--maxassignlength0

VAR syntax

Starting from Robot Framework 7.0, it is possible to create variables insidetests and user keywords using theVAR syntax. TheVAR marker is case-sensitiveand it must be followed by a variable name and value. Other than the mandatoryVAR, the overall syntax is mostly the same as when creating variablesin theVariable section.

The new syntax aims to make creating variables simpler and more uniform. It isespecially indented to replace theBuiltIn keywordsSet Variable,Set Local Variable,Set Test Variable,Set Suite VariableandSet Global Variable, but it can be used instead ofCatenate,Create List andCreate Dictionary as well.

*** Test Cases ***Scalar examplesVAR    ${simple}variableVAR    ${equals} =this works tooVAR    ${variable}value contains${simple}VAR    ${sentence}This is a bit longer variable value     ...that is split into multiple rows.     ...These parts are joined with a space.VAR    ${multiline}This is another longer value.     ...This time there is a custom separator.     ...As the result this becomes a multiline string.     ...separator=\n

*** Test Cases ***List examplesVAR    @{two items}RobotFrameworkVAR    @{empty list}VAR    @{lot of stuff}     ...first item     ...second item     ...third item     ...fourth item     ...last itemDictionary examplesVAR    &{two items}name=Robot Frameworkurl=http://robotframework.orgVAR    &{empty dict}VAR    &{lot of stuff}     ...first=1     ...second=2     ...third=3     ...fourth=4     ...last=5

*** Variables ***${SUITE}this value is overridden*** Test Cases ***Scope exampleVAR    ${local}local valueVAR    ${TEST}test valuescope=TESTVAR    ${SUITE}suite valuescope=SUITEVAR    ${SUITES}nested suite valuescope=SUITESVAR    ${GLOBAL}global valuescope=GLOBALShould Be Equal    ${local}local valueShould Be Equal    ${TEST}test valueShould Be Equal    ${SUITE}suite valueShould Be Equal    ${SUITES}nested suite valueShould Be Equal    ${GLOBAL}global valueKeywordShould Be Equal    ${TEST}new test valueShould Be Equal    ${SUITE}new suite valueShould Be Equal    ${SUITES}new nested suite valueShould Be Equal    ${GLOBAL}new global valueScope example, part 2Should Be Equal    ${SUITE}new suite valueShould Be Equal    ${SUITES}new nested suite valueShould Be Equal    ${GLOBAL}new global value*** Keywords ***KeywordShould Be Equal    ${TEST}test valueShould Be Equal    ${SUITE}suite valueShould Be Equal    ${SUITES}nested suite valueShould Be Equal    ${GLOBAL}global valueVAR    ${TEST}new${TEST}scope=TESTVAR    ${SUITE}new${SUITE}scope=SUITEVAR    ${SUITES}new${SUITES}scope=SUITESVAR    ${GLOBAL}new${GLOBAL}scope=GLOBALShould Be Equal    ${TEST}new test valueShould Be Equal    ${SUITE}new suite valueShould Be Equal    ${SUITES}new nested suite valueShould Be Equal    ${GLOBAL}new global value

*** Test Cases ***IF/ELSE exampleIF"${ENV}" == "devel"VAR    ${address}127.0.0.1VAR    ${name}demoELSEVAR    ${address}192.168.1.42VAR    ${name}robotENDInline IFIF"${ENV}" == "devel"VAR    ${name}demoELSEVAR    ${name}robot

*** Test Cases ***Dynamic nameVAR    ${x}y# Normal assignment.VAR    ${${x}}z# Name created dynamically.Should Be Equal    ${y}z

Set Test/Suite/Global Variable keywords

TheBuiltIn library has keywordsSet Test Variable,Set Suite Variable andSet Global Variable which canbe used for setting variables dynamically during the testexecution. If a variable already exists within the new scope, itsvalue will be overwritten, and otherwise a new variable is created.

Variables set withSet Test Variable keyword are availableeverywhere within the scope of the currently executed test case. Forexample, if you set a variable in a user keyword, it is available bothin the test case level and also in all other user keywords used in thecurrent test. Other test cases will not see variables set with thiskeyword. It is an error to callSet Test Variableoutside the scope of a test (e.g. in a Suite Setup or Teardown).

Variables set withSet Suite Variable keyword are availableeverywhere within the scope of the currently executed testsuite. Setting variables with this keyword thus has the same effect ascreating them using theVariable section in the test data file orimporting them fromvariable files. Other test suites, includingpossible child test suites, will not see variables set with thiskeyword.

Variables set withSet Global Variable keyword are globallyavailable in all test cases and suites executed after settingthem. Setting variables with this keyword thus has the same effect ascreating variables on the command line using the--variable and--variablefile options. Because this keyword can change variableseverywhere, it should be used with care.

Variable type conversion

Variable values are typically strings, but non-string values are often neededas well. Various ways how to create variables with non-string values hasalready been discussed:

• Variable files allow creating any kind of objects.
• Return values from keywords can contain any objects.
• Variables can be created based on existing variables that contain non-string values.
• @{list} and&{dict} syntax allows creating lists and dictionaries natively.

In addition to the above, it is possible to specify the variable type like${name: int} when creating variables, and the value is converted tothe specified type automatically. This is calledvariable type conversionand how it works in practice is discussed in this section.

*** Variables ***${VERSION: float}7.3${CRITICAL: list[int]}[3278, 5368, 5417]*** Test Cases ***Variables sectionShould Be Equal    ${VERSION}       ${7.3}Should Be Equal    ${CRITICAL}      ${{[3278, 5368, 5417]}}VAR syntaxVAR    ${number: int}42Should Be Equal    ${number}    ${42}Assignment# In simple cases the VAR syntax is more convenient.    ${number: int} =Set Variable42Should Be Equal    ${number}    ${42}# In this case conversion is more useful.    ${match}    ${version: float} =Should Match RegexpRF 7.3^RF (\\d+\\.\\d+)$Should Be Equal    ${match}RF 7.3Should Be Equal    ${version}    ${7.3}

*** Variables ***@{NUMBERS: int}12345&{DATES: date}rc1=2025-05-08final=2025-05-30&{PRIORITIES: int=str}3278=Critical4173=High5334=High

*** Variables ***${NUMBERS: list[int]}[1, 2, 3, 4, 5]${DATES: list[date]}{'rc1': '2025-05-08', 'final': '2025-05-30'}${PRIORITIES: dict[int, str]}{3278: 'Critical', 4173: 'High', 5334: 'High'}

*** Variables ***${PAYLOAD: dict}{'id': 1, 'name': 'Robot', 'children': [2, 13, 15]}

*** Variables ***@{CHILDREN: int}21315&{PAYLOAD: dict}id=${1}name=Robotchildren=${CHILDREN}

--variable "ITERATIONS: int:99"--variable "PAYLOAD: dict:{'id': 1, 'name': 'Robot', 'children': [2, 13, 15]}"--variable "START_TIME: datetime:now"

*** Test Cases ***Invalid valueVAR    ${example: int}invalidInvalid typeVAR    ${example: invalid}123

Operating-system variables

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

*** Test Cases ***ExampleCreate Binary File    ${CURDIR}${/}input.dataSome text here${\n}on two linesSet Environment VariableCLASSPATH    ${TEMPDIR}${:}${CURDIR}${/}foo.jar

Number variables

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

*** Test Cases ***Example 1AConnectexample.com80# Connect gets two strings as argumentsExample 1BConnectexample.com    ${80}# Connect gets a string and an integerExample 2Do X    ${3.14}    ${-1e-4}# Do X gets floating point numbers 3.14 and -0.0001

It is possible to create integers also from binary, octal, andhexadecimal values using0b,0o and0x prefixes, respectively.The syntax is case insensitive.

*** Test Cases ***ExampleShould Be Equal    ${0b1011}    ${11}Should Be Equal    ${0o10}      ${8}Should Be Equal    ${0xff}      ${255}Should Be Equal    ${0B1010}    ${0XA}

Boolean and None/null variables

Also Boolean values and PythonNone canbe created using the variable syntax similarly as numbers.

*** Test Cases ***BooleanSet Status    ${true}# Set Status gets Boolean true as an argumentCreate Ysomething   ${false}# Create Y gets a string and Boolean falseNoneDo XYZ    ${None}# Do XYZ gets Python None as an argument

These variables are case-insensitive, so for example${True} and${true}are equivalent. Keywords accepting Boolean values typically do automaticargument conversion and handle string values likeTrue andfalse asexpected. In such cases using the variable syntax is not required.

Space and empty variables

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

*** Test Cases ***One spaceShould Be Equal    ${SPACE}\ \Four spacesShould Be Equal    ${SPACE * 4}\ \ \ \ \Ten spacesShould Be Equal    ${SPACE * 10}\ \ \ \ \ \ \ \ \ \ \Quoted spaceShould Be Equal"${SPACE}"" "Quoted spacesShould Be Equal"${SPACE * 2}"" \ "EmptyShould Be Equal    ${EMPTY}\

There is also an emptylist variable@{EMPTY} and an emptydictionaryvariable&{EMPTY}. Because they have no content, they basicallyvanish when used somewhere in the test data. They are useful, for example,withtest templates when thetemplate keyword is used withoutarguments or when overriding list or dictionary variables in differentscopes. Modifying the value of@{EMPTY} or&{EMPTY} is not possible.

*** Test Cases ***Template    [Template]Some keyword    @{EMPTY}OverrideSet Global Variable    @{LIST}    @{EMPTY}Set Suite Variable     &{DICT}    &{EMPTY}

Automatic variables

Some automatic variables can also be used in the test data. Thesevariables can have different values during the test execution and someof them are not even available all the time. Altering the value ofthese variables does not affect the original values, but some valuescan be changed dynamically using keywords from theBuiltIn library.

Suite related variables${SUITE SOURCE},${SUITE NAME},${SUITE DOCUMENTATION}and&{SUITE METADATA} as well as options related to command line options like${LOG FILE} and&{OPTIONS} are available already when libraries and variablefiles are imported. Possible variables in these automatic variables are not yetresolved at the import time, though.

Variable priorities

Variables from the command line

Variablesset on the command line have the highest priority of allvariables that can be set before the actual test execution starts. Theyoverride possible variables created in Variable sections in test casefiles, as well as in resource and variable files imported in thetest data.

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

Variable section in a test case file

Variables created using theVariable section in a test case fileare available for all the test cases in that file. These variablesoverride possible variables with same names in imported resource andvariable files.

Variables created in the Variable sections are available in all other sectionsin the file where they are created. This means that they can be used alsoin the Setting section, for example, for importing more variables fromresource and variable files.

Imported resource and variable files

Variables imported from theresource and variable files have thelowest priority of all variables created in the test data.Variables from resource files and variable files have the samepriority. If several resource and/or variable file have samevariables, 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 section have a higher priority thanvariables it imports. All these variables are available for files thatimport this resource file.

Note that variables imported from resource and variable files are notavailable in the Variable section of the file that imports them. Thisis due to the Variable section being processed before the Setting sectionwhere the resource files and variable files are imported.

Variables set during test execution

Variables set during the test execution usingreturn values from keywords,VAR syntax orSet Test/Suite/Global Variable keywordsalways override possible existingvariables in the scope where they are set. In a sense they thushave the highest priority, but on the other hand they do not affectvariables 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 overriddenusing Variable section or from command line, but even they can be reset duringthe test execution. An exception to this rule arenumber variables, whichare resolved dynamically if no variable is found otherwise. They can thus beoverridden, 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 aglobal, test suite, test case or local scope.

Extended variable syntax

Extended variable syntax allows accessing attributes of an object assignedto a variable (for example,${object.attribute}) and even callingits methods (for example,${obj.get_name()}).

Extended variable syntax is a powerful feature, but it shouldbe used with care. Accessing attributes is normally not a problem, onthe contrary, because one variable containing an object with severalattributes is often better than having several variables. On theother hand, calling methods, especially when they are used witharguments, can make the test data pretty complicated to understand.If that happens, it is recommended to move the code into a library.

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

classMyObject:def__init__(self,name):self.name=namedefeat(self,what):returnf'{self.name} eats{what}'def__str__(self):returnself.nameOBJECT=MyObject('Robot')DICTIONARY={1:'one',2:'two',3:'three'}

*** Test Cases ***ExampleKW 1    ${OBJECT.name}KW 2    ${OBJECT.eat('Cucumber')}KW 3    ${DICTIONARY[2]}

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

• KW 1 gets stringRobot
• KW 2 gets stringRobot eats Cucumber
• KW 3 gets stringtwo

The extended variable syntax is evaluated in the following order:

1. The variable is searched using the full variable name. The extendedvariable syntax is evaluated only if no matching variable is found.
2. The name of the base variable is created. The body of the nameconsists of all the characters after the opening{ untilthe first occurrence of a character that is not an alphanumeric character,an underscore or a space. For example, base variables of${OBJECT.name}and${DICTIONARY[2]}) areOBJECT andDICTIONARY, respectively.
3. A variable matching the base name is searched. If there is no match, anexception is raised and the test case fails.
4. The expression inside the curly brackets is evaluated as a Pythonexpression, so that the base variable name is replaced with itsvalue. If the evaluation fails because of an invalid syntax or thatthe queried attribute does not exist, an exception is raised andthe test fails.
5. The whole extended variable is replaced with the value returnedfrom the evaluation.

Many standard Python objects, including strings and numbers, havemethods that can be used with the extended variable syntax eitherexplicitly or implicitly. Sometimes this can be really useful andreduce the need for setting temporary variables, but it is also easyto overuse it and create really cryptic test data. Following examplesshow few pretty good usages.

*** Test Cases ***StringVAR    ${string}abcLog    ${string.upper()}# Logs 'ABC'Log    ${string * 2}# Logs 'abcabc'NumberVAR    ${number}    ${-2}Log    ${number * 10}# Logs -20Log    ${number.__abs__()}# Logs 2

Note that even thoughabs(number) is recommended overnumber.__abs__() in normal Python code, using${abs(number)} does not work. This is because the variable namemust be in the beginning of the extended syntax. Using__xxx__methods in the test data like this is already a bit questionable, andit is normally better to move this kind of logic into test libraries.

Extended variable syntax works also inlist variable anddictionary variablecontexts. If, for example, an object assigned to a variable${EXTENDED} hasan attributeattribute that contains a list as a value, it can beused as a list variable@{EXTENDED.attribute}.

Extended variable assignment

It is possible to set attributes ofobjects stored to scalar variables usingkeyword return values anda variation of theextended variable syntax. Assuming we havevariable${OBJECT} from the previous examples, attributes couldbe set to it like in the example below.

*** Test Cases ***Example    ${OBJECT.name} =Set VariableNew name    ${OBJECT.new_attr} =Set VariableNew attribute

The extended variable assignment syntax is evaluated using thefollowing rules:

1. The assigned variable must be a scalar variable and have at leastone dot. Otherwise the extended assignment syntax is not used andthe variable is assigned normally.
2. If there exists a variable with the full name(e.g.${OBJECT.name} in the example above) that variablewill 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 nameconsists of all the characters between the opening${ andthe last dot, for example,OBJECT in${OBJECT.name}andfoo.bar in${foo.bar.zap}. As the second exampleillustrates, the base name may contain normal extended variablesyntax.
4. The name of the attribute to set is created by taking all thecharacters between the last dot and the closing}, forexample,name in${OBJECT.name}. If the name does notstart with a letter or underscore and contain only these charactersand numbers, the attribute is considered invalid and the extendedsyntax is not used. A new variable with the full name is createdinstead.
5. A variable matching the base name is searched. If no variable isfound, the extended syntax is not used and, instead, a new variableis created using the full variable name.
6. If the found variable is a string or a number, the extended syntaxis ignored and a new variable created using the full name. This isdone because you cannot add new attributes to Python strings ornumbers, and this way the syntax is also less backwards-incompatible.
7. If all the previous rules match, the attribute is set to the basevariable. If setting fails for any reason, an exception is raisedand the test fails.

Variables inside variables

Variables are allowed also inside variables, and when this syntax isused, variables are resolved from the inside out. For example, if youhave a variable${var${x}}, then${x} is resolvedfirst. If it has the valuename, the final value is then thevalue of the variable${varname}. There can be several nestedvariables, but resolving the outermost fails, if any of them does notexist.

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

*** Variables ***${JOHN HOME}/home/john${JANE HOME}/home/jane*** Test Cases ***Example    ${name} =Get NameDo X    ${${name} HOME}

Inline Python evaluation

Variable syntax can also be used for evaluating Python expressions. Thebasic syntax is${{expression}} i.e. there are double curly braces aroundthe expression. Theexpression can be any valid Python expression such as${{1 + 2}} or${{['a', 'list']}}. Spaces around the expression are allowed,so also${{ 1 + 2 }} and${{ ['a', 'list'] }} are valid. In addition tousing normalscalar variables, alsolist variables anddictionary variables support@{{expression}} and&{{expression}} syntax,respectively.

Main usages for this pretty advanced functionality are:

• Evaluating Python expressions involving Robot Framework's variables(${{len('${var}') > 3}},${{$var[0] if $var is not None else None}}).
• Creating values that are not Python base types(${{decimal.Decimal('0.11')}},${{datetime.date(2019, 11, 5)}}).
• Creating values dynamically (${{random.randint(0, 100)}},${{datetime.date.today()}}).
• Constructing collections, especially nested collections (${{[1, 2, 3, 4]}},${{ {'id': 1, 'name': 'Example', 'children': [7, 9]} }}).
• Accessing constants and other useful attributes in Python modules(${{math.pi}},${{platform.system()}}).

This is somewhat similar functionality than theextended variable syntaxdiscussed earlier. As the examples above illustrate, this syntax is even morepowerful as it provides access to Python built-ins likelen() and moduleslikemath. In addition to being able to use variables like${var} inthe expressions (they are replaced before evaluation), variables are alsoavailable using the special$var syntax during evaluation. The whole expressionsyntax is explained in theEvaluating expressions appendix.

Basic syntax

In many ways, the overall user keyword syntax is identical to thetest case syntax. User keywords are created in Keyword sectionswhich differ from Test Case sections only by the name that is used toidentify them. User keyword names are in the first column similarly astest cases names. Also user keywords are created from keywords, eitherfrom keywords in test libraries or other user keywords. Keyword namesare normally in the second column, but when setting variables fromkeyword return values, they are in the subsequent columns.

*** Keywords ***Open Login PageOpen Browserhttp://host/login.htmlTitle Should BeLogin PageTitle Should Start With    [Arguments]    ${expected}    ${title} =Get TitleShould Start With    ${title}    ${expected}

Most user keywords take some arguments. This important feature is usedalready in the second example above, and it is explained in detaillater in this section, similarly asuser keyword returnvalues.

User keywords can be created insuite files,resource files,andsuite initialization files. Keywords created in resourcefiles are available for files using them, whereas other keywords areonly available in the files where they are created.

Settings in the Keyword section

User keywords can have similar settings astest cases, and theyhave the same square bracket syntax separating them from keywordnames. All available settings are listed below and explained later inthis section.

[Documentation]

Used for setting auser keyword documentation.

[Tags]

Setstags for the keyword.

[Arguments]

Specifiesuser keyword arguments.

[Setup],[Teardown]

Specifyuser keyword setup and teardown.[Setup] is new inRobot Framework 7.0.

[Timeout]

Sets the possibleuser keyword timeout.Timeouts are discussedin a section of their own.

[Return]

Specifiesuser keyword return values. Deprecated in Robot Framework 7.0,theRETURN statement should be used instead.

*** Keywords ***One line documentation    [Documentation]One line documentation.No OperationMultiline documentation    [Documentation]The first line creates the short doc.    ...    ...This is the body of the documentation.    ...It is not shown in Libdoc outputs but only    ...the short doc is shown in logs.No OperationShort documentation in multiple lines    [Documentation]If the short doc gets longer, it can span    ...multiple physical lines.    ...    ...The body is separated from the short doc with    ...an empty line.No Operation

Note

Prior to Robot Framework 3.1, the short documentation containedonly the first physical line of the keyword documentation.

*** Settings ***Keyword Tagsguihtml*** Keywords ***No own tags    [Documentation]Keyword has tags 'gui' and 'html'.No OperationOwn tags    [Documentation]Keyword has tags 'gui', 'html', 'own' and 'tags'.    [Tags]owntagsNo OperationRemove common tag    [Documentation]Test has tags 'gui' and 'own'.    [Tags]own-htmlNo Operation

*** Keywords ***Settings tags using separate setting    [Tags]myfinetagsNo OperationSettings tags using documentation    [Documentation]I have documentation. And my documentation has tags.    ...Tags: my, fine, tagsNo Operation