【读书笔记】Robot Framework 的变量

Robot Framework 的变量分为 标量, 列表 和 字典, 分别使用语法格式 ${SCALAR}, @{LIST} 和 &{DICT} 来定义. 变量名称的构成包括: 一个表示变量类型的标识符($, @, &, %), 一对花括号({, }), 以及包含在花括号中的变量名.此外, 环境变量 可以直接使用语法 %{ENV_VAR} 来获取.当需要传递对象而不是字符串参数给关键字时. 这种情况下只能使用变量实现.如果要在字面字符串中表示变量的语法格式, 则必须使用 反斜杠转义, 例如 \${NAME}.

Robot Framework 变量, 与关键字类似, 是不区分大小写的, 同时其中的下划线和空格也会被忽略.

当使用标量变量时, 变量被其赋值所替代. 最常用的标量赋值是字符串, 实际上标量可以是任何对象, 包括列表,字典等. 

如果单元格内还有其它内容(例如字符串或其它变量), 则变量的值会首先转换为Unicode字符串, 然后再和单元格内的其它内容拼接起来. 变量作为关键字的参数使用 命名参数 语法时, 例如, argname=${var} 这时变量值会原样传递, 不做字符串转换.

命名参数语法是大小写敏感和空格敏感的. 前者的意思是, 如果参数名为 arg, 则必须使用 arg=value, 而 Arg=value 或 ARG=value 都是错误的. 后者的意思是, 等号 = 的前面不能有空格, = 后面可以有空格, 这些空格会被视作值的一部分.

当命名参数语法用在 user keywords 时, 参数名称必须去掉 ${} 标示. 例如, ${arg1}=first, ${arg2}=second 必须写成如 arg2=override.

因为 命名参数 要求位置参数必须在命名参数之前, 所以字典变量后面只能跟命名参数或者其它的字典.

不允许字符串作为字符列表使用, 但是其它的序列对象如元组或字典是可以的.

Robot Framework 2.9版本之前, 标量和列表变量是分开存储的, 但是两者可以互换使用, 即列表变量作为标量使用, 标量变量作为列表使用.

如果一个列表变量在单元格内和其它内容(比如字符串或其它变量)混用, 则最终的值会是该变量的字符串表示, 就跟标量变量的处理方式一样.

使用下标语法 @{NAME}[index] 可以获取到列表变量中指定项的值, 其中 index 是要获取的项的下标. 下标从0开始, 负数的下标等同于从列表末尾向前数. 下标长度超过列表范围会导致错误. 下标值自动转换为整数, 同样支持变量表示. 获取到的列表项基本等同于一个标量变量.

列表变量可以用在库和变量文件导入时的参数, 不过库和变量文件自身的名称不能是列表变量. Setup和Teardown中的关键字的参数也可以使用列表变量, 但是关键字名称不可以. 不过这些名称都支持使用标量型变量. 标签相关的设置可以自由使用列表变量.

因为Robot Framework所有的变量都存储在相同的命名空间, 赋值给标量变量还是列表变量其实没有太多的差别. 最主要的差别就是当创建列表变量时, Robot Framework 自动校验值是否为列表或类似列表, 并且新建一个列表来保存返回的值. 当赋值给标量变量时, 返回值不会校验, 完全按照返回对象的类型保存值.

*** Settings ***
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

如果一个字典变量在单元格内和其它内容(字符串或其它变量)混用, 最终的值会是变量的字符串表示, 就跟把变量当作标量变量的处理结果一样.

可以通过 &{NAME}[key] 这样的语法格式获取字典中某项的值, 其中 key 是键的名称. 键名当作字符串处理, 非字符串的键可以用变量代替. 通过这种方式获取到的值可作为标量变量使用.如果键是字符串, 还可以使用另一种语法格式 ${NAME.key}. 

*** Test Cases ***
Dict Variable Item
    Login    &{USER}[name]    &{USER}[password]
    Title Should Be    Welcome &{USER}[name]!

Key As Variable
    Log Many    &{DICT}[${KEY}]    &{DICT}[${42}]

Attribute Access
    Login    ${USER.name}    ${USER.password}
    Title Should Be    Welcome ${USER.name}!

字典变量除了在import, setup, teardown中充当关键字的参数使用, 不能在其它设置项中使用.

*** Settings ***
Library        ExampleLibrary    &{LIB ARGS}
Suite Setup    Some Keyword      &{KW ARGS}     named=arg

使用 %{ENV_VAR_NAME} 这种语法格式来使用环境变量. 环境变量的值只能是字符串.

在测试执行前已设置的操作系统环境变量在执行过程中都是可用的, 同时还可以使用关键字 Set Environment Variable 创建新的环境变量, 或者 Delete Environment Variable 删除某个环境变量, 这两个关键字都是来自于 OperatingSystem 库.

因为环境变量是全局的, 所以在一个测试用例中设置的环境变量可以在后续执行的另一个测试用例中使用. 不过, 测试执行中改变的环境变量在测试执行完成后即恢复原状, 即不会真正改变系统的环境变量.

*** Test Cases ***
Env Variables
    Log    Current user: %{USER}
    Run    %{JAVA_HOME}${/}javac

如果一个标量变量的值很长, 可以分割到多列甚至 多行. 默认情况下, 各个单元格中的值最终会使用空格拼接起来, 不过可以在第一格中使用 SEPARATOR= 来指定连接符.

*** Variables ***
${EXAMPLE}      This value is joined    together with a space
${MULTILINE}    SEPARATOR=\n    First line
...             Second line     Third line
上面的这种拼接方式是Robot Framework 2.9版本的新特性. 
在2.8版本中, 这种格式会引发一个语法错误. 而在更早的版本中, 这会创建一个列表值.

*** Variables ***
@{NAMES}        Matti       Teppo
@{NAMES2}       @{NAMES}    Seppo
@{NOTHING}
@{MANY}         one         two      three      four
...             five        six      seven
一个列表变量可以有任意多的值, 包括0个值. 如果值比较多, 同样可以 分为多行.

*** Variables ***
&{USER 1}       name=Matti    address=xxx         phone=123
&{USER 2}       name=Teppo    address=yyy         phone=456
&{MANY}         first=1       second=${2}         ${3}=third
&{EVEN MORE}    &{MANY}       first=override      empty=
...             =empty        key\=here=value
字典变量的创建方式类似列表. 不同之处在于字典的项需要使用 name=value 的语法格式, 或者其它的字典变量.
如果有多个项重名, 只保留最后那个. 如果项中包含字面的等号, 则该等号必须使用反斜杠进行 转义, 如 \=

字典变量相较于普通的Python字典有两个额外的属性(properties).

首先, 字典的项可以作为属性(attributes)获取, 也就是说使用 扩展变量语法 如 ${VAR.key}. 前提是该key是一个合法的属性名且不会匹配上任何其它普通的属性. 例如, &{USER}[name] 同样可以通过 ${USER.name} 获取(注意到这里是 $ ), 但是 ${MANY.3} 就不可以.

另一个特别之处在于字典变量中的项是有顺序的. 也就是说字典总是会按定义时的顺序迭代. 这在把字典当作 列表变量 使用时(例如在 FOR循环 )很有用. 当字典被当作列表迭代时, 实际返回的值是字典的键. 例如, @{MANY} 变量的值是 ['first', 'second', 3].

--variable EXAMPLE:value
--variable HOST:localhost:7272 --variable USER:robot
--variable ESCAPED:Qquotes_and_spacesQ --escape quot:Q --escape space:_

在上例中, 变量值分别是:
${EXAMPLE} 值为 value
${HOST} 和 ${USER} 值分别为 localhost:7272 和 robot
${ESCAPED} 值为 "quotes and spaces"

变量可以在命令行中通过选项 --variable (-v) 单个设置, 也可以通过选项 --variablefile (-V) 设置变量文件. 通过命令行设置的变量对所有执行的测试文件是全局可见的, 不过如果局部的变量表格或者局部导入的变量文件中存在重名的变量, 则这些变量也会被命令行中指定的值所覆盖.

设置单个变量的选项格式是 --variable name:value, 其中 name 是变量名, 不带 ${} value`是变量的值. 有多个变量的话就使用这个选项多次. 这种方式只能定义标量变量. 很多特殊字符必须使用选项 :option:–escape` 经过 转义 才能表示.如果变量同时在命令行的变量文件中和单独指定, 则单独指定的变量有更高的 优先级

如果一个关键字返回列表或类似列表的对象, 还可以一次性将其中的值同时赋值给多个变量. 可以是多个标量, 也可以是标量和列表混合, 如下例所示:

*** Test Cases ***
Assign Multiple
    ${a}    ${b}    ${c} =    Get Three
    ${first}    @{rest} =    Get Three
    @{before}    ${last} =    Get Three
    ${begin}    @{middle}    ${end} =    Get Three

如果返回的列表的元素个数多于或者少于可供赋值的标量, 将会报错. 另外, 待赋值的变量中最多只能有一个列表变量, 而字典变量只能单独赋值.早期版本中, 列表变量只被允许出现在待赋值变量的最后, 现在则可以是任意位置.

关键字 Set Test/Suite/Global Variable 直接在 各自作用域 内设置变量, 没有返回值. 而 Set Variable 设置局部变量, 并且 返回.

可用的操作系统相关的内置变量

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 /tmp , and in Windows c:\Documents and Settings\<user>\Local Settings\Temp .
${EXECDIR}	An absolute path to the directory where test execution was started from.
${/}	The system directory path separator. / in UNIX-like systems and \ in Windows.
${:}	The system path element separator. : in UNIX-like systems and ; in Windows.
${\n}	The system line separator. \n in UNIX-like systems and \\r\\n in Windows. New in version 2.7.5.

*** Test Cases ***
Example
    Create Binary File    ${CURDIR}${/}input.data    Some text here${\n}on two lines
    Set Environment Variable    CLASSPATH    ${TEMPDIR}${:}${CURDIR}${/}foo.jar

数字变量

*** Test Cases ***
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
    
使用 0b 0o 和 0x 前缀还可以创建二进制, 八进制 和十六进制的数字. 注意这里的语法不区分大小写.
*** Test Cases ***
Example
    Should Be Equal    ${0b1011}    ${11}
    Should Be Equal    ${0o10}      ${8}
    Should Be Equal    ${0xff}      ${255}
    Should Be Equal    ${0B1010}    ${0XA}

布尔值和Python中的 None 以及Java中的 null 也可以使用类似数字变量的语法来表示.这些变量都不区分大小写, 例如 ${True} 和 ${true} 是一样的. 同样, ${None} 和 ${null} 也是同义的, 因为当使用Jython解释器运行时, Jython会视情况自动转换.

变量 ${SPACE} 和 ${EMPTY} 分别用来创建空格和空字符串. 使用这些变量相对于使用反斜杠来 转义空格 容易的多. 同时还可以使用 扩展变量语法 表示连续的多个空格, 例如 ${SPACE * 5}。同样还可以使用 列表变量 的格式 @{EMPTY} 表示空列表, 字典变量 的格式 &{EMPTY} 表示空字典.

Robot Framework还提供了若干的自动变量. 这些变量在测试执行过程中有不同的值, 有些还是全局可用的. 改变这些变量的值不会影响其初始值, 不过其中某些可用通过 BuiltIn 库中的关键字进行动态修改.

Available automatic variables

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 alphabetical order. Can be modified dynamically using Set Tags and Remove Tags keywords.	Test case
${TEST DOCUMENTATION}	The documentation of the current test case. Can be set dynamically using using Set Test Documentation keyword. New in Robot Framework 2.7.	Test case
${TEST STATUS}	The status of the current test case, either PASS or FAIL.	Setup和Teardown
${TEST MESSAGE}	The message of the current test case.	Setup和Teardown
${PREV TEST NAME}	The name of the previous test case, or an empty string if no tests have been executed yet.	Everywhere
${PREV TEST STATUS}	The status of the previous test case: either PASS, FAIL, or an empty string when no tests have been executed.	Everywhere
${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.	Everywhere
${SUITE DOCUMENTATION}	The documentation of the current test suite. Can be set dynamically using using Set Suite Documentation keyword. New in Robot Framework 2.7.	Everywhere
&{SUITE METADATA}	The free metadata of the current test suite. Can be set using Set Suite Metadata keyword. New in Robot Framework 2.7.4.	Everywhere
${SUITE STATUS}	The status of the current test suite, either PASS or FAIL.	套件的Setup和Teardown
${SUITE MESSAGE}	The full message of the current test suite, including statistics.	套件的Setup和Teardown
${KEYWORD STATUS}	The status of the current keyword, either PASS or FAIL. New in Robot Framework 2.7	用户关键字的Teardown
${KEYWORD MESSAGE}	The possible error message of the current keyword. New in Robot Framework 2.7.	用户关键字的Teardown
${LOG LEVEL}	Current `log level`_ . New in Robot Framework 2.8.	Everywhere
${OUTPUT FILE}	An absolute path to the `output file`_ .	Everywhere
${LOG FILE}	An absolute path to the 日志文件 or string NONE when no log file is created.	Everywhere
${REPORT FILE}	An absolute path to the 报告文件 or string NONE when no report is created.	Everywhere
${DEBUG FILE}	An absolute path to the 调试文件 or string NONE when no debug file is created.	Everywhere
${OUTPUT DIR}	An absolute path to the 输出目录 .	Everywhere

测试套件相关的变量 ${SUITE SOURCE} ${SUITE NAME} ${SUITE DOCUMENTATION} 和 &{SUITE METADATA} 在测试库和变量文件被导入时即可访问. 

扩展的变量语法支持获取变量对象的属性值(例如, ${object.attribute}), 甚至还可以执行对象的方法(例如, ${obj.getName()}). 这种语法对标量和列表都可用。

变量名可以嵌套使用. 这种情况下, 变量的解析从内往外进行.

例如, 有一个变量 ${var${x}}, ${x} 首先被解析. 如果值为 name, 则最终的变量名变为 ${varname}. 可以有多层嵌套, 不过如果任何一层变量不存在, 整个变量的解析失败.