Keywords, Arguments, Return Values, and Reusable Abstractions: Diagnostics, Failure Modes, and Production Practices

1. The diagnostic sequence: preserve evidence, then descend through ownership layers

flowchart TD
A[Preserve first-failure output.xml/log/report] --> B[Confirm Robot/Python/tool versions]
B --> C[Confirm executed path, selection and inputs]
C --> D[Validate parse and import graph]
D --> E[Inspect keyword resolution]
E --> F[Inspect argument binding / conversion]
F --> G[Inspect variable scope and return ownership]
G --> H[Inspect nested keyword/library state]
H --> I[Inspect external/timing/parallel/CI state if relevant]
I --> J[Apply least destructive correction]
J --> K[Rerun smallest controlled slice]

This order prevents a common waste pattern: investigating a browser, API, database, or CI runner when Robot never resolved the intended keyword or never bound its arguments successfully.

2. Intentionally broken example: a local keyword shadows a standard-library/BuiltIn name

Current scope rules give a user keyword in the current suite file the highest priority. That can surprise a maintainer who expects a BuiltIn call.

*** Keywords ***
Should Be Equal
    [Arguments]    ${actual}    ${expected}
    Log    LOCAL WRAPPER called: ${actual} vs ${expected}
    BuiltIn.Should Be Equal    ${actual}    ${expected}

*** Test Cases ***
Name collision is visible
    Should Be Equal    alpha    beta

The test fails, but the log proves that the local user keyword was selected first. The nested qualified BuiltIn.Should Be Equal then produces the real assertion failure. The repair is usually to rename the local keyword to a domain-specific intent. Explicit qualification is appropriate when a real conflict must remain.

3. Too many arguments signal multiple responsibilities or a missing domain concept

An argument-binding error is easy to spot. A worse failure is a keyword that technically accepts everything but no caller can understand the combinations.

# Warning-sign interface — technically possible, operationally vague.
Run Release Flow
    [Arguments]    ${id}    ${component}    ${env}    ${dry_run}    ${retry}
    ...            ${prefix}    ${suffix}    ${normalize}    ${capture}
    ...            ${cleanup}    ${timeout}    ${owner}

Do not hide this with @{args}/&{kwargs}. Revisit responsibility boundaries and group only genuinely cohesive configuration.

4. Hidden suite/global state creates order dependence

A helper that silently sets a suite variable can make one test pass only because another test or setup ran first.

Remember Candidate
    [Arguments]    ${candidate}
    Set Suite Variable    ${CURRENT_CANDIDATE}    ${candidate}

Verify Candidate
    Should Not Be Empty    ${CURRENT_CANDIDATE}

The safer routine design is ${candidate}= Build Candidate followed by an explicit argument to Verify Candidate. Wider scope may be valid for suite lifecycle configuration, but then the setup/ownership must be obvious and independently verifiable.

5. Deep forwarding chains make logs longer without adding meaning

Consider Prepare Release → Create Release → Build Release → Make Release → Normalize Release. If each wrapper forwards the same argument unchanged, call depth is not architecture—it is indirection.

Keep the layers that correspond to stable concepts. Collapse purely forwarding wrappers, then verify the refactor preserves the high-level name and the low-level failure evidence you actually need.

6. Swallowed failures are more dangerous than visible failures

Helpers sometimes use “ignore error” behavior to keep going and then return a default. That can convert a release-blocking assertion into a PASS unless the caller remembers a hidden status protocol.

*** Keywords ***
Broken Compare
    [Arguments]    ${actual}    ${expected}
    ${status}    ${message}=    Run Keyword And Ignore Error
    ...    Should Be Equal    ${actual}    ${expected}
    Log    Comparison status was ${status}
    RETURN    ${message}

*** Test Cases ***
Failure is accidentally converted to data
    ${message}=    Broken Compare    alpha    beta
    Log    ${message}

The test can finish PASS because the failure became data and the caller did not assert the status. If a failure is expected/recoverable, define a clear return contract such as ${ok} ${detail} and make the caller assert or branch deliberately. For ordinary assertions, allow failure to propagate.

7. Inconsistent return shapes create a hidden runtime protocol

This anti-pattern forces every caller to inspect runtime shape:

Lookup Candidate
    [Arguments]    ${id}
    IF    '${id}' == 'missing'
        RETURN    ${EMPTY}
    ELSE IF    '${id}' == 'partial'
        RETURN    partial    warning
    END
    RETURN    found    ok    metadata

Prefer one stable structure. For example, always return ${found} ${detail}, where ${found} is Boolean and ${detail} has one documented meaning, or return one dictionary with a defined schema. Keep error status distinct from business data.

8. Keyword names must disclose meaningful side effects

A keyword named Get Candidate should not also delete temporary state, change environment variables, or write a shared file unless that behavior is explicit and central to the contract. Hidden side effects are particularly dangerous when a keyword is reused in CI, Pabot, or RPA contexts where workers share fewer assumptions.

In this chapter, all examples are local and synthetic. Later integration chapters require explicit target guards and cleanup boundaries for real files/processes/APIs/databases/SSH/browser sessions.

9. Circular abstraction is an ownership problem before it is an import problem

Chapter 12 will teach resource-file imports in detail. The design failure to recognize now is two abstraction modules that conceptually depend on each other: “payments” calls “orders,” while “orders” calls back into “payments” for a supposedly lower-level helper. Even if a particular import graph can be made to load, ownership is unclear and changes ripple in both directions.

Repair by extracting a one-way utility/domain boundary or by moving orchestration to a higher layer that is allowed to depend on both lower layers.

10. Preserve first-failure artifacts before experimentation

For each broken case, run into its own evidence directory:

python -m robot --outputdir evidence/shadowing --test "Name collision is visible" broken.robot
python -m robot --outputdir evidence/swallowed --test "Failure is accidentally converted to data" broken.robot

Do not delete output.xml/log.html before the diagnosis is complete. If you need a repaired run, write it to evidence/repaired-... so the before/after comparison remains auditable.

11. Least-destructive correction patterns

12. Performance diagnosis belongs after correctness layers

Keyword parsing/call overhead, external-system latency, output logging, Pabot scheduling, container startup, CI provisioning, and rerun cost are distinct. Chapter 05 failures are usually interface/architecture failures, not performance failures. Do not add parallelism or retries to compensate for an ambiguous contract.

13. Knowledge check

14. Summary and next step

Production keyword diagnosis starts with first-failure evidence and ownership: confirm runtime and input, validate imports, inspect resolution, bind arguments, inspect scope/returns, then descend into library/external state. Repair ambiguity rather than hiding it with retries or catch-all wrappers.

Lesson 5 is the checkpoint: refactor a deliberately flat suite into layered domain and utility keywords, prove behavior equivalence, inject a low-level failure, and verify the higher-level log still points clearly to the broken contract.

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.