使用参数

前面有的例子已经展示了关键字是怎样 接受 不同的参数的, 本节将更具体地讨论这个重要的功能点.

如何 实现 这些带各种参数的 用户关键字 和 库关键字 则在其它独立的章节讨论.

关键字可以接受零到多个参数, 并且有些参数还可以有默认值. 总的来说,一个关键字可以接受的参数数量和类型取决于它的实现, 一般来讲, 最好的去处是去该关键字的文档中来搜索相关信息.

对本章中的例子而言, 相关的文档可以使用 库文档工具(Libdoc) 工具生成. 不过, 也可是使用其它的文档生成工具, 例如 javadoc.

提示

译注: 调用关键字的传参方式和调用Python函数的语法如出一辙,所以熟悉Python的小伙伴可以快速掠过本节内容.

必填参数

大多数的关键字有部分参数是必须要传递的. 在关键字的文档中, 这部分参数的表示方式是 first, second, third. 这里的参数名称实际上并不重要, 仅作为描述该参数的意义, 但是参数的个数必须完全一致. 少传或者多传都会导致错误发生.

下面的用例用到了关键字 Create Directory 和 Copy File, 两者都来自于 OperatingSystem_ 库. 它们的参数定义分别是 path 和 source, destination, 也就是说, 分别需要1个和2个参数. 最后一个关键字, 来自 BuiltIn_ 的 No Operation 不接受参数.

  1. *** Test Cases ***
  2. Example
  3.     Create Directory    ${TEMPDIR}/stuff
  4.     Copy File    ${CURDIR}/file.txt    ${TEMPDIR}/stuff
  5.     No Operation

缺省值

可以为参数指定缺省值. 在关键字文档中, 缺省值通常表示为 name=default value, 即使用等于号把参数名和缺省值连接起来.

对于使用Java实现的关键字来说, 意味着同一个关键字, 需要使用不同的参数 多次实现 (实际上就是重载).

所有参数都可以指定缺省值, 不过位置参数 不可以 跟在带缺省值的参数的后面.

使用缺省值的情况见下例, 使用了关键字 Create File, 可接受的参数是 path, content=, encoding=UTF-8. 可以尝试不带任何参数, 或者多于3个参数来调用该关键字, 将会报错.

  1. *** Test Cases ***
  2. Example
  3.     Create File    ${TEMPDIR}/empty.txt
  4.     Create File    ${TEMPDIR}/utf-8.txt         Hyvä esimerkki
  5.     Create File    ${TEMPDIR}/iso-8859-1.txt    Hyvä esimerkki    ISO-8859-1

可变数量的参数

一个关键字还可以接受任意数量的参数, 也就是说, 参数个数是不确定的. 这种类型的参数一般称之为 varargs. varargs可以和必需参数以及带缺省值的参数混合使用, 不过在参数列表中必须排在它们的后面.在文档中, 此种参数通过在参数名称前加一个星号()来表示, 例如 varargs.

例如, OperatingSystem_ 库中的关键字 Remove Files 和 Join Paths, 参数分别是 paths 和 base, parts. 前者可以接受任意数量的参数, 后者则至少需要一个参数.

  1. *** Test Cases ***
  2. Example
  3.     Remove Files    ${TEMPDIR}/f1.txt    ${TEMPDIR}/f2.txt    ${TEMPDIR}/f3.txt
  4.     @{paths} =    Join Paths    ${TEMPDIR}    f1.txt    f2.txt    f3.txt    f4.txt

命名参数

命名参数语法使 缺省值 参数用起来更加灵活, 因为它可以明确地标示要传递的值对应的是哪个参数. 这种语法格式和Python语言中的 keyword arguments 如出一辙.

基础语法

可以使用 arg=value 的格式来指定传值给某个参数. 当多个参数有默认值时, 这种方式就显得特别有用, 因为我们只需要指定其中一些, 让其余的继续使用默认值.

例如, 如果一个关键字接受参数 arg1=a, arg2=b, arg3=c, 调用时传参 arg3=override, 则参数 arg1 和 arg2 使用默认值, 而 arg3 的值为 override. 这一切说起来颇为啰嗦, 查看下面的 命名参数示例 就比较清楚了.

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

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

不可以在命名参数后面使用普通的位置参数, 例如 | Keyword | arg=value | positional |.从Robot Framework 2.8 开始, 这会导致一个明确的错误提示.命名参数之间的相对位置则无关紧要.

注解

在Robot Framework 2.8版本之前, 不可以针对没有默认值的参数使用命名参数语法.

带变量的命名参数

变量 不但可以用于参数的值, 也可以用于参数名称. 如果变量值是一个单独的 标量变量, 则将按原值传递给关键字. 变量的值可以是任何的对象, 不仅限于字符串.例如, 调用关键字时使用 arg=${object}, 则变量 ${object} 最终会传递给关键字.

如果将变量用在命名参数的名称上, 变量需要在匹配参数名称之前就被解析出来. 这是2.8.6版本后才有的新功能.

命名参数语法需要在调用关键字时使用字面的等号(=), 也就是说, 不能把 = 放在一个变量里, 例如 foo=bar, 是不可能触发命名参数语法的.

当封装关键字的时候, 这点必须特别注意. 如果上层的关键字接受 可变数量的参数, 也就是 @{args}, 该关键字中调用另一个关键字时把所有的参数都通过 @{args} 传递过去, 则其中可能包含的 named=arg 将不会被识别.具体请看下面的例子.

  1. *** Test Cases ***
  2. Example
  3.     Run Program    shell=True    # This will not come as a named argument to Run Process
  4.  
  5. *** Keywords ***
  6. Run Program
  7.     [Arguments]    @{args}
  8.     Run Process    program.py    @{args}    # Named arguments are not recognized from inside @{args}

如果关键字需要接受并传递任意的命名参数, 它必须改用 任意关键字参数.参见 Kwargs示例, 这个例子展示了一个封装后的关键字如何既传递位置参数, 又传递命名参数.

转义命名参数语法

只有在参数等号前面的部分匹配上了某个参数名称时, 命名参数语法才起作用.假如有一个位置参数需要传入一个值 foo=quux, 假设同时有一个参数名是 foo, 此时, 大多数情况也许会触发语法错误, 还可能将 quux 值传递给了参数 foo, 当然也有可能是如我们预期的那样(位置参数接受到了完整的字符串值), 取决于参数的位置顺序等实际情况. 这时候, 需要使用反斜杠转义符来将其中的等号 转义, 如 foo\=quux. 这样, 位置参数将会明确的接受到值 foo=quux.

注意, 如果关键字没有参数名称是 foo, 则这里的转义不是必需的. 不过, 由于这种写法会更明确, 所以推荐的做法是不管什么情况下都转义.

支持命名参数的地方

如前所述, 命名参数语法可以用于关键字. 此外, 它还可以用在 importing libraries.

user keywords 以及大部分的 使用测试库 也都支持命名参数. 唯一的例外是基于Java的 static library API 库.使用 库文档工具(Libdoc) 生成的库文档中会显示该库是否支持命名参数.

注解

Robot Framework2.8版本之前, 使用 动态库API的库也不支持命名参数语法.

命名参数示例

下面的例子展示了命名参数语法如何应用在库关键字和用户关键字上, 以及在导入 Telnet 测试库时的应用.

  1. *** Settings ***
  2. Library    Telnet    prompt=$    default_log_level=DEBUG
  3.  
  4. *** Test Cases ***
  5. Example
  6.     Open connection    10.0.0.42    port=${PORT}    alias=example
  7.     List files    options=-lh
  8.     List files    path=/tmp    options=-l
  9.  
  10. *** Keywords ***
  11. List files
  12.     [Arguments]    ${path}=.    ${options}=
  13.     Execute command    ls ${options} ${path}

任意命名参数

Robot Framework 2.8加入了对 Python风格的命名参数 <python kwargs> (**kwargs)的支持. 这意味着关键字可以接受任意数量的 name=value 语法格式的参数.

Kwargs和 命名参数 类似, 也支持变量. 实际应用中, 变量既可以作为参数名, 也可以作为参数值, 但是必须明确的使用转义符.例如, foo=${bar} 和 ${foo}=${bar} 都是合法的, 只要这些变量本身没问题. 一个额外的限制是, 作为参数名称的变量值必须是字符串.

注解

支持在参数名称中使用变量是Robot Framework 2.8.6才加入的新功能.

最初 **kwargs 只可用于Python编写的库, 后来Robot Framework 2.8.2扩展到 动态库API, 2.8.3版本继续扩展到支持基于的Java测试库以及 远程测试库接口. 最终, 用户关键字在2.9版本也开始支持 kwargs.

也就是说, 当前最新的版本中, 所有的关键字都可以使用 **kwargs.

Kwargs示例

第1个例子中, 使用了 Process_ 中的 Run Process 关键字. 该关键字的参数签名是: command, arguments, **configuration, 分别的含义是: command 表示要执行的命令, 命令所需的参数通过 可变数量的参数 即 arguments 指定, 最后是可选的配置参数 **configuration.例子中同时展示了kwargs中变量的用法, 就和 使用命名参数 一样.

  1. *** Test Cases ***
  2. Using Kwargs
  3.     Run Process    program.py    arg1    arg2    cwd=/home/user
  4.     Run Process    program.py    argument    shell=True    env=${ENVIRON}

关于如何在自定义的测试库中使用 kwargs 语法, 请参阅: 创建测试库 中的 free keyword arguments (**kwargs) 部分内容.

第2个例子中, 我们封装了一个 user keyword 来简化调用上述的运行 program.py 过程.封装后的关键字 Run Program 接受任意数量的参数和kwargs, 并将它们传递给底层的关键字 Run Process, 只是固定其中的 command 参数.

  1. *** Test Cases ***
  2. Using Kwargs
  3.     Run Program    arg1    arg2    cwd=/home/user
  4.     Run Program    argument    shell=True    env=${ENVIRON}
  5.  
  6. *** Keywords ***
  7. Run Program
  8.     [Arguments]    @{arguments}    &{configuration}
  9.     Run Process    program.py    @{arguments}    &{configuration}

关键字名称中嵌入参数

在关键字的名称中嵌入参数是一种全新的指定参数的方式. 这种语法同时被 测试库关键字 和 用户关键字 支持.