Skip to content
Tutorials Center
My learning

Topics

Lesson 10 of 36 ยท Keywords and Variables

User Keywords, Arguments and Return Values

Create your own Robot Framework keywords: use [Arguments], default values, varargs, named-only and kwargs, return values with RETURN, and keyword documentation.

Keywords are the vocabulary of your tests. Library keywords come from code, but user keywords are written in Robot syntax inside a *** Keywords *** section (or in a resource file). They are how you turn low-level steps such as "click this, type that" into business-level steps such as Log In As Customer. Well-chosen keywords are what keeps a suite of thousands of tests readable and cheap to maintain.

Your first user keyword

ROBOTFRAMEWORK
*** Test Cases ***
Greet someone
    Greet    Robot
    ${text}=    Build Greeting    Ada
    Should Be Equal    ${text}    Hello, Ada!

*** Keywords ***
Greet
    [Arguments]    ${name}
    Log    Hello, ${name}!

Build Greeting
    [Arguments]    ${name}
    ${greeting}=    Catenate    SEPARATOR=    Hello,${SPACE}    ${name}    !
    RETURN    ${greeting}

A keyword has a name at the left edge and a body of indented steps. Settings in square brackets must come before the steps. The name can contain spaces and is matched ignoring case, spaces and underscores. RETURN (Robot 5.0 and later) ends the keyword and returns a value. The older [Return] setting still works but is deprecated.

Arguments

Kind Syntax in [Arguments] Example call
Required ${name} Greet Ann
Default value ${greeting}=Hello Greet Ann or Greet Ann Hi
Variable number @{names} Greet All Ann Bob Cy
Named-only after @{} or @{rest} Connect host=db1 port=5432
Free named &{options} Run verbose=True retries=3
ROBOTFRAMEWORK
*** Keywords ***
Send Message
    [Arguments]    ${to}    ${text}=(empty)    @{attachments}    ${urgent}=${False}    &{headers}
    Log    To: ${to}, text: ${text}
    Log    Attachments: ${attachments}
    Log    Urgent: ${urgent}
    Log    Headers: ${headers}

How a call is matched to these parameters:

  • Positional values fill required and default arguments from the left.
  • Everything left over goes into @{attachments}.
  • After a @{varargs}, parameters such as ${urgent} can only be given by name: urgent=${True}.
  • Named values that match no parameter are collected into &{headers}.

Defaults may refer to earlier arguments: ${b}=${a}. A default value is a string unless you write it as a variable like ${False}. Robot 7.3 and later can also convert argument types from a declared type: [Arguments] ${count: int} ${enabled: bool}=False. This is a convenience; in older versions convert inside the keyword with Convert To Integer.

If a value passed positionally contains an equals sign and the keyword has no such parameter name, Robot treats it as a normal value. When in doubt, escape it: a\=b.

Return values

ROBOTFRAMEWORK
*** Keywords ***
Min And Max
    [Arguments]    @{numbers}
    ${min}=    Evaluate    min(${numbers})
    ${max}=    Evaluate    max(${numbers})
    RETURN    ${min}    ${max}

*** Test Cases ***
Use both values
    ${low}    ${high}=    Min And Max    ${4}    ${9}    ${2}
    Should Be Equal As Integers    ${low}     2
    Should Be Equal As Integers    ${high}    9

Returning several values returns a list; assigning to several variables unpacks it. RETURN may be used inside IF or FOR to end a keyword early, and it can be conditional: IF ${x} > 3 RETURN big.

Settings in keywords

ROBOTFRAMEWORK
*** Keywords ***
Open Account
    [Documentation]    Opens an account for ${owner} and returns its number.
    [Tags]             accounts    setup
    [Arguments]        ${owner}
    [Teardown]         Log    Account step finished
    [Timeout]          10 seconds
    ${number}=    Create Account    ${owner}
    RETURN    ${number}

[Documentation] is shown in the log and in generated keyword documentation (libdoc). [Teardown] always runs when the keyword ends. [Timeout] fails the keyword if it takes too long.

Keyword names: write for the reader

  • Use business wording: Customer Adds Book To Cart, not Click Button Id Add.
  • Start with a verb or use a sentence for Given-When-Then steps.
  • Keep a keyword at one level of abstraction: do not mix "click the button" with "the order is valid".
  • Keywords should be short (about 3 to 10 steps) and do one thing.

Stand-in 1: matching a call to an argument list

The blocks below are not Robot Framework. The first one reproduces the binding rules: required, default, varargs, named-only and free-named arguments. The real engine is stricter and gives more detailed errors.

Python Stand-in: argument binding

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Stand-in 2: keywords calling keywords

User keywords can call other user keywords; each call has its own local variables. The stand-in builds a keyword table where a user keyword is just a list of steps, and shows RETURN handing a value back.

Python Stand-in: user keywords and RETURN

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Common mistakes

  • Forgetting the [Arguments] line and then using ${name} that does not exist.
  • A default written as a number (${count}=3) and expecting an integer. It is the string "3"; write ${count}=${3} or use a typed argument in Robot 7.3+.
  • Naming clashes. Two keywords with the same name in different imported files give a "multiple keywords" error; call one with its file prefix, for example common.Log In.
  • Overlong keywords. If you scroll to read it, split it.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which line declares a keyword argument with a default value?

    A default is written after an equals sign in the [Arguments] list.
  2. 2. How do you return a value from a user keyword in Robot 5 and later?

    RETURN is a native statement. The [Return] setting still works but is deprecated.
  3. 3. What does @{attachments} in [Arguments] collect?

    @{name} is a varargs list; &{name} is the dictionary of free named arguments.
  4. 4. What is a good keyword name?

    Good keyword names describe intent at a business level so the test reads like a specification.

Summary

  • User keywords live in *** Keywords *** and are built from other keywords.
  • [Arguments] supports required, default, @{varargs}, named-only and &{kwargs} parameters.
  • Use RETURN to return values; several values return a list and can be unpacked.
  • Keyword settings: [Documentation], [Tags], [Teardown], [Timeout].
  • Name keywords for readers and keep each one short and at one abstraction level.

Next: Scalar, List and Dictionary Variables