Writing Python Test Libraries and the Library API: Configuration, Design Patterns, and Trade-Offs

1. Design from the observable contract backward

A library design is good when a Robot author can predict keyword names, arguments, status, side effects, scope, and evidence without reading implementation internals. Start by listing the operations Robot truly needs. Then decide the smallest Python object lifetime and packaging mechanism that makes those operations deterministic.

Do not choose GLOBAL because construction is inconvenient, or choose a module because it uses fewer lines. Those shortcuts change state sharing and import behavior.

2. Module versus class library

For a module library, __all__, underscore aliases, or ROBOT_AUTO_KEYWORDS=False can restrict exposure. A class with @library is often easier to govern because keyword methods are visibly marked next to implementation.

3. Decorators versus automatic exposure

Automatic discovery is convenient in tiny libraries, but convenience becomes ambiguity as inheritance, imports, and helper methods grow. Explicit decorators improve code review: a reviewer can search for @keyword and see the entire Robot-facing surface.

@keyword can also define a custom keyword name, tags, and type information. Avoid changing names gratuitously: the Python method name can remain implementation-oriented while the Robot keyword name should be stable and domain-oriented.

from robot.api.deco import keyword, library

@library(scope="TEST")
class AccountLibrary:
    @keyword("Create Synthetic Account", tags=["domain:account"])
    def create_synthetic_account(self, name: str, limit: int = 10) -> dict[str, object]:
        ...

4. TEST, SUITE, GLOBAL: choose based on ownership, not speed

Scope affects parallelism indirectly. Pabot uses separate processes, so a GLOBAL Python library instance is global only inside one worker process, while the external resource it points to may still be shared across workers. Chapter 24 will make that capacity/state math explicit.

5. Stateless functions versus instance state

Prefer passing values into functions and returning values out when state does not need to persist. Instance state is justified when it represents a real resource lifecycle (connection, session, client) or a deliberate aggregation. Hidden state increases the number of prerequisites needed to understand a keyword.

If state exists, expose verification and cleanup operations. Do not force Robot tests to inspect self internals; provide a domain-facing keyword or return value that can prove state.

6. Robot assertions versus Python exceptions

A custom library should not reimplement every Robot assertion. If a method returns data, Robot can often assert it with BuiltIn/Collections. If the Python operation itself cannot satisfy its domain contract, raise a precise Python exception or robot.api.Failure in the adapter.

Keep pure domain code framework-neutral. A domain function can raise ValueError; the Robot adapter can translate it to a concise Failure. Use SkipExecution, ContinuableFailure, or FatalError only when their specific execution semantics are actually required.

7. Python logging versus robot.api.logger

robot.api.logger is best for messages that should belong to the current Robot keyword/result hierarchy. It provides accurate timestamps while Robot is running and falls back to Python logging when Robot is not running.

Python logging is appropriate inside framework-neutral domain modules and reusable clients. The adapter can configure/bridge behavior if needed, but avoid global logging configuration at import time. Libraries embedded in larger test processes should not unexpectedly change the application's root logger.

8. Types: optimize the call boundary, not just editor hints

Annotations make the keyword contract executable for supported arguments. Robot conversion errors then name the argument/type before the library body runs. This improves diagnostics and removes repetitive int(...)/bool(...) parsing.

Return annotations improve Libdoc and Python static tooling but are not runtime conversion/validation in 7.4.2. If returning a custom object, document what Robot callers are expected to do with it. Prefer simple values, mappings, sequences, and domain objects with a clear public contract over opaque internal client handles.

9. Secret-typed arguments: narrow acceptance, narrow exposure

Use a Secret annotation when a keyword should accept only Robot Secret objects. This is stronger than accepting any string and hoping callers handle it safely. However, a Secret union such as str | Secret deliberately permits plain strings and therefore weakens that boundary.

Once a keyword reads .value, treat the result like any plaintext secret: do not include it in exception messages, logger calls, subprocess command lines, screenshots, or returned dictionaries.

10. Local --pythonpath versus packaged dependency

Packaging does not automatically improve architecture. A poorly scoped global library remains poorly scoped after publishing. Conversely, --pythonpath is not inherently bad when it is an explicit documented project-root command rather than a workstation-specific environment tweak.

11. Keep configuration layers distinct

12. Worked decision table

Knowledge check

13. Summary and next lesson

Library architecture is a set of explicit contracts: public keyword discovery, object scope, state ownership, argument conversion, return semantics, failures, logging, secrets, and import/packaging. Lesson 4 deliberately breaks these contracts and uses a layered diagnostic sequence to repair them without private APIs or broad workarounds.

References and version anchors

• Robot Framework 7.4.2 — Static library API — module/class discovery and keywords
• Robot Framework 7.4.2 — Argument conversion — annotations/defaults/decorator types
• Robot Framework 7.4.2 — Library scope — TEST/SUITE/GLOBAL
• Robot Framework public logging API — logger behavior
• Python packaging guide — packaged dependency boundary