Skip to content
Robot Framework Essentials

Named keywords and Libdoc

Chapter lab: Custom librariesch18-custom-libraries.zip · 4 KB

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

Download ch18-custom-libraries.zip

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

Terminal window
curl -fsSLO https://manykarim.github.io/robotframework-essentials-web/labs/ch18-custom-libraries.zip && unzip -q ch18-custom-libraries.zip && rm ch18-custom-libraries.zip

Open the folder in VS Code with code rfe-ch18-custom-libraries (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-ch18-custom-libraries/
    • Directory.vscode/
      • extensions.json
    • Directorychecks/
      • smoke.robot
    • Directorylibraries/
      • README.md
    • Directoryvariables/
      • README.md
    • .gitignore
    • .python-version
    • LAB.md
    • pyproject.toml
    • README.md
    • requirements.txt
    • uv.lock

Two finishing touches make a library pleasant to use.

  • @keyword("...") sets the keyword’s name explicitly, and the name can carry embedded arguments: @keyword("Order ${number} Should Be ${expected}") makes a keyword you call as Order 1042 Should Be complete — it reads like a sentence.
  • Libdoc turns your library’s signatures and docstrings into an HTML reference: uv run libdoc libraries/<file>.py results/<file>.html.

Task 1 — An embedded-argument keyword

Section titled “Task 1 — An embedded-argument keyword”
Edit

Goal: create libraries/order_state.py with a keyword named Order ${number} Should Be ${expected} that checks a known order’s status.

Here is the same idea over different data — stock levels. Adapt it to order statuses.

Worked example — adapt it, don’t copy it

from robot.api.deco import keyword


STOCK = {"trail-backpack": 12, "travel-mug": 24}




@keyword("Stock Of ${slug} Should Be ${expected}")
def stock_should_be(slug: str, expected: int) -> None:
    actual = STOCK.get(slug)
    if actual != expected:
        raise AssertionError(f"Stock of {slug} is {actual}, expected {expected}")

Done when

libraries/order_state.py defines a function decorated with an embedded-argument @keyword name.

Hint 1

The two ${...} parts in the @keyword name become the function’s two parameters, in order: def order_status_should_be(number, expected):.

Hint 2

Look the status up and compare: actual = ORDERS.get(number) then raise AssertionError if actual != expected.

Solution
from robot.api.deco import keyword


ORDERS = {"1042": "complete", "1043": "pending"}




@keyword("Order ${number} Should Be ${expected}")
def order_status_should_be(number: str, expected: str) -> None:
    actual = ORDERS.get(number)
    if actual != expected:
        raise AssertionError(f"Order {number} is {actual}, expected {expected}")

Task 2 — Run it, then generate its docs

Section titled “Task 2 — Run it, then generate its docs”
Run

Create checks/order_state.robot. With embedded arguments the values live inside the keyword name, so they are written with single spaces, not cell separation:

*** Settings ***
Library    ../libraries/order_state.py


*** Test Cases ***
Orders Read Naturally
    Order 1042 Should Be complete
    Order 1043 Should Be pending

Run the suite, then generate the library’s documentation:

Terminal window
uv run robot checks/order_state.robot
uv run libdoc libraries/order_state.py results/order_state.html
Terminal window
robot checks/order_state.robot
libdoc libraries/order_state.py results/order_state.html
Terminal window
poetry run robot checks/order_state.robot
poetry run libdoc libraries/order_state.py results/order_state.html

Open results/order_state.html — your keyword is documented with its embedded name.

Done when

the suite passes and results/order_state.html was generated.

Check your understanding

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

  1. In @keyword("Order ${number} Should Be ${expected}"), the ${...} parts are…

    Show the answer

    Answer: the function's arguments, embedded in the name — Embedded arguments become the function parameters, in order, and are written inline in the call.

  2. What does libdoc produce?

    Show the answer

    Answer: HTML documentation of a library's keywords — libdoc <library> <out.html> turns signatures and docstrings into a keyword reference.

Key terms

embedded argumentsconcept
${...} in a keyword name become its arguments, written inline.
Libdocconcept
Generate HTML keyword docs from a library.

All terms in the glossary →