Skip to content
Tutorials Center
My learning

Topics

Lesson 12 of 36 ยท Keywords and Variables

Variable Scopes and Built-in Variables

Understand global, suite, test and local variable scope in Robot Framework, how Set Test Variable and VAR work, command-line precedence and built-in variables.

Where a variable exists, and for how long, depends on its scope. Understanding scope explains most "variable not found" errors and most "why did my test see the old value" surprises. This lesson covers the four scopes, the keywords that change scope, which value wins when the same variable is defined twice, and the many variables Robot provides for free.

The four scopes

Scope Visible in Created by
Global Everything in the run --variable, --variablefile, Set Global Variable, VAR ... scope=GLOBAL
Suite All tests of one suite file (and its keywords) The Variables section, Variables import, Set Suite Variable, VAR ... scope=SUITE
Test The current test and everything it calls Set Test Variable, VAR ... scope=TEST
Local The current keyword (or test body) only Normal assignment ${x}= ..., VAR without scope, FOR variables
flowchart TB
    G["Global: command line, Set Global Variable"] --> S["Suite: Variables section, Set Suite Variable"]
    S --> T["Test: Set Test Variable"]
    T --> L["Local: assigned inside a keyword"]

Narrower scopes can read wider ones. A local assignment with the same name hides a wider variable only inside that keyword.

Local by default

ROBOTFRAMEWORK
*** Variables ***
${SUITE_VALUE}    from the suite

*** Test Cases ***
Local variable stays local
    ${total}=    Calculate Total
    Log    ${total}
    Variable Should Not Exist    ${partial}

*** Keywords ***
Calculate Total
    ${partial}=    Set Variable    ${40}
    ${total}=      Evaluate    ${partial} + 2
    RETURN    ${total}

${partial} exists only inside Calculate Total. To get a value out of a keyword, return it. That keeps data flow visible.

Widening scope on purpose

ROBOTFRAMEWORK
*** Test Cases ***
Share within the test
    Prepare Order
    Log    Order id is ${ORDER_ID}

*** Keywords ***
Prepare Order
    Set Test Variable    ${ORDER_ID}    A-1001
    Set Suite Variable   ${SHOP_OPEN}   ${True}
    Set Global Variable  ${RUN_LABEL}   nightly
    VAR    ${NOTE}    prepared    scope=TEST
Keyword Scope after it runs Notes
Set Test Variable the current test gone when the test ends
Set Suite Variable the current suite other suite files do not see it, unless children=True
Set Global Variable everything use rarely: it is invisible shared state
Set Local Variable the current keyword rarely needed
VAR ... scope=... LOCAL (default), TEST, SUITE, GLOBAL Robot 7.0 and later

Prefer returning values and passing arguments. Wide-scope variables make tests depend on each other, which breaks --test filtering and parallel runs.

Which definition wins?

When the same variable is defined in several places, Robot picks one by priority. In general:

  1. A value set while running (Set Test/Suite/Global Variable, VAR) replaces whatever was there, within its scope.
  2. Values given on the command line (--variable, --variablefile) override values from files.
  3. The suite's own Variables section beats imported variable files and resource files.
  4. Imported variable files and resources supply the rest.

This lets you write defaults in the file and override them from outside: the variable ${ENV} in the Variables section is dev, but robot --variable ENV:staging tests/ makes it staging for that run. To give a Variables-section value a default but still allow the outside override, nothing extra is needed. Do not rely on subtle ordering among several imported files; give variables unique names instead.

Built-in variables

Robot defines many variables automatically.

Variable Value
${TEST NAME} Name of the running test
@{TEST TAGS} Tags of the running test
${TEST DOCUMENTATION} Its documentation
${TEST STATUS}, ${TEST MESSAGE} Only in a test teardown
${PREV TEST NAME}, ${PREV TEST STATUS} Result of the previous test
${SUITE NAME}, ${SUITE SOURCE}, ${SUITE DOCUMENTATION}, &{SUITE METADATA} The suite
${OUTPUT DIR}, ${OUTPUT FILE}, ${LOG FILE}, ${REPORT FILE} Where results go
${LOG LEVEL} Current log level
${CURDIR} Directory of the current .robot file
${EXECDIR} Directory where robot was started
${TEMPDIR} The system temporary directory
${/} and ${:} The path separator and path-list separator of the OS
${\n} A newline
${True}, ${False}, ${None}, ${EMPTY}, ${SPACE} Literals
&{OPTIONS} Selected run options (Robot 7.0 and later)

A typical use: build paths that work on every system.

ROBOTFRAMEWORK
*** Variables ***
${DATA_DIR}    ${CURDIR}${/}data
${INPUT}       ${DATA_DIR}${/}users.json

*** Test Cases ***
Report where we are
    Log    Running ${TEST NAME} in ${SUITE NAME}
    Log    Results will be in ${OUTPUT DIR}

${CURDIR} is replaced when the file is parsed, so it always points to the file that contains it, even inside a resource file. ${EXECDIR} depends on where you start robot, so use it carefully.

Stand-in 1: a scope chain

The blocks below are not Robot Framework. This stand-in models lookup through test, suite and global scopes with collections.ChainMap, and shows that a name set in a narrower scope disappears when that scope ends.

Python Stand-in: scope lookup

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: command line beats the Variables section

The same variable can be defined in a file and on the command line. The stand-in resolves it using the priority rules from this lesson.

Python Stand-in: variable priority

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.

Debugging variables

  • Log Variables writes every visible variable to the log. It is the quickest way to see what a test knows.
  • Variable Should Exist ${name} and Variable Should Not Exist assert presence.
  • Get Variable Value ${name} default returns a default instead of failing when a variable is missing.
  • An unresolved variable error reads "Variable '${name}' not found" and often lists close matches: check scope and spelling first.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. A keyword assigns ${x}= Set Variable 1. Where can the caller read ${x}?

    Normal assignment creates a local variable. Return the value, or widen the scope with Set Test Variable.
  2. 2. Which keyword makes a variable visible in the whole run?

    Global scope covers all suites and tests. Use it rarely because it creates hidden coupling.
  3. 3. robot --variable ENV:staging is run and the suite defines ${ENV} dev. What is ${ENV}?

    Command-line variables override values defined in files.
  4. 4. Which variable holds the directory of the current .robot file?

    ${CURDIR} is the file's own folder. ${EXECDIR} is where robot was started.

Summary

  • Scopes are global, suite, test and local; narrower scopes read wider ones.
  • Normal assignment is local; widen with Set Test/Suite/Global Variable or VAR ... scope=; prefer returning values.
  • Command-line values override file values; the Variables section outranks imported files.
  • Built-ins include ${TEST NAME}, ${SUITE NAME}, ${OUTPUT DIR}, ${CURDIR}, ${EXECDIR}, ${TEMPDIR}, ${/} and the literals.
  • Debug with Log Variables, Variable Should Exist and Get Variable Value.

Next: Embedded Arguments and Return Values