Skip to content
Tutorials Center
My learning

Topics

Lesson 18 of 36 ยท Libraries and Resources

Variable Files, Environments and libdoc

Load variables from Python, YAML and JSON files, choose a test environment with get_variables or --variablefile arguments, handle secrets and document with libdoc.

Tests rarely run against only one place. You have a local machine, a staging server and production, each with its own URL, user names and timeouts. Hard-coding those values in .robot files is a bad idea. Variable files keep configuration out of the tests, and let you pick the environment when you start the run. This lesson also introduces libdoc for documenting what you build.

Python variable files

A Python module becomes a variable file: every module-level name that does not start with an underscore is a variable.

variables/staging.py:

Python
BASE_URL = "https://staging.shop.example.org"
TIMEOUT = 20
BROWSERS = ["chromium", "firefox"]
USER = {"name": "tester", "role": "admin"}

_internal = "not a variable"

Import it in a suite:

ROBOTFRAMEWORK
*** Settings ***
Variables    ../variables/staging.py

*** Test Cases ***
Use the configuration
    Log    ${BASE_URL}
    Log    ${TIMEOUT}
    Log    @{BROWSERS}
    Log    ${USER}[name]

Variables keep their Python type: ${TIMEOUT} is an integer here and @{BROWSERS} is a list, without any ${20} tricks. Name them in upper case by convention. You can expose them under list and dictionary markers (LIST__NAME, DICT__NAME) when you want @{NAME} and &{NAME} to work with plain Python values; this is usually unnecessary because a list variable can be used with @{} anyway.

Choosing an environment

With command-line files

Terminal
robot --variablefile variables/staging.py tests/
robot --variablefile variables/production.py tests/

With one file and an argument

A file can define a function get_variables(*args) returning a dictionary. Robot passes the arguments you give after the file name:

variables/env.py:

Python
ENVIRONMENTS = {
    "dev":     {"BASE_URL": "http://localhost:8000",       "TIMEOUT": 5},
    "staging": {"BASE_URL": "https://staging.example.org", "TIMEOUT": 20},
}

def get_variables(environment="dev"):
    values = dict(ENVIRONMENTS[environment])
    values["ENVIRONMENT"] = environment
    return values
Terminal
robot --variablefile variables/env.py:staging tests/

or in the suite: Variables ../variables/env.py staging. The argument is separated from the file name with a colon on the command line and with the usual cell separator in the Settings section.

With plain --variable

For one or two values, name them directly:

Terminal
robot --variable ENV:staging --variable BROWSER:firefox tests/

Everything on the command line is a global variable and beats values written in files (see Variable Scopes).

YAML and JSON variable files

Data-only configuration is easy in YAML (needs the PyYAML package) or JSON (Robot 6.1 and later):

variables/staging.yaml:

YAML
BASE_URL: https://staging.shop.example.org
TIMEOUT: 20
BROWSERS:
  - chromium
  - firefox
USER:
  name: tester
  role: admin
ROBOTFRAMEWORK
*** Settings ***
Variables    ../variables/staging.yaml

Dictionaries in YAML become dictionary variables (${USER}[name] or ${USER.name}) and lists become list variables. Choose YAML or JSON for plain data and Python when you need computed values, such as building a URL or reading from the environment.

Secrets

Never commit passwords or API tokens to a variable file. Read them from the environment:

Python
import os

API_TOKEN = os.environ.get("SHOP_API_TOKEN", "")

or in the suite ${TOKEN} %{SHOP_API_TOKEN}. Keyword arguments appear in log.html, so a secret passed as an argument would be visible there. Use the Log level options, a library that hides values, or the --loglevel setting NONE around the sensitive step with Set Log Level NONE and restore it afterwards.

Documenting with libdoc

libdoc builds keyword documentation from libraries and resources, which makes your resources usable by teammates:

Terminal
libdoc resources/shop.resource docs/shop.html
libdoc libs/MyHelpers.py docs/helpers.html
libdoc --format json libs/MyHelpers.py docs/helpers.json

The page lists each keyword with arguments, defaults, types and the documentation you wrote in [Documentation] or the docstring. Add a short documentation line to every shared keyword; the tool turns it into searchable reference pages. In IDEs the same data powers autocompletion and hover help.

Stand-in 1: reading a variable file

The blocks below are not Robot Framework. The first one performs the same selection: every non-underscore name of a module becomes a variable, keeping its Python type. It builds a module object in memory to avoid needing a file.

Python Stand-in: module to variables

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Stand-in 2: get_variables and the environment argument

The stand-in calls get_variables as Robot would when you pass env.py:staging, and shows the precedence of a command-line override.

Python Stand-in: pick an environment

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Notice that the override arrives as the string "60": values from --variable are always strings. Convert them in the test (${{ int($TIMEOUT) }}) or in a keyword when a number is needed.

  1. variables/common.py for values shared everywhere.
  2. One file per environment, or a single env.py with get_variables.
  3. Test files import only Variables ../variables/env.py with the default environment, so they run locally with no options.
  4. CI passes --variablefile variables/env.py:staging and secrets as environment variables.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which names in a Python variable file become variables?

    Every public module-level name is a variable, and keeps its Python type.
  2. 2. How do you pass the argument staging to variable file env.py on the command line?

    The file name and argument are separated with a colon, and get_variables receives the argument.
  3. 3. What type does a value given with --variable have?

    Command-line variables are strings; convert them where you need numbers.
  4. 4. Why not store passwords in a variable file you commit?

    Read secrets from environment variables or a secret store instead.

Summary

  • Variable files (Python, YAML, JSON) keep configuration out of tests; import them with Variables or --variablefile.
  • Python files keep real types; get_variables(*args) allows one file to serve several environments.
  • --variable creates global string variables that beat file values.
  • Keep secrets in environment variables, not in files or logs.
  • libdoc turns resources and libraries into searchable keyword documentation.

Next: Web testing with SeleniumLibrary