Skip to content
Tutorials Center
My learning

Topics

Lesson 13 of 36 ยท Keywords and Variables

Embedded Arguments and Return Values

Write keywords whose arguments sit inside the keyword name, restrict them with regular expressions, and master return values, multiple assignment and unpacking.

Sometimes the most readable keyword is a sentence: Customer adds 3 books to the cart. Robot lets you write exactly that with embedded arguments, where the values are part of the keyword's name instead of separate cells. This lesson shows how they work, how to keep them unambiguous, and then takes a second look at return values and multiple assignment.

Embedded arguments

Put the variable names in the keyword name:

ROBOTFRAMEWORK
*** Test Cases ***
Shopping
    Given an empty cart
    When customer adds 3 books to the cart
    And customer adds 1 pen to the cart
    Then the cart should contain 4 items

*** Keywords ***
An empty cart
    Set Test Variable    ${CART_COUNT}    ${0}

Customer adds ${count} ${thing} to the cart
    ${count}=    Convert To Integer    ${count}
    ${new}=    Evaluate    ${CART_COUNT} + ${count}
    Set Test Variable    ${CART_COUNT}    ${new}

The cart should contain ${expected} items
    Should Be Equal As Integers    ${CART_COUNT}    ${expected}

The call customer adds 3 books to the cart matches the keyword Customer adds ${count} ${thing} to the cart; ${count} becomes "3" and ${thing} becomes "books". The Given, When, Then prefix is stripped before matching, as explained in Writing Test Cases.

Notes:

  • Embedded values are strings. Convert them yourself (Convert To Integer) or, in recent Robot versions, declare a type in the name such as ${count: int} (Robot 7.3 and later).
  • The values can be variables too: customer adds ${QTY} books to the cart.
  • A keyword with embedded arguments cannot also declare positional parameters in [Arguments] in older versions; from Robot 6.1 you may mix them.

Restricting what matches

By default an embedded argument matches any text (the pattern .*?). That can cause ambiguity: with a keyword User ${name} logs in and another User ${name} logs in with ${password}, a call to the second may match the first. Restrict an argument with a regular expression after a colon:

ROBOTFRAMEWORK
*** Keywords ***
Add ${amount:\d+} dollars to the account
    Log    adding ${amount}

Add ${item:apple|banana|cherry} to the basket
    Log    basket gets ${item}

Pick ${color:red|green|blue} or ${other:red|green|blue}
    Log    ${color}, ${other}
  • ${amount:\d+} only matches digits, so "Add many dollars" does not match.
  • Write regular expressions without capturing groups; use (?:...) when you need grouping.
  • Backslashes inside the pattern do not need doubling.
  • If several embedded-argument keywords match a call, Robot reports a "multiple keywords match" error. Narrow the patterns or rename a keyword. A keyword whose name is an exact match (with no embedded arguments) wins over embedded patterns.

When to use them: for specification-style tests, with Given/When/Then, and for keywords with one or two arguments that are naturally part of a sentence. For keywords with many arguments, normal [Arguments] are clearer.

Return values revisited

You have seen RETURN. Here are the patterns you will meet daily.

ROBOTFRAMEWORK
*** Test Cases ***
Assignments
    ${name}=                Get Name
    ${first}    ${last}=    Get Full Name
    ${head}    @{tail}=     Create List    a    b    c    d
    @{all}=                 Create List    1    2    3
    &{person}=              Create Dictionary    name=Ada    age=${36}
    ${first}    ${second}    ${third}=    Set Variable    ${all}

*** Keywords ***
Get Name
    RETURN    Ada

Get Full Name
    RETURN    Ada    Lovelace
Assignment Effect
${x}= Keyword One value
${a} ${b}= Keyword Unpack a list of exactly two values
${head} @{tail}= Keyword First value, then the rest as a list
@{items}= Keyword Value must be a list; creates a list variable
&{map}= Keyword Value must be a dictionary; creates a dictionary variable
${a} ${b}= Create List 1 2 3 Error: three values for two variables

The = is optional but recommended. ${scalar}= Create List a b keeps the list as one object; @{list}= Create List a b creates a list variable you can expand with @{list}.

You can also return conditionally from inside a block:

ROBOTFRAMEWORK
*** Keywords ***
Classify
    [Arguments]    ${n}
    IF    ${n} < 0    RETURN    negative
    IF    ${n} == 0    RETURN    zero
    RETURN    positive

RETURN finishes the keyword immediately, even inside FOR or IF. Without RETURN, a keyword returns nothing (None). Teardown steps and [Teardown] still run.

Stand-in 1: matching embedded arguments

The blocks below are not Robot Framework. The first one turns a keyword name with ${...} parts into a regular expression and matches calls against it, just as Robot does conceptually, including the ${name:pattern} form.

Python Stand-in: embedded-argument matching

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: unpacking assignments

How many variables may receive a returned list? The stand-in implements the rules in the table: exact count, or one @{rest} variable collecting the remainder.

Python Stand-in: multiple assignment

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.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does the keyword name Customer adds ${count} books define?

    Variables in the keyword name are embedded arguments, filled from the text of the call.
  2. 2. What type does an embedded argument have by default?

    Embedded values are text. Convert them in the keyword, or declare a type in Robot 7.3 and later.
  3. 3. How do you make an embedded argument match only digits?

    A regular expression after the colon restricts what the argument may match.
  4. 4. What does ${head} @{tail}= Create List a b c do?

    A list variable at the end of the assignment collects the remaining values.

Summary

  • Embedded arguments put ${variables} into the keyword name, perfect for sentence-like steps.
  • They are strings; restrict them with ${name:regex} and avoid ambiguous patterns.
  • Assign return values to one variable, several, or ${head} @{tail} to split.
  • RETURN ends a keyword early, even inside IF or FOR.

Next: Retrying, Expecting Errors and the Run Keyword Family