Resource Files, Variable Files, Library Imports, and Project Layout: Core Concepts and Mental Model

1. The problem: a passing suite can still be location-dependent

Chapter 11 gave you compact, diagnosable variants. The next scaling problem appears when reusable keywords, data, and custom Python capabilities are split across files. A suite may pass from an IDE because the editor silently sets a project root, then fail in CI because the runner starts in another directory. Another suite may import ../../../../common.resource successfully until somebody moves one folder.

The fix is not “add more paths until it works.” The fix is to define which file owns each dependency and which path-resolution mechanism is responsible for finding it.

2. Inspect the current runtime before editing imports

python --version
python -m robot --version
python -c "import os, sys; print('cwd=', os.getcwd()); print('python=', sys.executable); print('sys.path[0:5]=', sys.path[0:5])"

These commands do not mutate the project. Record the interpreter, Robot Framework version, process working directory, and initial Python search path. When an import later fails, this snapshot answers whether the runner changed rather than the source.

3. Define the objects and owners before wiring them together

4. Mental model: dependencies flow inward; evidence flows outward

flowchart TD
S[Suite / test intent] --> R[Resource imports]
R --> K[User keywords / shared Robot variables]
S --> V[Variable file imports]
V --> C[Configuration values]
S --> L[Library imports]
L --> P[Python module / library instance]
K --> X[External or local capability]
P --> X
C --> K
X --> A[Assertion / status]
A --> O[output.xml / log.html / report.html]
M[Module search path] --> R
M --> V
M --> L

The suite points to three different dependency types. Resource imports bring Robot-level keywords/variables. Variable files supply values. Library imports expose Python keywords and may own Python object state. The module search path can help Robot locate all three, but that does not make them the same kind of dependency. Result artifacts are outputs of execution, not dependencies to import back into source.

5. Four path concepts that must not collapse into “the current folder”

${CURDIR} is stable when a source file moves together with its nearby data; ${EXECDIR} changes when the launch location changes. Neither should be used as a magical “project root” unless your project explicitly defines that contract.

6. Resource imports: source-relative first, module-search fallback second

*** Settings ***
Resource    ../resources/common.resource

*** Test Cases ***
Example
    Common Validation    sample-42

For a non-absolute resource path, Robot Framework first checks relative to the file doing the import. If it is not found there, Robot searches the Python module search path. The recommended extension is .resource. A resource cannot contain tests/tasks; it exists to share Robot-level keywords and variables.

Imports are transitive for available keywords/variables: a resource can import a library or another resource and make those capabilities available to its importer. That convenience is why resource dependency direction needs governance—deep or cyclic chains are difficult to reason about.

7. Variable files: values with different execution risk

*** Settings ***
Variables    ../variables/demo.py
Variables    ../variables/demo.json

Settings-level variable-file paths follow the same source-relative-then-module-search rule. A Python variable file is executable Python code when imported, so import-time I/O, random values, environment reads, prints, or network calls are real side effects. JSON is data-only and needs no extra dependency. YAML is also supported, but requires PyYAML.

8. Library imports: name/module lookup versus physical path

*** Settings ***
Library    libraries.text_tools
# A physical path is possible, but module imports are easier to standardize:
# Library    ../libraries/text_tools.py

A library imported by name must be on Python's module search path. A library imported by a physical path is resolved relative to the current data file. For reusable project libraries, one explicit project-root --pythonpath contract keeps imports identical across suites. For published/reused libraries, normal Python packaging is stronger because installation puts the package on the module search path without project-specific path injection.

9. Keyword collisions are an execution-resolution problem, not a filesystem problem

If two resources provide Normalize Value, Robot cannot infer your architectural intent from the folder names. Qualify the call using the resource basename, for example billing.Normalize Value versus identity.Normalize Value, or rename the abstractions so the ambiguity disappears. Robot gives suite-local user keywords highest scope priority, then resource keywords, external-library keywords, and standard-library keywords. Do not rely on accidental import order to choose between two same-named resource keywords.

10. Why this matters in DevOps

CI runners, containers, local shells, IDEs, and Pabot workers may start with different working directories and different Python environments. A deterministic project defines the interpreter/dependencies, a stable source root, import direction, and a separate output root. That makes an import failure attributable: source-relative path, module search path, Python package, or runner contract—not “Robot randomly cannot find it.”

11. Knowledge check

12. Summary and next step

A portable Robot project separates test intent, reusable Robot resources, configuration values, Python capabilities, fixture data, and result artifacts. ${CURDIR}, ${EXECDIR}, cwd, and the module search path answer different questions. Lesson 2 refactors a monolithic suite into explicit tests/, resources/, variables/, libraries/, data/, and results/ boundaries and proves the imports with dry-run and Libdoc.

Further reading

• Robot Framework 7.4.2 User Guide — Resource and variable files — resource structure, import rules, Python/YAML/JSON variable files, and precedence.
• Robot Framework 7.4.2 User Guide — Using test libraries — importing libraries by name or path and library aliases.
• Robot Framework 7.4.2 User Guide — Module search path — installed packages, PYTHONPATH, and --pythonpath.
• Robot Framework 7.4.2 User Guide — Built-in variables — ${CURDIR}, ${EXECDIR}, path separators, and temporary directory.
• Robot Framework 7.4.2 User Guide — Handling keywords with same names — scope priority, explicit qualification, and search order.
• Robot Framework 7.4.2 User Guide — Libdoc — library/resource documentation and import verification.
• Robot Framework 7.4.2 on PyPI — pinned stable package metadata and Python requirement.
• Robot Framework releases — re-check stable/pre-release status when updating the chapter.