Keywords, Arguments, Return Values, and Reusable Abstractions: Configuration, Design Patterns, and Trade-Offs

1. Abstraction has a cost curve, not a single correct level

Once teams discover user keywords, they often overcorrect: every primitive gets wrapped, wrappers call wrappers, and tests become short but opaque. The opposite failure is equally common: every test invokes low-level library keywords directly, causing duplication and exposing implementation details everywhere.

The design question is therefore not “Should we use keywords?” but “Which knowledge belongs behind this keyword boundary, and which choices must remain visible to the caller?”

2. Design model: optimize the contract, not the line count

flowchart TD
A[Automation intent] --> B{Stable project/domain concept?}
B -->|Yes| C[Domain keyword]
B -->|No| D[Direct library / small utility]
C --> E{Inputs genuinely variable?}
E -->|Few meaningful values| F[Explicit arguments]
E -->|Structured cohesive policy| G[Structured config value]
F --> H[RETURN explicit result]
G --> H
H --> I[Caller assertion / next step]
C --> J[Low-level implementation keywords]
J --> K[Library or external boundary]
K --> L[Evidence in nested log]

3. Few explicit arguments versus configuration objects

Explicit arguments are excellent when each value is meaningful at the call site. A giant list of loosely related arguments becomes difficult to read and version. A dictionary/configuration object can group a coherent policy, but a generic “options” bag can hide required fields and typos.

If a configuration object is used, validate required keys at the boundary and document the contract. Do not pass arbitrary production secrets in a generic dictionary simply because it is convenient.

4. Return values versus suite/global mutation

Return values keep dependencies local. A test reads the returned value, decides whether to assert it, pass it to another keyword, or discard it. Suite/global variables intentionally extend lifetime and coupling; they can be appropriate for suite setup data or framework-wide configuration, but using them as routine helper output makes parallelism and reruns harder to reason about.

5. Composition versus deep keyword chains

Composition is the mechanism that makes user keywords useful. Depth becomes a problem when every layer merely renames the next layer or when a simple failure requires opening six nearly empty wrappers.

6. Wrapper keyword versus direct library use

Direct library calls are appropriate when the library keyword already expresses the intent and your project has no extra policy. A wrapper is useful when it creates a stable project contract: it may normalize inputs, enforce safe defaults, attach domain terminology, or isolate a vendor/library API that is likely to change.

# Direct use is clearer when no project policy is added.
${lower}=    String.Convert To Lower Case    ${value}

# A project wrapper can be justified when it defines one stable normalization rule.
Normalize Release Id
    [Arguments]    ${raw}
    ${lower}=    String.Convert To Lower Case    ${raw}
    ${slug}=     String.Replace String    ${lower}    ${SPACE}    -
    RETURN    ${slug}

A wrapper that simply calls String.Convert To Lower Case with the same arguments and return value would add little value.

7. Business-language names versus technical names

Choose names according to the keyword’s abstraction level. Domain keywords should describe the behavior visible to a product/operations reader. Technical utilities should be precise about the transformation they perform. Do not give a destructive or state-changing keyword a harmless-sounding name such as Ensure Ready if it deletes/recreates data.

8. One responsibility versus convenience mega-keywords

A mega-keyword often starts as convenience: authenticate, create data, trigger workflow, poll, assert, capture evidence, and clean up in one call. The test becomes one line, but failure semantics become ambiguous and reuse drops because callers cannot select only the part they need.

Split at ownership boundaries: preparation, action, observation/assertion, and cleanup can be separate domain capabilities while still being composed by a scenario-level keyword when that scenario is stable.

9. Security and privacy belong in the interface design

Arguments and return values may appear in logs. A keyword that accepts credentials, tokens, personal identifiers, or raw response bodies therefore has a privacy contract in addition to a functional contract. Later chapters cover Robot Framework secret variables and external secret management in depth; at this stage, use only fake values and design names/signatures so sensitive data is not casually logged or returned.

10. Runtime cost: abstraction overhead is usually smaller than external work, but evidence can grow

User-keyword call overhead is normally tiny compared with browser, HTTP, database, process, or network latency. The operational cost of excessive layering is more often diagnostic: larger logs, deeper trees, more setup/teardown, and more places to search when behavior changes.

Measure before optimizing. Do not flatten useful domain layers merely to remove a few Robot calls, and do not hide real external waits behind generic helper timeouts.

11. Worked decision: design a release-candidate keyword API

Suppose callers need to normalize a candidate ID, attach a component/environment, and receive a label. Compare the choices:

12. Version-aware contract choices

• RETURN is the current recommended return mechanism; [Return] is deprecated.
• User-keyword automatic type conversion such as ${count: int} requires Robot Framework 7.3+.
• Libdoc on the current stable line represents argument kind, defaults, and type information automatically.
• Keyword resolution/qualification behavior should be checked against the current User Guide when resource/library architecture grows.
• Do not introduce pre-release-only 7.5 syntax into a 7.4.2 course lab without an explicit stable fallback.

13. Knowledge check

14. Summary and next step

Keyword design is an interface-design discipline. Prefer small explicit contracts, use structured values only for cohesive configuration, return data rather than mutating shared scope by default, compose layers that add meaning, wrap libraries only when you create a stable project boundary, name side effects honestly, and preserve failure context.

Lesson 4 deliberately breaks these rules so you can diagnose resolution conflicts, hidden state, deep call stacks, swallowed failures, inconsistent returns, and circular ownership.

Further reading

• Robot Framework 7.4.2 User Guide — Creating user keywords — keyword syntax, arguments, embedded arguments, return values, setup/teardown, privacy, and recursion.
• Robot Framework 7.4.2 User Guide — Handling keywords with same names — resolution scope, explicit qualification, and search order.
• Robot Framework 7.4.2 User Guide — Libdoc — generating user/library documentation and inspecting keyword signatures.
• RFCP syllabus — User Keyword Definition & Arguments — keyword naming, interfaces, arguments, and maintainable design.
• Robot Framework Style Guide — naming, abstraction level, keyword design, and maintainability guidance.
• Robot Framework 7.4.2 release notes — current stable-line changes and deprecations.