Skip to content
Robot Framework Essentials

Keyword documentation and arguments

Chapter lab: Keywords and importsch03-keywords-imports.zip · 3 KB

This lesson continues in the same lab as the lesson before it. If you don’t have it yet, download it here.

Download ch03-keywords-imports.zip

Or fetch and unpack it from a terminal in VS Code:

Terminal window
curl -fsSLO https://manykarim.github.io/robotframework-essentials-web/labs/ch03-keywords-imports.zip && unzip -q ch03-keywords-imports.zip && rm ch03-keywords-imports.zip

Open the folder in VS Code with code rfe-ch03-keywords-imports (or File → Open Folder…) and accept the recommended RobotCode and Python extensions. Then set it up:

Terminal window
uv sync
Terminal window
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Keep the environment active in every terminal where you run lesson commands.

Terminal window
poetry install --no-root

Python 3.13 or newer is required; uv installs it when it is missing.

Open in browserNo setup? Try the lab right here: its files, an editor and a terminal, running in your browser.

What's inside
  • Directoryrfe-ch03-keywords-imports/
    • Directory.vscode/
      • extensions.json
    • Directorychecks/
      • imports.robot
    • Directoryresources/
      • common.resource
    • .gitignore
    • .python-version
    • LAB.md
    • pyproject.toml
    • README.md
    • requirements.txt
    • uv.lock

Your own keywords live in *** Keywords ***. A user keyword declares what it accepts with [Arguments] and what it does below. Arguments come in kinds:

  • Mandatory — ${name}.
  • Optional — ${name}=world, with a default used when the caller omits it.
  • Varargs — @{items} collects any number of trailing values.

Give every keyword a [Documentation] line. That text is what editors, log.html, and libdoc show — it is how a teammate learns to call your keyword without reading its body.

Task 1 — Write a keyword with a mandatory and an optional argument

Section titled “Task 1 — Write a keyword with a mandatory and an optional argument”
Edit

Goal: in checks/args.robot, write a Greeting For keyword that takes a name (defaulting to world) and returns a greeting, plus tests that call it with and without the name.

Here is a keyword of the same shape over a different job — repeating a word an optional number of times. Adapt the arguments and body.

Worked example — adapt it, don’t copy it

*** Test Cases ***
Chants Three Times By Default
    ${line}=    Chant    go
    Should Be Equal    ${line}    go go go


*** Keywords ***
Chant
    [Documentation]    Repeat a word, space-separated; three times by default.
    [Arguments]    ${word}    ${times}=3
    ${line}=    Evaluate    " ".join([$word] * int($times))
    RETURN    ${line}

Done when

checks/args.robot defines the user keyword Greeting For, and calling it with a name passes.

Hint 1

Declare Greeting For with [Arguments] ${name}=world — the =world default makes the name optional.

Hint 2

Return the greeting with RETURN Hello, ${name}!.

Hint 3

Call it two ways: with no argument (uses world) and with Ada.

Solution
*** Test Cases ***
Greets With A Default
    ${greeting}=    Greeting For
    Should Be Equal    ${greeting}    Hello, world!


Greets A Named Person
    ${greeting}=    Greeting For    Ada
    Should Be Equal    ${greeting}    Hello, Ada!


*** Keywords ***
Greeting For
    [Documentation]    Build a greeting; name defaults to world.
    [Arguments]    ${name}=world
    RETURN    Hello, ${name}!

Task 2 — Call it both ways and pass

Section titled “Task 2 — Call it both ways and pass”
Run

Run it:

Terminal window
uv run robot checks
Terminal window
robot checks
Terminal window
poetry run robot checks

Both tests pass: one uses the default, one passes a name.

Done when

the test Greets A Named Person passes.

Check your understanding

Quick recall. Your first answer stays in this browser; the quiz never blocks your progress.

  1. How do you give a keyword argument a default value?

    Show the answer

    Answer: ${name}=default — An argument becomes optional with = and a default, e.g. [Arguments] ${name}=world.

  2. Where does a keyword's documentation come from for libdoc and editors?

    Show the answer

    Answer: The [Documentation] setting — [Documentation] inside the keyword feeds Keyword Documentation, editor tooltips, and libdoc.

Key terms

[Arguments]concept
Declares a user keyword's arguments; ${x}=default makes one optional, @{rest} collects varargs.
[Documentation]concept
A keyword's or test's documentation — surfaced in editors, log.html, and libdoc.

All terms in the glossary →