robot framework 最全的Variables

Variables

---------

.. contents::

:depth: 2

:local:

Introduction

~~~~~~~~~~~~

Variables are an integral feature of Robot Framework, and they can be

used in most places in test data. Most commonly, they are used in

arguments for keywords in test case tables and keyword tables, but

also all settings allow variables in their values. A normal keyword

name *cannot* be specified with a variable, but the `BuiltIn

keyword`_ :name:`Run Keyword` can be used to get the same effect.

Robot Framework itself has two kinds of variables, scalars__ and lists__,

and they have the syntaxes :var:`${SCALAR}` and :var:`@{LIST}`,

respectively. In addition to this, `environment variables`_ can be used

directly with the syntax :var:`%{VARIABLE}`.

.. warning:: Using scalar variables and list variables with the same

base name, for example :var:`${VAR}` and :var:`@{VAR}`,

has been deprecated in Robot Framework 2.5. For more

information, see `issue 484`__ in the issue tracker.

The use of variables is recommended in the following cases:

- When strings change often in the test data. With variables you only

need to make these changes in one place.

- When creating system-independent and operating-system-independent

test data. Using variables instead of hard-coded strings eases that

considerably (for example, :var:`${RESOURCES}` instead of

:code:`c:\\resources`, or :var:`${HOST}` instead of

:code:`10.0.0.1:8080`). Because variables can be `set from the

command line`__ when tests are started, changing system-specific

variables is easy (for example, :cli:`--variable HOST:10.0.0.2:1234

--variable RESOURCES:/opt/resources`). This also facilitates

localization testing, which often involves running the same tests

with different strings.

- When there is a need to have objects other than strings as arguments

for keywords.

- When different keywords, even in different test libraries, need to

communicate. You can assign a return value from one keyword to a

variable and give that as an argument to another.

- When values in the test data are long or otherwise complicated. For

example, :var:`${URL}` is shorter than

:code:`\http://long.domain.name:8080/path/to/service?foo=1&bar=2&zap=42`.

If a nonexistent variable is used in the test data, the keyword using

it fails. If the same syntax that is used for variables is needed as a

literal string, it must be `escaped with a backslash`__ as in :code:`\\${NAME}`.

__ `Scalar variables`_

__ `List variables`_

__ http://code.google.com/p/robotframework/issues/detail?id=484

__ `Setting variables in command line`_

__ Escaping_

Variable types

~~~~~~~~~~~~~~

Different variable types are briefly described in this section. The

creation and usage of variables is described in more detail in the

following subsections.

Robot Framework variables, similarly as keywords, are

case-insensitive, and also spaces and underscores are

ignored. However, it is recommended to use all capital letters with

global variables (for example, :var:`${PATH}` or :var:`${TWO_WORDS}`)

and small letters with variables that are only available in certain

test cases or user keywords (for example, :var:`${my_var}` or

:var:`${myVar}`). Much more importantly, though, cases should be used

consistently.

Unlike in some programming languages where similar variable syntax is

used, curly braces (:code:`{` and :code:`}`) are mandatory in Robot Framework test

data. Basically, variable names can have any characters between the

curly braces. However, using only alphabetic characters from a to z,

numbers, underscore and space is recommended, and it is

even a requirement for using the `extended variable syntax`_.

Scalar variables

''''''''''''''''

When scalar variables are used in the test data, they are replaced

with the value they are assigned to. While scalar variables are most

commonly used for simple strings, you can assign any objects,

including lists, to them. The scalar variable syntax, for example

:var:`${NAME}`, should be familiar to most users, as it is also used,

for example, in shell scripts and Perl programming language.

The example below illustrates the usage of scalar variables. Assuming

that the variables :var:`${GREET}` and :var:`${NAME}` are available

and assigned to strings :code:`Hello` and :code:`world`, respectively,

both the example test cases are equivalent.

.. table:: Scalar variables with string values

:class: example

============ ======== ==================== ==========

Test Case Action Argument Argument

============ ======== ==================== ==========

Strings Log Hello \

\ Log Hello, world!! \

Variables Log ${GREET} \

\ Log ${GREET}, ${NAME}!! \

============ ======== ==================== ==========

When a scalar variable is used as the only value in a test data cell,

the scalar variable is replaced with the value it has. The value may

be any object. When a scalar variable is used in a test data cell with

anything else (constant strings or other variables), its value is

first converted into a Unicode string and then catenated to whatever is in

that cell. Converting the value into a string means that the object's

method :code:`__unicode__` (in Python, with :code:`__str__` as a fallback)

or :code:`toString` (in Java) is called.

.. note:: Variable values are used as-is without conversions also when

passing arguments to keywords using the `named arguments`_

syntax like :code:`argname=${var}`.

The example below demonstrates the difference between having a

variable in a cell alone or with other content. First, let us assume

that we have a variable :var:`${STR}` set to a string :code:`Hello,

world!` and :var:`${OBJ}` set to an instance of the following Java

object:

.. sourcecode:: java

public class MyObj {

public String toString() {

return "Hi, tellus!";

}

}

With these two variables set, we then have the following test data:

.. table:: Scalar variables with objects as values

:class: example

=========== ======== ================= ==========

Test Case Action Argument Argument

=========== ======== ================= ==========

Objects KW 1 ${STR} \

\ KW 2 ${OBJ} \

\ KW 3 I said "${STR}" \

\ KW 4 You said "${OBJ}" \

=========== ======== ================= ==========

Finally, when this test data is executed, different keywords receive

the arguments as explained below:

- :name:`KW 1` gets a string :code:`Hello, world!`

- :name:`KW 2` gets an object stored to variable :var:`${OBJ}`

- :name:`KW 3` gets a string :code:`I said "Hello, world!"`

- :name:`KW 4` gets a string :code:`You said "Hi, tellus!"`

.. Note:: Converting variables to Unicode obviously fails if the variable

cannot be represented as Unicode. This can happen, for example,

if you try to use byte sequences as arguments to keywords so that

you catenate the values together like :code:`${byte1}${byte2}`.

A workaround is creating a variable that contains the whole value

and using it alone in the cell (e.g. :code:`${bytes}`) because then

the value is used as-is.

List variables

''''''''''''''

List variables are compound variables that can have several

values assigned to them. In short, they are always lists and can

contain an unlimited number of entries (also empty lists are

possible). The main benefit of list variables is that they allow you

to assign a name for a larger data set. While list variables normally

contain only strings, other content is also possible.

When you use a list variable in test data, then the elements of the list

are inserted as new cells in the test data. Thus, if the list variable

contains two elements, the cell containing the list variable is turned

into two cells with the content of the list variable. Note that cells

with list variables should not contain other content. The list variable

syntax, :var:`@{NAME}`, is borrowed from Perl.

Assuming that the list variable :var:`@{USER}` is set to the value

:code:`['robot','secret']`, the following two test cases

are equivalent.

.. table:: Using list variables

:class: example

============= ======== =========== ==========

Test Case Action User Name Password

============= ======== =========== ==========

Strings Login robot secret

List Variable Login @{USER} \

============= ======== =========== ==========

Accessing individual list variable items

````````````````````````````````````````

It is also possible to access a certain value from the list variable

with the syntax :var:`@{NAME}[i]`, where :var:`i` is the index of the

selected value. Indexes start from zero, and trying to access a value

with too large an index causes an error. List items accessed in this

manner can be used similarly as scalar variables:

.. table:: Accessing list variable items

:class: example

============= =============== =================== ==========

Test Case Action Argument Argument

============= =============== =================== ==========

Strings Login robot secret

\ Title Should Be Welcome robot! \

List Variable Login @{USER} \

\ Title Should Be Welcome @{USER}[0]! \

============= =============== =================== ==========

Using list variables as scalar variables

````````````````````````````````````````

It is possible to use list variables as scalar variables containing

lists simply by replacing :var:`@` with :var:`$`. This makes it

possible to use list variables with list related keywords, for

example, from from BuiltIn_ and Collections_ libraries. This feature

works only if there is no scalar variable with same basename as the

list variable has. In these cases the scalar variable has precedence

and its value is used instead.

.. table:: Using list variables as scalars

:class: example

============= ================ ============== ========== ==========

Test Case Action Argument Argument Argument

============= ================ ============== ========== ==========

Example @{items} = Create List first second

\ Length Should Be ${items} 2 \

\ Append To List ${items} third \

\ Length Should Be ${items} 3 \

\ Remove From List ${items} 1 \

\ Length Should Be ${items} 2 \

\ Log Many @{items} \ \

============= ================ ============== ========== ==========

Using list variables with settings

``````````````````````````````````

List variables can be used only with some of the settings__. They can

be used in arguments to imported libraries and variable files, but

library and variable file names themselves cannot be list

variables. Also with setups and teardowns list variable can not be used

as the name of the keyword, but can be used in arguments. With tag related

settings they can be used freely. Using scalar variables is possible in

those places where list variables are not supported.

.. table:: Using list variables with settings

:class: example

============== ================ =============== ====================

Settings Value Value Comment

============== ================ =============== ====================

Library ExampleLibrary @{LIB ARGS} # This works

Library ${LIBRARY} @{LIB ARGS} # This works

Library @{NAME AND ARGS} # This does not work

Suite Setup Some Keyword @{KW ARGS} # This works

Suite Setup ${KEYWORD} @{KW ARGS} # This works

Suite Setup @{KEYWORD} # This does not work

Default Tags @{TAGS} # This works

============== ================ =============== ====================

__ `All available settings in test data`_

Environment variables

'''''''''''''''''''''

Robot Framework allows using environment variables in the test

data using the syntax :var:`%{ENV_VAR_NAME}`. They are limited to string

values.

Environment variables set in the operating system before the test execution are

available during it, and it is possible to create new ones with the keyword

:name:`Set Environment Variable` or delete existing ones with the

keyword :name:`Delete Environment Variable`, both available in the

`OperatingSystem library`_. Because environment variables are global,

environment variables set in one test case can be used in other test

cases executed after it. However, changes to environment variables are

not effective after the test execution.

.. table:: Using environment variables

:class: example

============= ======== ===================== ==========

Test Case Action Argument Argument

============= ======== ===================== ==========

Env Variables Log Current user: %{USER}

\ Run %{JAVA_HOME}${/}javac

============= ======== ===================== ==========

Java system properties

''''''''''''''''''''''

When running tests with Jython, it is possible to access `Java system properties`__

using same syntax as `environment variables`_. If an environment variable and a

system property with same name exist, the environment variable will be used.

Support for accessing Java system properties was added in Robot Framework 2.6.

.. table:: Using Java system properties

:class: example

================= ======== ======================================== ==========

Test Case Action Argument Argument

================= ======== ======================================== ==========

System Properties Log %{user.name} running tests on %{os.name}

================= ======== ======================================== ==========

__ http://download.oracle.com/javase/tutorial/essential/environment/sysprop.html

Creating variables

~~~~~~~~~~~~~~~~~~

Variables can spring into existence from different sources as

described in the subsections below.

Variable table

''''''''''''''

The most common source for variables are Variable tables in `test case

files`_ and `resource files`_. Variable tables are convenient, because they

allow creating variables in the same place as the rest of the test

data, and the needed syntax is very simple. Their main disadvantage is

that they only enable assigning variables into strings or a list of

strings. If other value types are needed, `variable files`_ are

probably a better option.

Creating scalar variables

`````````````````````````

The simplest possible variable assignment is setting a string into a

scalar variable. This is done by giving the variable name (including

:var:`${}`) in the first column of the Variable table and the value in

the second one. If the second column is empty, an empty string is set

as a value. Also an already defined variable can be used in the value.

.. table:: Creating scalar variables

:class: example

============ ================== =========

Variable Value Value

============ ================== =========

${NAME} Robot Framework \

${VERSION} 2.0 \

${ROBOT} ${NAME} ${VERSION} \

${EMPTY} \ \

============ ================== =========

It is also possible, but not obligatory,

to use the equals sign :code:`=` after the variable name to make assigning

variables slightly more explicit.

.. table:: Creating scalar variables using the equals sign

:class: example

============ =============== =========

Variable Value Value

============ =============== =========

${NAME} = Robot Framework \

${VERSION} = 2.0 \

============ =============== =========

Creating list variables

```````````````````````

Creating list variables is as easy as creating scalar variables. Again, the

variable name is in the first column of the Variable table and

values in the subsequent columns. A list variable can have any number

of values, starting from zero, and if many values are needed, they

can be `split into several rows`__.

__ `Dividing test data to several rows`_

.. table:: Creating list variables

:class: example

============ ========= ========= =========

Variable Value Value Value

============ ========= ========= =========

@{NAMES} Matti Teppo \

@{NAMES2} @{NAMES} Seppo \

@{NOTHING} \ \ \

@{MANY} one two three

... four five six

... seven \ \

============ ========= ========= =========

Variable file

'''''''''''''

Variable files are the most powerful mechanism for creating different

kind of variables. It is possible to assign variables to any object

using them, and they also enable creating variables dynamically. The

variable file syntax and taking variable files into use is explained

in section `Resource and variable files`_.

Setting variables in command line

'''''''''''''''''''''''''''''''''

Variables can be set from the command line either individually with

the :opt:`--variable (-v)` option or using a variable file with the

:opt:`--variablefile (-V)` option. Variables set from the command line

are globally available for all executed test data files, and they also

override possible variables with the same names in the Variable table and in

variable files imported in the test data.

The syntax for setting individual variables is :cli:`--variable

name:value`, where :cli:`name` is the name of the variable without

:var:`${}` and :cli:`value` is its value. Several variables can be

set by using this option several times. Only scalar variables can be

set using this syntax and they can only get string values. Many

special characters are difficult to represent in the

command line, but they can be escaped__ with the :opt:`--escape`

option.

__ `Escaping complicated characters`_

.. sourcecode:: bash

--variable EXAMPLE:value

--variable HOST:localhost:7272 --variable USER:robot

--variable ESCAPED:Qquotes_and_spacesQ --escape quot:Q --escape space:_

In the examples above, variables are set so that

- :var:`${EXAMPLE}` gets the value :code:`value`

- :var:`${HOST}` and :var:`${USER}` get the values

:code:`localhost:7272` and :code:`robot`

- :var:`${ESCAPED}` gets the value :code:`"quotes and spaces"`

The basic syntax for taking `variable files`_ into use from the command line

is :cli:`--variablefile path/to/variables.py`, and `Taking variable files into

use`_ section has more details. What variables actually are created depends on

what variables there are in the referenced variable file.

If both variable files and individual variables are given from the command line,

the latter have `higher priority`__. Additionally, if multiple variable files

have same variables, the ones in the file specified first are taken into use.

__ `Variable priorities and scopes`_

Return values from keywords

'''''''''''''''''''''''''''

Return values from keywords can also be set into variables. This

allows communication between different keywords even in different test

libraries. The syntax for a simple case is illustrated in the example below:

.. table:: Assigning values from keywords to variables

:class: example

=========== ========== ============ ============

Test Case Action Argument Argument

=========== ========== ============ ============

Returning ${x} = Get X an argument

\ Log We got ${x}! \

=========== ========== ============ ============

In the example above, the value returned by the :name:`Get X` keyword is

first set into the variable :var:`${x}` and then used by the :name:`Log`

keyword. This syntax works in all cases where a keywords returns

something, and the variable is set to whatever value returned by the

keyword. Having the equals sign :code:`=` after the variable name is

not obligatory, but recommended, because it makes the assignment

more explicit.

If a keyword returns a list, it is also possible to assign the return

value into several scalar variables and/or one list variable. Starting

from Robot Framework 2.5 this works with all list-like objects, but

prior to it only Python lists and tuples and Java arrays were supported.

.. table:: Assigning multiple values at once

:class: example

=============== ============ ========== ========== ==========

Test Case Action Argument Argument Argument

=============== ============ ========== ========== ==========

Return Multiple ${scalar} = Get 3 \ \

\ ${a} ${b} ${c} = Get 3

\ ${first} @{rest} = Get 3 \

\ @{list} = Get 3 \ \

=============== ============ ========== ========== ==========

Assuming that the keyword :name:`Get 3` returns a list

:code:`[1, 2, 3]`, the following variables are created:

- :var:`${scalar}` with the value :code:`[1, 2, 3]`

- :var:`${a}`, :var:`${b}` and :var:`${c}` with the values :code:`1`,

:code:`2`, and :code:`3`, respectively

- :var:`${first}` with the value :code:`1`, and :var:`@{rest}` with the value

:code:`[2, 3]`

- :var:`@{list}` with the value :code:`[1, 2, 3]`

Variables set in this manner are otherwise similar to any other

variables, but they are available only within the scope of the test

case or keyword where they are created. Thus it is not possible, for

example, to set a variable in one test case and use it in another. This is

because, in general, automated test cases should not depend on each

other, and accidentally setting a variable that is used elsewhere

could cause hard-to-debug errors. If there is a genuine need for

setting a variable in one test case and using it in another, it is

possible to use built-in keywords as explained in the next section.

Using built-in :name:`Set Test/Suite/Global Variable` keywords

''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''

The `BuiltIn library`_ has keywords :name:`Set Test Variable`,

:name:`Set Suite Variable` and :name:`Set Global Variable` which can

be used for setting variables dynamically during the test

execution. If a variable already exists within the new scope, its

value will be overwritten, and otherwise a new variable is created.

Variables set with :name:`Set Test Variable` keyword are available

everywhere within the scope of the currently executed test case. For

example, if you set a variable in a user keyword, it is available both

in the test case level and also in all other user keywords used in the

current test. Other test cases will not see variables set with this

keyword.

Variables set with :name:`Set Suite Variable` keyword are available

everywhere within the scope of the currently executed test

suite. Setting variables with this keyword thus has the same effect as

creating them using the `Variable table`_ in the test data file or

importing them from `variable files`_. Other test suites, including

possible child test suites, will not see variables set with this

keyword.

Variables set with :name:`Set Global Variable` keyword are globally

available in all test cases and suites executed after setting

them. Setting variables with this keyword thus has the same effect as

`creating from the command line`__ using the options :opt:`--variable` or

:opt:`--variablefile`. Because this keyword can change variables

everywhere, it should be used with care.

__ `Setting variables in command line`_

Built-in variables

~~~~~~~~~~~~~~~~~~

Robot Framework provides some built-in variables that are available

automatically.

Operating-system variables

''''''''''''''''''''''''''

Built-in variables related to the operating system ease making the test data

operating-system-agnostic.

.. table:: Available operating-system-related built-in variables

:class: tabular

+------------+------------------------------------------------------------------+

| Variable | Explanation |

+============+==================================================================+

| ${CURDIR} | An absolute path to the directory where the test data |

| | file is located. This variable is case-sensitive. |

+------------+------------------------------------------------------------------+

| ${TEMPDIR} | An absolute path to the system temporary directory. In UNIX-like |

| | systems this is typically :path:`/tmp`, and in Windows |

| | :path:`c:\\Documents and Settings\\<user>\\Local Settings\\Temp`.|

+------------+------------------------------------------------------------------+

| ${EXECDIR} | An absolute path to the directory where test execution was |

| | started from. New in Robot Framework 2.1. |

+------------+------------------------------------------------------------------+

| ${/} | The system directory path separator. :code:`/` in UNIX-like |

| | systems, :code:`\\` in Windows. |

+------------+------------------------------------------------------------------+

| ${:} | The system path element separator. :code:`:` in UNIX-like |

| | systems and :code:`;` in Windows. |

+------------+------------------------------------------------------------------+

.. table:: Using operating-system-related built-in variables

:class: example

============= ======================== ======================= ===================================

Test Case Action Argument Argument

============= ======================== ======================= ===================================

Example Create File ${CURDIR}${/}input.data Some text here

\ Set Environment Variable CLASSPATH ${TEMPDIR}${:}${TEMPDIR}${/}foo.jar

============= ======================== ======================= ===================================

Number variables

''''''''''''''''

The variable syntax can be used for creating both integers and

floating point numbers, as illustrated in the example below. This is

useful when a keyword expects to get an actual number, and not a

string that just looks like a number, as an argument.

.. table:: Using number variables

:class: example

=========== ======== =========== ========== ===================================================

Test Case Action Argument Argument Comment

=========== ======== =========== ========== ===================================================

Example 1A Connect example.com 80 # Connect gets two strings as arguments

Example 1B Connect example.com ${80} # Connect gets a string and an integer

Example 2 Do X ${3.14} ${-1e-4} # Do X gets floating point numbers 3.14 and -0.0001

=========== ======== =========== ========== ===================================================

Starting from Robot Framework 2.6, it is possible to create integers

also from binary, octal, and hexadecimal values using :var:`0b`, :var:`0o`

and :var:`0x` prefixes, respectively. The syntax is case insetive.

.. table:: Using integer variables with base

:class: example

=========== =============== ========== ==========

Test Case Action Argument Argument

=========== =============== ========== ==========

Example Should Be Equal ${0b1011} ${11}

\ Should Be Equal ${0o10} ${8}

\ Should Be Equal ${0xff} ${255}

\ Should Be Equal ${0B1010} ${0XA}

=========== =============== ========== ==========

Boolean and None/null variables

'''''''''''''''''''''''''''''''

Also Boolean values and Python :code:`None` and Java :code:`null` can

be created using the variable syntax similarly as numbers.

.. table:: Using Boolean and None/null variables

:class: example

=========== =============== ========== ========== =============================================

Test Case Action Argument Argument Comment

=========== =============== ========== ========== =============================================

Boolean Set Status ${true} \ # Set Status gets Boolean true as an argument

\ Create Y something ${false} # Create Y gets a string and Boolean false

None Do XYZ ${None} \ # Do XYZ gets Python None as an argument

Null ${ret} = Get Value arg # Checking that Get Value returns Java null

\ Should Be Equal ${ret} ${null} \

=========== =============== ========== ========== =============================================

These variables are case-insensitive, so for example :var:`${True}` and

:var:`${true}` are equivalent. Additionally, :var:`${None}` and

:var:`${null}` are synonyms, because when running tests on the Jython

interpreter, Jython automatically converts :code:`None` and

:code:`null` to the correct format when necessary.

Space and empty variables

'''''''''''''''''''''''''

It is possible to create spaces and empty strings using variables

:var:`${SPACE}` and :var:`${EMPTY}`, respectively. These variables are

useful, for example, when there would otherwise be a need to `escape

spaces or empty cells`__ with a backslash. If more than one space is

needed, it is possible to use the `extended variable syntax`_ like

:var:`${SPACE * 5}`. In the following exmaple, :name:`Should Be

Equal` keyword gets identical arguments but those using variables are

easier to understand than those using backslashes.

__ Escaping_

.. table:: Using :var:`${SPACE}` and :var:`${EMPTY}`

:class: example

============= ================= ================ ================================

Test Case Action Argument Argument

============= ================= ================ ================================

One Space Should Be Equal ${SPACE} \\ \\

Four Spaces Should Be Equal ${SPACE * 4} \\ \\ \\ \\ \\

Ten Spaces Should Be Equal ${SPACE * 10} \\ \\ \\ \\ \\ \\ \\ \\ \\ \\ \\

Quoted Space Should Be Equal "${SPACE}" " "

Quoted Spaces Should Be Equal "${SPACE * 2}" " \\ "

Empty Should Be Equal ${EMPTY} \\

============= ================= ================ ================================

Automatic variables

'''''''''''''''''''

Some automatic variables can also be used in the test data. These

variables can have different values during the test execution and some

of them are not even available all the time.

.. table:: Available automatic variables

:class: tabular

+-----------------------+-------------------------------------------------------+----------------+

| Variable | Explanation | Available |

+=======================+=======================================================+================+

| ${TEST NAME} | The name of the current test case. | Test case |

+-----------------------+-------------------------------------------------------+----------------+

| @{TEST TAGS} | Contains the tags of the current test case in | Test case |

| | alphabetical order. | |

+-----------------------+-------------------------------------------------------+----------------+

| ${TEST STATUS} | The status of the current test case, either PASS or | Test teardown |

| | FAIL. | |

+-----------------------+-------------------------------------------------------+----------------+

| ${TEST MESSAGE} | The possible error message of the current test case. | Test teardown |

+-----------------------+-------------------------------------------------------+----------------+

| ${PREV TEST NAME} | The name of the previous test case, or an empty string| Everywhere |

| | if no tests have been executed yet. | |

+-----------------------+-------------------------------------------------------+----------------+

| ${PREV TEST STATUS} | The status of the previous test case: either PASS, | Everywhere |

| | FAIL or an empty string when no tests have been | |

| | executed. | |

+-----------------------+-------------------------------------------------------+----------------+

| ${PREV TEST MESSAGE} | The possible error message of the previous test case. | Everywhere |

+-----------------------+-------------------------------------------------------+----------------+

| ${SUITE NAME} | The full name of the current test suite. | Everywhere |

+-----------------------+-------------------------------------------------------+----------------+

| ${SUITE SOURCE} | An absolute path to the suite file or directory. New | Everywhere |

| | in Robot Framework 2.5. | |

+-----------------------+-------------------------------------------------------+----------------+

| ${SUITE STATUS} | The status of the current test case, either PASS or | Suite teardown |

| | FAIL. | |

+-----------------------+-------------------------------------------------------+----------------+

| ${SUITE MESSAGE} | The full message of the current test suite, including | Suite teardown |

| | statistics. | |

+-----------------------+-------------------------------------------------------+----------------+

| ${OUTPUT FILE} | An absolute path to the current `output file`_. Has | Everywhere |

| | different values during execution when | |

| | `outputs are split`_. | |

+-----------------------+-------------------------------------------------------+----------------+

| ${LOG FILE} | An absolute path to the current `log file`_ or string | Everywhere |

| | NONE when no log file is created. Has different values| |

| | during execution when `outputs are split`_. | |

+-----------------------+-------------------------------------------------------+----------------+

| ${REPORT FILE} | An absolute path to the `report file`_ or string NONE | Everywhere |

| | when no report is created. | |

+-----------------------+-------------------------------------------------------+----------------+

| ${SUMMARY FILE} | An absolute path to the `summary file`_ or string NONE| Everywhere |

| | when no summary is created. | |

+-----------------------+-------------------------------------------------------+----------------+

| ${DEBUG FILE} | An absolute path to the `debug file`_ or string NONE | Everywhere |

| | when no debug file is created. | |

+-----------------------+-------------------------------------------------------+----------------+

| ${OUTPUT DIR} | An absolute path to the `output directory`_. | Everywhere |

+-----------------------+-------------------------------------------------------+----------------+

Variable priorities and scopes

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Variables coming from different sources have different priorities and

are available in different scopes.

Variable priorities

'''''''''''''''''''

*Variables from the command line*

Variables `set in the command line`__ have the highest priority of all

variables that can be set before the actual test execution starts. They

override possible variables created in Variable tables in test case

files, as well as in resource and variable files imported in the

test data.

Individually set variables (:opt:`--variable` option) override the

variables set using `variable files`_ (:opt:`--variablefile`

option). Additionally, if multiple variable files have same variables,

the ones in the file specified first have the highest priority.

*Variable table in a test case file*

Variables created using the `Variable table`_ in a test case file

are available for all the test cases in that file. These variables

override possible variables with same names in imported resource and

variable files.

Variables created in the variable tables are available in all other tables

in the file where they are created. This means that they can be used also

in the Setting table, for example, for importing more variables from

resource and variable files.

*Imported resource and variable files*

Variables imported from the `resource and variable files`_ have the

lowest priority of all variables created in the test data.

Variables from resource files and variable files have the same

priority. If several resource and/or variable file have same

variables, the ones in the file imported first are taken into use.

If a resource file imports resource files or variable files,

variables in its own Variable table have a higher priority than

variables it imports. All these variables are available for files that

import this resource file.

Note that variables imported from resource and variable files are not

available in the Variable table of the file that imports them. This

is due to the Variable table being processed before the Setting table

where the resource files and variable files are imported.

*Variables set during test execution*

Variables set during the test execution either using `return values

from keywords`_ or `built-in keywords`__ :name:`Set

Test/Suite/Global Variable` always override possible existing

variables in the scope where they are set. In a sense they thus

have the highest priority, but on the other hand they do not affect

variables outside the scope they are defined.

*Built-in variables*

`Built-in variables`_ like :var:`${TEMPDIR}` and :var:`${TEST_NAME}`

have the highest priority of all variables. They cannot be overridden

using Variable table or from command line, but even they can be reset during

the test execution. An exception to this rule are `number variables`_, which

are resolved dynamically if no variable is found otherwise. They can thus be

overridden, but that is generally a bad idea. Additionally :var:`${CURDIR}`

is special because it is replaced already during the test data processing time.

__ `Setting variables in command line`_

__ `Using built-in Set Test/Suite/Global Variable keywords`_

Variable scopes

'''''''''''''''

Depending on where and how they are created, variables can have a

global, test suite, test case or user keyword scope.

*Global scope*

Global variables are available everywhere in the test data. These

variables are normally `set from the command line`__ with the

:opt:`--variable` and :opt:`--variablefile` options, but it is also

possible to create new global variables or change the existing ones

with the `BuiltIn keyword`_ :name:`Set Global Variable` anywhere in

the test data. Additionally also `built-in variables`_ are global.

It is recommended to use capital letters with all global variables.

*Test suite scope*

Variables with the test suite scope are available anywhere in the

test suite where they are defined or imported. They can be created

in Variable tables, imported from `resource and variable files`_,

or set during the test execution using the `BuiltIn keyword`_

:name:`Set Suite Variable`.

The test suite scope *is not recursive*, which means that variables

available in a higher-level test suite *are not available* in

lower-level suites. If necessary, `resource and variable files`_ can

be used for sharing variables.

Since these variables can be considered global in the test suite where

they are used, it is recommended to use capital letters also with them.

*Test case scope*

Variables created in test cases from the return values of keywords have a

test case scope and they are available only in that test

case. Another possibility to create them is using the `BuiltIn keyword`_

:name:`Set Test Variable` anywhere in that particular test case. Test

case variables are local and should use lower-case letters.

*User keyword scope*

User keywords get their own variables from `arguments passed to them`__

and return values from the keywords they use. Also these variables

are local and should use lower-case letters.

__ `Setting variables in command line`_

__ `User keyword arguments`_

Advanced variable features

~~~~~~~~~~~~~~~~~~~~~~~~~~

Extended variable syntax

''''''''''''''''''''''''

Extended variable syntax can be used with objects set into scalar

variables. It allows accessing the attributes of the object (for example,

:var:`${obj.name}` or :var:`${obj.some_attr}`), and even calling

its methods (for example, :var:`${obj.get_name()}` or

:var:`${obj.getSomething('arg')}`).

Extended variable syntax is a powerful feature, but it should

be used with care. Accessing attributes is normally not a problem, on

the contrary, as one variable with an object having several

attributes is often better than having several variables. On the

other hand, calling methods, especially when they are used with

arguments, can make the test data complicated. If that happens,

it is recommended to move the code into a test library.

The most common usages of extended variable syntax are illustrated

in the example below. First assume that we have the following `variable file`_

and test case:

.. sourcecode:: python

class MyObject:

def __init__(self, name):

self.name = name

def greet(self, who):

return '%s says hello to %s' % (self.name, who)

def __str__(self):

return self.name

OBJECT = MyObject('Robot')

DICTIONARY = { 1: 'one', 2: 'two', 3: 'three'}

.. table::

:class: example

=========== ======== ====================== ==========

Test Case Action Argument Argument

=========== ======== ====================== ==========

Example KW 1 ${OBJECT.name} \

\ KW 2 ${OBJECT.greet('Fit')} \

\ KW 3 ${DICTIONARY[2]} \

=========== ======== ====================== ==========

When this test data is executed, the keywords get the arguments as

explained below:

- :name:`KW 1` gets string :code:`Robot`

- :name:`KW 2` gets string :code:`Robot says hello to Fit`

- :name:`KW 3` gets string :code:`two`

The extended variable syntax is evaluated in the following order:

1. The variable is searched using the full variable name. The extended

variable syntax is evaluated only if no matching variable

is found.

2. The real name of the base variable is created. The body of the name

consists of all the characters after :var:`${` until the first

occurrence of a non-alphanumeric character or a space (for example,

:var:`OBJECT` in :var:`${OBJECT.name}` and :var:`DICTIONARY` in

:var:`${DICTIONARY[2]}`).

3. A variable matching the body is searched. If there is no match, an

exception is raised and the test case fails.

4. The expression inside the curly brackets is evaluated as a Python

expression, so that the base variable name is replaced with its

value. If the evaluation fails because of an invalid syntax or that

the queried attribute does not exist, an exception is raised and

the test fails.

5. The whole extended variable is replaced with the value returned

from the evaluation.

If the object that is used is implemented with Java, the extended

variable syntax allows you to access attributes using so-called bean

properties. In essence, this means that if you have an object with the

:code:`getName` method set into a variable :var:`${OBJ}`, then the

syntax :var:`${OBJ.name}` is equivalent to, but clearer than

:var:`${OBJ.getName()}`. Thus the Python object used in the previous

example could be replaced with the following Java implementation:

.. sourcecode:: java

public class MyObject:

private String name;

public MyObject(String name) {

name = name;

}

public String getName() {

return name;

}

public String greet(String who) {

return name + " says hello to " + who;

}

public String toString() {

return name;

}

}

Many standard Python objects, including strings and numbers, have

methods that can be used with the extended variable syntax either

explicitly or implicitly. Sometimes this can be really useful and

reduce the need for setting temporary variables, but it is also easy

to overuse it and create really cryptic test data. Following examples

show few pretty good usages.

.. table:: Using methods of strings and numbers

:class: example

=========== ============ =================== ===============

Test Case Action Argument Argument

=========== ============ =================== ===============

String ${string} = Set Variable abc

\ Log ${string.upper()} # Logs 'ABC'

\ Log ${string * 2} # Logs 'abcabc'

Number ${number} = Set Variable ${-2}

\ Log ${number * 10} # Logs -20

\ Log ${number.__abs__()} # Logs 2

=========== ============ =================== ===============

Note that even though :code:`abs(number)` is recommended over

:code:`number.__abs__()` in normal Python code, using

:var:`${abs(number)}` does not work. This is because the variable name

must be in the beginning of the extended syntax. Using :code:`__xxx__`

methods in the test data like this is already a bit questionable, and

it is normally better to move this kind of logic into test libraries.

Variables inside variables

''''''''''''''''''''''''''

Variables are allowed also inside variables, and when this syntax is

used, variables are resolved from the inside out. For example, if you

have a variable :var:`${var${x}}`, then :var:`${x}` is resolved

first. If it has the value :code:`name`, the final value is then the

value of the variable :var:`${varname}`. There can be several nested

variables, but resolving the outermost fails, if any of them does not

exist.

In the example below, :name:`Do X` gets the value :var:`${JOHN_HOME}`

or :var:`${JANE_HOME}`, depending on if :name:`Get Name` returns

:code:`john` or :code:`jane`. If it returns something else, resolving

:var:`${${name}_HOME}` fails.

.. table:: Using a variable inside another variable

:class: example

============ ========== ======= =======

Variable Value Value Value

============ ========== ======= =======

${JOHN_HOME} /home/john \ \

${JANE_HOME} /home/jane \ \

============ ========== ======= =======

.. table::

:class: example

=========== ============ ======================== ==========

Test Case Action Argument Argument

=========== ============ ======================== ==========

Example ${name} = Get Name \

\ Do X ${${name}_HOME} \

=========== ============ ======================== ==========