Robot Framework Tutorial: Keyword Testing Guide

Robot Framework tests can read like clear acceptance examples or like vague prose that happens to execute. The difference is not the number of keywords. It is whether each keyword exposes a useful business action while keeping data, timing, and assertions precise.

Begin with one executable .robot file and the generated report. Once you understand how Robot separates test cases, library keywords, and your own resource keywords, you can add structure without turning the suite into a private language nobody can debug.

Install a Minimal Web Test Project

Robot Framework itself is a runner and keyword engine. A library supplies browser or API capabilities. This example uses SeleniumLibrary.

python -m venv .venv
source .venv/bin/activate
python -m pip install robotframework robotframework-seleniumlibrary
robot --version

Create a small layout:

tests/
  login.robot
resources/
  pages/
    login.resource
results/

Run a suite with:

robot --outputdir results tests

Robot creates output.xml, log.html, and report.html. The log is especially important because it shows keyword nesting, arguments, timestamps, messages, and failure details. Read it after the first run, even when the test passes. A structure that looks elegant in the source can be painfully deep in the execution log.

Pin dependencies in the project's normal dependency file. A suite rebuilt on CI should not silently receive different library behavior from a developer machine.

Learn the Four Sections That Matter First

A beginner suite can be understood through settings, variables, test cases, and keywords.

*** Settings ***
Library         SeleniumLibrary
Test Setup      Open Login Page
Test Teardown   Close All Browsers

*** Variables ***
${BASE_URL}     https://example.test
${BROWSER}      chrome

*** Test Cases ***
Invalid Email Shows Guidance
    Input Text       id=email       not-an-email
    Input Password   id=password    ValidPass123
    Click Button     id=sign-in
    Element Text Should Be    id=email-error    Enter a valid email address

*** Keywords ***
Open Login Page
    Open Browser    ${BASE_URL}/login    ${BROWSER}
    Wait Until Element Is Visible    id=sign-in    10s

Robot separates cells by two or more spaces or a tab. Consistent four-space separation is easy to review. The first cell is a keyword and the remaining cells are arguments.

The test name states the behavior. Setup gets the browser to a known entry point. The primary assertion remains visible in the case. That makes a failed report understandable without opening a large resource file.

Design Keywords at the Right Altitude

Library keywords such as Click Button describe mechanics. User keywords can describe product capabilities such as Sign In As or Create Buyer Through API. Both are useful, but they serve different readers.

A resource keyword can group a stable sequence:

*** Keywords ***
Submit Credentials
    [Arguments]    ${email}    ${password}
    Input Text        id=email       ${email}
    Input Password    id=password    ${password}
    Click Button      id=sign-in

The test still controls the data and expected result. Avoid building keywords that branch on many optional arguments. Several focused keywords are easier to document than one Login keyword with flags for role, remember-me, expected failure, MFA, and redirect.

Keep Variables and Test Data Visible

Robot supports scalar ${value}, list @{items}, and dictionary &{user} variables. Use them to name meaningful data, not to move every literal away from the behavior.

*** Variables ***
&{BUYER}        email=buyer@example.com    password=ValidPass123
${LOGIN_ERROR}  Email or password is incorrect

*** Test Cases ***
Unknown Buyer Cannot Sign In
    Submit Credentials    missing@example.com    ${BUYER}[password]
    Element Text Should Be    id=login-error    ${LOGIN_ERROR}

Environment-specific values can come from variable files, command-line variables, or environment variables. Precedence must be documented so a local override does not accidentally point a destructive test at production.

Never place production secrets in .robot files, generated logs, or command lines captured by CI. Use the CI secret mechanism and prevent keywords from logging sensitive arguments. Password fields may be hidden in the browser while their values remain visible in keyword logs if handled carelessly.

For permutations, templates can express data-driven cases without copying steps:

*** Test Cases ***
Rejected Emails
    [Template]    Validate Rejected Email
    ${EMPTY}              Email is required
    buyer@                Enter a valid email address
    ${SPACE}buyer@x.com   Enter a valid email address

*** Keywords ***
Validate Rejected Email
    [Arguments]    ${email}    ${expected}
    Submit Credentials    ${email}    ValidPass123
    Element Text Should Be    id=email-error    ${expected}

The template runs the same keyword once for each data row while reporting the row values. Do not push dozens of pure validation combinations through the UI when a unit or API test can cover them faster.

Separate Resource Files by Product Capability

As the suite grows, move reusable user keywords and locators into .resource files. Organize them around domains such as login, orders, and checkout, not generic buckets named common and helpers.

*** Settings ***
Library    SeleniumLibrary

*** Variables ***
${EMAIL_FIELD}       id=email
${PASSWORD_FIELD}    id=password
${SUBMIT_BUTTON}     id=sign-in

*** Keywords ***
Submit Credentials
    [Arguments]    ${email}    ${password}
    Input Text        ${EMAIL_FIELD}       ${email}
    Input Password    ${PASSWORD_FIELD}    ${password}
    Click Button      ${SUBMIT_BUTTON}

Import it from a suite with Resource ../resources/pages/login.resource. Resource files can import other resources, but deep chains make keyword origins hard to trace. Prefer a shallow, explicit dependency structure.

Locators should be stable product contracts. IDs and accessible attributes are preferable to absolute XPath. When a locator changes, the resource file can centralize the update, but that convenience should not excuse poor selectors.

Synchronize on Browser State

SeleniumLibrary keywords execute against a real browser, so rendering and network timing still matter. Never use Sleep as the ordinary synchronization strategy.

Submit Order
    Click Button    id=place-order
    Wait Until Element Is Not Visible    css:[data-testid="saving"]    10s
    Wait Until Page Contains Element     id=order-confirmation         10s

These waits describe two transitions: saving ends, then confirmation exists. If the confirmation can appear before the spinner is rendered, waiting for the spinner to disappear may pass immediately. Select conditions that match the application's actual state machine.

Set reasonable suite defaults, then use explicit waits around known asynchronous boundaries. Very long timeouts make missing elements slow to diagnose. A retrying keyword that clicks again can duplicate an order, so retries around side effects require special care.

When a wait fails intermittently, inspect screenshots, browser logs, network behavior, and Robot's timestamps. Do not simply increase the timeout until the failure becomes rare.

Combine UI and API Work Without Blurring the Test

API calls are useful for arranging data and checking server state. RequestsLibrary can create a customer or order before a UI test, avoiding slow navigation through unrelated screens. Keep the final user-facing behavior in the UI when that is the risk under test.

A practical split is:

• API keyword creates unique test data.
• UI keyword opens the relevant record.
• Test case performs the important action.
• UI assertion proves what the user sees.
• API cleanup removes the record if needed.

Do not hide every operation inside Prepare Complete Scenario. Name created records and return their IDs so the report shows which data the case used. Parallel workers need unique emails, order numbers, or tenant namespaces.

Custom Python libraries are appropriate when logic becomes awkward in Robot syntax, such as signing requests, generating structured data, or integrating a specialized protocol. Keep business expectations in the test layer instead of recreating a programming language through nested Run Keyword If calls.

Diagnose Reports and Common Failure Patterns

Robot's readable syntax does not guarantee readable failures. Use tags for meaningful selection, clear suite names, and setup scoped to the smallest group that needs it.

Tags such as smoke, checkout, and destructive should describe selection needs. Avoid tag sets so detailed that maintaining them becomes more work than selecting the suite.

Build the First Maintainable Suite

Create one suite with three cases: a successful critical flow, one meaningful validation, and one recovery or error path. Use one resource file for stable locators and capability keywords. Keep expected outcomes in the test cases and remove every fixed sleep.

Then review log.html from both a pass and an intentional failure. Confirm the keyword path is short, the data is recognizable, secrets are absent, and cleanup still runs. Only after that review should you introduce data templates, API libraries, shared setup, or parallel execution. Robot Framework is most effective when its reports remain readable to the same people who review the acceptance behavior.